Spring Boot 请求参数接收控制指南
1. 概述
在Spring Boot项目中，我们可以通过不同的注解来接收来自HTTP请求的各种参数。本指南将详细介绍各种参数接收方式及其使用场景。
2. 有注解时参数接收方式对比
| 参数类型 | 注解 | 位置 | 适用HTTP方法 | 示例 |
|---|
| 路径参数 | @PathVariable | URL路径中 | GET, DELETE | /users/{id} |
| 查询参数 | @RequestParam | URL?后 | GET | /users?name=John |
| 请求体 | @RequestBody | 请求体 | POST, PUT, PATCH | JSON/XML数据 |
| 请求头 | @RequestHeader | HTTP头 | 任意 | Authorization: Bearer token |
| Cookie值 | @CookieValue | Cookie头 | 任意 | Cookie: JSESSIONID=xxx |
| 表单数据 | @RequestParam | 表单体 | POST | application/x-www-form-urlencoded |
| 文件上传 | @RequestParam | multipart/form-data | POST | 文件上传表单 |
3. 无注解时接收参数默认位置
Spring Boot 默认参数绑定规则（不加注解时）
| 请求类型 | 参数类型 | 默认绑定位置 | 示例 | 注意事项 |
|---|
| GET | 基本类型/String | 自动绑定到URL查询参数 | GET /user?name=Tom → public String getUser(String name) | 参数名必须与URL中的key一致 |
| POJO对象 | 自动绑定到URL查询参数 | GET /user?name=Tom&age=20 → public String getUser(User user) | 对象的字段名需与URL参数匹配 |
| 数组/集合 | 自动绑定到URL查询参数 | GET /user?ids=1,2,3 → public String getUser(List<Integer> ids) | 支持逗号分隔或同名参数（ids=1&ids=2） |
| POST | 基本类型/String | 表单数据 (Form Data) | POST /user (Content-Type: application/x-www-form-urlencoded) | 需设置Content-Type为表单类型 |
| POJO对象 | 表单数据或JSON请求体 | 若为application/json → 绑定到请求体；若为表单 → 按字段名匹配 | 需明确指定Content-Type，否则可能解析失败 |
| 数组/集合 | 表单数据或JSON请求体 | 同POJO规则 | 表单格式需用同名参数（names=Tom&names=Jerry） |
| MultipartFile | 文件上传 (multipart) | POST /upload (enctype="multipart/form-data") | 必须设置enctype="multipart/form-data" |
| PUT/PATCH | 所有类型 | JSON/XML请求体 | PUT /user { "name": "Tom" } → public String updateUser(User user) | 默认按@RequestBody处理，需显式加注解才能覆盖 |
| DELETE | 基本类型/String | URL查询参数 | DELETE /user?id=123 → public String deleteUser(Long id) | 与GET相同 |
| POJO对象 | 不支持 | - | DELETE通常只用路径参数或简单查询参数 |
关键规则总结
- GET/DELETE 请求：
- 参数默认绑定到 URL查询字符串（
?key=value）。 - POJO对象会按字段名自动拆解到查询参数。
- POST 请求：
- 默认按 表单数据（
application/x-www-form-urlencoded）解析。 - 若请求头为
Content-Type: application/json，则需显式加 @RequestBody，否则绑定失败。
- PUT/PATCH 请求：
- 默认按请求体（JSON/XML）处理，类似
@RequestBody行为，但实际开发中建议显式加注解。
- 特殊类型：
MultipartFile：仅在 multipart/form-data 类型的POST中自动绑定。- 数组/集合：支持URL查询参数（GET）或表单同名参数（POST）。
常见误区澄清
- 表单数据不会放在请求头
- 请求头仅用于元数据（如
Content-Type、Authorization等），表单内容一定在请求体。
- GET请求能否带表单数据？
- ❌ 不能。GET请求的参数只能通过URL查询字符串（
?key=value）传递，且长度受限。
- 不加注解时Spring Boot如何绑定表单数据？
- 默认按参数名匹配请求体中的表单字段（需参数名与表单字段名一致）。
- POST JSON vs 表单数据
- JSON数据必须显式使用
@RequestBody，而表单数据默认绑定（无需注解）。
4.HTTP请求参数位置自定义控制对照表
| 参数位置 | Spring Boot注解 | 手动提取方式 | 适用场景 | 示例请求 |
|---|
| URL路径参数 | @PathVariable | HttpServletRequest.getRequestURI() | RESTful资源标识 | GET /users/123 → id=123 |
| URL查询参数 | @RequestParam | request.getParameter("name") | 过滤条件、分页 | GET /users?name=Tom → name=Tom |
| 请求头 | @RequestHeader | request.getHeader("Authorization") | 认证令牌、客户端信息 | Header: Authorization: Bearer xxx |
| 请求体（JSON） | @RequestBody | InputStream + JSON解析库 | 复杂数据提交 | POST /users + {"name":"Tom"} |
| 请求体（表单） | @RequestParam | request.getParameterMap() | 传统表单提交 | POST /login + username=Tom&password=123 |
| 请求体（文件） | @RequestPart | MultipartHttpServletRequest | 文件上传 | POST /upload + multipart/form-data |
| Cookie | @CookieValue | request.getCookies() | 会话管理 | Cookie: sessionId=abc123 |
