當邏輯錯誤時，返回 http code?400，body 體內是具體的錯誤原因，也可以加上自定義的狀態碼，解決了 http code 不能滿足業務狀態的需求 \### 接口命名規范 \*\*前端對接時如果發現后端提供的接口不符合規范有權拒接(包括后端對接爬蟲)，如接入了不符合規范的接口，需要及時整改\*\* 為了便于管理接口,我們將接口分為三類: 1\. `public`: 不用登錄即可訪問的資源,舉例:登錄接口 `https://api.buffdj.com/public/quick\_login` 2\. `api`: 需要用戶登錄才能進行訪問的接口,舉例:獲取用戶詳細信息接口: `https://api.buffdj.com/api/user/info?id=666` 3\. `rpc`: 微服務之間相互調用才能用的,外部不允許訪問.舉例: 調用pay 微服務的 pay 接口:`https://api.buffdj.com/rpc/service-pay/pay?param=666` \### Restful 風格的 API 1\. `get`:用于獲取資源 2\. `post`:用于提交新增一個資源 3\. `put`:用于修改一個資源 4\. `delete`:用于刪除一個資源 \*\*所有 API 返回值都必須是 application/json 形式，不允許字符串格式的返回值\*\* 詳細可參考 :\[如何向其他人解釋Restful\](http://www.jianshu.com/p/e77d2f60aa5d) 我們的接口規范如下: 1\. 獲取書籍列表: `GET /api/book?size=10&page=1` size 和 page為分頁參數 2\. 獲取書籍詳情: `GET /api/book/info?id=666` id 為要查詢的資源`主鍵` 其實`GET /api/books/{bookId}`才是最標準的 3\. 修改書籍信息: `PUT /api/book ?` ? ? body里邊放更新依據`主鍵 id`,以及其他參數 4\. 新增數據資源: `POST /api/book ? ` ? ?body里放主鍵之外的參數 5\. 刪除書籍資源: `DELETE /api/book?id=666` ?id 為要刪除的資源`主鍵` 不使用 PathVariable 的原因是由于 Spring Could 系列的監控、追蹤等軟件還不兼容，會認為 GET /api/book/1, GET /api/book/2 是不同的 URL，所以我們不使用它 ps:? 1\. 不要在路徑里使用動詞如: getXXX,queryXXX,findXXX,只需資源的名字即可,比如:獲取書籍封面`GET /api/book/cover`,因為請求方法`GET` 就已經表明當前是獲取資源而不是增加或者刪除 2\. 路徑統一使用小寫字母,多個單詞使用`\_`分割 \### ?Response Body 狀態碼規范 便于交流和協作,我們統一使用 HTTP 標準的狀態碼 \* 200:本次請求成功,服務器已返回正確的數據在 body 里 \* 4XX:出現業務邏輯異常或錯誤,包括:路徑錯誤,參數錯誤,具體信息會在response body 中展示 \* 5XX:這個是服務器出現了一些意料之外的錯誤 \*\*找不到數據,查詢數據結果為空的時候,需要返回404\*\* 狀態碼4xx,具體的Response Body 數據結構 ``` { ? "timestamp": 1512611487539, ? "status": 400, ? "error": "Bad Request", ? "exception": "org.springframework.web.bind.MethodArgumentNotValidException", ? "message": "Validation failed for object='person'. Error count: 1" } ``` \### 關于控制前端彈出信息相關規范 控制前端彈出信息統一放在 Response Header 中 ``` X-dialog-message: \\u6d88\\u606f\\u63d0\\u793a X-dialog-type: warning ``` `X-dialog-message` 這個message 是后端根據該用戶的語言返回對應的提示信息的 \*\*Unicode 編碼\*\* ,因為 header 中不能存放中文 `X-dialog-type` 目前只有warning 和 error 類型，純展示,后續根據產品需要可以擴充更多類型 \### 網關與其他微服務之間一些約定 \#### Header 中存放了一些用戶的基本信息 `X-user-id` 根據前端傳遞的 token 解析出來的 userId 放在 header中的這個字段里傳遞給其他微服務,其他微服務通過 HttpServletRequest.header 來獲取 `X-user-nickname` 獲取用戶昵稱? `X-user-phone` 獲取用戶手機號碼,如果有的話 `X-user-photo` 獲取用戶頭像? `X-user-account` 獲取用戶賬號,手機號碼或者郵箱? ps: Java 可直接通過 duiker 提供的 \*\*HttpUtils\*\* 中提供的方法獲取用戶基本信息