常见的注解梳理：
url参数与表单参数形式相同都是key-value，但是url参数在url中，尔表单参数实在请求体中
对比维度 |
URL 参数 |
表单参数（请求体） |
位置 |
查询字符串（URL 末尾）或路径中 |
HTTP 请求体（Body）中 |
安全性 |
完全暴露在 URL 中，敏感数据易泄露 |
POST 请求体中的参数更隐蔽 |
数据量限制 |
受 URL 长度限制（浏览器通常限制 2000 字符） |
无严格限制（取决于服务器配置） |
数据类型支持 |
仅支持简单字符串（需编码） |
支持复杂类型（JSON、XML、文件等） |
语义化 |
路径参数用于标识资源（如 RESTful 风格） |
用于传递具体数据内容 |
典型场景 |
查询条件（如 ）、资源定位（如 ） |
表单提交（注册、登录）、文件上传 |
Spring 框架注解 |
（查询字符串）、 （路径参数） |
（JSON 等结构化数据） |
何时需要加注解、加什么注解，以及何时可以省略注解。
一、核心注解分类与作用
注解 |
参数来源 |
绑定逻辑 |
|
URL 参数（Query String）或表单数据 |
从 URL 或表单中获取单个参数值，支持类型转换（如 String→Integer） |
|
URL 路径变量（如 ） |
从路径中提取变量值（如 中的 ） |
|
HTTP 请求体（如 JSON、XML） |
将请求体中的数据反序列化为 Java 对象（需配合 Jackson 等序列化工具） |
|
HTTP 请求头（如 、 ） |
获取请求头中的值 |
|
HTTP Cookie（如 ） |
获取 Cookie 中的值 |
无注解 |
URL 参数（简单类型）或请求体（复杂类型） |
根据参数类型自动判断：简单类型走 ，复杂类型走 （容易混淆，需谨慎） |
二、按参数类型和来源选择注解
1. 简单类型参数（String、int、Long 等）
规则：
- 从 URL 参数或表单中获取值，推荐加
@RequestParam，显式声明参数来源。 - 若参数名与方法参数名一致且为可选参数，可省略
@RequestParam（但可能导致歧义，不推荐）。
// 推荐写法：显式指定参数来源和规则 @GetMapping("/api/users") public List<User> getUsers( @RequestParam(required = false, defaultValue = "1") int pageNum, @RequestParam(required = false, defaultValue = "10") int pageSize, @RequestParam String keyword ) { // 请求示例：/api/users?pageNum=2&keyword=test } // 省略@RequestParam的写法（不推荐，可能导致歧义） @GetMapping("/api/users") public List<User> getUsers(int pageNum, String keyword) { // 等价于@RequestParam，但无法设置required或defaultValue }
2. 路径变量（Path Variable）
规则：
- 必须加
@PathVariable，从 URL 路径中提取变量。多层要写多次
@GetMapping("/api/users/{id}") public User getUser(@PathVariable Long id) { // 请求路径：/api/users/123 → id=123 } // 路径变量名与参数名不一致时的写法 @GetMapping("/api/users/{userId}") public User getUser(@PathVariable("userId") Long id) { // 将{userId}绑定到参数id }
3. 复杂类型参数（自定义对象、List、Map 等）
规则：
- 若参数来自请求体（JSON/XML），必须加
@RequestBody。 - 若参数来自URL / 表单，需加
@RequestParam（List / 数组）或@ModelAttribute（自定义对象）。
案例 1：接收 JSON 对象
@PostMapping("/api/users") public void createUser(@RequestBody User user) { // 请求体：{"name":"Alice","age":25} → 自动映射到User对象 }
案例 2：接收 URL 参数中的 List
@GetMapping("/api/users") public List<User> getUsers(@RequestParam List<Long> ids) { // 请求：/api/users?ids=1&ids=2&ids=3 → ids=[1,2,3] }
案例 3：接收表单数据到对象（需表单格式）
@PostMapping("/api/users") public void createUser(@ModelAttribute User user) { // 表单参数：name=Alice&age=25 → 自动映射到User对象 // 注意：Content-Type必须是application/x-www-form-urlencoded }
4. 请求头和 Cookie 参数
规则：
- 从请求头获取值，加
@RequestHeader。 - 从 Cookie 获取值，加
@CookieValue。
案例：
@GetMapping("/api/profile") public User getProfile( @RequestHeader("Authorization") String token, @CookieValue("session_id") String sessionId ) { // 从请求头获取token，从Cookie获取session_id }
5. 文件上传参数
规则：
- 单文件上传用
@RequestParam+MultipartFile。 - 多文件上传用
@RequestParam+MultipartFile[]或List<MultipartFile>。
案例：
@PostMapping("/api/upload") public void uploadFile(@RequestParam("file") MultipartFile file) { // 处理单个上传文件 } @PostMapping("/api/upload/multiple") public void uploadFiles(@RequestParam("files") List<MultipartFile> files) { // 处理多个上传文件 }
三、常见误区与最佳实践
误区 1：List / 数组参数省略@RequestParam
错误示例：
@GetMapping("/api/users") public List<User> getUsers(List<Long> ids) { // 错误！Spring会尝试从请求体解析JSON // ids 会为null或空列表 }
正确写法：
@GetMapping("/api/users") public List<User> getUsers(@RequestParam List<Long> ids) { // 正确 // 请求：/api/users?ids=1&ids=2 → ids=[1,2] }
误区 2：JSON 请求体省略@RequestBody
错误示例：
@PostMapping("/api/users") public void createUser(User user) { // 错误！若未配置HttpMessageConverter，会导致参数绑定失败 // user对象的字段全为null }
正确写法：
@PostMapping("/api/users") public void createUser(@RequestBody User user) { // 正确 // 从JSON请求体解析User对象 }
最佳实践总结
- 显式优于隐式：
- 始终使用
@RequestParam、@PathVariable、@RequestBody明确参数来源，避免省略注解导致的歧义。
- 复杂对象用
@RequestBody：
- 当前端传递 JSON/XML 时，必须用
@RequestBody接收，否则参数无法正确绑定。
- List / 数组用
@RequestParam：
- 从 URL 参数接收 List / 数组时，必须加
@RequestParam。
- 路径变量必加
@PathVariable：
- 从 URL 路径中提取变量时，必须显式使用
@PathVariable。
