Restful 风构架构
Spring mvc 框架是完全支持 Restful 风格的,我们采用 / 匹配模式可以完美地实现Restful 操作
REST 定义
Representation State Transfer, 表述性状态转移, 后端的任何资源都可以采用 统一资源定位符[URI] 来定位,配合上请求的动作,可以完整地表达出请求的含义。 根据数据的常用操作,把它与不同的请求类型相匹配,主要有:
C操作,Create, 创建数据, 可以使用 POST 请求
R操作,Retrieve, 获取数据,可以使用 GET 请求
U操作,Update, 更新数据,可以使用 PUT 请求
D操作,Delete, 删除数据,可以使用 DELETE 请求
在控制器的方法中, @RequestMapping中有一个 method属性,它可以指定此方法只接收哪种请求类型。
如何开发 REST风格的控制器
与开发普通的控制器相比,需要使用 @ResponseBody 来表明以方法返回值做为响应体,基本上都是以JSON做数据交换的格式。
- 我们的控制器可以使用 @Controller + @ResponseBody 组合注解,也可以使用 @RestController 【推荐这个】
- 在方法上面,使用 @RequestMapping 时,要指定 method 以及 produces
- 由于在Rest风格上,可以通过 路径参数来传递请求参数,所以需要用到 @PathVariable 注解以及 @RequestBody 注解
Rest风格与普通的URI对比
获取id为1的Employee实例或获取所有的Employee实例
非REST风格URI: localhost:9090/emp/get?id=1 和 localhost:9090/emp/list
Rest风格URI: GET localhost:9090/emp/1 和 GET localhost:9090/emp
删除ID为2的Employee 和 删除所有的 Employee
非REST风格URI: localhost:9090/emp/delete?id=1 和 localhost:9090/emp/deleteAll
Rest风格URI: DELETE localhost:9090/emp/2 和 DELETE localhost:9090/emp
综上所述,REST风格的URI 充份利用了请求的类型这个动词,所以,不需要在URI层面再去说明不同的操作【相当于“动词”前移】,在REST风格的URI中,它的格式:
请求动作 + URI名词
REST风格API的设计
首先了解一下HTTP的请求方式
- GET -> 获取数据,也就是对应 查询【R】
- POST -> 提交数据, 也就是对应 创建 【C】
- DELETE -> 删除数据,也就是对应 删除【D】
- PUT -> 更新数据【全部】,也就是对应 更新【U】
- PATCH -> 更新数据【局部】, 也就是对应 更新 【U】
- ….
再来看一下设计REST 风格API时需要注意的事项:
- 在URI中不要使用动词,仅可能地全部使用名词
- 在URI中尽可能使用复数,如:/users, /users/1
- 如果有多级层的情况,可以把子级做为查询字符串【请求参数】来传递
- 在URI中加入版本号, 如:/api/v1/users, /api/v2/users
- 当然,也要根据公司的具体业务情况,再具体分析
如:
请求方式 | URI | 描述 |
---|---|---|
GET | /users | 获取所有的用户信息 |
GET | /users/{id} | 获取指定ID的用户信息 |
GET | /addr/{province}?q=xxx | 根据省份以及过滤条件查询出地址信息 |
POST | /users | 插入用户信息 |
DELETE | /users | 删除所有用户信息 |
DELETE | /USERS/{id} | 删除指定的用户 |
PUT | /users/{id} | 更新指定ID的用户所有信息【ID除外】 |
PATCH | /user/{id} | 更新指定ID的用户部分信息 |
响应状态码
在HTTP协议中定义了5大类,分别是:
- 1xx
- 2xx —> 服务端处理OK
- 200 代表OK
- 201 代表 CREATE
- 203 …
- 204 …
- 3xx -> 服务端请求转移
- 4xx –> 访问的资源不存在
- 5xx –> 服务端出错了
- 500
- 50? …
Spring 框架提供的 响应体实例类 ResponseEntity
此类可以封装响应数据以及响应头和响应状态,并由spring mvc框架自动转换成 json格式后响应给客户端。
具体的代码操作请查看 项目案例
所涉及到的注解及API
- 注解
- @PathVariable
- @RequestBody
- @RestController
- API
- ResponseEntity
- HttpStatus
- HttpHeaders
- UriComponentBuilder
- ResponseEntity
注:以上类型 和注解 都可以在 API 中查看原义,或是通过阅读代码理解它的作用。