[case20]聊聊rest api設計

序

本文主要研究下rest api的設計。

設計準則

• easy to use & hard to misuse

易用不易誤用，也就是api設計不要太複雜，要簡單易用，並且還不能容易用錯。

• least astonishment

簡單就好，不要試圖提供其餘花哨、華麗的額外功能，好比對於時間相似的字符串參數，規定好一個輸入格式便可，不要試圖同時兼容多種格式輸入。

• use case & document story

api文檔要圍繞story或者use case來進行，在一個業務場景下提供完整的閉環操做。

輸入規範

• url中的路徑

避免駝峯，避免下劃線，優先採用橫槓

• request method

post表示新增( url中沒有id)，delete表示刪除，get表示查詢，put表示全量更新( 冪等操做)，post url中攜帶id也可用於表示更新。

• 分頁

好比page及size，或者limit及offset

• 排序

好比sort=+field2,-field2，用逗號分隔多個排序字段，用+表示升序，用-表示降序

• 字段過濾

好比fields=field1,field2,field3

• 複雜查詢

簡單的好比用eq表明等，lt表明小於，lte表明小於等於，gt表明大於，gte表明大於等於，like表明模糊查詢；更復雜的話，能夠參考rsql規範。

• 版本

不建議版本化，建議採用新的領域命名才與原有的api區分開來

輸出規範

• 返回碼

遵循http的返回碼規範，4xx表示客戶端錯誤，5xx表示服務端錯誤。

• 返回jsonObject而不是jsonArray

頂層結構返回jsonArray的話，就不容易擴展了。通常返回jsonObject，一般會攜帶code，error之類的

• 返回jsonObject的字段

success表示請求是否成功，data表示數據，msg表示消息描述，error描述錯誤信息詳情。

• 錯誤信息格式

type表示錯誤異常類型，code表示錯誤編號用於個性化錯誤提示，msg用於錯誤信息描述，link提供該錯誤信息的具體描述頁面

安全相關

• 調用方鑑權

對於api的消費者，要求調用的時候強制提供appId及appKey，用於最基本的調用源的鑑權

• 細粒度鑑權

對於更細粒度的數據權限控制，要細化到url及requestMethod基本

• 參數校驗

對於查詢、修改等參數要作基本校驗，對參數內容進行非法參數過濾。

• 屏蔽錯誤堆棧

不要暴露後端的錯誤堆棧，若是是要方便排查問題，能夠設置一個開關，來設置是否屏蔽錯誤堆棧

• 敏感數據脫敏

對於敏感的數據，要適當作一些脫敏處理，好比身份證號，手機號等。在真正須要真實數據的話，須要額外進行請求。

• 帳號密碼須要加密

登錄接口必須走https，並且必需要有圖形驗證碼，並且還必須防暴力破解，有錯誤鎖定機制，對於密碼的傳遞，必須加密處理

• 防止id遍歷問題

對於url的參數，若是id是遞增的，則須要處理遍歷問題，要麼對外暴露通過處理後的id，要麼作數據權限控制

• 防止token replay

對於token要有必定的失效機制，另外建議token對url參數進行簽名

• 防止文件下載目錄遍歷

對於提供文件下載的接口，必定要避免目錄遍歷問題

服務質量保障

• 提供SLA
• 提供流量管理、熔斷、限流
• 提供服務擴容機制
• 提供故障演練
• 提供審計功能
• 監控異常流量
• 提供調用方間的隔離

小結

rest api的設計牽扯的方面比較多，本文暫時只是先列了一些，後續有待補充。

doc

• API設計要點
• 聊聊jpa的動態查詢
• 使用RSQL實現端到端的動態查詢