基于 Spring Boot 的 RESTful API 设计与实现

2022 年 9 月 08 日
北京
本文字数：3417 字
阅读完需：约 11 分钟

RESTful 是一种规范，符合 RESTful 的 Api 就是 RESTful Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有 URI 标识的服务器资源，返回统一格式的资源信息，包括 JSON、XML、CSV、ProtoBuf、其他格式。RESTful 的核心思想是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /case 这个命令，GET 是动词，/case 是宾语。

RESTful API 简介 RESTful 架构遵循统一接口原则，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的 HTTP 方法如 GET ，PUT 和 POST ，并遵循这些方法的语义。设计规范常用的动词有以下 5 个

详情见 https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Spring Boot 实现 RESTful API 我们可以通过 Spring Boot 注解来实现 RESTful API 。

现在需要编写的是对一个用户的增删改查操作，如下表是一个非 RESTful 和标准 RESTful 的对比表。

下面我们着重介绍下以下两对注解。

Controller 一般应用在有返回界面的应用场景下。例如，管理后台使用了模板技术如 thymeleaf 开发，需要从后台直接返回 Model 对象到前台，那么这时候就需要使用 Controller 来注解。

RestController 一般应用在只有接口的应用场景下. 例如开发前后端分离的项目时，通过 Ajax 请求服务端接口，那么接口就使用 RestController 统一注解。

需要注意的是 RestController 是 Controller 的子集。RestController 是 Spring4 后新加的注解，从 RestController 注解源码可以看出 RestController 是 Controller 和 ResponseBody 两个注解的结合体，即 Controller=RestController+ResponseBody。

RestController 注解源码

@Target({ElementType.TYPE})@Retention(RetentionPolicy.RUNTIME)@Documented@Controller@ResponseBodypublic @interface RestController {@AliasFor(annotation = Controller.class)String value() default "";}

RequestMapping 和 GetMapping/PostMapping/PutMapping/DeleteMapping 作用一样，其实可以相互替换，后者是前者的简化版本。

GetMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 GET，PostMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 POST，PutMapping、DeleteMapping 其实就等于将 RequestMapping 注解的 method 属性分别设置为 PUT、DELETE。

也就是说 GetMapping、PostMapping、PutMapping、DeleteMapping 是 RequestMapping 的子集。

我们来看看 RequestMapping 的源码：

@Target({ElementType.TYPE, ElementType.METHOD})@Retention(RetentionPolicy.RUNTIME)@Documented@Mappingpublic @interface RequestMapping {String name() default "";

//请求URI@AliasFor("path")String[] value() default {};@AliasFor("value")String[] path() default {};//请求类型，如 GET、POST、PUT、DELETE 等RequestMethod[] method() default {};//请求参数中必须包含某些参数值，才让该方法处理。String[] params() default {};//请求参数中必须包含某些指定的header值，才能让该方法处理请求。String[] headers() default {};//请求的内容类型（Content-Type），例如application/json, text/html;String[] consumes() default {};//响应的内容类型，仅当 request 请求头中的( Accept )类型中包含该指定类型才返回；String[] produces() default {};

复制代码

}

示例说明：

新增 2 个文件：dto/UserDto.java 和 controller/HogwartsTestUserController.java ，其中 UserController 类中包括了对用户的 4 个操作增删改查。public class UserDto {

private String name;private String pwd;
public String getName() {    return name;}
public void setName(String name) {    this.name = name;}
public String getPwd() {    return pwd;}
public void setPwd(String pwd) {    this.pwd = pwd;}

复制代码

}

/**

RESTful API 风格示例对资源 user 进行操作
本示例没有使用数据库，也没有使用 service 类来辅助完成，所有操作在本类中完成
*/@Api(tags = "霍格沃兹测试学院-用户管理模块", hidden = true)@RestController@RequestMapping("/api/user")public class HogwartsTestUserController {
/**
查询用户列表，返回一个 JSON 数组
*/@ApiOperation("查询用户列表")@GetMapping("/users")@ResponseStatus(HttpStatus.OK)public Object getUsers(){List<UserDto> list = getData();return list;}
/**
查询用户信息，返回一个新建的 JSON 对象
*/@ApiOperation("查询用户信息")@GetMapping("/users/{id}")@ResponseStatus(HttpStatus.OK)public Object getUser(@PathVariable("id") Long id){
if(Objects.isNull(id)){return null;}
List<UserDto> list= getData();UserDto userDto = getUserDto(id, list);
return userDto;}
/**
新增用户
*/@ApiOperation("新增用户")@PostMapping("/users")@ResponseStatus(HttpStatus.CREATED)public Object addUser(@RequestBody UserDto user){
List<UserDto> list= getData();list.add(user);//模拟向列表中增加数据 return user;}
/**
编辑用户
*/@ApiOperation("编辑用户")@PutMapping("/users/{id}")@ResponseStatus(HttpStatus.CREATED)public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){List<UserDto> list = getData();for (UserDto userDto:list) {if(id.equals(userDto.getId())){userDto = user;break;}}
return user;}
/**
删除用户
*/@ApiOperation("删除用户")@DeleteMapping("/users/{id}")@ResponseStatus(HttpStatus.NO_CONTENT)public Object deleteUser(@PathVariable("id") Long id){List<UserDto> list = getData();UserDto userDto = getUserDto(id, list);return userDto;}
/**
模拟数据
*/private List<UserDto> getData(){List<UserDto> list=new ArrayList<>();
UserDto userDto = new UserDto();userDto.setId(1L);userDto.setName("admin");userDto.setPwd("admin");list.add(userDto);
userDto = new UserDto();userDto.setId(2L);userDto.setName("HogwartsTest1");userDto.setPwd("HogwartsTest1");list.add(userDto);
userDto = new UserDto();userDto.setId(3L);userDto.setName("HogwartsTest2");userDto.setPwd("HogwartsTest2");list.add(userDto);
userDto = new UserDto();userDto.setId(4L);userDto.setName("HogwartsTest3");userDto.setPwd("HogwartsTest3");list.add(userDto);
return list;}
/**
模拟根据 id 查询列表中的数据
@param id
@param list
@return*/private UserDto getUserDto( Long id, List<UserDto> list) {UserDto UserDto = null;for (UserDto user : list) {if (id.equals(user.getId())) {UserDto = user;break;}}return UserDto;}}

获取全部资源获取所有用户

GET http://127.0.0.1:8081/api/user/users/

响应参数

[{"id": 1,"name": "admin","pwd": "admin"},{"id": 2,"name": "HogwartsTest1","pwd": "HogwartsTest1"},{"id": 3,"name": "HogwartsTest2","pwd": "HogwartsTest2"},{"id": 4,"name": "HogwartsTest3","pwd": "HogwartsTest3"}]

获取单个资源获取用户

GET http://127.0.0.1:8081/api/user/users/3

新增一个资源新增一个用户

POST http://127.0.0.1:8081/api/user/users

请求参数

{"id": 4,"name": "HogwartsTest5","pwd": "HogwartsTest5"}

编辑更新一个资源

PUT http://127.0.0.1:8081/api/user/users/3

请求参数

{"name": "HogwartsTest6","pwd": "HogwartsTest6"}

删除一个资源

DELETE http://127.0.0.1:8081/api/user/users/3