Restful规范

Api设计6要素

• 资源路径(URI)

• HTTP动词(Method)

• 过滤信息(query-string)

• 状态码(Status-code)

• 错误信息(Error)

• 返回结果(Result)

1.接口定义
接口定义必须符合restful规范，因为我们这个命名规范是非常依赖请求地址的合理性的
比如，我有一个用户管理的需求，有下面几个功能
用户列表：GET /users
创建用户：POST /users
修改用户：PUT /users/{id}
删除用户：DELETE /users/{id}
我们第一步就是要像上面这样先定义好每个接口的请求地址，一般我都会先设计好请求地址，实现交给开发自己去做。在做接口设计的时候，其实也是需求分析的过程，开发按照已经设计好的接口清单去开发，能够被规范在一个框架内，不至于跑偏。

2.controller和service命名
一般情况下，我们会按照系统有用的功能模块进行controller的划分，通常都是一个模块一个controller。比如系统有用户管理、报表管理，那么controller就会这么定义：
用户管理：UserController
报表管理：ReportController

一个controller至少需要一个主的service，比如：
用户管理：UserService
报表管理：ReportService
controller中一般只调用主service的入口方法，主service可以依赖其他service。

3.方法命名
这部分是规范的关键，命名这个事情真的是考验英文水平的。所以为了消除这个差异，让不同水平的开发都能定义出相对合理的命名，我们最终的做法就是按照接口的请求地址进行转换，比如：
用户列表：GET /users -> listUser
创建用户：POST /users -> createUser
修改用户：PUT /users/{id} -> updateUser
删除用户：DELETE /users/{id} -> deleteUser
转换的规则就是请求的Method + RequestMapping，当然这里不是直接拼接，还是要做一些处理的，Method部分的处理：
GET -> list/get/find
POST -> create/add
PUT -> update/modify
DELETE -> delete/remove/drop

4.RequestMaping部分，直接转成驼峰写法即可，比如：
用户操作日志：GET /users/opr_log -> listUserOprLogs
删除某用户拥有的角色：DELETE /users/{id}/roles -> deleteUserRoles或deleteUserRolesById

请求类和返回类定义
这部分更简单：
请求类：方法名+Request
返回类：方法名+Response
request/response是我们项目的一个规范，有些人喜欢params/data，或者阿里规范的dto/vo等都可以，按照自己的项目要求来即可。

举例：
用户列表：ListUserRequest/ListUserResponse
创建用户：CreateUserRequest/CreateUserResponse
修改用户：UpdateUserRequest/UpdateUserResponse