SpringBoot?中處理接口傳參時常用的注解及使用場景分析

更新時間：2026年02月03日 09:31:49 作者：Elieal

SpringBoot提供了多種注解來處理不同位置的參數(shù),包括路徑參數(shù)、URL請求參數(shù)、請求體參數(shù)、請求頭參數(shù)和Cookie參數(shù),每種注解都有其特定的使用場景和核心用法,下面給大家介紹SpringBoot中處理接口傳參時常用的注解及使用場景分析,感興趣的朋友跟隨小編一起看看吧

1. 路徑參數(shù)（URL 中 /{xxx} 形式）：@PathVariable
2. URL 請求參數(shù)（?key=value 形式）：@RequestParam
3. 請求體參數(shù)（JSON/XML）：@RequestBody
4. 請求頭參數(shù)：@RequestHeader
5. Cookie 參數(shù)：@CookieValue
6. 無注解（自動綁定）
總結(jié)

SpringBoot 接收前端參數(shù)的核心注解都基于 Spring MVC，主要解決不同位置參數(shù)（URL 路徑、請求頭、請求體、URL 參數(shù)等）的綁定問題，下面按使用場景分類說明：

1. 路徑參數(shù)（URL 中 /{xxx} 形式）：@PathVariable

核心作用：綁定 URL 路徑中的動態(tài)參數(shù)（如/user/123中的123）到方法參數(shù)。
使用場景：RESTful 風格接口，獲取資源 ID、分類標識等。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    // 訪問路徑：/user/123
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "獲取到用戶ID：" + id;
    }
    // 多路徑參數(shù) + 指定參數(shù)名（參數(shù)名與路徑變量名不一致時）
    @GetMapping("/{id}/order/{orderId}")
    public String getUserOrder(
        @PathVariable("id") Long userId, 
        @PathVariable("orderId") Long orderId
    ) {
        return "用戶ID：" + userId + "，訂單ID：" + orderId;
    }
}

關鍵說明：默認要求路徑變量名與方法參數(shù)名一致，不一致時需用@PathVariable("xxx")指定。

2. URL 請求參數(shù)（?key=value 形式）：@RequestParam

核心作用：綁定 URL 中?后的查詢參數(shù)（如/user?name=張三）到方法參數(shù)。
使用場景：分頁、篩選、簡單條件查詢（如page=1&size=10）。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    // 訪問路徑：/user/list?name=張三&age=20
    @GetMapping("/list")
    public String getUserList(
        @RequestParam String name, // 必傳參數(shù)
        @RequestParam(required = false, defaultValue = "18") Integer age // 非必傳+默認值
    ) {
        return "姓名：" + name + "，年齡：" + age;
    }
}

關鍵屬性：
- required：是否必傳，默認true（不傳會報錯）；
- defaultValue：參數(shù)未傳時的默認值（僅required=false時生效）；
- value：指定 URL 參數(shù)名（與方法參數(shù)名不一致時用）。

3. 請求體參數(shù)（JSON/XML）：@RequestBody

核心作用：綁定 HTTP 請求體（通常是 JSON 格式）到 Java 對象（POJO）。
使用場景：POST/PUT 請求，傳遞復雜數(shù)據(jù)（如新增 / 修改用戶信息）。
核心用法：

// 1. 定義POJO（接收前端JSON）
public class UserDTO {
    private String name;
    private Integer age;
    // 省略getter/setter
}
// 2. 控制器接收參數(shù)
@RestController
@RequestMapping("/user")
public class UserController {
    // 前端POST請求體：{"name":"張三","age":20}
    @PostMapping("/add")
    public String addUser(@RequestBody UserDTO userDTO) {
        return "新增用戶：" + userDTO.getName() + "，年齡：" + userDTO.getAge();
    }
}

關鍵說明：
- 僅支持 POST/PUT 等有請求體的請求（GET 請求無請求體，用會報錯）；
- 前端需保證 Content-Type 為application/json，否則解析失敗；
- 可搭配@Valid/@Validated做參數(shù)校驗（如@NotBlank(message = "姓名不能為空")）。

4. 請求頭參數(shù)：@RequestHeader

核心作用：綁定 HTTP 請求頭中的參數(shù)（如 Token、Content-Type）。
使用場景：獲取令牌（Token）、語言標識（Accept-Language）等。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/info")
    public String getUserInfo(
        @RequestHeader("token") String token, // 獲取token請求頭
        @RequestHeader(value = "Accept-Language", required = false) String lang // 非必傳
    ) {
        return "Token：" + token + "，語言：" + (lang == null ? "zh-CN" : lang);
    }
}

5. Cookie 參數(shù)：@CookieValue

核心作用：綁定 HTTP Cookie 中的參數(shù)。
使用場景：獲取前端存儲的 Cookie（如用戶登錄態(tài)）。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/cookie")
    public String getCookie(@CookieValue("JSESSIONID") String sessionId) {
        return "SessionID：" + sessionId;
    }
}

6. 無注解（自動綁定）

核心作用：當參數(shù)是簡單類型（String、Integer、Long 等）或 POJO 時，SpringBoot 會自動綁定 URL 參數(shù) / 表單參數(shù)到方法參數(shù)。
使用場景：簡單表單提交、參數(shù)名與 POJO 字段名完全一致的場景。
核心用法：

// 1. 簡單類型自動綁定（訪問路徑：/user/simple?name=李四）
@GetMapping("/simple")
public String simpleParam(String name) {
    return "姓名：" + name;
}
// 2. POJO自動綁定（訪問路徑：/user/pojo?name=李四&age=22）
@GetMapping("/pojo")
public String pojoParam(UserDTO userDTO) {
    return "姓名：" + userDTO.getName() + "，年齡：" + userDTO.getAge();
}