建設目標

平台介面建設規範旨在為介面開發、測試、使用劃定一個框架邊界，明確技術目標與要求，並要求提供完備的介面文檔說明，為自有平台與第三方平台提供數據及服務支援。

建設標準

介面規範

命名規範

在標準的RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞。

根據觀察大多數平台在介面設計當中，都無法完全按照此規範，這裡我的建議是無論介面命名還是參數命名必須基於業務與理解需要進行合理設計，確保簡潔務實、便於理解。

冪等性

冪等性是指任意多次請求的執行結果和一次請求的執行結果所產生的影響相同。查詢操作無論查詢多少次都不會影響數據本身，因此查詢操作本身就是冪等的。但是新增操作，每執行一次資料庫就會發生變化，所以它是非冪等的。

關於冪等性的實現方式有很多種，比如前端禁用、參數傳入唯一Key值或者先查詢後操作等，這裡不做詳細概述。一般來說介面中新增操作、部分帶條件的刪除和修改操作都是要考慮冪等性的，這也是保證數據一致性和安全性的必要措施。

請求方式

• • GET請求：查詢數據
• • POST請求：新增數據
• • PUT請求：更新數據，調用者提供完整數據，要求冪等性
• • DELETE請求： 刪除數據，要求冪等性
• • PATCH（UPDATE）請求：更新數據，調用者提供需改變數據

這裡建議介面建設中最少支援GET、POST、DELETE三種請求方式，對應查詢、新增/編輯、刪除三大類操作。如存在PUT、DELETE請求方式的介面需要保證冪等性。

安全規範

傳輸加密

• • HTTPS

條件允許情況下服務盡量啟用HTTPS

• • 帳號密碼

登錄認證時對帳號密碼進行加密，建議採用「 RSA 」非對稱加密，非對稱加密演算法有兩個密鑰，這兩個密鑰完全不同但又完全匹配。只有使用匹配的一對公鑰和私鑰，才能完成對明文的加密和解密過程。

登錄認證

• • 認證方式

Bear Token https請求header裡面放Authorization ，具備時效性；

• • 登錄防護

連續登錄失敗一定次數應拒絕響應一段時間；

介面日誌

• • 使用AOP全局記錄請求日誌，便於定位與追溯異常請求，排查問題原因。
• • 日誌必須包含調用帳號、調用介面、傳入參數、調用時間等關鍵資訊。返回數據可以只記錄異常情況。
• • 日誌非同步存儲，避免影響介面性能；

數據脫敏

• • 數據加密

在介面調用過程中，可能會涉及到位置、金額、個人資訊等敏感數據，需對這類數據進行加密脫敏處理。 建議也採用 RSA 」非對稱加密

• • 數據屏蔽

盡量不要在介面中返回不必要的數據，如ID、編號等敏感資訊

黑白名單

• • 可針對IP對介面的訪問許可權進行限制。這樣就能避免其他ip進行訪問攻擊；
• • 具備針對IP、帳號的封禁功能；

IP限流

服務平台應實現基於IP的限流功能, 如每秒並發請求不高於1000次；

防重放

除登錄介面外,其他請求除包含頭部token外，應包含timestamp 時間戳,nonce 隨機數、signature簽名等三個參數；服務平台將token、timestamp、nonce三個參數進行字典序排序 ,將三個參數字元串拼接成一個字元串進行數字簽名加密, 伺服器將加密後的字元串與signature對比，標識該請求來源於特定用戶。

這裡建議針對業務敏感類介面，如涉及數據修改、設備操作等介面增加防重放機制，一方面既不提高常規介面調用的複雜性，另一方面對安全風險較大的介面進一步加固，保持業務與技術層面的平衡。

版本控制

如果涉及版本區分問題，可在介面中設計版本號標識

• • 一種方式是在URL中添加版本號，比如//api/v1。
• • 另一種是將版本加到header中。

數據規範

統一響應數據格式

以統一的JSON格式返回數據

{
        "code": 200, //返回狀態碼;
        "msg": "成功",  //成功：無數據或成功資訊;失敗：失敗資訊
        "data": {}      //成功：數據實體失敗：無數據
}

統一響應狀態碼

這裡需要區分介面狀態碼與HTTP狀態碼的區別

介面狀態碼盡量設計的清晰統一，如用1或200代表介面調用成功，正常返回數據，其他視為調用異常，異常資訊通過《附錄狀態表》 進行說明，一般情況下你只需要定義好平台介面返回狀態碼即可。

HTTP狀態碼則是代表伺服器向用戶返回的狀態碼和提示資訊。含義如下：

• • 200 OK - [GET]：伺服器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
• • 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
• • 202 Accepted - [*]：表示一個請求已經進入後台排隊（非同步任務）
• • 204 NO CONTENT - [DELETE]：用戶刪除數據成功。
• • 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，伺服器沒有進行新建或修改數據的操作，該操作是冪等的。
• • 401 Unauthorized - [*]：表示用戶沒有許可權（令牌、用戶名、密碼錯誤）。
• • 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。
• • 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是冪等的。
• • 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。
• • 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。
• • 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。
• • 500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，用戶將無法判斷發出的請求是否成功。

介面文檔

文檔作為介面建設中的一個非常重要的指標必須予以足夠的重視，如果介面本身的設計與開發需要考慮技術與業務的實際情況，那麼文檔的編製完全是團隊素質的體現，所以說文檔完備性也是衡量技術成熟型的一個重要標準。

無論是線上文檔還是線下文檔，內容務必完整詳實，特別是要站在文檔使用者的角度，對一些關鍵點進行說明，便於理解。

實時推送

針對實時性較強的數據，建議通過隊列方式分用戶、分許可權向調用方實時推送數據，建設數據推送服務。

總結

介面設計的規範一方面既是軟體系統工程化、標準化的體現，另一方面也是前人經驗的總結匯總，必然會帶著一定的主觀性。而在實際介面設計開發當中，小的系統追求快速落地，可能無法完全匹配標準。大平台場景複雜，標準也相應比以上規範要更加繁多。所以各位見仁見智，根據實際情況綜合考慮，技術層面力爭做到嚴謹 ，務實， 精進。

希望本文對大家能有所幫助，其中如有不足與不正確的地方還望指正與海涵，十分感謝。

  關注微信公眾號，查看更多技術文章。