Spring MVC @RequestParam注解全解析

@RequestParam 注解详解

@RequestParam 是 Spring MVC 中最常用的注解之一，用于从 HTTP 请求中提取查询参数（Query String）或表单数据。它主要处理 application/x-www-form-urlencoded 类型的请求（如 GET 请求或 POST 表单提交）。

一、核心作用

1. 参数绑定
   将请求中的参数值绑定到控制器方法的参数上。

   // 示例：获取请求中的 `name` 参数
   @GetMapping("/user")
   public String getUser(@RequestParam String name) {
       return "User: " + name;
   }
   

   • 访问 /user?name=Alice → 输出 User: Alice

2. 处理可选参数
   通过 required 属性控制参数是否必须。

   @GetMapping("/search")
   public String search(@RequestParam(required = false) String keyword) {
       return keyword != null ? "Results for: " + keyword : "All items";
   }
   

   • 访问 /search → 输出 All items
   • 访问 /search?keyword=spring → 输出 Results for: spring

二、关键属性

示例：

@PostMapping("/register")
public String register(
    @RequestParam("username") String user,  // 绑定到"username"参数
    @RequestParam(name = "age", defaultValue = "18") int age, // 缺省时默认为18
    @RequestParam(required = false) String hobby // 可选参数
) {
    // 业务逻辑
}

三、使用场景

1. 获取单个参数

   @GetMapping("/detail")
   public String detail(@RequestParam Long id) { ... }
   

2. 获取多个同名参数（如复选框）

   @PostMapping("/submit")
   public String submit(@RequestParam List<String> interests) {
       // interests 接收如 ?interests=music&interests=sports 的值
   }
   

3. 映射到 Map 对象

   @GetMapping("/filters")
   public String applyFilters(@RequestParam Map<String, String> filters) {
       // 接收所有参数，如 ?category=books&price=100
   }
   

四、注意事项

1. 参数名匹配规则

   • 默认根据方法参数名匹配请求参数（需编译时开启 -parameters 或显式指定 @RequestParam("param")）。
   • 若参数名未指定且编译未保留参数名，会抛出 MissingServletRequestParameterException。

2. 类型转换
   Spring 自动将 String 类型的参数转为目标类型（如 int, LocalDate 等）。

   • 转换失败 → 抛出 TypeMismatchException。

3. 与 @PathVariable 区别

   特性	@RequestParam	@PathVariable
   来源	查询字符串（?key=value）	URL 路径（/users/{id}）
   是否可选	可通过 required=false 设为可选	通常是必须的
   示例	/api?page=1	/api/users/123

4. 与 @RequestBody 区别

   • @RequestParam：处理 URL 编码数据（简单键值对）。
   • @RequestBody：处理 JSON/XML 等复杂数据（如 POST 请求体）。

五、常见问题解决方案

1. 参数缺失异常

   // 方案1: 设置 required=false
   @RequestParam(required = false) String param
   
   // 方案2: 提供默认值
   @RequestParam(defaultValue = "default") String param
   

2. 参数名冲突
   显式指定参数名避免歧义：

   public String query(
       @RequestParam("from") Date startDate,  // 使用"from"作为参数名
       @RequestParam("to") Date endDate
   ) { ... }
   

3. 接收数组/列表

   // 前端传参: ?ids=1,2,3 或 ?ids=1&ids=2
   public String getItems(@RequestParam List<Long> ids) { ... }
   

六、最佳实践

1. 简单查询：优先用 @RequestParam 处理过滤条件（如分页、排序）。
2. RESTful 路径：资源标识用 @PathVariable（如 /users/{id}），附加参数用 @RequestParam（如 /users?role=admin）。
3. 明确命名：避免依赖编译参数名，显式声明 @RequestParam("paramName")。
4. 设置默认值：对分页参数等推荐使用 defaultValue：

   @GetMapping("/posts")
   public Page<Post> getPosts(
       @RequestParam(defaultValue = "0") int page,
       @RequestParam(defaultValue = "10") int size
   ) { ... }
   

总结：@RequestParam 是 Spring 中处理请求参数的基石级注解，适用于大多数简单数据绑定场景。掌握其用法能高效处理 URL 编码数据，但复杂 JSON 数据应使用 @RequestBody。