11條軍規，讓你的介面設計無可挑剔

作為後端工程師，多數情況都是給別人提供介面，寫的好不好使你得重視起來。

最近我手頭一些活，需要和外部公司對接，我們需要提供一個介面文檔，這樣可以節省雙方時間、也可以防止後續扯皮。這是就要考驗我的介面是否規範化。

1. 介面名稱清晰、明確

顧名思義，介面是做什麼的，是否準確、清晰？讓使用這一眼就能知道這個介面在做什麼，力求言簡意賅。比如：查詢用戶信息，簡單明瞭。

2. 介面路徑規整

介面地址，也就是介面的 URL 路徑。當別人調用你的介面，就是通過 URL 配合請求時參數來調用。比如： /api/user/queryById 。一般來說，介面地址的命名也要可以大概看出介面的作用，比如前面這個介面，它是作用使用：通過用戶id查詢用戶信息。

除了介面路徑，還需要指明介面的功能變數名稱或IP。以 http 協議為例、埠是 8080，當我請求 javapub 的用戶中心信息時：

https://javapub.net.cn:8080/api/user/queryById

3. 請求方式規範

請求方式常用的有如下幾種：

• GET（SELECT）：從伺服器取出資源，通常用於查詢數據（一項或多項）。
• POST（CREATE）：在伺服器新建一個資源，通常用在新增、修改、刪除操作。
• PUT（UPDATE）：在伺服器更新資源，通常用於更新數據（客戶端提供改變後的完整資源）。
• PATCH（UPDATE）：在伺服器更新資源，通常用於修改部分數據（客戶端提供改變的屬性）。
• DELETE（DELETE）：從伺服器刪除資源，通常用於刪除數據。

這麼多請求方式，多數中小公司只用 GET 和 POST，可能還有些公司只用 POST。但是選擇合適的請求方式可以提升開發效率、並且讓我們的介面更容易復用。

不管用哪種，一定要寫清楚。

4. 介面詳細說明

如果是非常簡單的介面，通過介面名就可以瞭解個大概。如果是一些非常複雜的介面，就一定要添加詳細說明文檔，包括功能描述、請求參數、請求相應參數等信息。

力求言簡意賅，通過入參、做了什麼動作、返回哪些值。

5. 編寫介面請求示例

介面文檔需要提供介面示例，介面實例是為了幫助調用者理解介面的使用方法和調用流程，快速開始調試程式。一般是 CURL 格式的示例。

curl javapub.net.cn

6. 引入介面版本管理

隨著功能開發的日趨完善，可能對介面做出修改更新，例如添加、刪除時變更參數，或者修改返回值的格式。這些新變更可能影響用戶的 API 使用體驗，造成現有客戶端無法使用。

https://javapub.net.cn:8080/api/user/v1/queryById

https://javapub.net.cn:8080/api/user/v2/queryById

7. 維護介面文檔版本更新

如果介面發生了變更，介面文檔也要做出相應調整，維護文檔。比如錯誤碼更新、參數類型變更等，要明確記錄。

8. 明確請求頭有哪些

介面文檔，要寫清楚請求頭信息，比如：有許可權校驗的介面請求，在請求頭中 apiKey。還有一些參數是 JSON 的，要設置 application/json。

• Accept：指定客戶端能夠接收的內容類型，如：Accept: text/plain, text/html。
• Authorization：一般存放令牌信息，如：Authorization: Basic QzPhZGRpbjpvcGVuIHNlc2FtZQ==
• Cookie：存放 Cookie 信息。
• User-Agent：指定客戶端信息，作為服務端處理時定製化。
• Accept-Encoding：指定客戶端允許的數據壓縮格式，如 gzip、deflate 等。

9. 介面安全

有些介面參數涉及到隱私和敏感數據、需要參數加密做好脫敏處理和說明。此外，還要做好介面授權訪問，防止出現拖庫、擊穿等P0問題。

10. 介面測試

在編寫介面文檔時，編寫測試案例也要給出測試數據，包括請求參數和返回結果。讓調用者有一個預期，節省溝通成本。

11. 定義錯誤碼

介面文檔，一定要錯誤碼，錯誤碼作為程式重要的參考，讓下游知道什麼時候做什麼動作。比如：當查詢不到用戶信息時，可以提示它跳轉到註冊頁面。