RequestParam

本章聚焦 HTTP 请求参数的获取与绑定。DispatcherServlet 将请求分发到 Controller 方法后，方法的参数需要从请求中提取数据。@RequestParam 是最基础、最常用的参数绑定注解，负责将 URL 查询参数或表单字段映射到 Java 方法参数。掌握它，是理解后续 @RequestBody、@ModelAttribute 等高级绑定机制的前提。

定义与作用

@RequestParam 用于将 HTTP 请求中的查询参数（Query String）或表单数据（Form Data）绑定到 Controller 方法的参数上。

当客户端发送如下请求时：

GET /employees?name=zhangsan&age=25

Spring MVC 需要把 name=zhangsan 和 age=25 这两个键值对，分别赋给 Controller 方法中声明的参数。@RequestParam 就是完成这个"对号入座"工作的注解。

生活类比：快递分拣

想象飞翔科技的仓库收到一批快递包裹，每个包裹上贴有标签（name=zhangsan、age=25）。分拣员（@RequestParam）的工作是：

• 查看标签上的键（name、age）
• 找到对应工位的变量名（String name、int age）
• 把标签上的值（zhangsan、25）放到对应工位

如果某个工位要求"必须有包裹"（required=true），但标签缺失，分拣员就会报错（抛出异常）。如果工位贴了"缺货时用默认值"（defaultValue），分拣员就会按默认值处理。

核心原理

参数绑定完整流程

当 DispatcherServlet 调用 Controller 方法时，Spring MVC 通过 HandlerMethodArgumentResolver 解析每个方法参数。@RequestParam 的参数由 RequestParamMethodArgumentResolver 负责处理：

关键节点说明：

1. 参数名匹配：默认使用 Java 参数名作为请求参数名（需编译时保留参数名，或显式指定 name 属性）
2. 类型转换：Spring 内置 PropertyEditor 和 Converter 体系，自动将字符串转换为 int、long、boolean、Date 等类型
3. 必填校验：required=true 时，参数缺失立即抛出 MissingServletRequestParameterException
4. 默认值回退：defaultValue 仅在参数缺失时生效，空字符串 "" 不算缺失

适用位置与常用属性

@RequestParam 只能标注在 Controller 方法的参数 上。

属性组合行为矩阵

重要：defaultValue 仅在参数完全缺失时生效。如果客户端传了 name=（空字符串），不会触发默认值，而是绑定空字符串 ""。

完整示例

场景

飞翔科技员工管理系统的搜索功能，支持按姓名模糊查询、按部门精确筛选、按状态过滤。后端小崔使用 @RequestParam 接收这些筛选条件。

代码实现

package com.feixiang.web;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/employees")
public class EmployeeController {

    /**
     * 基础绑定：参数名与 Java 参数名一致
     */
    @GetMapping("/search")
    public String searchByName(@RequestParam String name) {
        return "搜索员工姓名包含: " + name;
    }

    /**
     * 显式指定参数名 + 非必填 + 默认值
     */
    @GetMapping("/filter")
    public String filter(
            @RequestParam(name = "dept", required = false) String department,
            @RequestParam(required = false, defaultValue = "ACTIVE") String status) {
        return String.format("部门=%s, 状态=%s", department, status);
    }

    /**
     * 多值参数：接收同名参数的多个值
     */
    @GetMapping("/batch")
    public String batchQuery(@RequestParam List<Long> ids) {
        return "批量查询员工ID: " + ids;
    }
}

HTTP 请求示例

示例 1：基础必填参数

curl "http://localhost:8080/employees/search?name=zhangsan"

响应：

搜索员工姓名包含: zhangsan

示例 2：参数缺失（required=true，报错）

curl "http://localhost:8080/employees/search"

响应（HTTP 400）：

{
  "timestamp": "2024-01-15T09:23:45.123+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Required request parameter 'name' for method parameter type String is not present"
}

示例 3：非必填 + 默认值

curl "http://localhost:8080/employees/filter?dept=技术部"

响应：

部门=技术部, 状态=ACTIVE

注意 status 参数未传，自动使用默认值 ACTIVE。

示例 4：多值参数

curl "http://localhost:8080/employees/batch?ids=101&ids=102&ids=103"

响应：

批量查询员工ID: [101, 102, 103]

易错场景与面试考点

误区一：不加 @RequestParam 也能绑定

现象：有时看到代码这样写：

@GetMapping("/search")
public String search(String name) {  // 没有 @RequestParam
    return "搜索: " + name;
}

解释：对于简单类型（String、int 等），Spring MVC 默认行为等价于 @RequestParam（参数名匹配、类型转换都生效）。但显式标注是最佳实践，原因有三：

1. 代码意图清晰，阅读者一眼知道数据从请求参数来
2. 可以使用 required、defaultValue 等属性精确控制
3. 避免与 @PathVariable、@RequestBody 等注解产生语义混淆

误区二：defaultValue 对空字符串生效

错误认知："客户端传 status=，会触发 defaultValue"

纠正：defaultValue 只在参数键完全不存在时生效。status= 表示参数存在但值为空字符串，此时绑定空字符串，不走默认值。

验证：

curl "http://localhost:8080/employees/filter?dept=技术部&status="

响应：

部门=技术部, 状态=        ← 空字符串，不是 ACTIVE

误区三：Date 类型自动绑定失败

现象：@RequestParam Date birthDate 报错，提示无法转换。

解决：Spring 默认只支持 yyyy/MM/dd 格式。需要注册自定义 Converter 或 @DateTimeFormat：

@GetMapping("/by-date")
public String byDate(@RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate hireDate) {
    return "入职日期: " + hireDate;
}

面试高频：required=true 和 false 的区别

标准回答：

• required=true（默认）：请求中必须包含该参数，否则 Spring MVC 抛出 MissingServletRequestParameterException，返回 HTTP 400
• required=false：参数可选，缺失时方法参数值为 null。注意：如果参数是基本类型（int、boolean），缺失会报错，因为基本类型不能为 null。此时应改用包装类（Integer、Boolean）或设置 defaultValue

小结

@RequestParam 是 Spring MVC 获取 HTTP 查询参数和表单数据的核心注解。它通过参数名匹配、自动类型转换、必填校验和默认值回退，将客户端传来的字符串键值对映射为 Java 方法参数。

核心要点：

• 默认 required=true，参数缺失报 400
• defaultValue 仅在参数完全缺失时生效，空字符串不走默认值
• 简单类型参数可省略注解，但显式标注是最佳实践
• 多值参数用 List<T> 或数组接收

本章与全局的关系：本章讲解了"如何从请求 URL 和表单中获取零散参数"。下一节 @RequestHeader 将讲解如何获取 HTTP 请求头中的元数据。