Fork me on GitHub

SpringMVC中RestFUL风格的API设计

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做数据交换的格式。

  1. 我们的控制器可以使用 @Controller + @ResponseBody 组合注解,也可以使用 @RestController 【推荐这个】
  2. 在方法上面,使用 @RequestMapping 时,要指定 method 以及 produces
  3. 由于在Rest风格上,可以通过 路径参数来传递请求参数,所以需要用到 @PathVariable 注解以及 @RequestBody 注解

Rest风格与普通的URI对比

  1. 获取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

  2. 删除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的请求方式

  1. GET -> 获取数据,也就是对应 查询【R】
  2. POST -> 提交数据, 也就是对应 创建 【C】
  3. DELETE -> 删除数据,也就是对应 删除【D】
  4. PUT -> 更新数据【全部】,也就是对应 更新【U】
  5. PATCH -> 更新数据【局部】, 也就是对应 更新 【U】
  6. ….

再来看一下设计REST 风格API时需要注意的事项:

  1. 在URI中不要使用动词,仅可能地全部使用名词
  2. 在URI中尽可能使用复数,如:/users, /users/1
  3. 如果有多级层的情况,可以把子级做为查询字符串【请求参数】来传递
  4. 在URI中加入版本号, 如:/api/v1/users, /api/v2/users
  5. 当然,也要根据公司的具体业务情况,再具体分析

如:

请求方式 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

  1. 注解
    • @PathVariable
    • @RequestBody
    • @RestController
  2. API
    • ResponseEntity
    • HttpStatus
    • HttpHeaders
    • UriComponentBuilder

注:以上类型 和注解 都可以在 API 中查看原义,或是通过阅读代码理解它的作用。