Spring MVC参数注解：@RequestParam、@RequestBody与@PathVariable详解

1. 三种注解的核心区别与应用场景

在Spring MVC开发中，@RequestParam、@RequestBody和@PathVariable这三个注解是处理HTTP请求参数的"三剑客"。很多刚接触Spring的开发者容易混淆它们的用法，今天我就结合自己五年的实战经验，带大家彻底搞懂它们的使用场景和底层原理。

先看一个日常开发中的典型场景：假设我们要开发一个用户管理系统，需要实现用户查询、创建和详情查看三个接口。这三个接口正好对应三种参数传递方式：

java复制// 查询用户列表（过滤条件用@RequestParam）
@GetMapping("/users")
public List<User> getUsers(@RequestParam String name, @RequestParam int age) {}

// 创建用户（复杂对象用@RequestBody）
@PostMapping("/users")
public User createUser(@RequestBody UserDTO dto) {}

// 查看用户详情（路径变量用@PathVariable）
@GetMapping("/users/{userId}")
public User getUser(@PathVariable Long userId) {}

2. @RequestParam深度解析

2.1 基本使用与原理

@RequestParam用于获取URL查询参数，也就是?后面的键值对。它的底层是通过ServletRequest.getParameter()方法获取值的。来看个电商平台的例子：

java复制@GetMapping("/products")
public Page<Product> searchProducts(
    @RequestParam String keyword,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(required = false) String sort) {
    // 分页查询逻辑
}

这个接口可以这样调用：/products?keyword=手机&page=2&sort=price_desc

2.2 实战技巧与坑点

1. 默认值设置：对于非必传参数，一定要设置defaultValue，否则当参数缺失时会报400错误
2. 数组参数：可以接收多个同名参数，比如?categories=1&categories=2
3. Content-Type影响：只适用于application/x-www-form-urlencoded和multipart/form-data

踩坑记录：曾经遇到一个诡异的bug，前端用axios默认发送的是application/json，导致@RequestParam获取不到值。解决方案是明确设置headers中的Content-Type。

3. @RequestBody核心机制

3.1 工作原理剖析

@RequestBody用于接收请求体中的JSON/XML数据，Spring会使用HttpMessageConverter将请求体反序列化为Java对象。它的典型应用场景是创建或更新复杂对象：

java复制@PostMapping("/orders")
public Order createOrder(@RequestBody OrderCreateVO vo) {
    // 订单创建逻辑
}

3.2 使用要点

1. 只能用在POST/PUT/PATCH请求：因为GET请求没有请求体
2. 必须指定Content-Type：通常是application/json
3. 数据校验：结合@Valid注解实现自动验证

java复制@PostMapping("/users")
public User createUser(@Valid @RequestBody UserDTO dto) {
    // 会自动校验UserDTO中的@NotNull等注解
}

3.3 性能优化建议

对于大JSON数据，可以考虑使用Streaming API处理：

java复制@PostMapping("/big-data")
public void handleBigData(InputStream requestBody) {
    // 使用流式处理避免内存溢出
}

4. @PathVariable详解

4.1 RESTful风格必备

@PathVariable用于获取URL路径中的变量，是RESTful API设计的核心元素：

java复制@GetMapping("/products/{id}")
public Product getProduct(@PathVariable Long id) {
    // 根据ID查询商品
}

对应的URL示例：/products/123

4.2 高级用法

1. 正则表达式约束：可以限制路径变量的格式

java复制@GetMapping("/products/{id:\\d+}")

2. Map接收多个变量：

java复制@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
    @PathVariable Long ownerId,
    @PathVariable Long petId,
    @PathVariable Map<String, String> vars) {
    // vars包含所有路径变量
}

5. 三种注解的对比决策

通过表格对比三种注解的关键特性：

6. 混合使用实战案例

在实际开发中，经常需要组合使用这些注解。比如实现一个分页查询商品详情的接口：

java复制@GetMapping("/categories/{categoryId}/products")
public Page<Product> getProductsByCategory(
    @PathVariable Long categoryId,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(defaultValue = "10") int size,
    @RequestParam(required = false) String sort) {
    // 实现分页查询逻辑
}

调用示例：/categories/5/products?page=2&size=20&sort=price,desc

7. 常见问题排查指南

1. 400 Bad Request错误：

   • @RequestParam：检查参数是否缺失（required=true时）
   • @RequestBody：检查JSON格式是否正确
   • @PathVariable：检查路径变量是否存在

2. 415 Unsupported Media Type：

   • 确保@RequestBody接口的Content-Type是application/json

3. 类型转换错误：

   • 比如用@RequestParam接收"abc"到int参数

4. URL编码问题：

   • 路径变量中的特殊字符需要编码处理

8. 最佳实践建议

1. 遵循RESTful规范：

   • 资源ID用@PathVariable
   • 过滤条件用@RequestParam
   • 创建/更新用@RequestBody

2. 参数校验要全面：

   • 结合javax.validation约束注解
   • 对@RequestParam也要做非空检查

3. 保持接口一致性：

   • 相同类型的参数尽量使用相同的注解方式
   • 比如所有ID都用@PathVariable

4. 文档化你的API：

   • 使用Swagger等工具生成接口文档
   • 明确每个参数的注解类型和约束

在实际项目中，我建议团队制定统一的参数传递规范。比如我们团队规定：

• 必须使用@PathVariable获取资源ID
• 简单查询条件用@RequestParam
• 所有POST/PUT请求必须使用@RequestBody
• 分页参数统一用page和size命名

这样的规范能显著提高代码可读性和维护性。