SpringMVC 参数绑定机制：`@RequestParam`, `@PathVariable`, `@RequestBody` 的使用

SpringMVC 参数绑定机制：@RequestParam, @PathVariable, @RequestBody 的那些事儿

各位看官，大家好！今天咱们来聊聊 SpringMVC 中参数绑定这档子事儿。话说，咱们辛辛苦苦写的 Controller，就是用来处理各种请求的。请求来了，总得知道用户想干嘛吧？用户想干嘛，通常都是通过各种参数来告诉我们的。 SpringMVC 提供了多种参数绑定机制，帮助我们轻松地从请求中提取数据。其中，最常用的就是 @RequestParam, @PathVariable, 和 @RequestBody 这三位大咖了。今天，咱们就来好好地认识一下它们，看看它们各自的绝招，以及在什么场合下使用它们。

一、@RequestParam：你要啥我都给你拿

首先登场的是 @RequestParam 大哥。它的职责很简单：从请求参数中获取数据。这里的请求参数，通常指的是 URL 中的查询参数（Query Parameters），或者表单提交的数据。

1.1 语法与用法

@RequestParam 的语法如下：

@RequestParam(value = "参数名", required = 是否必须, defaultValue = "默认值") 数据类型  参数名

value: 指定要绑定的请求参数的名字。如果省略，则默认使用方法参数的名字。
required: 指定该参数是否必须。默认为 true，表示该参数必须存在。如果设为 false，则表示该参数可以不存在。
defaultValue: 指定参数的默认值。如果请求中没有该参数，则使用默认值。

1.2 示例：从 URL 中获取参数

假设我们有一个 Controller 方法，需要从 URL 中获取用户名和年龄：

@Controller
public class UserController {

    @GetMapping("/user")
    @ResponseBody
    public String getUser(@RequestParam("name") String name,
                          @RequestParam(value = "age", required = false, defaultValue = "18") int age) {
        return "Hello, " + name + "! You are " + age + " years old.";
    }
}

访问 http://localhost:8080/user?name=Tom&age=25，会得到：

Hello, Tom! You are 25 years old.

访问 http://localhost:8080/user?name=Tom，会得到：

Hello, Tom! You are 18 years old.

因为 age 参数设置了 required = false 和 defaultValue = "18"，所以即使 URL 中没有 age 参数，程序也不会报错，而是使用默认值 18。

如果没有传递 name 参数，会报错，因为 name 参数默认 required = true。

1.3 示例：从表单中获取参数

假设我们有一个 HTML 表单：

<form action="/submit" method="post">
    <input type="text" name="username" value="John"><br>
    <input type="password" name="password" value="123456"><br>
    <button type="submit">Submit</button>
</form>

对应的 Controller 方法：

@Controller
public class FormController {

    @PostMapping("/submit")
    @ResponseBody
    public String submitForm(@RequestParam("username") String username,
                             @RequestParam("password") String password) {
        return "Username: " + username + ", Password: " + password;
    }
}

当用户提交表单后， SpringMVC 会自动将表单中的 username 和 password 参数绑定到 Controller 方法的参数上。

1.4 使用场景总结

从 URL 查询参数中获取数据。
从表单提交的数据中获取数据。
参数是简单类型（如 String, int, boolean 等）。

1.5 注意事项

如果请求参数的名字和方法参数的名字相同，可以省略 @RequestParam 的 value 属性。例如：

@GetMapping("/test")
@ResponseBody
public String test(@RequestParam String param1, @RequestParam String param2) {
    // ...
}

@RequestParam 可以用于处理数组类型的参数。例如：

@GetMapping("/skills")
@ResponseBody
public String skills(@RequestParam("skill") List<String> skills) {
    return "Skills: " + skills;
}

访问 http://localhost:8080/skills?skill=Java&skill=Spring&skill=Hibernate，会得到：

Skills: [Java, Spring, Hibernate]

二、@PathVariable：路径上的小秘密

接下来，我们来认识一下 @PathVariable 小弟。它的作用是从 URL 的路径变量中获取数据。路径变量，顾名思义，就是 URL 路径中的一部分，用 {} 括起来。

2.1 语法与用法

@PathVariable 的语法如下：

@PathVariable(value = "路径变量名", required = 是否必须) 数据类型  参数名

value: 指定要绑定的路径变量的名字。如果省略，则默认使用方法参数的名字。
required: 指定该参数是否必须。默认为 true，表示该参数必须存在。如果设为 false，则表示该参数可以不存在。(但通常不建议这么做，路径变量不存在，路由就可能出错)

2.2 示例：从 URL 路径中获取用户 ID

@Controller
public class UserController {

    @GetMapping("/user/{id}")
    @ResponseBody
    public String getUser(@PathVariable("id") Long id) {
        return "User ID: " + id;
    }
}

访问 http://localhost:8080/user/123，会得到：

User ID: 123

2.3 示例：多个路径变量

@GetMapping("/product/{category}/{id}")
@ResponseBody
public String getProduct(@PathVariable("category") String category,
                           @PathVariable("id") Long id) {
    return "Category: " + category + ", Product ID: " + id;
}

访问 http://localhost:8080/product/electronics/456，会得到：

Category: electronics, Product ID: 456

2.4 使用场景总结

RESTful 风格的 API 设计。
从 URL 路径中提取数据，例如：用户 ID、商品 ID 等。
构建层次结构的 URL。

2.5 注意事项

@PathVariable 必须和 @GetMapping, @PostMapping 等注解中的 URL 模板配合使用。例如：@GetMapping("/user/{id}")。
如果路径变量的名字和方法参数的名字相同，可以省略 @PathVariable 的 value 属性。例如：

@GetMapping("/book/{bookId}")
@ResponseBody
public String getBook(@PathVariable Long bookId) {
    // ...
}

路径变量是 URL 的一部分，因此需要保证 URL 的合法性。例如，如果路径变量是数字类型，需要确保 URL 中的值也是数字。
@PathVariable 可以搭配正则表达式使用，做更精确的匹配。
例如：

@GetMapping("/user/{userId:[0-9]+}") // 限制 userId 只能是数字
@ResponseBody
public String getUser(@PathVariable("userId") Long userId) {
   return "User ID: " + userId;
}

三、@RequestBody：身体里装着啥秘密？

最后，我们来认识一下 @RequestBody 老兄。它的作用是从请求体（Request Body）中获取数据。请求体通常是 JSON 或 XML 格式的数据。

3.1 语法与用法

@RequestBody 的语法如下：

@RequestBody 数据类型  参数名

@RequestBody 没有 value、required 和 defaultValue 属性。它直接将整个请求体的内容绑定到方法参数上。

3.2 示例：接收 JSON 数据

假设客户端发送一个 JSON 请求：

{
  "name": "Alice",
  "age": 30,
  "email": "[email protected]"
}

对应的 Controller 方法：

@Controller
public class UserController {

    @PostMapping("/user")
    @ResponseBody
    public String createUser(@RequestBody User user) {
        return "User: " + user;
    }
}

// 定义一个 User 类
class User {
    private String name;
    private int age;
    private String email;

    // 省略 getter 和 setter 方法

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    @Override
    public String toString() {
        return "User{" +
                "name='" + name + ''' +
                ", age=" + age +
                ", email='" + email + ''' +
                '}';
    }
}

SpringMVC 会自动将 JSON 数据转换为 User 对象。要实现这个功能，需要配置消息转换器（Message Converter）。 SpringMVC 默认使用 MappingJackson2HttpMessageConverter 来处理 JSON 数据。如果你使用的是 Spring Boot，则无需手动配置，Spring Boot 会自动配置好。

3.3 示例：接收 XML 数据

如果客户端发送一个 XML 请求：

<user>
    <name>Bob</name>
    <age>40</age>
    <email>[email protected]</email>
</user>

对应的 Controller 方法不变，只需要在 User 类上添加 XML 相关的注解：

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "user") // 指定 XML 根元素的名字
class User {
    private String name;
    private int age;
    private String email;

    // 省略 getter 和 setter 方法
}

并且需要添加 Jaxb2RootElementHttpMessageConverter 这个消息转换器。

3.4 使用场景总结

接收 JSON 或 XML 格式的请求数据。
处理复杂的对象类型。
RESTful 风格的 API 设计。

3.5 注意事项

使用 @RequestBody 需要配置消息转换器。
请求体的 Content-Type 必须和消息转换器支持的类型一致。例如，如果请求体是 JSON 数据，则 Content-Type 应该是 application/json。
如果请求体的数据格式不正确，或者无法转换为目标对象，会抛出异常。
@RequestBody 通常和 @PostMapping, @PutMapping, @PatchMapping 等注解一起使用，因为这些请求通常会携带请求体。

四、总结与比较

特性	@RequestParam	@PathVariable	@RequestBody
数据来源	URL 查询参数或表单数据	URL 路径变量	请求体 (JSON, XML 等)
适用场景	获取简单类型的参数，例如：用户名、页码等	RESTful API，获取资源 ID 等	接收复杂的对象，例如：用户信息、订单信息等
常用请求方法	GET, POST	GET, PUT, DELETE	POST, PUT, PATCH
是否必须	可以设置 required 属性	可以设置 required 属性 (通常不建议设为 false)	默认必须，如果请求体为空会报错
默认值	可以设置 defaultValue 属性	无	无
消息转换器	不需要	不需要	需要 (例如：MappingJackson2HttpMessageConverter)

简单记忆口诀：

@RequestParam: 问号（URL 参数）后面的都是我的菜！
@PathVariable: 斜杠（URL 路径）里面的秘密我来揭！
@RequestBody: 身体（请求体）里面藏着宝，我来掏！

五、实战演练：一个完整的例子

现在，我们来一个完整的例子，把这三个注解都用上。假设我们要开发一个用户管理 API：

创建用户（POST /users）: 接收 JSON 格式的用户信息，使用 @RequestBody。
获取用户（GET /users/{id}）: 从 URL 路径中获取用户 ID，使用 @PathVariable。
搜索用户（GET /users?name=xxx&age=xxx）: 从 URL 查询参数中获取搜索条件，使用 @RequestParam。

代码如下：

@Controller
@RequestMapping("/users")
public class UserController {

    // 创建用户
    @PostMapping
    @ResponseBody
    public String createUser(@RequestBody User user) {
        // 保存用户到数据库
        System.out.println("Creating user: " + user);
        return "User created successfully: " + user;
    }

    // 获取用户
    @GetMapping("/{id}")
    @ResponseBody
    public String getUser(@PathVariable("id") Long id) {
        // 从数据库中获取用户
        System.out.println("Getting user with ID: " + id);
        return "User ID: " + id;
    }

    // 搜索用户
    @GetMapping
    @ResponseBody
    public String searchUsers(@RequestParam(value = "name", required = false) String name,
                              @RequestParam(value = "age", required = false) Integer age) {
        // 根据条件搜索用户
        System.out.println("Searching users with name: " + name + ", age: " + age);
        return "Searching users with name: " + name + ", age: " + age;
    }
}

// 用户类 (简化版)
class User {
    private String name;
    private int age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "User{" +
                "name='" + name + ''' +
                ", age=" + age +
                '}';
    }
}

这个例子展示了 @RequestParam, @PathVariable, 和 @RequestBody 在实际项目中的应用。通过合理地使用这些注解，可以使 Controller 代码更加简洁、易读、易维护。

六、总结

希望通过今天的讲解，大家对 SpringMVC 的参数绑定机制有了更深入的了解。记住， @RequestParam, @PathVariable, 和 @RequestBody 各有千秋，要根据不同的场景选择合适的注解。掌握了这些技巧，你就可以轻松地处理各种请求参数，写出优雅高效的 SpringMVC 代码了。以后再遇到参数绑定问题，就不用再抓耳挠腮了！祝大家编程愉快！

SpringMVC 参数绑定机制：@RequestParam, @PathVariable, @RequestBody 的那些事儿

一、@RequestParam： 你要啥我都给你拿

二、@PathVariable： 路径上的小秘密

三、@RequestBody： 身体里装着啥秘密？