1 後端接口開發規範
1.1 開發原則
-
自頂向下的設計原則：功能應該從表現層分析再到控制層、服務層、持久層逐層設計
-
自底向上的開發原則：上層需調用下層，因此開發應從底層向上層逐層開發
項目中開發的層次次序參考DB->中間件->持久層->服務層->控制層
-
單一職責的開發原則：類或者方法提供的功能應該單一明確，特別越底層越應單一職責，以便維護
項目中Mapper方法必須功能單一，參數明確，拒絕兩種以上的持久邏輯使用同一個Mapper方法
-
依賴倒置的開發原則：上層依賴下層，是依賴下層接口，並不是依賴下層的實現
項目中每層都是通過接口調用Controller->Service->Mapper
1.2 開發步驟
- 明確類定義：明確哪些是重用類，哪些是需要新增的類
- 明確主鍵規則：確認操作表的ID生成規則，是Mycat主鍵，還是Zk主鍵
- Mapper實現：查、改、刪時注意是否使用mycat註解確認DN，插入時是否要插入主鍵id
- Service實現：可用通過時序圖幫助我們梳理實現邏輯
- ControllerApi定義
- Controller實現：簡單的Service層調用
- 單元測試
1.2 接口版本規範說明
隨着業務的複雜，同一個接口可能出現多個版本，爲了方便後期切換和AB測試，需要定義接口的版本號
-
在某一個微服務下訪問controller的時候在包名下加一個版本號,如下
com.jigeyin.article.controller.v1 -
在訪問具體的接口方法的url映射的時候也應該加上版本說明，如下：
@RequestMapping("/api/v1/article")
2.3 接口通用規範
| ID混淆 | 請求和響應的連續增長的ID需要經過混淆加密 |
|---|---|
| Date數化 | 請求和響應的的時間字段，統一轉換成13位時間戳 |
| 字符編碼 | 請求和響應的內容字符集爲UTF-8 |
| 支持多格式 | 響應結果支持JSON和XML，可通過Header Accept設置 |
| URL格式 | Url爲全小寫字符，多個單詞用下劃線分隔 |
| token | 請求頭中存放當前用戶的請求token（JWT格式） |
| t | 請求頭中存放當前請求的時間，用於基本的請求時效判斷 |
| md | 請求頭中存放當前請求的參數驗簽字符串（查詢串排序MD5加密） |
| 響應格式 | 響應格式只接受ResponseResult，code碼需定義在AppHttpCodeEnum |