介面文件設計的12個注意點

前言

大家,我是田螺。

我們做後端開發的,經常需要定義介面文件。

最近在做介面文件評審的時候，發現一個小夥伴定義的出參是個列舉值，但是介面文件沒有給出對應具體的列舉值。其實，如何寫好介面文件，真的很重要。今天田螺哥，給你帶來介面文件設計的12個注意點~

1. 你的介面名稱是否清晰？

換句話說，你的介面是做什麼的，是否易懂清晰？一般介面url也要求能看得出介面的作用。比如說，查詢使用者資訊（queryUserInfo），就是一個不錯的介面名稱。

2. 你的介面地址是否完整

介面的地址，也叫介面的URL地址。即別人呼叫你的介面，用的是什麼URL。比如/api/user/queryUserInfo就是一個介面地址。但是，我想說的是，這還不是一個完整的介面地址。你的介面是不是HTTP呼叫呢？

如果是HTTP呼叫的話，域名是什麼呢？埠呢。一個好的http介面地址，應當是這樣的：

https//tianluo.com:15000/api/user/queryUserInfo

3.你的介面請求方式是否正確

介面請求方式通常有以下幾種：

• GET：從伺服器獲取資源，可以在URL中傳遞引數，通常用於查詢資料。
• POST：向伺服器提交資料，通常用於新增、修改、刪除等操作。
• PUT：向伺服器更新資源，通常用於更新資料。
• DELETE：從伺服器刪除資源，通常用於刪除資料。
• PATCH：向伺服器區域性更新資源，通常用於修改部分資料。
• HEAD：類似於GET請求，但是隻返回響應頭，不返回實體內容，通常用於獲取資源的元資訊。
• OPTIONS：請求伺服器返回支援的請求方式等資訊，通常用於客戶端與服務端協商請求方式。

你定義介面文件的時候，需要寫清楚，你的介面請求方式是哪一個？一般情況下，我們用POST和GET比較多。也有些公司的所有介面都用POST請求。

4.請求引數的8大要素

我們定義介面的時候,請求引數是最主要的部分之一。一份合格的介面文件,請求引數應當包含這八大要素:

• 引數名: 引數的名字,都是駝峰命名，比如userId。
• 型別: 引數的型別,比如String、Integer等。
• 是否必填: 請求引數是不是必填的，如果要求必填的，當上遊不傳這個引數的時候，應當拋引數校驗異常。
• 預設值: 如果這個引數不傳，是否有預設值，預設值是多少。
• 取值範圍: 如果是Long，Integer等數值型別的話，這個就是一個範圍值，比如1~10，如果是列舉值的話，那就是列舉範圍，比如ACTIVE、INACTIVE。
• 引數格式：比如你的引數是個日期的話，就需要說明引數格式，如yyyyMMdd
• 入參示例值: 提供該響應引數的示例值，以便開發人員更好地理解和使用該引數。
• 備註: 如果這個入參欄位有特殊說明的話，可以在這一欄說明。如果沒有特殊說明，那隻描述這個引數作用也可以。

以下就是入參的文件樣例：

5.響應引數的7大要求

響應引數其實跟入參差不多，有7種要素：

• 引數名稱：描述該響應引數的名稱。
• 引數型別：描述該響應引數的資料型別，如String、Integer等。
• 引數格式：描述該響應引數的資料格式，如yyyy-MM-dd、HH:mm:ss等。
• 引數說明：對該響應引數的含義進行詳細的描述。
• 取值範圍：描述該響應引數的取值範圍，如整數範圍、字串長度等。
• 是否必填：描述該響應引數是否為必填項。
• 示例值：提供該響應引數的示例值，以便開發人員更好地理解和使用該引數。

不一樣的地方是，響應引數，一般都是按照code，msg，data的格式返回的：

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

6. 介面錯誤碼

一份好的介面文件，一定少不了錯誤碼列舉。一般錯誤碼定義包括三列：錯誤碼、錯誤碼資訊、含義

7.介面安全

定義介面文件時，對於一些需要保護的介面，也需要考慮介面的安全，例如許可權管理、防止 SQL 注入等。

因此，介面文件應當包含介面的安全性說明：例如介面的訪問授權方式、資料傳輸加密方式等。此外，介面文件還應該對於敏感資料和操作進行標註，方便使用者注意隱私和安全問題。

8. 介面版本管理

在介面文件定義時，介面版本管理是非常重要的一個方面。由於軟體專案的迭代和升級，介面可能會隨著版本的變化而發生變化。為了避免介面變化給使用者帶來不必要的困擾，需要對介面進行版本管理。

以下是一些常用的介面版本管理方法：

• 在介面文件中明確版本號：在介面文件中明確標識介面的版本號，例如在介面地址中新增版本號資訊，如，表示該介面的版本號為v1。
• 使用語義化版本號：採用語義化版本號（Semantic Versioning）規範，即版本號格式為X.Y.Z，其中X表示主版本號、Y表示次版本號、Z表示修訂號。當進行相容性變更時，需升級主版本號；當增加功能且不影響現有功能時，需升級次版本號；當進行bug修復或小功能改進時，需升級修訂號。
• 增量釋出：在介面發生變化時，先發布新版本的介面，同時保留舊版本的介面。使用者可以根據自己的需求來選擇使用哪個版本的介面。隨著新版本的介面逐步替換舊版本的介面，最終可以將舊版本的介面廢棄。

無論採用何種方法，介面版本管理都應該得到充分的考慮。在介面版本變化時，需要及時更新介面文件（詳細描述版本的變化、相容性問題、版本切換方式等），以確保使用者能夠獲得最新的介面資訊。

9. 維護介面文件更新迭代

如果介面發生了變更，比如引數有哪些變更，錯誤碼變更等等，都需要維護到文件上。同時需要登記變更的記錄。

10.明確請求頭有哪些

介面文件，是需要寫清楚的請求頭的。介面文件的請求頭可以看到以下的資訊：

• Content-Type：指定請求體的資料格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用於身份驗證的令牌資訊，如Token、Bearer等。
• Accept：指定客戶端可以接受的響應資料格式，如application/json、text/html等。
• User-Agent：指定客戶端的型別和版本資訊，可以用於服務端進行針對性最佳化。
• Accept-Encoding：指定客戶端可以接受的資料壓縮格式，如gzip、deflate等。
• Cache-Control：指定客戶端快取的策略，如no-cache、max-age等。
• Cookie：包含客戶端傳送給伺服器的cookie資訊。

這是是一個介面文件的請求頭的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: 
Origin: 
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 介面請求示例

介面文件，需要提供介面的使用案例：以方便開發者理解介面的使用方法和呼叫流程。

12. 介面測試

一般來說，介面文件需要完善：介面測試的方法和測試結果，以便使用者可以測試介面是否符合自己的需求，讓使用者用得放心~哈哈