Spring Boot 常用请求注解解析：看这一篇就够了！

在 Spring Boot / Spring MVC 里，这些注解本质上都是在做一件事：
👉 把 HTTP 请求里的数据，映射成 Java 方法参数。
我按「请求从哪来 → 用什么注解」的思路，给你一套系统 + 实战向的讲解。

一、核心请求参数注解（你最常用的）

1️⃣ @RequestParam

从 URL 查询参数 或 表单参数中取值

📌 典型来源：

• ?name=tom&age=18
• application/x-www-form-urlencoded
• multipart/form-data

GET /user?name=tom&age=18

@GetMapping("/user")
public String getUser(
        @RequestParam String name,
        @RequestParam Integer age) {
    return name + ":" + age;
}

🔹 特点：

• 默认必填
• 适合：分页、筛选、简单参数

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

2️⃣ @RequestBody

从 HTTP 请求体（Body）中取数据

📌 典型来源：

• Content-Type: application/json

POST /user
Content-Type: application/json

{
  "name": "tom",
  "age": 18
}

@PostMapping("/user")
public void saveUser(@RequestBody UserDTO user) {
}

🔹 特点：

• 只能用一次
• 自动 JSON → Java 对象
• 常用于：新增 / 修改接口

❗GET 请求 不能用 @RequestBody（规范上不推荐）

3️⃣ @PathVariable

从 URL 路径中取值

GET /user/1001

@GetMapping("/user/{id}")
public User getById(@PathVariable Long id) {
}

📌 RESTful 风格必备
👉 资源定位用路径，条件用参数

二、请求头 & Cookie

4️⃣ @RequestHeader

从请求头中取值

Authorization: Bearer xxx

@GetMapping("/info")
public void info(@RequestHeader("Authorization") String token) {
}

📌 常见场景：

• Token
• 设备信息
• 语言

5️⃣ @CookieValue

从 Cookie 中取值

@GetMapping("/cookie")
public void cookie(@CookieValue("SESSION") String sessionId) {
}

三、文件上传相关

6️⃣ @RequestPart

多用于：JSON + 文件混合上传

multipart/form-data

@PostMapping("/upload")
public void upload(
        @RequestPart("file") MultipartFile file,
        @RequestPart("info") UserDTO user) {
}

📌 区别：

7️⃣ MultipartFile

接收文件

@PostMapping("/upload")
public void upload(@RequestParam MultipartFile file) {
}

四、参数绑定（很多人没意识到）

8️⃣ 不写注解（隐式绑定）

Spring 会自动按规则绑定

GET /user?name=tom&age=18

@GetMapping("/user")
public void user(UserDTO user) {
}

📌 原理：

• QueryParam / Form → JavaBean
• 字段名自动匹配

❗不支持 JSON

五、请求 / 响应对象（底层）

9️⃣ HttpServletRequest / HttpServletResponse

@GetMapping("/raw")
public void raw(HttpServletRequest request) {
    request.getHeader("User-Agent");
}

📌 适合：

• 兼容老代码
• 读取原始请求

六、校验 & 绑定增强（高级）

🔟 @Validated / @Valid

参数校验

@PostMapping("/user")
public void save(@RequestBody @Valid UserDTO user) {
}

@NotNull
private String name;

1️⃣1️⃣ @ModelAttribute

将参数封装成对象（Form 场景）

@PostMapping("/form")
public void form(@ModelAttribute UserDTO user) {
}

📌 常见于：

• 表单提交
• MVC 页面（非前后端分离）

七、最全速查表（重点 ⭐）

八、真实项目中的使用建议（很重要）

✅ 推荐规范

• 查询：@RequestParam
• 新增/修改：@RequestBody
• ID：@PathVariable
• Token：@RequestHeader

❌ 不推荐

• 一个接口又 @RequestBody 又一堆 @RequestParam
• GET 用 @RequestBody