建設目標
平臺介面建設規范旨在為介面開發、測驗、使用劃定一個框架邊界，明確技術目標與要求，并要求提供完備的介面檔案說明，為自有平臺與第三方平臺提供資料及服務支持，
建設標準
介面規范
命名規范
在標準的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中添加版本號，比如https://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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功，
介面檔案
檔案作為介面建設中的一個非常重要的指標必須予以足夠的重視，如果介面本身的設計與開發需要考慮技術與業務的實際情況，那么檔案的編制完全是團隊素質的體現，所以說檔案完備性也是衡量技術成熟型的一個重要標準，
無論是線上檔案還是線下檔案，內容務必完整詳實，特別是要站在檔案使用者的角度，對一些關鍵點進行說明，便于理解，
實時推送
針對實時性較強的資料，建議通過佇列方式分用戶、分權限向呼叫方實時推送資料，建設資料推送服務，
總結
介面設計的規范一方面既是軟體系統工程化、標準化的體現，另一方面也是前人經驗的總結匯總，必然會帶著一定的主觀性，而在實際介面設計開發當中，小的系統追求快速落地，可能無法完全匹配標準，大平臺場景復雜，標準也相應比以上規范要更加繁多，所以各位見仁見智，根據實際情況綜合考慮，技術層面力爭做到嚴謹 ，務實， 精進，
希望本文對大家能有所幫助，其中如有不足與不正確的地方還望指正與海涵，十分感謝，
關注微信公眾號，查看更多技術文章，
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/468723.html
標籤：Java
上一篇：maven依賴的詳解說明
下一篇：CAS入門實戰(1)--簡介