新入職程序員亂用RESTFul接口！總監：求求你，不懂別亂用了

分享阿里 P8 高級架構師吐血總結的 《Java 核心知識體系&面試資料.pdf》

據說是阿里 P8 級高級架構師吐血總結的一份 Java 核心知識.pdf, 內容覆蓋很廣，Java 核心基礎、Java 多線程、高併發、Spring、微服務、Netty 與 RPC、Zookeeper、Kafka、RabbitMQ、Habase、設計模式、負載均衡、分佈式緩存、Hadoop、Spark、Storm、雲計算等。

另外，附送 100G 學習、面試視頻文檔喲~

獲取方式：【關注 + 轉發】後，私信我，回覆關鍵字【資源】，即可免費無套路獲取哦~

以下是資源的部分目錄以及內容截圖：

重要的事再說一遍，獲取方式：【關注 + 轉發】後，私信我，回覆關鍵字【資源】，即可免費無套路獲取哦~

正文開始

RESTful 是目前最流行的 API 規範，適用於 Web 接口規範的設計。讓接口易讀，且含義清晰。本文將介紹如何設計易於理解和使用的 API，並且藉助 Docker api 的實踐說明。

URL 設計

1.1 動詞 + 賓語

它的核心思想就是客戶端發出的數據操作指令都是「動詞 + 賓語」的結構，比如 GET /articles這個命令，GET是動詞，/articles是賓語。

動詞通常來說就是五種 HTTP 方法，對應我們業務接口的 CRUD 操作。而賓語就是我們要操作的資源，可以理解成面向資源設計。我們所關注的數據就是資源。

• GET: 讀取資源
• POST：新建資源
• PUT：更新資源
• PATCH：資源部分數據更新
• DELETE：刪除資源

正確的例子

• GET /zoos：列出所有動物園
• POST /zoos：新建一個動物園
• GET /zoos/ID：獲取某個指定動物園的信息
• PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息）
• PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
• DELETE /zoos/ID：刪除某個動物園
• GET /zoos/ID/animals：列出某個指定動物園的所有動物
• DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

1.2 動詞的覆蓋

有些客戶端只能使用GET和POST這兩種方法。服務器必須接受 POST 模擬其他三個方法（PUT、PATCH、DELETE）。

這時，客戶端發出的 HTTP 請求，要加上 X-HTTP-Method-Override 屬性，告訴服務器應該使用哪一個動詞，覆蓋 POST 方法。

1.3 賓語必須是名詞

就是 API 的url ，是 HTTP 動詞作用的對象，所以應該是名詞。例如 /books 這個 URL 就是正確的，而下面的 URL 不是名詞，都是錯誤的寫法。

錯誤示範：

GET /getAllUsers?name=jl
POST /createUser
POST /deleteUSer
複製代碼

1.4 複數名詞

URL 是名詞，那麼是使用複數還是單數？

沒有統一的規定，但是我們通常操作的數據多數是一個集合，比如 GET /books ,所以我們就使用複數。

統一規範，建議都使用複數 URL， 比如 獲取 id = 2 的書 GET /books/2 要好於 GET /book/2。

1.5 避免出現多級 URL

有時候我們要操作的資源可能是有多個層級，因此很容易寫多級 URL，比如獲取某個作者某種分類的文章。

GET /authors/2/categories/2 獲取作者ID = 2 分類 = 2 的文章

這種 URL 不利於拓展，語義 也不清晰。

更好的方式就是 除了第一級，其他級別都是通過查詢字符串表達。

正確方式： GET /authors/12?categories=2

查詢已發佈的文章

錯誤 寫法： GET /artichels/published

正確寫法： GET /artichels?published=true

過濾信息（Filtering）

狀態碼如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

下面是一些常見的參數。

• ?limit=10：指定返回記錄的數量
• ?offset=10：指定返回記錄的開始位置。
• ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
• ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
• ?animal_type_id=1：指定篩選條件

參數的設計允許存在冗餘，即允許API路徑和URL參數偶爾有重複。比如，GET /zoo/ID/animals 與 GET /animals?zoo-id=ID 的含義是相同的。推薦後者，避免出現多級URL。

2.1 狀態碼必須精確

客戶端的請求，服務求都必須響應，包含 HTTP 狀態碼和數據。

HTTP 狀態碼就是一個三位數，分成五個類別。

• 1xx：相關信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客戶端錯誤
• 5xx：服務器錯誤

2.2 2xx 狀態碼

200狀態碼錶示操作成功，但是不同的方法可以返回更精確的狀態碼。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• PATCH: 200 OK
• DELETE: 204 No Content

2.3 4xx 狀態碼

4xx狀態碼錶示客戶端錯誤，主要有下面幾種。

• 400 Bad Request：服務器不理解客戶端的請求，未做任何處理。
• 401 Unauthorized：用戶未提供身份驗證憑據，或者沒有通過身份驗證。
• 403 Forbidden：用戶通過了身份驗證，但是不具有訪問資源所需的權限。
• 404 Not Found：所請求的資源不存在，或不可用。
• 405 Method Not Allowed：用戶已經通過身份驗證，但是所用的 HTTP 方法不在他的權限之內。
• 410 Gone：所請求的資源已從這個地址轉移，不再可用。
• 415 Unsupported Media Type：客戶端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。
• 422 Unprocessable Entity ：客戶端上傳的附件無法處理，導致請求失敗。
• 429 Too Many Requests：客戶端的請求次數超過限額。

2.4 5xx 狀態碼

5xx狀態碼錶示服務端錯誤。一般來說，API 不會向用戶透露服務器的詳細信息，所以只要兩個狀態碼就夠了。

• 500 Internal Server Error：客戶端請求有效，服務器處理時發生了意外。
• 503 Service Unavailable：服務器無法處理請求，一般用於網站維護狀態。

服務器響應

3.1 不要返回純文本

API 返回的數據格式，不應該是純文本，而應該是一個 JSON 對象，因為這樣才能返回標準的結構化數據。所以，服務器回應的 HTTP 頭的 Content-Type 屬性要設為 application/json 。

客戶端請求時，也要明確告訴服務器，可以接受 JSON 格式，即請求的 HTTP 頭的ACCEPT 屬性也要設成 application/json。下面是一個例子。

3.2 發生錯誤的時候，不要返回 200 狀態碼

有一種不恰當的做法是，即使發生錯誤，也返回200狀態碼，把錯誤信息放在數據體裡面，就像下面這樣。

錯誤例子：

HTTP/1.1 200 OK
ConteNTP-Type: application/json
{
\t"status": "fail",
\t"msg": "錯誤"
}
複製代碼

上面代碼中，解析數據體以後，才能得知操作失敗。

這張做法實際上取消了狀態碼，這是完全不可取的。正確的做法是，狀態碼反映發生的錯誤，具體的錯誤信息放在數據體裡面返回。下面是一個例子。

正確方式：

HTTP/1.1 400 Bad Request
ConteNTP-Type: application/json
{
\t"status": "fail",
\t"msg": "錯誤"
}
複製代碼

docker RESTful 規範解析

接下來我們分析 docker api 對於 restful 的使用，助於我們在實際工作中合理設計。

docker 文檔 url ：docs.docker.com/engine/api/…

4.1 GET 獲取容器列表

GET /v1.19/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1

通過 all=1&before=8dfafdbc3a40&size=1 過濾容器數據

4.2 GET 獲取指定ID或者名字容器

GET /containers/(id or name)/json

GET /v1.19/containers/4fa6e0f0c678/json HTTP/1.1

4.3 GET 獲取某個容器的進程

GET /v1.19/containers/4fa6e0f0c678/top HTTP/1.1

假如想過濾進程等可以通過查詢字符串實現

GET /v1.19/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1

返回的數據

HTTP/1.1 200 OK
Content-Type: application/json
{
 "Titles" : [
 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
 ]
 "Processes" : [
 [
 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
 ],
 [
 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
 ]
 ],
}
複製代碼

4.4 POST 創建容器

POST /containers/create

POST /v1.19/containers/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345
{
 "Hostname": "",
 "Domainname": "",
 "User": "",
 "AttachStdin": false,
 "AttachStdout": true,
 "AttachStderr": true,
 "Tty": false,
 "OpenStdin": false,
 "StdinOnce": false,
 "Env": [
 "FOO=bar",
 "BAZ=quux"
 ],
 "Cmd": [
 "date"
 ],
 "Entrypoint": null,
 "Image": "ubuntu",
 "Labels": {
 "com.example.vendor": "Acme",
 "com.example.license": "GPL",
 "com.example.version": "1.0"
 },
 "Volumes": { 

 "/volumes/data": {}
 }
 
 }
複製代碼

4.5 DELETE 刪除容器

根據容器 id 刪除一個容器，v是請求是否刪除 容器 volumes

DELETE /v1.19/containers/16253994b7c4?v=1 HTTP/1.1

Query parameters:

• v – 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false.
• force - 1/True/true or 0/False/false, Kill then remove the container. Default false.
• link - 1/True/true or 0/False/false, Remove the specified link associated to the container. Default false.