第6章 构建 RESTful 服务
6.1 RESTful 简介
6.2 构建 RESTful 应用接口
6.3 使用 Swagger 生成 Web API 文档
6.4 实战:实现 Web API 版本控制
6.2 构建 RESTful 应用接口
6.2.1 Spring Boot 对 RESTful 的支持
Spring Boot 提供的spring-boot-starter-web
组件完全支持开发 RESTful API,提供了与 REST 操作方式(GET、POST、PUT、DELETE)对应的注解:
- @GetMapping:处理 GET 请求,获取资源。
- @PostMapping:处理 POST 请求,新增资源。
- @PutMapping:处理 PUT 请求,更新资源。
- @DeleteMapping:处理 DELETE 请求,删除资源。
- @PatchMapping:处理 PATCH 请求,用于部分更新资源。
通过这些注解就可以在 Spring Boot 项目中轻松构建 RESTful 接口。其中比较常用的是 @GetMapping、@PostMapping、@PutMapping、@DeleteMapping 四个注解。
使用 Spring Boot 开发 RESTful 接口非常简单,通过 @RestController 定义控制器,然后使用 @GetMapping 和 @PostMapping 等注解定义地址映射,实现相应的资源操作方法即可。
示例:
RESTfulController.java
package com.example.restfulproject.controller;
import com.example.restfulproject.model.User;
import org.springframework.web.bind.annotation.*;
/**
* RESTful 接口简单案例(增删改查)
*/
@RestController
public class RESTfulController {
@GetMapping(value = "/user/{id}")
public String getUserById(@PathVariable String id) {
return "getUserById:" + id;
}
@PostMapping(value = "/user")
public String save(@RequestBody User user) {
String name = user.getName();
return "save successed";
}
@PutMapping(value = "/user")
public String update(@RequestBody User user) {
return "update successed";
}
@DeleteMapping(value = "/user/{id}")
public String delete(@PathVariable String id) {
return "delete id:" + id;
}
/*
// 上面的注解是 @RequestMapping 注解的简化:
@RequestMapping(value = "/user/{id}", method = RequestMethod.GET)
public String getUserById(@PathVariable String id) {
return "getUserById:" + id;
}
@RequestMapping(value = "/user", method = RequestMethod.POST)
public String save(User user) {
return "save successed";
}
@RequestMapping(value = "/user", method = RequestMethod.PUT)
public String update(User user) {
return "update successed";
}
@RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE)
public String delete(@PathVariable String id) {
return "delete id:" + id;
}
*/
}
6.2.2 Spring Boot 实现 RESTful API
1. 设计API
在 RESTful 架构中,每个网址代表一种资源,所以 URI 中建议不要包含动词,只包含名词即可,而且所用的名词往往与数据库的表名对应。
(1)接口定义
下表是用户管理模块的接口定义,实际项目的 RESTful API 文档要更详细,还会定义全部请求的数据结构体。
用户管理模块API说明
HTTP Method | 接口地址 | 接口说明 |
---|---|---|
POST | /user | 创建用户 |
GET | /user/id | 根据id获取用户信息 |
PUT | /user | 更新用户 |
DELETE | /user/id | 根据id删除对应的用户 |
上表中定义了用户管理模块的接口,根据 REST 的定义,我们将用户定义为一种资源,通过 POST、DELETE、PUT、GET 等 HTTP Method 实现对用户的增、删、改、查。
(2)状态码和提示信息定义
除了设计 URL 接口之外,还需要定义服务端向客户端返回的状态码和提示信息。详细状态码说明见下表。
用户管理模块状态码
说明:
状态码 | 状态说明 |
---|---|
200 | Ok,请求成功 |
201 | Created,新增成功 |
203 | Updated,修改成功 |
204 | Deleted,删除成功 |
除了定义用户管理相关的业务状态码之外,还需要定义通用的错误码,如 400 对应数据校验错误、401 对应数据无权限等。
用户管理模块错误码
说明:
错误码 | 错误说明 |
---|---|
400 | 数据验证错误 |
401 | 无权限 |
404 | 资源不存在 |
500 | 服务端错误 |
2. 实现用户管理接口
UserManagementController.java
package com.example.restfulproject.controller;
import com.example.restfulproject.comm.utils.JSONResult;
import com.example.restfulproject.m