首页 > 编程笔记 > Java笔记 阅读：16

Spring Boot构建RESTful（非常详细）

RESTful 架构是目前最流行的互联网软件架构规范，是 Web API（应用编程接口）的大趋势和主流规范，了解了 RESTful 的众多优点之后，接下来一步一步地学习如何使用 Spring Boot 构建 RESTful Web API。

Spring Boot对RESTful的支持

Spring Boot 提供的 spring-boot-starter-web 组件完全支持开发 RESTful API，提供了与 REST 操作方式（GET、POST、PUT、DELETE）对应的注解：
通过这些注解就可以在 Spring Boot 项目中轻松构建 RESTful 接口。其中比较常用的是 @GetMapping、@PostMapping、@PutMapping、@DeleteMapping 四个注解。

使用 Spring Boot 开发 RESTful 接口非常简单，通过 @RestController 定义控制器，然后使用 @GetMapping 和 @PostMapping 等注解定义地址映射，实现相应的资源操作方法即可。 
@GetMapping(value="/user/{id}")
public String getUserByID(@PathVariable int id){
    return "getUserByID:"+id;
}
@PostMapping(value="/user ")
public String save(User user){
    return "save successed";
}
@PutMapping(value="/user")
public String update(User user){
    return "update successed";
}
@DeleteMapping(value="/{id}")
public String delete(@PathVariable int id){
    return "delete id:"+id;
}

在上面的示例中，通过 Spring Boot 提供的 @GetMapping 等注解简单实现了对用户（user）的操作。其实，这些注解就是 @RequestMapping 注解的简化： 
@RequestMapping(value = "/user/{id}", method = RequestMethod.GET)
public String getUserByID(@PathVariable int 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 int id){
    return "delete id:"+id;
}
之前介绍的 @RequestMapping 注解通过 method 参数定义映射的 HTTP 请求方法，就相当于 @RequestMapping+ RequestMethod 的简化版。

我们看到，Get 和 Delete、Post 和 Put 请求的 URL 是相同的，不同的 Method(GET、PUT、POST、DELETE) 会被映射到对应的处理方法上。这就是 REST 的魅力，简单明了的 URL 就能显示它的功能和作用。

Spring Boot实现RESTful API

接下来根据之前介绍的 RESTful 设计风格，以用户管理模块为例演示 Spring Boot 如何实现 RESTful API。

1) 设计API

在 RESTful 架构中，每个网址代表一种资源，所以 URI 中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应。

下表是用户管理模块的接口定义，实际项目的 RESTful API 文档要更详细，还会定义全部请求的数据结构体。

表：用户管理模块 API 说明
HTTP Method 接口地址 接口说明
POST /user 创建用户
GET /user/id 根据 id 获取用户信息
PUT /user 更新用户
DELETE /user/id 根据 id 删除对应的用户

上表定义了用户管理模块的接口，根据 REST 的定义，我们将用户定义为一种资源，通过 POST、DELETE、PUT、GET 等 HTTP Method 实现对用户的增、删、改、查。

可能大家会有疑问，为什么 URI 中没有我们习惯的 getUser、saveUser 这类路径？这正是 RESTful 优雅的地方，它将对资源的操作都定义在 HTTP Method 中，使得 URL 地址看起来更简洁。

除了设计 URL 接口之外，还需要定义服务端向客户端返回的状态码和提示信息。详细的状态码说明见下表。

表：用户管理模块状态码和错误码说明
状态码 状态说明 错误码 错误说明
200 OK，请求成功 400 数据验证错误
201 Created，新增成功 401 无权限
203 Updated，修改成功 404 资源不存在
204 Deleted，删除成功 500 服务端错误

上表中除了定义用户管理相关的业务状态码之外，还需要定义通用的错误码，如 400 对应数据校验错误、401 对应数据无权限等。

2) 实现用户管理接口

上面定义了 RESTful API 以及接口返回的状态码，接下来根据之前的接口定义先创建 UserController，再实现用户管理模块的用户新增、用户修改、用户删除、用户查询等接口。

① 用户新增： 
@PostMapping(value = "user")
public JSONResult save(@RequestBody User user){
    System.out.println("用户创建成功："+user.getName());
    return JSONResult.ok(201,"用户创建成功");
}
@PostMapping 注解表示此为 POST 接口。通过 POST 方法传入用户数据，然后调用 Save 方法保存用户数据。

② 用户修改： 
@PutMapping(value = "user")
public JSONResult update(@RequestBody User user) {
    System.out.println("用户修改成功："+user.getName());
    return JSONResult.ok(203,"用户修改成功");
}
@PutMapping 注解表示此为 PUT 接口。PUT 和 POST 的 URL 是相同的，只是通过 PUT、POST 方法加以区分。后端处理逻辑不同，所以使用时千万别搞混了。

③ 用户删除： 
@DeleteMapping("user/{userId}")
public JSONResult delete(@PathVariable String userId) {
    System.out.println("用户删除成功："+userId);
    return JSONResult.ok(204,"用户删除成功");
}
@DeleteMapping 注解表示此为删除接口。通过传入参数 userId 删除人员信息。

④ 获取用户： 
@GetMapping("user/{userId}")
public JSONResult queryUserById(@PathVariable String userId) {
    User user =new User();
    user.setUserId(userId);
    user.setName("weiz");
    user.setAge(20);
    System.out.println("获取用户成功："+userId);
    return JSONResult.ok(200,"获取用户成功",user);
}
@GetMapping 注解表示此为查询接口。@PathVariable 注解用于参数映射，获取传入的参数。

3) 验证测试

至此，用户管理的模块接口都实现了。接下来验证接口调用。我们可以使用单元测试或者 Postman 工具调用用户管理模块的相关接口，测试接口是否正常。这里就以 Postman 工具演示 RESTful API 的测试。

打开 Postman，使用 POST 方法请求 /user 接口，验证新增人员的接口是否正常，如下图所示。


图 1 在用户管理模块中验证新增用户的接口

通过 Postman 发送 POST 请求，调用人员新增接口，后台接口处理成功后，返回人员信息保存成功。

接下来，使用 GET 方法请求 /user/2001 获取 userId 为 2001 的人员信息，从而验证获取人员的接口是否正常，如下图所示：


图 2 在用户管理模块验证获取用户的接口

通过 Postman 向后台接口发送 GET 方法请求 /user/2001，RESTful API 成功返回人员详细信息。

相关文章