6.2 构建 RESTful 应用接口

待我称王封你为后i 2023-10-08 17:53 29阅读 0赞

> ## 第6章 构建 RESTful 服务 ##
> 
> 6.1 [RESTful 简介][RESTful]  
> 6.2 [构建 RESTful 应用接口][RESTful 1]  
> 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）对应的注解：

1.  @GetMapping：处理 GET 请求，获取资源。
2.  @PostMapping：处理 POST 请求，新增资源。
3.  @PutMapping：处理 PUT 请求，更新资源。
4.  @DeleteMapping：处理 DELETE 请求，删除资源。
5.  @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说明**

<table> 
 <thead> 
  <tr> 
   <th>HTTP Method</th> 
   <th>接口地址</th> 
   <th>接口说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>POST</td> 
   <td>/user</td> 
   <td>创建用户</td> 
  </tr> 
  <tr> 
   <td>GET</td> 
   <td>/user/id</td> 
   <td>根据id获取用户信息</td> 
  </tr> 
  <tr> 
   <td>PUT</td> 
   <td>/user</td> 
   <td>更新用户</td> 
  </tr> 
  <tr> 
   <td>DELETE</td> 
   <td>/user/id</td> 
   <td>根据id删除对应的用户</td> 
  </tr> 
 </tbody> 
</table>

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

（2）状态码和提示信息定义

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

**用户管理模块`状态码`说明：**

<table> 
 <thead> 
  <tr> 
   <th>状态码</th> 
   <th>状态说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>200</td> 
   <td>Ok，请求成功</td> 
  </tr> 
  <tr> 
   <td>201</td> 
   <td>Created，新增成功</td> 
  </tr> 
  <tr> 
   <td>203</td> 
   <td>Updated，修改成功</td> 
  </tr> 
  <tr> 
   <td>204</td> 
   <td>Deleted，删除成功</td> 
  </tr> 
 </tbody> 
</table>

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

**用户管理模块`错误码`说明：**

<table> 
 <thead> 
  <tr> 
   <th>错误码</th> 
   <th>错误说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>400</td> 
   <td>数据验证错误</td> 
  </tr> 
  <tr> 
   <td>401</td> 
   <td>无权限</td> 
  </tr> 
  <tr> 
   <td>404</td> 
   <td>资源不存在</td> 
  </tr> 
  <tr> 
   <td>500</td> 
   <td>服务端错误</td> 
  </tr> 
 </tbody> 
</table>

##### 2. 实现用户管理接口 #####

UserManagementController.java

package com.example.restfulproject.controller;
    
    import com.example.restfulproject.comm.utils.JSONResult;
    import com.example.restfulproject.m

[RESTful]: https://blog.csdn.net/Shipley_Leo/article/details/129090115
[RESTful 1]: https://blog.csdn.net/Shipley_Leo/article/details/129093550