Spring Boot 获取 HTTP 请求参数

• 请求：GET /search?keyword=手机&size=20
• 结果：搜索关键词：手机，返回数量：20

常用选项

• required = false：参数可选
• defaultValue = "xxx"：默认值（自动类型转换）

@RequestParam(required = false, defaultValue = "1") int page

如果参数名和方法参数名一致，@RequestParam 可省略（但建议保留，更清晰）。

参数如果多了，也可以绑定到实体上

1. 定义查询参数实体类

public class UserQuery {
    private String name;
    private Integer age;
    private String email;
    private Integer page = 1; // 默认值
    private Integer size = 10; // 必须提供 getter/setter（Lombok 可简化）

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    // ... 其他 getter/setter
}

注意：必须有 setter 方法，Spring 才能通过反射赋值。

2. Controller 中直接使用该实体（无需注解！）

@GetMapping("/users")
public List<User> searchUsers(UserQuery query) {
    System.out.println("查询条件：" + query.getName() + ", 年龄：" + query.getAge());
    // 调用 service 查询...
    return userService.search(query);
}

关键点：不需要加 @RequestParam 或 @RequestBody！ Spring 会自动将 ?name=张三&age=25&page=2 绑定到 UserQuery 对象。

3. 测试请求

GET /users?name=张三&age=25&[email protected]&page=2&size=20

Spring 会自动创建 UserQuery 实例，并调用：

• setName("张三")
• setAge(25)
• setEmail("[email protected]")
• setPage(2)
• setSize(20)

四、请求体（JSON）：@RequestBody

用于接收 POST/PUT 请求中的 JSON 数据（最常见于 REST API）。

示例

@PostMapping("/user")
public String createUser(@RequestBody User user) {
    return "创建用户：" + user.getName();
}

public class User {
    private String name;
    private int age;
    // getter/setter
}

• 结果：创建用户：李四

请求（Content-Type: application/json）：

POST /user
{
  "name": "李四",
  "age": 25
}

Spring Boot 默认用 Jackson 自动把 JSON 转成 Java 对象。 不能用于 GET 请求（GET 没有请求体）。

五、表单参数（传统 Web 表单）

HTML 表单提交的数据（Content-Type: application/x-www-form-urlencoded），Spring 会自动绑定到对象或参数。

方式一：用对象自动绑定（推荐）

@PostMapping("/login")
public String login(UserForm form) {
    // 不需要注解！
    return "用户名：" + form.getUsername();
}

public class UserForm {
    private String username;
    private String password;
    // getter/setter
}

表单：

<form action="/login" method="post">
    <input name="username" value="admin">
    <input name="password" value="123">
    <button type="submit">登录</button>
</form>

方式二：用 @RequestParam 一个个取

@PostMapping("/login")
public String login(@RequestParam String username, @RequestParam String password) {
    // ...
}

表单参数和查询参数都用 @RequestParam，Spring 会自动区分来源。 如果参数名和方法参数名一致，@RequestParam 可省略（但建议保留，更清晰）。

六、请求头（Header）：@RequestHeader

获取 HTTP 请求头中的信息，比如 Token、语言偏好等。

示例

@GetMapping("/profile")
public String profile(@RequestHeader("Authorization") String auth) {
    return "Token 是：" + auth;
}

• 结果：Token 是：Bearer abc123xyz

请求头：

Authorization: Bearer abc123xyz

可选 + 默认值

@RequestHeader(value = "Accept-Language", defaultValue = "zh-CN") String lang

七、特殊情况：获取原始请求对象

如果你需要更底层的操作，可以直接注入：

@GetMapping("/raw")
public void handle(HttpServletRequest request, HttpServletResponse response) {
    String ip = request.getRemoteAddr(); // 直接操作 request/response
}

但一般不推荐，除非做特殊处理（如文件下载、自定义响应流）。

八、总结

九、使用 Map 接收请求参数

尤其适用于：

• 参数结构动态不确定（比如第三方回调、表单字段不固定）
• 不想定义专门的 POJO 类
• 快速原型开发或调试

下面详细讲解 如何用 Map 接收各种请求参数，以及注意事项。

一、用 Map 接收表单或查询参数（最常见）

场景：application/x-www-form-urlencoded 或 URL 查询参数

@PostMapping("/submit")
public String handleForm(@RequestParam Map<String, String> params) {
    // params 会自动包含所有表单字段
    String name = params.get("username");
    String email = params.get("email");
    return "收到参数：" + params;
}

请求（表单或 curl）： → params = {username=alice, [email protected], age=25}

关键点：

• 必须加 @RequestParam！ 如果写成 Map<String, String> params（无注解），Spring 会认为你想用 @RequestBody，从而报错。
• 值类型是 String：所有参数值都会被转为字符串（即使传的是数字 "25"）。
• 支持多值吗？ ❌ Map<String, String> 只取第一个值。如果需要多值，用 MultiValueMap（见下文）。

二、用 Map 接收 JSON 请求体（动态 JSON）

如果你收到的是 结构不固定的 JSON，也可以用 Map 接收：

@PostMapping("/dynamic-json")
public String handleJson(@RequestBody Map<String, Object> payload) {
    // payload 是解析后的 JSON 对象
    String name = (String) payload.get("name");
    Integer age = (Integer) payload.get("age");
    return "JSON 内容：" + payload;
}

请求： → payload = {name=Bob, age=30, tags=[java, spring]}

关键点：

• 必须加 @RequestBody
• 值类型是 Object，可以是 String、Number、List、嵌套 Map 等
• Spring 使用 Jackson 自动将 JSON 转为 Map<String, Object>

三、高级用法：接收多值参数（如 ?tag=A&tag=B）

如果同一个参数名出现多次（如复选框），用 Map 会丢失数据。此时应使用 MultiValueMap：

@GetMapping("/search")
public String search(@RequestParam MultiValueMap<String, String> params) {
    List<String> tags = params.get("tag"); // 可能是 ["A", "B"]
    return "标签：" + tags;
}

请求：/search?tag=Java&tag=Spring → tags = ["Java", "Spring"]

MultiValueMap 是 Spring 提供的接口，常用实现是 LinkedMultiValueMap。

常见误区与注意事项

完整示例代码

@RestController
public class MapParamController {
    // 1. 接收表单/查询参数
    @PostMapping("/form-map")
    public Map<String, String> handleForm(@RequestParam Map<String, String> params) {
        return params;
    }

    // 2. 接收动态 JSON
    @PostMapping("/json-map")
    public Map<String, Object> handleJson(@RequestBody Map<String, Object> payload) {
        return payload;
    }

    // 3. 接收多值参数
    @GetMapping("/multi")
    public List<String> handleMulti(@RequestParam MultiValueMap<String, String> params) {
        return params.get("item");
    }
}

什么时候该用 Map？

总结

记住：表单/查询 → @RequestParam Map
JSON → @RequestBody Map
永远不要省略注解！

用好 Map，让你的接口更灵活；用好 POJO，让你的代码更健壮。根据场景选择即可！