微服務RESTful 介面設計規範
1、RESTful發展背景及簡介
網路應用程式，分為前端和後端兩個部分。當前的發展趨勢，就是前端裝置層出不窮（手機、平板、桌面電腦、其他專用裝置......）。因此，必須有一種統一的機制，方便不同的前端裝置與後端進行通訊。這導致API構架的流行，甚至出現"APIFirst"的設計思想。RESTful API是目前比較成熟的一套網際網路應用程式的API設計理論。
REST（Representational State Transfer）表述性狀態轉換，REST指的是一組架構約束條件和原則。 如果一個架構符合REST的約束條件和原則，我們就稱它為RESTful架構。REST本身並沒有創造新的技術、元件或服務，而隱藏在RESTful背後的理念就是使用Web的現有特徵和能力， 更好地使用現有Web標準中的一些準則和約束。雖然REST本身受Web技術的影響很深， 但是理論上REST架構風格並不是繫結在HTTP上，只不過目前HTTP是唯一與REST相關的例項。
2、RESTful設計風格
2.1、推薦格式
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.2、協議
考慮到服務的安全性，建議使用https作為API的通訊協議，當然http也是可以的。
2.3、域名
建議將API部署在專有域名下，以此遮蔽消費者對服務提供方的部署細節（可藉助於平臺的反向代理+路由閘道器），在服務地圖豐富起來之後可以考慮多級域名。
https://api.example.com
https://example.org/api/
2.4、版本
考慮到微服務的平滑升級，可以將API的版本號放入URL，也可以將版本號放在HTTP頭資訊中，但不如放入URL方便和直觀。Github採用這種做法。
https://api.example.com/v1/
2.5、複數名詞路徑
在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與資料庫的表格名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用複數。
https://api.example.com/v1/employees
2.6、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.7、過濾資訊
請求資訊應該為集合提供過濾、排序、選擇和分頁等功能
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.8、返回結果為統一的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.9、返回結果應該包含狀態碼
常見狀態碼，Http1.1協議完整狀態碼定義參考地址：
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
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.10、返回結果中提供幫助連結
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.11、API擴充套件事項
1）RESTful API依託PaaS平臺治理，需要對API進行認證、授權、引數加密等操作，可考慮在HTTP頭部加認證token、呼叫鏈指令、狀態資訊等系列資訊。
2）如PPT所言，API分層，會有內部API和外部API之分，兩種API的設計或有不同（甚至是不同協議）。
3）對於API設計的狀態選擇，建議為無狀態、N次冪等，但後續或存在效能優化問題，http2.0待評測。