Web API規範設計指引

關於RESTful

應認真考慮要不要使用RESTful規範，不要盲目跟風。它的缺點在小公司里特別明顯：

高度抽象，需要一定的設計能力。初級程序員很容易破壞整體設計，這不可能都被Review到。介面使用者也未必能做好反饋

需要對HTTP協議有一定的理解

一般越好的設計就有越多的約束，也可能有越高複雜度，因此交接工作的學習成本高

產品迭代很快時，介面可能變動很頻繁導致版本升級也很快，各種為了好設計而花費的時間都失去意義

不針對業務，複雜場景需要多次請求

如果確定使用，可以參考Github上這兩個最多star的規範

https://github.com/OAI/OpenAPI-Specification

https://github.com/interagent/http-api-design

文檔系統

無論是獨立的wiki還是整合在網關係統中，文檔系統都應該支持全局模糊搜索。

文檔有3種，全局設計規範、API參考手冊、文檔系統本身的使用指南。

其中，參考手冊的每個API說明應包括這些信息：

URL

method

傳參方式（URL query、HTTP header、body）

請求與響應的參數表

參數名

類型（string、array、object、int、float、bool）

是否必填，必填時的默認值

說明：中文名稱、功能意義、取值範圍。至少要能看出對應需求文檔或UI稿的哪個東西

可能的錯誤碼與錯誤信息

示例

全局規範

URL格式

大小寫和連接符的規範應該全局統一：snake_case或者camelCase。一般snake_case會更像普通的web URL。

如果使用RESTful，URL格式可以是

https://api.example.com/{service_name}/{version}/{api_name}?{filters}

或

https://www.example.com/api/{service_name}/{version}/{api_name}?{filters}。

header

如果不用RESTful，最好也不要把參數放到header里，盡量在HTTP協議框架內實現業務。在此前提下，如果存在（所有介面都需要的）公共參數，可以放在URL query里；或者最方便地使所有介面的method都是POST然後放body里。

JSON格式的Content-Type是application/json。如果進行了加密或BASE64轉碼，正確的Content-Type應該是text/plain。

如有必要，可進一步指定編碼：application/json;charset=utf-8。

業務參數

（以下討論的是放在body里的JSON。）

各個key的大小寫和連接符的規範應該全局統一：snake_case或者camelCase。

必填參數應該約定默認值。如不指定，可認為各類型的默認值是0、0.0、{}、[]、""、false，決不能是null或undefined。

非必填參數有3種風格，應該選定一種全局統一：

不存在這個key

value是null

value是undefined

非必填參數不允許是這個參數類型的默認值（0、0.0、{}、[]、""、false）

值是數字就用數字類型，不要用字元串。

布爾類型用JSON的語義true/false來表示，不要用1/0。

值為枚舉時，盡量用字元串表示而不是用數字。犧牲一點點性能但可以大大增強代碼可讀性。

// 直接把枚舉value寫成字元串更便於開發維護

type: "duck",

type: "chicken"

// 「用數字表示然後在文檔中詳細說明」可讀性差，通常不會有人把文檔複製成代碼注釋

type: 1, // duck

type: 2 // chicken

1

2

3

4

5

6

盡量不要為前端做格式化。例如時間，應返回「1970年1月1日0點至今的秒數」或者「按ISO8601進行格式化的UTC（世界標準時間）時間」，而不是直接返回「2018年11月11日 23:22:33」。讓大前端自己做格式化能更好應對UI變化以及兼容特殊要求。比如客戶端從中文切換成英文，界面上的「5月6日」需要變成「May 6th」；這種場景下如果是後端傳的「5月6日」，那無論是再次請求英文還是客戶端自行解釋時間後做轉換都是糟糕的設計。

保證向後兼容的前提下及時刪除廢棄的參數或介面。可以先對參數或介面標記Deprecated，在前端發布後或客戶端強制升級後刪除。

同一意義的欄位名，在不同介面返回的命名統一。不要這邊叫「page_count」，那邊叫「page_size」或"page_amount"。

響應體

較常見的JSON結構是這樣的：

{

"status": 0,

"message": "",

"data": {}

}

1

2

3

4

5

status：0表示正常/成功，非0代表錯誤碼。

message：表示錯誤信息。

data：業務數據

其中，錯誤碼和錯誤信息也可以設計一份全局統一的對照表。

如果不用考慮多語言，message錯誤信息可以是面向用戶的中文語句，由前端/客戶端直接toast告知用戶。

分頁設計

請求參數應包含：

當前頁碼

每頁條數

（可選）排序

響應參數應包含：

（可選）當前頁碼

（可選）每頁條數

（可選）排序

數據數組

總頁數或總條數，或是否還有下一頁。總之不要讓使用者再請求一次才知道沒有更多數據了。

組合請求

為了減少請求數，後端可提供組合請求介面，並且可組合任意介面。以下設計僅是舉例：

假如有3個介面（示例的響應體經簡化僅保留data）：

/a：請求{"a": "a"}會響應{"data": {"d": "d"}}

/b：請求{"b": "b"}會響應{"data": {"e": "e"}}

/c：請求{"c": "c"}會響應{"data": {"f": "f"}}

增加一個介面/combo可以一次性獲取這3個介面的數據：

// 請求

{

"api": {

"/a": {"a": "a"},

"/b": {"b": "b"},

"/c": {"c": "c"}

}

}

// 響應

{

"data": {

"/a": {"data": {"d": "d"}},

"/b": {"data": {"e": "e"}},

"/c": {"data": {"f": "f"}}

}

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

防攻擊

加密機制。可對body做加密，使用AES、DES、3DES、RSA、DSA、ECC等演算法。一般會對密文做BASE64轉碼再在網路上傳輸。

校驗機制，防篡改。對body做簽名，可使用MD5、SHA1、HMAC等演算法。簽名只能放在URL query或HTTP header中。

防重放機制。可使用timestamp、nonce等機制，在一定時間內重複即認為是重放。

最好在測試環境能通過參數控制上述機制的開關，方便調試、測試。

---------------------

作者：hursing

原文：https://blog.csdn.net/hursing/article/details/85247530

版權聲明：本文為博主原創文章，轉載請附上博文鏈接！

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！