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