微服務(wù)接口定義規(guī)范標(biāo)準(zhǔn)[詳]

1、. . . . 接口定義規(guī)范研發(fā)部2018/01參考.資料1 URI命名規(guī)范32 使用HTTP方法表示動作行為43 使用HTTP內(nèi)容協(xié)商處理資源表示內(nèi)容44 使用HTTP響應(yīng)狀態(tài)碼標(biāo)識處理結(jié)果狀態(tài)55 使用 HAL(Hypertext Application Language)作為響應(yīng)數(shù)據(jù)格式66 各HTTP方法成功處理后的返回數(shù)據(jù)97 不要對返回結(jié)果進行封裝98 支持資源的字段裁剪，減少響應(yīng)中返回的字段數(shù)量109 使用 OAuth2 來確保 API 的安全性1010 確保GET，PUT，DELETE 請求是冪等的1011 API版本10微服務(wù)

2、接口設(shè)計采用Restful風(fēng)格的接口規(guī)范，下面是基于Restful風(fēng)格要求制訂的接口設(shè)計規(guī)范。1 URI命名規(guī)范Ø 不用大寫；Ø 用中杠-不用下杠_；Ø 參數(shù)列表要encode；Ø 使用名詞作為資源名稱 (例如，不要在網(wǎng)址中使用動詞)；Ø 使用資源集合的概念；v 每種資源有兩類URI（接口）：u 資源集合（例如，/orders）；u 集合中的單個資源（例如，/orders/orderId）。v 使用復(fù)數(shù)形式 (使用 orders 而不是 order)；v 資源名稱和 ID 組合可以作為一個網(wǎng)址的節(jié)點；例如，/orders/orderId/ite

3、ms/itemId；v 盡可能的讓網(wǎng)址越短越好，單個網(wǎng)址最好不超過三個節(jié)點?？梢允褂貌樵儏?shù)代替路徑中的節(jié)點組合Ø 對Composite資源的訪問服務(wù)器端的組合實體必須在uri中通過父實體的id導(dǎo)航訪問。GET /orders/12/itemsØ 使用有意義的資源描述；v “禁止單純的使用 ID!” 響應(yīng)信息中不應(yīng)該存在單純的 ID，應(yīng)使用鏈接或是引用的對象；v 設(shè)計資源的表述信息，而不是簡簡單單的做數(shù)據(jù)庫表的映射；v 合并表述信息，不要通過兩個 ID 直接表示兩個表的關(guān)系；Ø 資源的集合應(yīng)支持過濾，排序和分頁；過濾、排序、分頁應(yīng)出現(xiàn)在參數(shù)列表中而不是Path中。

4、例如：GET /currencies?page=1&size=10過濾條件應(yīng)該合并到一個參數(shù)里：GET poobah” 排序字段也應(yīng)該合并到一個參數(shù)里,使用-代表倒序GET Ø 經(jīng)常使用的、復(fù)雜的查詢標(biāo)簽化，降低維護成本。如：GET /trades?status=closed&sort=created desc快捷方式：GET /trades/recently-closed2 使用HTTP方法表示動作行為v POST - 創(chuàng)建資源，非冪等性操作；v PUT - 更新資源；v PATCH - 部分更新資源；v GET - 獲取單個資源或資源集合；v DELETE - 刪

5、除單個資源或資源集合；原則上URI中不應(yīng)該出現(xiàn)動詞，當(dāng)出現(xiàn)復(fù)雜操作超出上述HTTP方法描述的行為時，可以考慮通過URL參數(shù)來指定動作。如 PUT /books/1?action=like 標(biāo)注ID為1的圖書為喜愛圖書使用其他動作時，HTTP方法仍然根據(jù)實際操作屬于那種類型設(shè)定，比如屬于資源的更新操作，那么就使用PUT方法。3 使用HTTP內(nèi)容協(xié)商處理資源表示內(nèi)容 通過請求頭/響應(yīng)頭中的Content-Type判斷請求提中的數(shù)據(jù)類型，然后根據(jù)數(shù)據(jù)類型做出相應(yīng)處理。v 請求Body內(nèi)容格式采用JSON格式，其格式通過HTTP Header Content-Type:application/json

6、表示。v 或From表單格式，其格式通過HTTP Header：Content-Type: application/x-www-form-urlencodedv 響應(yīng)內(nèi)容格式為JSON，響應(yīng)頭Content-Type:application/jsonv 或HAL+JSON，響應(yīng)頭為Content-Type:application/hal+jsonv 或XML格式，響應(yīng)頭為Content-Type:text/xml4 使用HTTP響應(yīng)狀態(tài)碼標(biāo)識處理結(jié)果狀態(tài)v 不要發(fā)生了錯誤但給2xx響應(yīng)，客戶端可能會緩存成功的http請求；v 正確設(shè)置http狀態(tài)碼，不要自定義； 下面是常用狀態(tài)碼及其意義： 響

7、應(yīng)碼說明200 OK請求處理正常，通常用于GET操作時內(nèi)容正常返回201 CreatedPost或PUT操作時對象被正常創(chuàng)建，通常在Body中返回對象內(nèi)容。204 No content處理成功，但沒返回值。如delete操作，沒有內(nèi)容可返回。301 Moved permanently 資源被移動到其它位置，需要客戶端重定向。400 Bad request請求有問題，可能是缺少參數(shù)或參數(shù)不正確，需要客戶端修正請求內(nèi)容?？梢栽谡埱篌w中返回錯誤提示信息。401 Unauthorized 指定資源需要授權(quán)，用戶未認(rèn)證身份所以不能訪問資源。403 Forbidden 用戶已登錄但是沒有指定資源的訪問權(quán)限

8、。404 Not found 指定的資源不存在。405 Method not allowed資源不支持訪問方法，如對只讀資源使用PUT進行更新409 Conflict將出現(xiàn)重復(fù)的數(shù)據(jù)或是無效的數(shù)據(jù)狀態(tài)。500 Internal server error服務(wù)器發(fā)生非預(yù)期錯誤，此時需要在響應(yīng)體中返回錯誤的具體信息。對于400、409、500這種需要進一步說明原因的錯誤碼，可以在響應(yīng)體中返回對應(yīng)的錯誤信息，格式如下：code:500,message:'服務(wù)暫不可用，請稍后重試或與管理員聯(lián)系' 5 使用 HAL(Hypertext Application&

9、#160;Language)作為響應(yīng)數(shù)據(jù)格式v 簡單資源對象： "_links": "self": "href": "/api/user/matthew" , "id": "matthew", "name": "Matthew Weier O'Phinney" v 復(fù)雜資源對象： "_links": "self": "href": &q

10、uot;/api/user/matthew" , "id": "matthew", "name": "Matthew Weier O'Phinney", "_embedded": "contacts": "_links": "self": "href": "/api/user/mac_nibblet" , &qu

11、ot;id": "mac_nibblet", "name": "Antoine Hedgecock" , "_links": "self": "href": "/api/user/spiffyjr" , "id": "spiffyjr", "name": "Kyle Spraggs" , "website": &q

12、uot;_links": "self": "href": "/api/locations/mwop" , "id": "mwop", "url": "" , v 帶有分頁的結(jié)果： "_embedded" : "currencyLogs" : "uid" : "quot;, "type" : 1, &q

13、uot;coin" : 0.50, "usercoin" : 5.50, "add_time" : "1504228164", "expressid" : 0 , "uid" : "quot;, "type" : 1, "coin" : 0.50, "usercoin" : 6.00, "add_time" : "1504228187", "e

14、xpressid" : 0,. "uid" : "quot;, "type" : 1, "coin" : 0.50, "usercoin" : 10.00, "add_time" : "1504228349", "expressid" : 0 , "_links" : "first" : "href" : "http:/localhost:80

15、11/userscurrencylogs/group-by-day?page=0&size=10" , "prev" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=0&size=10" , "self" : "href" : "http:/localhost:8011/userscurrenc

16、ylogs/group-by-day?page=1&size=10" , "next" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=2&size=10" , "last" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=5345

17、&size=10" , "page" : "size" : 10, "totalElements" : 53454, "totalPages" : 5346, "number" : 1 6 各HTTP方法成功處理后的返回數(shù)據(jù)HTTP方法response 格式GET單個對象、集合POST新增成功的對象、或URIPUT/PATCH更新成功的對象或URIDELETE空7 不要對返回結(jié)果進行封裝response 的 body 直接就是數(shù)據(jù)，不要做多余的包裝。 "uid&quo

18、t; : "quot;, "type" : 1, "coin" : 24991.50, "expressid" : 0, "_links" : "self" : "href" : "http:/localhost:8011/currencies/270" 8 支持資源的字段裁剪，減少響應(yīng)中返回的字段數(shù)量9 使用 OAuth2 來確保 API 的安全性v 使用 Bearer Token 進行身份驗證；v OAuth2 的 Bearer token 要求必須通過 HTTPS / TLS / SSL 來訪問你的 API。通過 HTTP 進行的未加密通信將導(dǎo)致竊聽和重放。10 確保GET，PUT，DELETE 請求是冪等的 冪等性：執(zhí)行1次和執(zhí)行N次，對資源狀態(tài)改變的效果是等價的。11 API版本使用HEADER傳遞版本信息。# RequestGET Accept: application/jsonContent-Type: application/json; version=1 1. 若不給自己設(shè)限，則人生中就沒有限制你發(fā)揮的藩籬。2. 若不是心寬似海