本文介绍了Spring Boot 开发REST接口最佳实践，分享给大家，具体如下：
HTTP动词与SQL命令对应
GET
|
1
2
3
4
5
|
从服务器获取资源，可一个或者多个，对应SQL命令中的SELECT
GET /users
获取服务器上的所有的用户信息
GET /users/ID
获取指定ID的用户信息
|
POST
|
1
2
3
|
在服务器上创建一个新资源，对应SQL命令中的CREATE
POST /users
创建一个新的用户
|
PUT
|
1
2
3
|
在服务器上更新一个资源，客户端提供改变后的完整资源，对应SQL命令中的UPDATE
PUT /users/ID
更新指定ID的用户的全部信息
|
DELETE
|
1
2
3
|
从服务器上删除一个资源，对应SQL命令中的DELETE
DELETE /users/ID
删除指定ID的用户信息
|
PATCH
|
1
2
3
|
在服务器更新一个资源的部分属性，对应SQL命令中的UPDATE
PATCH /users/ID
更新指定ID的用户的某个属性
|
URL中的约定
URL中名词使用复数形式
URL中的名称是使用单数还是使用复数的问题，争议由来已久。URL中的名词一般对应数据库中的表，表中存储的是同类数据， 在实践中我是强制使用复数形式 ，看上去更舒服些。
|
1
2
3
4
|
/users
/users/1
/roles
/roles/1
|
至于一些不规则的、不可数的名词就见仁见智吧。
|
1
2
3
4
5
6
7
8
|
/heroes
/heroes/1
/people
/people/1
/foots
/foots/1
/feet
/feet/1
|
版本
讲版本号加入到URL中以应对不兼容的和破坏性的更改。发布新API时，客户端可以自如的迁移到新API，不会因调用完全不同的新API而陷入窘境。使用直观的“V”前缀来表示后面的数字是版本号，不需要次级版本号，不应该频繁的发布API版本。
|
1
2
|
/edu/v1/users
/edu/v1/roles
|
对可选的、复杂的参数使用查询字符串
为了让URL更小、更简洁，为资源设置一个基本URL，讲可选的、复杂的参数用查询字符串表示。
|
1
|
/edu/v1/users?enabled=1&roleid=1
|
提供分页信息
一次性返回数据库中的所有的资源不是一个好主意，因此需要提供分页机制。通常使用数据库中众所周知的参数offset和limit
|
1
|
/edu/v1/users?enabled=1&offset=1&limit=15
|
如果客户端没有传递这些参数，则应使用默认值，通常offset=0，limit=10。
非资源请求使用动词
有时API调用并不涉及资源，在这种情况下，服务器执行一个操作病将结果返回给客户端。
|
1
|
/edu/v1/calc?p=100
|
考虑特定资源和跨资源搜索
提供对特定止缘的搜索很容易，只需要使用相应的资源集合，并将搜索字符串附加到查询参数中即可。
|
1
|
/edu/v1/users?username=李庆海
|
如果需要对所有资源提供全局搜索，则需要使用其他方法。
|
1
|
/edu/v1/search?key=李庆海
|
响应结果
使用小驼峰命名法作为属性标识符
通常，RESTful Web服务将被JavaScript编写的客户端使用。客户端会将JSON响应转换为JavaScript对象，然后调用其属性。因此，最好遵循JavaScript代码通用规范。
|
1
2
3
|
person.year_of_birth // 不推荐，违反JavaScript代码通用规范
person.YearOfBirth // 不推荐，JavaScript构造方法命名
person.yearOfBirth // 推荐
|
提供分页信息
返回结果比较多时，应提供分页信息。
|
1
2
3
4
5
6
7
8
|
{
"page": 0,
"size": 10,
"total": 3465,
"obj": [
]
}
|
Spring MVC开发REST接口
常用注解
@RestController
@RestController是@ResponseBody和@Controller的组合注解。
@RequestMapping
此注解即可以作用在控制器的某个方法上，也可以作用在此控制器类上。当控制器在类级别上添加@RequestMapping注解时，这个注解会应用到控制器的所有处理器方法上。处理器方法上的@RequestMapping注解会对类级别上的@RequestMapping的声明进行补充。
@PostMapping
组合注解，是@RequestMapping(method =RequestMethod.POST)的缩写。
@PutMapping
组合注解，是@RequestMapping(method = RequestMethod.PUT)的缩写。
@PatchMapping
组合注解，是@RequestMapping(method = RequestMethod.PATCH)的缩写。
@DeleteMapping
组合注解，是@RequestMapping(method = RequestMethod.DELETE)的缩写。
@GetMapping
组合注解，是@RequestMapping(method = RequestMethod.GET)的缩写。
@PathVariable
获取url中的数据。
@RequestParam
获取请求参数的值。
REST接口及Swagger 编写API文档示例
关于Swagger的使用可参考Spring Boot 项目中使用Swagger2 。方法体中的代码不重要，重要的是方法的签名以及与HTTP动词的映射。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|