微服務RESTful 接口設計規範

 

一、RESTful發展背景及簡介

網絡應用程序，分爲前端和後端兩個部分。當前的發展趨勢，就是前端設備層出不窮（手機、平板、桌面電腦、其餘專用設備......）。所以，必須有一種統一的機制，方便不一樣的前端設備與後端進行通訊。這致使API構架的流行，甚至出現"APIFirst"的設計思想。RESTful API是目前比較成熟的一套互聯網應用程序的API設計理論。

REST（Representational State Transfer）表述性狀態轉換，REST指的是一組架構約束條件和原則。 若是一個架構符合REST的約束條件和原則，咱們就稱它爲RESTful架構。REST自己並無創造新的技術、組件或服務，而隱藏在RESTful背後的理念就是使用Web的現有特徵和能力， 更好地使用現有Web標準中的一些準則和約束。雖然REST自己受Web技術的影響很深， 可是理論上REST架構風格並非綁定在HTTP上，只不過目前HTTP是惟一與REST相關的實例。

二、RESTful設計風格

2.一、推薦格式

1）url格式：

http(s)://server.com/api-name/{version}/{domain}/{rest-convention}

這裏，{version}表明api的版本信息。{domain}是一個你能夠用來定義任何技術的區域(例如：安全-容許指定的用戶能夠訪問這個區域。)或者業務上的區域(例如：一樣的功能在同一個前綴之下。)。{rest-convention} 表明這個域(domain)下，約定的rest接口集合。

2）參數格式：

GET採用兩種常見格式:

① URL參數（更推薦），如：

https://www.example.com/v1.1？name=‘lk-abc%’&age=’lt-10’

②路徑參數，如：

https://www.example.com/v1.1/employees/{id}

 POST採用兩種常見格式:

①Json格式包裝參數提交

POST  https://www.example.com/v1.1
Content-Type: application/json;charset=utf-8
{"title":"test","sub":[1,2,3]}

②form表單參數提交

POST   https://www.example.com/v1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
title=test&sub%5B%5D=1&sub%5B%5D=2&sub%5B%5D=3

3）返回體格式：

{"status」: 200,
"message」:"用戶查詢返回成功」,
「document」:」https://www.example.com/doc#userinfo」,
   "data」: {
       "className」: "com.fiberhome.smartas.pricecloud.User」,
        "id」:「1b434wtert564564sdffey32」,
        "name」: "lilei",
        "age」: 18,
        "job」: {
             "className」:"com.fiberhome.smartas.pricecloud.Job」,
            "id」: 「1b434wtert564564sdffeyey」,
            "name」: 「微服務架構師」
        }
    }
}

2.二、協議

考慮到服務的安全性，建議使用https做爲API的通訊協議，固然http也是能夠的。

2.三、域名

建議將API部署在專有域名下，以此屏蔽消費者對服務提供方的部署細節（可藉助於平臺的反向代理+路由網關），在服務地圖豐富起來以後能夠考慮多級域名。

https://api.example.com
https://example.org/api/

2.四、版本

考慮到微服務的平滑升級，能夠將API的版本號放入URL，也能夠將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github採用這種作法。

https://api.example.com/v1/

2.五、複數名詞路徑

在RESTful架構中，每一個網址表明一種資源（resource），因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表格名對應。通常來講，數據庫中的表都是同種記錄的"集合"（collection），因此API中的名詞也應該使用複數。

https://api.example.com/v1/employees

2.六、http協議類型表達資源操做

HTTP協議裏的8種方法，及其餘衍生方法，經常使用的Get、post能夠間接的實現其他全部的操做，根據框架和瀏覽器的兼容性選擇性使用。

1)  GET（SELECT）：從服務器取出資源（一項或多項）。

2)  POST（CREATE）：在服務器新建一個資源。

3)  PUT（UPDATE）：在服務器更新資源（客戶端提供改變後的完整資源）。

4)  PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。

5)  DELETE（DELETE）：從服務器刪除資源

6)  HEAD：獲取資源的元數據。

7)  OPTIONS：獲取信息，關於資源的哪些屬性是客戶端能夠改變的。

8)  TRACE：回顯服務器收到的請求，主要用於測試或診斷。 

9)  CONNECT：HTTP/1.1協議中預留給可以將鏈接改成管道方式的代理服務器。

10) MOVE： 請求服務器將指定的頁面移至另外一個網絡地址。

11) COPY： 請求服務器將指定的頁面拷貝至另外一個網絡地址。

12) LINK： 請求服務器創建連接關係。

13) UNLINK： 斷開連接關係。

14) WRAPPED： 容許客戶端發送通過封裝的請求。

15) Extension-mothed：在不改動協議的前提下，可增長另外的方法。

GET  https://api.example.com/v1/employees/ 獲取全部僱員

 

2.七、過濾信息

請求信息應該爲集合提供過濾、排序、選擇和分頁等功能

1）Filtering過濾:

使用惟一的查詢參數進行過濾：

GET /cars?color=red 返回紅色的cars

2）Sorting排序:

容許針對多個字段排序

GET /cars?sort=-manufactorer,+model

這是返回根據生產者降序和模型升序排列的car集合

3）Fieldselection

移動端可以顯示其中一些字段，它們其實不須要一個資源的全部字段，給API消費者一個選擇字段的能力，這會下降網絡流量，提升API可用性。

GET /cars?fields=manufacturer,model,id,color

4）Paging分頁

使用 limit 和offset.實現分頁，缺省limit=20 和offset=0；

GET /cars?offset=10&limit=5

爲了將總數發給客戶端，使用訂製的HTTP頭：X-Total-Count.

連接到下一頁或上一頁能夠在HTTP頭的link規定，遵循Link規定:

Link:<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>;rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>;rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>;rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>;rel="prev",

2.八、返回結果爲統一的json格式

一方面，出於平臺標準化的API管理，另外一方面，遵循微服務的寬進嚴出設計理念，建議RESTful採用標準的Json格式。

返回結構體

{   
　　"className」: "com.fiberhome.smartas.pricecloud.User」,
    "id」:「1b434wtert564564sdffey32」,
    "name」: "lilei",
    "age」: 18,
    "job」: {
             "className」:"com.fiberhome.smartas.pricecloud.Job」,
            "id」: 「1b434wtert564564sdffeyey」,
            "name」: 「微服務架構師」
     }
}

Object implements Serializable;
JSONObject.fromObject(json);
JSONObject.parseObject(text)

 

2.九、返回結果應該包含狀態碼

常見狀態碼

1)  200 OK - [GET]：服務器成功返回用戶請求的數據，該操做是冪等的（Idempotent）。

2)  201 CREATED -[POST/PUT/PATCH]：用戶新建或修改數據成功。

3)  202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）

4)  204 NO CONTENT - [DELETE]：用戶刪除數據成功。

5)  400 INVALID REQUEST -[POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操做，該操做是冪等的。

6)  401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。

7)  403 Forbidden - [*] 表示用戶獲得受權（與401錯誤相對），可是訪問是被禁止的。

8)  404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操做，該操做是冪等的。

9)  406 Not Acceptable - [GET]：用戶請求的格式不可得（好比用戶請求JSON格式，可是隻有XML格式）。

10)  410Gone -[GET]：用戶請求的資源被永久刪除，且不會再獲得的。

11)  422Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。

12)  500INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。

 

2.十、返回結果中提供幫助連接

RESTful API最好作到Hypermedia，即返回結果中提供連接，連向其餘API方法，使得用戶不查文檔，也知道下一步應該作什麼。注：Github就是這麼作的

返回體結構

{"link": 
    {
     "document":" https://www.example.com/docs#zoos",
     "href":"https://api.example.com/zoos",
     "title":"List of zoos",
     "type":"application/vnd.yourformat+json"
    }
}

 

2.十一、API擴展事項

     1）RESTful API依託PaaS平臺治理，須要對API進行認證、受權、參數加密等操做，可考慮在HTTP頭部加認證token、調用鏈指令、狀態信息等系列信息。     2）如PPT所言，API分層，會有內部API和外部API之分，兩種API的設計或有不一樣（甚至是不一樣協議）。     3）對於API設計的狀態選擇，建議爲無狀態、N次冪等，但後續或存在性能優化問題，http2.0待評測。