Restful API详解

用户7386338

发布于 2020-05-29 07:32:18

2.4K00

代码可运行

文章被收录于专栏：Java患者Java患者

运行总次数：0

代码可运行

Restful API介绍

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

Restful API特点

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

Restful API的成熟模型

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

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

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

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

与传统请求方式对比

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文件导入一下的依赖：

<!-- 引入spring 的测试框架 -->
<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){}