RESTful API实践
-
RESTful介绍
RESTful相关介绍请参考：
https://www.runoob.com/w3cnote/restful-architecture.html
RESTfulAPI标准接口文档请参考：
https://developer.openstack.org/api-ref/application-catalog/v1/index.html
-
示例代码
代码总体结构基于Spring4.3.10版本，代码配置基于XML和注解配置（相比传统此示例代码大多数配置通过注解完成），支持配置分离，集成spring data redis(项目中常用，建议对Redis的操作通过RedisTemplate完成，代码中附有操作示例，如无法满足需求另外写代码)。
|
Spring data Redis介绍: 官方文档： https://docs.spring.io/spring-data/redis/docs/2.0.9.RELEASE/reference/html/ 参考文档： https://blog.csdn.net/niugang0920/article/details/81530492
题外如项目需要还可以引入spring-data-jpa,spring-data-elasticsearch |
对MyBatis操作也基于了一定的封装。引入大量最新支持的注解简化代码开发。Banner打印，去掉web 层Try Catch异常捕获，统一交@ControllerAdvice处理。你将看到与以往不同的Response Code.
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
400 - Bad Request |
无效请求内容，参数错误 |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
操作示例
1.创建用户
POST http://localhost:8084/mis-xdja/restful/user
创建用户：
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
400 - Bad Request |
无效请求内容，参数错误 |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
Request Parameters
|
参数名 |
所在域 |
类型 |
描述 |
|
account |
Body |
String |
账号 |
|
name |
Body |
String |
姓名 |
|
phone |
Body |
String |
电话 |
|
|
Body |
String |
邮箱 |
Request Example
|
{ "account":"110113", "name":"李龙", "phone":"13060401016", "email":"863263957@qq.com" }
|
Response Parameters
|
参数名 |
所在域 |
类型 |
描述 |
|
id |
Body |
Integer |
账号 |
|
account |
Body |
String |
姓名 |
|
sex |
Body |
String |
电话 |
|
phone |
Body |
String |
邮箱 |
|
quanPin |
Body |
String |
全拼 |
|
jianPin |
Body |
String |
简拼 |
|
ip |
Body |
String |
Ip地址 |
|
deptId |
Body |
Integer |
部门id |
|
roleId |
Body |
Integer |
角色id |
|
idCard |
Body |
String |
身份证 |
|
fileUrl |
Body |
String |
头像URL |
|
password |
Body |
String |
密码 |
|
deleteFlag |
Body |
String |
删除标识 |
|
createTime |
Body |
String |
创建时间 |
|
creator |
Body |
String |
创建者 |
|
updateTime |
Body |
String |
更新时间 |
|
updator |
Body |
String |
更新者 |
|
version |
Body |
String |
版本 |
Response Example
|
{ "id": 34, "account": "110113", "name": "李龙", "sex": null, "phone": "13060401016", "email": "863263957@qq.com", "quanPin": "lilong", "jianPin": "ll", "ip": null, "deptId": null, "roleId": null, "idCard": null, "fileUrl": null, "password": "e10adc3949ba59abbe56e057f20f883e", "deleteFlag": "1", "createTime": 1535111701000, "creator": null, "updateTime": null, "updator": null, "version": 180824195501 } |
2.用户列表
查询用户列表，支持动态参数和分页
GET http://localhost:8084/mis-xdja/restful/user
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
Request Parameters
请求参数只有只要实体中定义了属性字段都可以当为请求参数，为了节约篇幅只列举部分参数
解释：
query(查询)
可选，用于给动态网页（如使用CGI、ISAPI、PHP/JSP/ASP/ASP。NET等技术制作的网页）传递参数，可有多个参数，用“&”符号隔开，每个参数的名和值用“=”符号隔开。
|
参数名 |
所在域 |
类型 |
描述 |
|
account |
query |
String |
账号 |
|
name |
query |
String |
姓名 |
|
phone |
query |
String |
电话 |
|
|
query |
String |
邮箱 |
|
… |
… |
… |
…. |
Request Example
Response Parameters
相应参数如：1.创建用户
Response Example
|
{ "data": [ { "id": 34, "account": "110113", "name": "李龙", "sex": null, "phone": "13060401016", "email": "863263957@qq.com", "quanPin": "lilong", "jianPin": "ll", "ip": null, "deptId": null, "roleId": null, "idCard": null, "fileUrl": null, "password": "e10adc3949ba59abbe56e057f20f883e", "deleteFlag": "1", "createTime": 1535111701000, "creator": null, "updateTime": null, "updator": null, "version": 180824195501 }, { "id": 4, "account": "110111", "name": "石磊", "sex": null, "phone": "13060401016", "email": "863263957@qq.com", "quanPin": "shilei", "jianPin": "sl", "ip": null, "deptId": null, "roleId": null, "idCard": null, "fileUrl": null, "password": "e10adc3949ba59abbe56e057f20f883e", "deleteFlag": "1", "createTime": 1535107901000, "creator": null, "updateTime": null, "updator": null, "version": 180824185139 } ], "total": 4 } |
3.修改用户
修改用户信息
PUT http://localhost:8084/mis-xdja/restful/user
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
400 - Bad Request |
无效请求内容，参数错误 |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
Request Parameters
|
参数名 |
所在域 |
类型 |
描述 |
|
id |
Body |
Integer |
用户id |
|
account |
Body |
String |
账号 |
|
name |
Body |
String |
姓名 |
|
phone |
Body |
String |
电话 |
|
|
Body |
String |
邮箱 |
对于以上put请求如id为空，后台会返回400状态码。这是客户端就知道请求参数头问题。
如需要具体的业务状态码在额外定义,如下。
Request Example
|
{ "id":34, "account":"110113", "name":"牛刚刚", "phone":"15094031789", "email":"1235656@qq.com" } |
4.用户详情
查询用户列表，支持动态参数和分页
GET http://localhost:8084/mis-xdja/restful/user/{id}
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
400 - Bad Request |
无效请求内容，参数错误 |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
Request Parameters
请求参数只有只要实体中定义了属性字段都可以当为请求参数，为了节约篇幅只列举部分参数
解释：
path（路径）
由零或多个“/”符号隔开的字符串，一般用来表示主机上的一个目录或文件地址。
|
参数名 |
所在域 |
类型 |
描述 |
|
id |
path |
Integer |
用户id |
Request Example
http://localhost:8084/mis-xdja/restful/user/34
Response Parameters
相应参数如：1.创建用户
Response Example
|
{ "id": 34, "account": "110113", "name": "牛刚刚", "sex": null, "phone": "15094031789", "email": "1235656@qq.com", "quanPin": "lilong", "jianPin": "ll", "ip": null, "deptId": null, "roleId": null, "idCard": null, "fileUrl": null, "password": "e10adc3949ba59abbe56e057f20f883e", "deleteFlag": "1", "createTime": 1535111701000, "creator": null, "updateTime": 1535115358000, "updator": null, "version": 180824195501 } |
5.删除用户
DELETE http://localhost:8084/mis-xdja/restful/user/{id}
Response Codes
Success
|
Code |
Reason |
|
200 - OK |
请求成功 |
Error
|
Code |
Reason |
|
400 - Bad Request |
无效请求内容，参数错误 |
|
401 - Unauthorized |
用户未授权(未登录) |
|
403 - Forbidden |
无权限访问访问 |
|
500- Internal Server Error |
服务器内部异常 |
Request Parameters
请求参数只有只要实体中定义了属性字段都可以当为请求参数，为了节约篇幅只列举部分参数
解释：
path（路径）
由零或多个“/”符号隔开的字符串，一般用来表示主机上的一个目录或文件地址。
|
参数名 |
所在域 |
类型 |
描述 |
|
id |
path |
Integer |
用户id |
Request Example
http://localhost:8084/mis-xdja/restful/user/34
Response Parameters
相应参数如：1.创建用户
Response Example
无响应参数，客户端根据返回的状态码就知道是否操作成功。
也可以返回返回业务处理成功信息
源码地址：https://gitee.com/niugangxy/RESTfulAPI
微信公众号
