Spring MVC @RequestParam注解全解析

@RequestParam 注解详解

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


一、核心作用
  1. 参数绑定

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

    java 复制代码
    // 示例:获取请求中的 `name` 参数
    @GetMapping("/user")
    public String getUser(@RequestParam String name) {
        return "User: " + name;
    }
    • 访问 /user?name=Alice → 输出 User: Alice
  2. 处理可选参数

    通过 required 属性控制参数是否必须。

    java 复制代码
    @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

二、关键属性
属性 说明 默认值
value / name 指定请求参数的名称 方法参数名
required 参数是否必须 true (必须)
defaultValue 参数缺失时的默认值
示例:
java 复制代码
@PostMapping("/register")
public String register(
    @RequestParam("username") String user,  // 绑定到"username"参数
    @RequestParam(name = "age", defaultValue = "18") int age, // 缺省时默认为18
    @RequestParam(required = false) String hobby // 可选参数
) {
    // 业务逻辑
}

三、使用场景
  1. 获取单个参数

    java 复制代码
    @GetMapping("/detail")
    public String detail(@RequestParam Long id) { ... }
  2. 获取多个同名参数(如复选框)

    java 复制代码
    @PostMapping("/submit")
    public String submit(@RequestParam List<String> interests) {
        // interests 接收如 ?interests=music&interests=sports 的值
    }
  3. 映射到 Map 对象

    java 复制代码
    @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. 参数缺失异常

    java 复制代码
    // 方案1: 设置 required=false
    @RequestParam(required = false) String param
    
    // 方案2: 提供默认值
    @RequestParam(defaultValue = "default") String param
  2. 参数名冲突

    显式指定参数名避免歧义:

    java 复制代码
    public String query(
        @RequestParam("from") Date startDate,  // 使用"from"作为参数名
        @RequestParam("to") Date endDate
    ) { ... }
  3. 接收数组/列表

    java 复制代码
    // 前端传参: ?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

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

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