resful · thinkphp5

当逻辑错误时，返回 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\*\* 中提供的方法获取用户基本信息