title: 一聲笑接口文檔
date: 2019-03-03 21:44:43
tags:

Author：Leguang

E-Mail：langmanleguang@qq.com

目標(biāo)

• 接口“粒度”爭取設(shè)計(jì)得足夠小率翅，爭取在業(yè)務(wù)發(fā)生變化后灭将，后臺接口不需要增減榆浓，只需要前端組合接口仍然能滿足新的業(yè)務(wù)需求菇曲。
• 任何一個(gè)接口都可以獲取到數(shù)據(jù)神僵，哪怕沒傳參數(shù)熊经。

要求

命名規(guī)范

一名二姓三風(fēng)水脏榆，四積陰德五讀書猖毫，名不正則言不順，言不順則事難成须喂。軟件開發(fā)其實(shí)就是門命名的藝術(shù)吁断，所以首先定義一些規(guī)范趁蕊，提出一些硬性要求，大家在命名的時(shí)候盡量多花點(diǎn)心思仔役，多參考優(yōu)秀的命名風(fēng)格掷伙。

• 強(qiáng)烈推薦參考：參考阿里巴巴Java開發(fā)手冊，Android開發(fā)規(guī)范又兵，iOS開發(fā)手冊任柜。
• 一個(gè)單詞盡量選擇5--7個(gè)字母的，這樣才最優(yōu)美沛厨。
• 首字母縮寫的單詞盡量每個(gè)字母都用大寫宙地，例如ID。用個(gè)小寫逆皮，人家還以為是一個(gè)單詞宅粥。當(dāng)然uri、url电谣、urn這種除外粹胯，因?yàn)榇蠹叶贾肋@個(gè)是什么。
• 規(guī)范并統(tǒng)一公司的基礎(chǔ)包名與項(xiàng)目的關(guān)系辰企。
• 前后端的某些名稱概念要統(tǒng)一用某一個(gè)單詞，比如支付的統(tǒng)一訂單况鸣，支付寶用的是order牢贸，微信用的是unifiedorder，那我們統(tǒng)一對訂單這個(gè)概念用order這個(gè)詞镐捧。再比如主機(jī)：后臺用gateway潜索，現(xiàn)在我們統(tǒng)一用host。這單詞不統(tǒng)一很容易分裂懂酱。

uri規(guī)范

uri 表示資源竹习，資源一般對應(yīng)服務(wù)器端領(lǐng)域模型中的實(shí)體類，要求如下：

• 不用大寫列牺。
• 盡量不用橫杠分隔符整陌，萬一要用，請使用中杠“-”不用下杠“_”瞎领。
• 參數(shù)列表要encode泌辫。
• uri中的名詞表示資源集合，使用復(fù)數(shù)形式九默。
• 路徑僅表示資源的路徑（位置）震放，以及一些特殊的actions操作。
• 以復(fù)數(shù)（名詞）進(jìn)行命名資源驼修，不管返回單個(gè)或者多個(gè)資源殿遂。
• 資源的路徑從父到子依次如：/{resource}/{resource_id}/{sub_resource}/{sub_resource_id}/{sub_resource_property}诈铛。
• 使用?來進(jìn)行資源的過濾、搜索以及分頁等墨礁。
• 使用版本號幢竹，且版本號在資源路徑之前。
• 優(yōu)先使用內(nèi)容協(xié)商來區(qū)分表述格式饵溅，而不是使用后綴來區(qū)分表述格式妨退。
• url最好越簡短越好，結(jié)果過濾蜕企，排序咬荷，搜索相關(guān)的功能都應(yīng)該通過參數(shù)實(shí)現(xiàn)。
• url失效則返回404 not found 或 410 gone轻掩；對遷移的API幸乒，返回 301 重定向。

JSON規(guī)范

暫時(shí)只考慮json的數(shù)據(jù)格式唇牧，要求如下：

• 不要使用縮寫罕扎。
• 統(tǒng)一用駝峰命名法。
• 不要使用“_”或者“-”丐重。
• 用名詞復(fù)數(shù)表示集合類型腔召。
• 為了方便以后的擴(kuò)展兼容，如果返回的是數(shù)組扮惦，強(qiáng)烈建議用一個(gè)包含如items屬性的對象進(jìn)行包裹臀蛛。如：{"items":[{},{}]}。
• 建議對每個(gè)字段設(shè)置默認(rèn)值（數(shù)組型可設(shè)置為[],字符串型可設(shè)置為””崖蜜，數(shù)值可設(shè)置為0浊仆，對象可設(shè)置為{}）,這一條是為了方便前端/客戶端進(jìn)行判斷字段存不存在操作。
• 建議資源使用UUID最為唯一標(biāo)識豫领。同時(shí)建議命名為id或者uid抡柿。
• 采用UTF-8編碼。
• 數(shù)據(jù)應(yīng)該拿來就能用等恐，不應(yīng)該還要進(jìn)行轉(zhuǎn)換操作洲劣。

草稿：JSON返回的格式是分門別類按對象來劃分，還是鋪大餅的形式鋪開鼠锈，兩者利弊各異闪檬，比如url，可能一個(gè)接口中返回多個(gè)url购笆，如果分json對象裝的話粗悯，則key都可以叫url，否則的話key就得命名成xxxUrl同欠。這個(gè)有待商議

HTTP部分

使用場景

• App的初始化數(shù)據(jù)盡量都用http協(xié)議獲取样傍。
• 頁面的初始化數(shù)據(jù)盡量都用http協(xié)議獲取横缔。

URL結(jié)構(gòu)

https://{serviceRoot}/{module}/{collection}/{id}

• {serviceRoot} – 域名+端口號 (site URL) + 根目錄
• {module} – 模塊名稱
• {collection} – 要訪問的資源
• {id} – 要訪問的資源的唯一編號

公共請求頭

通過Content-Type指定請求與返回的數(shù)據(jù)格式有JSON和XML,暫時(shí)我們只管json的。其中請求數(shù)據(jù)還要指定Accept衫哥。其中額外添加的請求頭里的參數(shù)注意大小寫茎刚。

Accept: application/json
Content-Type: application/json;charset=UTF-8
Token: token_G34G34G34G34G35G5
Application: 應(yīng)用:版本
Platform: Android
Locale: zh

暫時(shí)只考慮4門語言

公共參數(shù)（部分公共參數(shù)建議公放到請求頭里）

公共參數(shù)是指每一個(gè)接口都可能有的互例，為了減少篇幅奢入，我在這里統(tǒng)一定義，同時(shí)后端要指定公共參數(shù)的默認(rèn)值媳叨，且要保證沒有傳公共參數(shù)不會報(bào)錯(cuò)腥光，所以需要一定的容錯(cuò)性，比如priceDes這個(gè)參數(shù)值糊秆，如果是用的是全部小寫的武福，只要是不沖突，則可認(rèn)為是準(zhǔn)確的參數(shù)并且表達(dá)了按價(jià)格降序排列這個(gè)語意痘番。常用公共參數(shù)如下：

個(gè)性參數(shù)

個(gè)性參數(shù)就是除了公共參數(shù)之外的腻扇，看能否考慮統(tǒng)一用JSON將公共參數(shù)和個(gè)性參數(shù)濃縮成一個(gè)參數(shù)，把想要表達(dá)的參數(shù)通過json中的key-value形式傳遞砾嫉。例如：https://api.xxx.com/both/v1/search/products?params={"extra":"你想填什么呢","token":"token_523523523","data":{"uid":"23523523523523"}} 或者考慮與業(yè)務(wù)相關(guān)的參數(shù)就用json形式包裝幼苛，而與業(yè)務(wù)無關(guān)的個(gè)性參數(shù)就還是用傳統(tǒng)的方式另立一個(gè)參數(shù)。例如：https://api.xxx.com/both/v1/search/products?limit=10&offset=10&params={"keyword":"方便面","sort":"des"}

通過商議將個(gè)性參數(shù)統(tǒng)一按原始的URL傳參形式傳遞焕刮，不考慮上面所說的那種方式舶沿。

公共響應(yīng)頭

Content-Type:application/json; charset=utf-8
Status:200 OK

其中狀態(tài)碼要與公共響應(yīng)體里的json中的code字段一樣墙杯。

公共響應(yīng)體

默認(rèn)會有以下字段，不需要全部都有括荡。

{
    "message": "居然被你查詢成功了",
    "code": 200,
    "page": 0,
    "pageSize": 20,
    "first": "https://...",
    "next": "https://...",
    "previous": "https://...",
    "last": "https://...",
    "data": {
        "uid": "6565656565665"
    }
}

HTTP動詞表示操作。

常用的HTTP動詞有下面五個(gè)（括號里是對應(yīng)的SQL命令）鲸阔。

• GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）偷霉。
  例如:GET /zoos：列出所有動物園。
• POST（CREATE）：在服務(wù)器新建一個(gè)資源。
  例如:POST /zoos：新建一個(gè)動物園踪栋。
• PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）昭雌。
  例如:PUT /zoos/ID：更新某個(gè)指定動物園的信息（提供該動物園的全部信息）。
• DELETE（DELETE）：從服務(wù)器刪除資源硫狞。
  例如:DELETE /zoos/ID：刪除某個(gè)動物園。

狀態(tài)碼

作為API的設(shè)計(jì)者晃痴，正確的將API執(zhí)行結(jié)果和失敗原因用清晰簡潔的方式傳達(dá)給客戶程序是十分關(guān)鍵的一步残吩。我們確實(shí)可以在HTTP的相應(yīng)內(nèi)容中描述是否成功，如果出錯(cuò)是因?yàn)槭裁刺群耍欢辏@就意味著用戶需要進(jìn)行內(nèi)容解析，才知道執(zhí)行結(jié)果和錯(cuò)誤原因紧唱。因此活尊，HTTP響應(yīng)代碼可以保證客戶端在第一時(shí)間用最高效的方式獲知 API 運(yùn)行結(jié)果，并采取相應(yīng)動作漏益。下表列出了比較常用的響應(yīng)代碼蛹锰。
常用的http狀態(tài)碼及使用場景：

分頁

分頁適用于GET類型且返回集合數(shù)據(jù)的請求凉夯，根據(jù)如下參數(shù)進(jìn)行分頁操作。分頁返回的數(shù)據(jù)見公共響應(yīng)體采幌。

{
    "extra": "你想填什么就填什么",
    "page": 0,
    "pageSize": 20,
}

錯(cuò)誤/異常處理

• 不要發(fā)生了錯(cuò)誤但給2xx響應(yīng)劲够，客戶端可能會緩存成功的HTTP請求；
• 正確設(shè)置http狀態(tài)碼休傍，不要自定義再沧；
• Response body 提供 1) 錯(cuò)誤的代碼（日志/問題追查）；2) 錯(cuò)誤的描述文本（展示給用戶）尊残。

對第三點(diǎn)的實(shí)現(xiàn)稍微多說一點(diǎn)：

Java 服務(wù)器端一般用異常表示 RESTful API 的錯(cuò)誤。API 可能拋出兩類異常：業(yè)務(wù)異常和非業(yè)務(wù)異常淤堵。業(yè)務(wù)異常由自己的業(yè)務(wù)代碼拋出寝衫，表示一個(gè)用例的前置條件不滿足、業(yè)務(wù)規(guī)則沖突等拐邪，比如參數(shù)校驗(yàn)不通過慰毅、權(quán)限校驗(yàn)失敗。非業(yè)務(wù)類異常表示不在預(yù)期內(nèi)的問題扎阶，通常由類庫汹胃、框架拋出婶芭，或由于自己的代碼邏輯錯(cuò)誤導(dǎo)致，比如數(shù)據(jù)庫連接失敗着饥、空指針異常犀农、除0錯(cuò)誤等等。

業(yè)務(wù)類異常必須提供2種信息：

1. 如果拋出該類異常宰掉，HTTP響應(yīng)狀態(tài)碼應(yīng)該設(shè)成什么呵哨；
2. 異常的文本描述；

錯(cuò)誤描述
{
    "message": "特么的又錯(cuò)了",
    "code": 500,
    "document": "https://developer.xxx.com/v1/errors/500",
    "exception": [
        {
            "code": "NullValue",
            "target": "PhoneNumber",
            "message": "Phone number must not be null"
        },
        {
            "code": "NullValue",
            "target": "LastName",
            "message": "Last name must not be null"
        },
        {
            "code": "MalformedValue",
            "target": "Address",
            "message": "Address is not valid"
        }
    ]
}

錯(cuò)誤請求頭
{
  "date": "Mon, 08 Jan 2018 03:07:08 GMT",
  "server": "nginx/1.10.3 (Ubuntu)",
  "connection": "keep-alive",
  "content-length": "237",
  "content-type": "application/json"
}

錯(cuò)誤狀態(tài)碼（非200）

通過分析發(fā)現(xiàn)轨奄，接口的錯(cuò)誤無非調(diào)用端傳遞給后臺的信息與預(yù)期不符孟害，其中包括公共參數(shù)和個(gè)性參數(shù)不符，不符包括缺失和內(nèi)容錯(cuò)誤（或格式錯(cuò)誤等）兩種挪拟，還有是部分特殊業(yè)務(wù)的特殊性質(zhì)造成非正常結(jié)果挨务，如：重復(fù)申請、重復(fù)簽到等玉组。經(jīng)商議決定將錯(cuò)誤碼分為四大類：

以上友好的message提示方便了我們队询，同時(shí)也方便了非法調(diào)用者派桩，為阻礙非法調(diào)用，決定設(shè)置一個(gè)開關(guān)蚌斩，該開關(guān)是系統(tǒng)自帶的铆惑，根據(jù)編譯環(huán)境變更，在調(diào)試階段就用以上友好提示送膳，在正式部署上線后就改成模糊提示员魏。

url失效

隨著系統(tǒng)發(fā)展，總有一些API失效或者遷移叠聋，對失效的API撕阎，返回404 not found 或 410 gone；對遷移的API碌补，返回 301 重定向虏束。

對于后臺文檔的要求

文檔要求

文檔要求描述詳盡，盡可能的引導(dǎo)接口使用者理解接口設(shè)計(jì)厦章，這樣才能減少接口的改動镇匀，又能適應(yīng)多變的業(yè)務(wù)。

容錯(cuò)性（健壯性）

考慮到如果測試或者運(yùn)營中有變動袜啃，要求每一個(gè)Web頁面得有容錯(cuò)機(jī)制汗侵，比如關(guān)停該功能，則web必須的有相應(yīng)的頁面展示群发。

國際化

此處的國際化是指語言的國際化晰韵，因此前后端都要考慮在界面的文字提示上要做國際化處理，暫時(shí)我們只做4種文字的國際化：中文（簡體）熟妓、英文雪猪、日文和韓文，經(jīng)商議滑蚯，通過兩方面來傳遞國際化信息：

• 專門的locale設(shè)置接口
• 請求頭中多一個(gè)locale字段

由于有兩個(gè)入口設(shè)置語言，因此有優(yōu)先級處理，請求頭中l(wèi)ocale字段優(yōu)先級大于locale設(shè)置接口告材，兩者不傳坤次，默認(rèn)都表示簡體中文。locale接口默認(rèn)為簡體中文斥赋，如果有設(shè)置其他語言缰猴，則為其他語言，請求頭里如果沒有l(wèi)ocale字段疤剑，則依據(jù)locale接口滑绒，如果請求頭里帶了locale字段，則依據(jù)請求頭為準(zhǔn)隘膘。