Restful API详解

今天药忘吃喽~ 2023-02-21 11:47 15阅读 0赞

> 微信公众号：**Java患者**  
> 专注Java领域技术分享

### Restful API介绍 ###

Restful API是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义，它使用URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

### Restful API特点 ###

*  用URL描述资源。
 *  使用HTTP方法描述行为，使用HTTP状态码表示不同的结果。
 *  使用json交互数据。
 *  Restful只是一种风格，并不是强制的标准。

### Restful API的成熟模型 ###

![format_png][]

Level 0：使用HTTP作为传输方式。

Level 1：引入资源概念，每一个资源都有对应的URL。

Level 2：使用HTTP方法进行不同的操作，使用HTTP状态码来表示不同的结果。

Level 3：使用超媒体，在资源的表达中包含了链接信息。需要注意的是，在我们实际的工作中，并没有达到这个级别。

### 与传统请求方式对比 ###

![format_png 1][]

### Restful API常用映射注解 ###

*  @Controller：在一个类上添加@Controller注解，表明了这个类是一个控制器类。
 *  @ResponseBody：表示方法的返回值直接以指定的格式写入Http response body中，而不是解析为跳转路径。
 *  @RestController：相当于@Controller+@ResponseBody注解。  
    
 *  @RequestMapping：这个注解会将 HTTP 请求映射到 MVC 和 REST 控制器的处理方法上。 
 *  @GetMapping：这个注解是@RequestMapping的变体，可以接收GET的请求方式，在RestFul在处理获取资源的请求。
 *  @PostMapping：这个注解是@RequestMapping的变体，可以接收Post的请求方式，在RestFul在处理创建资源的请求。
 *  @PutMapping：这个注解是@RequestMapping的变体，可以接收Put的请求方式，在RestFul在处理修改资源的请求。
 *  @DeleteMapping：这个注解是@RequestMapping的变体，可以接收Delete的请求方式，在RestFul在处理删除资源的请求。
 *  @RequestParam：将请求参数绑定到你控制器的方法参数上。
 *  @PathVariable：接收请求路径中占位符的值。
 *  @RequestBody：用来接收前端传递给后端的json字符串中的数据的(请求体中的数据的)。

### Restful API的测试用例 ###

在我们实际开发中，需要对我们的接口进行测试，确保我们后端接口的可用，这时我们在不启动整个项目的情况下，可以利用到spring的测试框架辅助我们的开发。

在security-demo工程pom文件导入一下的依赖：

<dependency>
        <artifactId>spring-boot-starter-test</artifactId>
        <groupId>org.springframework.boot</groupId>
    </dependency>

然后就可以在我们项目工程中的test目录下创建我们的测试用例了，如：

// 如何运行测试用例
    @RunWith(SpringRunner.class)
    // 这是一个测试用例的类
    @SpringBootTest
    public class UserControllerTest {
    
    
        @Autowired
        private WebApplicationContext context;
        private MockMvc mockMvc;
    
    
        // 伪造mvc的环境，这样不会去启动我们的tomcat。提高测试速度。
        @Before
        public void setup(){
            mockMvc = MockMvcBuilders.webAppContextSetup(context).build();
        }
    
    
        @Test
        public void whenQuerySeccess() {
            // perform是执行的意思
            try {
                mockMvc.perform(
                        // 构建一个get请求
                        MockMvcRequestBuilders.get("/user")
                                // 添加我们的请求参数
                                .param("userName","hzh")
                                // 设置utf8的contentType
                                .contentType(MediaType.APPLICATION_JSON_UTF8)
                                )
                        // 执行上面的请求结果后，我们对请求结果的期望是返回的结果是ok（200）
                        .andExpect(MockMvcResultMatchers.status().isOk())
                        // 返回的结果是集合，集合的长度是3
                        .andExpect(MockMvcResultMatchers.jsonPath("$.length()").value(3));
            } catch (Exception e) {
                e.printStackTrace();
            }
    }

注意：由于存在大量静态方法，我们之后的讲解使用jdk1.5的静态方法导入特性。简化我们的代码。

接下来实现我们的第一个控制器：

@RestController
    @RequestMapping("user")
    public class UserController {
        @GetMapping
        public List<User> query(@RequestParam(required = false, name = "userName", defaultValue = "hzh") String nickName) {
            List<User> users = new ArrayList<>();
            users.add(new User());
            users.add(new User());
            users.add(new User());
            return users;
        }
    }

在上面的代码中，@RequestMapping定义了这个控制器的请求前缀，而@RequestParam对请求参数进行规范，name属性定义了请求参数名为username获取需要的参数值，若不设置name的值，默认会按照我们的方法参数名称去获取对相应的值。required和default属性定义了这个参数是可以省略的，若省略，默认值“hzh”。

写好我们的控制器后，我们可以运行从我们的测试用例去请求我们的控制器，而无需去把整个项目启动了。

### 使用对象接收请求的参数 ###

若一个请求需要传递多个参数，我们直接在方法参数上写接受的参数，这样会造成我们代码的繁琐和不美观。这时候，我们可以考虑用定义一个对象去接收我们的请求的参数。若是一个分页的功能，我们还可以使用spring为我们提供好的Pageable对象接收分页参数。

@GetMapping
      public List<User> query(UserQueryCondition condition, Pageable pageable) {
          System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.MULTI_LINE_STYLE));
          System.out.println(ReflectionToStringBuilder.toString(pageable, ToStringStyle.MULTI_LINE_STYLE));
          List<User> users = new ArrayList<>();
          users.add(new User());
          users.add(new User());
          users.add(new User());
          return users;
      }

这时候我们可以把测试用例写成这样：

try {
          String result = mockMvc.perform(
                  // 构建一个get请求
                  get("/user")
                          // 普通的参数
                          .param("userName", "hzh")
                          .param("age", "18")
                          .param("ageTo", "60")
                          .param("xxx", "yyy")
                          // 分页参数相关
                          // size表示每页显示数目
                          .param("size", "10")
                          // page表示第几页
                          .param("page", "3")
                          // sort表示排序的方式
                          .param("sort", "age.desc")
                          // 设置utf8的contentType
                          .contentType(MediaType.APPLICATION_JSON_UTF8))
                  // 执行上面的请求结果后，我们对请求结果的期望是返回的结果是ok（200）
                  .andExpect(status().isOk())
                  // 返回的结果是集合，集合的长度是3
                  .andExpect(jsonPath("$.length()").value(3))
                  // 获取返回的数据
                  .andReturn().getResponse().getContentAsString();
          System.out.println(result);
      } catch (Exception e) {
          e.printStackTrace();
    }

### @PathVariable的使用 ###

由于在Restful API中，有时候需要把参数直接放在URL中，那么我们该如何映射到我们的参数上呢?

下面我们以一个获取用户信息为例：

@RequestMapping(value = "/user/{id:\\d+}", method = RequestMethod.GET)
      public User getUserInfo(@PathVariable(name = "id") String id){
          User user = new User();
          user.setName("hzh");
          return user;
      }

我们使用到的正是@PathVariable的注解来获取url中的数据，并且为了规范我们的id只能是数字，我们还可以在@RequestMapping的value中加入正则表达式进行校验。

下面是我们的测试用例：

@Test
      public void whenGenInfoSuccess() {
          try {
              String result = mockMvc.perform(get("/user/1")
                      .contentType(MediaType.APPLICATION_JSON_UTF8))
                      .andExpect(status().isOk())
                      // 返回的json中有一个值为hzh的username
                      .andExpect(jsonPath("$.name").value("hzh"))
                      // 获取返回的数据
                      .andReturn().getResponse().getContentAsString();
              System.out.println(result);
          } catch (Exception e) {
              e.printStackTrace();
          }
      }

如果我们发送一个错误的请求，那么可以使用以下的方式说明这个请求是错误的，并且测试运行时控制台不会不爆红。

@Test
      public void whenGenInfoFail() {
          try {
              mockMvc.perform(get("/user/a")
                      .contentType(MediaType.APPLICATION_JSON_UTF8))
                      // 判断服务端返回的是一个4xx的状态码
                      .andExpect(status().is4xxClientError());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }

### @JsonView的使用 ###

在某一些请求返回的JSON中，我们并不希望返回某些字段，而在另一些请求中需要返回某些字段。比如我们在上面的代码中我们希望调用查询user集合只返回name，而查询每一个user返回的是name和password。我们可以在User类中使用接口的方式定义过个返回的视图。

public class User {
    
    
        public interface UserSimpleView{}
        // 继承的方式，简化视图字段的定义
        public interface UserDetailView extends UserSimpleView{}
    
    
        private String name;
    
    
        @NotBlank
        private String password;
    
    
        @JsonView(UserSimpleView.class)
        public String getName() {
            return name;
        }
    
    
        public void setName(String name) {
            this.name = name;
        }
    
    
        @JsonView(UserDetailView.class)
        public String getPassword() {
            return password;
        }
    
    
        public void setPassword(String password) {
            this.password = password;
        }
    
    
    }

并在Controller的方法上面也指定视图，这样就会自动过滤不需要返回的字段。

@RequestMapping(value = "/user", method = RequestMethod.GET)
    @JsonView(User.UserSimpleView.class)
    public List<User> query(UserQueryCondition condition, Pageable pageable) {}
        
    @RequestMapping(value = "/user/{id:\\d+}", method = RequestMethod.GET)
    @JsonView(User.UserDetailView.class)
    public User getUserInfo(@PathVariable(name = "id") String id){}

查看![format_png 2][]

[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X3BuZy9PalpmWGtUTTYxN2g0TjU5R3ZNck1uSXBhcGliUzNMRUF0anBiM3UwOVdab0dlcjR5MGxzd3hUNWliemppY1ZqeFdvaWFIazVKVGE4OXlyOWNWQWdMY2RUYlEvNjQw?x-oss-process=image/format,png
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxN2g0TjU5R3ZNck1uSXBhcGliUzNMRUFnRnNQNkRTaHU0M1c5aHdzc0NQSG9JcmRwbWE3WmtoOURWWUZCZWRyYnM2TU95RlFLMDdCN1EvNjQw?x-oss-process=image/format,png
[format_png 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9tbWJpei5xcGljLmNuL21tYml6X2pwZy9PalpmWGtUTTYxNDhpY3BEMHpSNGphYjRpYkNDbGZ1TDF4SFJQbG41VHNxdlRpYVZOUGxSc3BucWszWFJhaWNHNFhjUlJhSW9pY3NIY1hIcko4d2dNaWFpY0ZmUkEvNjQw?x-oss-process=image/format,png