前言

實(shí)際工作中，我們經(jīng)常需要和第三方平臺打交道，可能要開放一個 API 給他人調(diào)用。 那么問題來了：怎樣做出一個優(yōu)雅的 API 接口？ 協(xié)議

API 一般使用的是 Http 協(xié)議，也可以和他人約定一種調(diào)用協(xié)議，但通常使用 Http 即可。 請求方法

API 的請求方法不像平時(shí)使用 Get，通常還可以使用 Post。Get 的請求參數(shù)在 URL 或請求頭部中，而 Post 的請求參數(shù)一般在請求正文中。 如果請求不帶參數(shù)或參數(shù)不敏感，可以使用 Get；否則盡量使用 Post。 請求 URI

URI 一般遵循駝峰命名法，例如：/v1/app/getUniqueAddress。強(qiáng)烈建議將主要版本號添加在 URI 前端，例如 /v1，能在重大更新時(shí)保證接口不出錯。 在 URI 命名中，盡量縮短其長度，避免意外錯誤。例如，App 相關(guān)的接口需要使用 app 而不是 application。 加密

雙方可以約定一個加密算法和一個密鑰，且加密密鑰最好不要和其它密鑰重復(fù)。 注意：Base64 是編碼算法，不是加密算法，出了問題別來找我！ 簽名

在 API 調(diào)用中，為了防止數(shù)據(jù)被篡改或被惡意利用，需要對請求進(jìn)行校驗(yàn)。 可以計(jì)算請求參數(shù)、時(shí)間戳、密鑰的摘要，加在請求頭的末尾；服務(wù)器收到后，將同樣的數(shù)據(jù)計(jì)算摘要，然后比對這些摘要，如果不相同，直接在網(wǎng)關(guān)返回錯誤。 請求應(yīng)當(dāng)設(shè)置一個過期時(shí)間，例如 5 分鐘或 10 分鐘。 密鑰可以讓雙方約定私鑰，然后計(jì)算一個 UUID 作為 Key，私鑰作為 Value 保存在服務(wù)器網(wǎng)關(guān)中，請求中帶上這個 UUID，計(jì)算摘要時(shí)使用對應(yīng)的私鑰。服務(wù)器便可以通過 UUID 查到對應(yīng)的私鑰，然后進(jìn)行比對。 也可以將加密密鑰保存到對應(yīng) UUID 下。 IP 白名單

IP 查驗(yàn)也可以做在網(wǎng)關(guān)上，如果 IP 在白名單上即可調(diào)用，否則直接返回?zé)o權(quán)限。 限流

限流方式（包括但不限于）以下幾種： 1. 限制同一 IP 對所有接口的調(diào)用頻率，例如：同一 IP 每分鐘對所有接口最多調(diào)用 3w 次。 2. 限制同一 IP 對單個接口的調(diào)用頻率，例如：同一 IP 每分鐘對單個接口最多調(diào)用 1w 次。 3. 限制同一個私鑰對所有/單個接口的調(diào)用頻率。 同樣做在網(wǎng)關(guān)上，如果網(wǎng)關(guān)發(fā)現(xiàn)調(diào)用頻率過高，則直接返回錯誤。 參數(shù)查驗(yàn)

在網(wǎng)關(guān)確認(rèn)請求有效后，會遞交處理程序進(jìn)行處理。處理程序要做的第一件事情就是參數(shù)查驗(yàn)，避免不必要的損失。 例如：消費(fèi)金額必須為非負(fù)數(shù)且僅允許兩位小數(shù)；身份證號必須為 18 位整數(shù)且校驗(yàn)碼準(zhǔn)確（校驗(yàn)碼算法在某度百科有）；（大陸）電話號碼必須為 11 位整數(shù)；郵政編碼必須為 6 位整數(shù)；姓名必須在兩位字符與六位字符之間；某字段長度不大于 128 位等。 否則想象一下，某人消費(fèi) -114 元，會是什么后果？數(shù)據(jù)庫直接把余額減去 -114，也就是加上 114 元！ 返回值

API 接口返回值首先要保證：狀態(tài)代碼的 Key 必須統(tǒng)一。 比方說，正常返回值為{"code": 0, "message": "……"}，錯誤返回值就應(yīng)該是{"code": XXX, "message": ……}，Key 絕對不能更改。 最容易出現(xiàn)的問題就是：處理程序的錯誤和網(wǎng)關(guān)的錯誤不統(tǒng)一，導(dǎo)致調(diào)用方無法理解。 錯誤處理

如果處理中出現(xiàn)了 Exception，或者服務(wù)器內(nèi)部錯誤，應(yīng)該怎么返回？ 如果直接把 Exception 轉(zhuǎn)為 String，封裝發(fā)送，那么會有很多敏感信息，不法分子就可以利用。 因此，我們可以直接返回 Internal Server Error，讓調(diào)用方聯(lián)系處理。 日志記錄

收到請求之后，可以計(jì)算請求的摘要，然后建立新文件，記錄該請求的日志。 例如：某請求摘要為 3c1b2cca587f，那么日志文件就可以建立在 logs/3c/3c1b2cca587f.log 中。 請求參數(shù)也可以帶上一個 requestID，還能保證請求的冪等。 限制參數(shù)長度

為了保證接口的穩(wěn)定性，可以限制請求中參數(shù)的長度，超過長度直接返回錯誤。此處不再詳細(xì)說明。 異步處理

如果某接口的處理程序非常的復(fù)雜，那么就需要建立處理線程，然后進(jìn)行異步處理，避免接口卡死。 壓力測試

API 上線前，必須先進(jìn)行壓力測試，然后再確認(rèn)限流的閾值。一般限流閾值要略小于最大可承受壓力。 數(shù)據(jù)打碼

沒啥好說的，就是把敏感數(shù)據(jù)進(jìn)行處理，例如電話號碼 114*****514，身份證號 11451**********514，不法分子即使拿到了也 p 用沒有。 處理流程總結(jié)

網(wǎng)關(guān)：收到請求 => 校驗(yàn) IP?=>?確認(rèn)流量（限流）?=>?簽名校驗(yàn)?=>?參數(shù)校驗(yàn)?=>?解密請求參數(shù) => 遞交處理程序 處理程序：建立處理線程?=>?按照處理流程進(jìn)行處理?=>?記錄日志 => 將處理信息遞交網(wǎng)關(guān) 網(wǎng)關(guān)：刪除隱私信息?=>?數(shù)據(jù)打碼?=>?生成響應(yīng)?=>?返回響應(yīng) 接口文檔

最后來到了最簡單，但也最重要的一部分：接口文檔。良好的文檔能夠減少很多溝通成本，建議使用 Markdown 編寫文檔。 文檔需要包括： 請求 URI；

請求方法；

Http 版本；

請求頭；

請求消息體；

返回格式；

加密規(guī)則；

簽名規(guī)則；

IP 白名單規(guī)則；

參數(shù)長度限制；

聯(lián)系方式；

協(xié)議。

文檔示例

協(xié)議

1. 本 API 為非開源項(xiàng)目； 2. API 內(nèi)所有文件歸本 API 所有； 3. 使用本 API，必須在用戶可視頁面注明 API 贊助鏈接； 4. API 為非開放性質(zhì)，必須進(jìn)行申請才可調(diào)用； 5. 禁止在本協(xié)議上二次封裝其它協(xié)議。 調(diào)用說明

普通用戶不能調(diào)用，需要提供 IP 地址等待審核。過審后，會提供加密密鑰、私鑰、UUID。聯(lián)系郵箱：someone@example.com。 基本信息

如無特殊說明，服務(wù)器使用 example.com，Http 端口 80，Https 端口 443。 摘要算法統(tǒng)一使用 MD5，時(shí)間戳使用 GMT 標(biāo)準(zhǔn)時(shí)間整形數(shù)值格式。 同一個 IP 請求頻率不能超過每分鐘 50000 次，請求參數(shù)長度不能超過 8192 字節(jié)。 Http 版本統(tǒng)一使用 HTTP/1.1，Http 頭 userUuid 為提供的 UUID。 加密說明：Http 消息體使用 Aes 加密，密鑰使用提供的加密密鑰。 簽名說明：1. 將請求報(bào)文的摘要、時(shí)間戳、提供的私鑰拼接為字符串，其間使用空格分割；2. 計(jì)算該字符串的摘要，作為請求頭 sign。 注冊

請求方法：POST URI：/v1/user/signup 請求頭 Content-Type：text/plain 請求消息體 Json 字段如下， email：string，注冊用戶的郵箱； username：string，注冊用戶的用戶名； password：string，注冊用戶的密碼； login：可選，boolean，是否立刻生成 Token，默認(rèn)為 true。 響應(yīng)如下， code：int，狀態(tài)代碼； message：string，錯誤說明； primaryToken：string，主令牌； accessToken：string，訪問令牌。 登錄

請求方法：POST URI：/v1/user/signin 請求頭 Content-Type：text/plain 請求如下， …… 總結(jié)

做好一個 API 接口，一是數(shù)據(jù)安全，二是服務(wù)器安全，三是提供數(shù)據(jù)準(zhǔn)確、高效，封裝良好的接口為他人調(diào)用。 做事都要做到安全第一，在安全條件下增加用戶體驗(yàn)。 這就是本期全部內(nèi)容了，我們下期再見。 字?jǐn)?shù)：3135