「springboot 2.x 系列」restful web 应用

使用 ​​@RestController​​​ 可以方便地编写 REST 服务，Spring 默认使用 ​​JSON​​ 作为输入和输出。

1、编写 RestController

编写 Rest Controller 只需要遵循以下要点：

总是标记 ​​@RestController​​​ 而不是 ​​@Controller​​​、​​@Component​​

使用 ​​@RestController​​​ 替代 ​​@Controller​​ 后，每个方法自动变成 API 接口方法。输入和输出只要能被 Jackson 序列化或反序列化为 JSON 就没有问题。

编写 ​​ApiController​​ 如下：

@RestController
public class ApiController
{
    @GetMapping("/users")
    public List<String> users(@RequestParam(value = "user_name") String userName )
    {
        return List.of("Apple", "Orange", "Banana", userName);
    }

    @GetMapping("/user/{user_name}")
    public String user(@PathVariable("user_name") String userName)
    {
        return userName;
    }
}

​​@GetMapping​​​ 表示 GET 类型的请求，括号里面的值 ​​"/users"​​ 表示请求地址

​​@RequestParam​​ 用于获取查询参数

​​@PathVariable​​ 用于获取路径参数

如果方法参数需要传入​​HttpServletRequest​​​、​​HttpServletResponse​​​或者 ​​HttpSession​​，直接添加这个类型的参数即可，Spring MVC 会自动按类型传入

测试如下：

​​192.168.123.100:8080/users?user_name=langya​​

即传入请求参数 user_name

​​192.168.123.100:8080/user/langya​​

即传入path路径传入参数 langya

2、请求地址分组

对 URL 进行分组，每组对应一个 Controller 是一种很好的组织形式，有效避免重复的URL映射。例如：

@RestController
@RequestMapping("/api")
public class ApiController{
  
}

此时上述的API请求路径变成 前缀（api）+ 路径，如 ​​/api/usesrs​​

3、请求与传参

常见的请求类型:

• GET ：请求从服务器获取特定资源。
• POST ：在服务器上创建一个新的资源。
• PUT ：更新服务器上的资源（客户端提供更新后的整个资源）。
• DELETE ：从服务器删除特定的资源。
• PATCH ：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新）

POST

• ReuqestBody 主要是处理 json 串格式的请求参数，要求使用方指定 header ​​content-type:application/json​​
• RequestBody 通常要求调用方使用 post 请求（也可以使用其他类型）
• RequestBody 接收到数据之后会自动将数据绑定到 Java 对象。系统会使用​​HttpMessageConverter​​​或者自定义的​​HttpMessageConverter​​将请求的 body 中的 json 字符串转换为 java 对象。

定义传入参数 ​​UserParam​​

这里使用了 ​​lombok​​ 依赖库 —— 为了精简代码，不用写一堆SET、GET属性函数

package com.langyastudio.springboot.bean.dto;

import lombok.Data;

/**
 * user 传入参数
 */
@Data
public class UserParam
{
    private String userName;
    private String nickName;
    private String telephone;
}

定义接口

@RestController
@RequestMapping("/api")
public class ApiController
{
    @PostMapping("/user/add")
    public UserParam addUser(@RequestBody UserParam userParam)
    {
        return userParam;
    }

    @PostMapping("/user/addex")
    public Map<String, Object> addUserEx(@RequestBody Map<String, Object> params)
    {
        return params;
    }
}

​​@RequestBody​​ 既可以使用 bean 实体类接收传入参数（建议使用），也可以使用 Map 接收（可读性、可维护性差）

测试如下：

​​192.168.123.100:8080/api/user/add​​

使用 Postman 测试时需要注意，使用 ​​Body -> raw -> json​​

一个请求方法只可以有一个​​@RequestBody​​​，但是可以有多个 ​​@RequestParam​​​ 和 ​​@PathVariable​​

完整代码：​​https://github.com/langyastudio/langya-tech/tree/springboot/restful/spring-boot​​