一篇文章搞懂 @PathVariable、@RequestParam、@RequestBody、@ModelAttribute 等所有請(qǐng)求參數(shù)注解

前言

在 Spring Boot 開(kāi)發(fā)過(guò)程中，相信大家都會(huì)遇到這樣的場(chǎng)景：前端傳來(lái)各種各樣的請(qǐng)求參數(shù)，有的是在 URL 路徑中，有的是在 URL “?” 后面，還有的是放在請(qǐng)求體中的 JSON 數(shù)據(jù)。我們應(yīng)該如何在后端優(yōu)雅地接收這些參數(shù)？Spring Boot 提供了一系列注解來(lái)幫助我們輕松完成請(qǐng)求參數(shù)的綁定，本文將對(duì)其中最常用的注解進(jìn)行詳細(xì)講解，包括它們的用法、區(qū)別以及最佳實(shí)踐。

掌握這幾個(gè)注解，可以說(shuō) Web 開(kāi)發(fā)中 90% 的參數(shù)接收?qǐng)鼍岸伎梢暂p松應(yīng)對(duì)。現(xiàn)在就讓我們一起來(lái)學(xué)習(xí)吧！

一、@PathVariable：路徑變量

1.1 簡(jiǎn)介

@PathVariable 注解用于從請(qǐng)求 URL 路徑中獲取變量的值。它非常適用于 RESTful 風(fēng)格的接口設(shè)計(jì)，將 URL 路徑中的某一部分作為參數(shù)傳遞給控制器方法。

比如，我們?cè)谠O(shè)計(jì)獲取用戶信息的接口時(shí)，通常會(huì)將用戶 ID（唯一標(biāo)識(shí)）放在 URL 路徑中：/api/users/123，其中 123 就是路徑變量。

1.2 基本用法

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // 訪問(wèn)示例：GET /api/users/100
    @GetMapping("/{userId}")
    public ResponseEntity<User> getUserById(@PathVariable Long userId) {
        // userId 的值自動(dòng)綁定為 100
        return ResponseEntity.ok(userService.getUserById(userId));
    }
}

1.3 多個(gè)路徑變量

一個(gè) URL 路徑中可以包含多個(gè)路徑變量：

// 訪問(wèn)示例：GET /api/users/100/orders/200
@GetMapping("/{userId}/orders/{orderId}")
public ResponseEntity<Order> getUserOrder(@PathVariable Long userId, @PathVariable Long orderId) {
    // userId=100, orderId=200
    return ResponseEntity.ok(orderService.findByUserAndOrder(userId, orderId));
}

1.4 參數(shù)名不一致時(shí)的處理

如果方法參數(shù)名與 URL 中的變量名不一致，可以通過(guò) @PathVariable 的 value 屬性顯式指定：

@GetMapping("/{userId}")
public ResponseEntity<User> getUserById(@PathVariable("userId") Long id) {
    // 將 {userId} 的值綁定到 id 參數(shù)上
    return ResponseEntity.ok(userService.getUserById(id));
}

1.5 @PathVariable 常用屬性

需要注意的是，如果 required=true 而路徑中沒(méi)有對(duì)應(yīng)的變量，請(qǐng)求將會(huì)失敗。

1.6 使用正則表達(dá)式精確匹配

可以對(duì) URL 變量進(jìn)行更精確的定義：

// 只允許大小寫(xiě)字母、數(shù)字和下劃線
@GetMapping("/user/{username:[a-zA-Z0-9_]+}")
public String getUserProfile(@PathVariable String username) {
    return "User: " + username;
}

這樣一來(lái)，不合法的 URL 路徑將直接被 Spring MVC 拒絕。

二、@RequestParam：請(qǐng)求參數(shù)（查詢參數(shù)）

2.1 簡(jiǎn)介

@RequestParam 注解用于從 HTTP 請(qǐng)求中獲取查詢參數(shù)（Query Parameters），這些參數(shù)通常出現(xiàn)在 URL 的 ? 之后，格式為 key=value，多個(gè)參數(shù)之間用 & 連接。

典型的使用場(chǎng)景包括：GET 請(qǐng)求的分頁(yè)參數(shù)（page、size）、搜索關(guān)鍵字等。

2.2 基本用法

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // 訪問(wèn)示例：GET /api/users/search?username=zhang
    @GetMapping("/search")
    public ResponseEntity<List<User>> searchUsers(@RequestParam String username) {
        return ResponseEntity.ok(userService.searchByUsername(username));
    }
}

當(dāng)參數(shù)名與方法參數(shù)名相同時(shí)，可以省略 value 屬性。

2.3 參數(shù)可選與默認(rèn)值

@RequestParam 提供了 required 和 defaultValue 兩個(gè)重要屬性來(lái)處理可選參數(shù)：

@GetMapping("/greet")
public String greet(
    @RequestParam(name = "name", required = false, defaultValue = "World") String name
) {
    // 當(dāng)請(qǐng)求沒(méi)有提供 name 參數(shù)時(shí)，使用默認(rèn)值 "World"
    return "Hello, " + name + "!";
}
// 訪問(wèn) /greet -> Hello, World!
// 訪問(wèn) /greet?name=John -> Hello, John!

屬性詳解：

• required：參數(shù)是否必須，默認(rèn)為 true。如果設(shè)為 false，表示參數(shù)可選，不傳時(shí)參數(shù)值為 null（對(duì)于基本數(shù)據(jù)類型需要特別注意空指針問(wèn)題）
• defaultValue：參數(shù)的默認(rèn)值，一旦設(shè)置了 defaultValue，required 的設(shè)置會(huì)失效
• value/name：指定請(qǐng)求參數(shù)名稱，如果不指定則默認(rèn)使用方法參數(shù)名

2.4 @RequestParam 接收數(shù)組/集合

// 訪問(wèn)示例：GET /api/users?ids=1,2,3&ids=4
@GetMapping
public ResponseEntity<List<User>> getUsers(@RequestParam List<Long> ids) {
    // ids = [1,2,3,4]
    return ResponseEntity.ok(userService.findByIds(ids));
}

當(dāng)請(qǐng)求中有多個(gè)同名參數(shù)時(shí)，Spring Boot 會(huì)自動(dòng)將其收集為數(shù)組或集合。

2.5 @RequestParam vs 不加注解的區(qū)別

如果在控制器方法參數(shù)上不加任何注解，Spring Boot 也會(huì)嘗試將請(qǐng)求參數(shù)綁定到該參數(shù)上，且默認(rèn)值為 required=false。但為了代碼可讀性和明確性，建議顯式使用 @RequestParam。

三、@RequestBody：請(qǐng)求體

3.1 簡(jiǎn)介

@RequestBody 注解用于接收 HTTP 請(qǐng)求體（Request Body）中的數(shù)據(jù)，并自動(dòng)將其轉(zhuǎn)換為 Java 對(duì)象。在前后端分離的架構(gòu)中，這是最常用的注解之一，通常用來(lái)接收 POST/PUT 請(qǐng)求中攜帶的 JSON 或 XML 數(shù)據(jù)。

3.2 基本用法

首先定義一個(gè)實(shí)體類：

@Data
public class UserRequest {
    private String username;
    private String email;
    private Integer age;
}

然后在控制器中使用 @RequestBody：

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // 請(qǐng)求示例：POST /api/users
    // 請(qǐng)求體：{"username": "zhang", "email": "zhang@example.com", "age": 25}
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody UserRequest userRequest) {
        // Spring Boot 自動(dòng)將 JSON 字符串映射到 userRequest 對(duì)象
        User user = userService.createUser(userRequest);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
}

3.3 底層原理：HttpMessageConverter

@RequestBody 的自動(dòng)轉(zhuǎn)換能力依賴于 Spring Boot 的 HTTP 消息轉(zhuǎn)換器（HttpMessageConverter） 機(jī)制。Spring Boot 默認(rèn)集成了 Jackson，它會(huì)自動(dòng)將請(qǐng)求體中的 JSON 反序列化為 Java 對(duì)象，同時(shí)也支持 XML、表單數(shù)據(jù)等多種格式：

• 反序列化：將 HTTP 請(qǐng)求體的字節(jié)流（JSON/XML）轉(zhuǎn)換為 Java 對(duì)象
• 序列化：將 Java 返回值對(duì)象轉(zhuǎn)換為 HTTP 響應(yīng)體的字節(jié)流（由 @ResponseBody 配合完成）

3.4 接收復(fù)雜嵌套對(duì)象

@Data
public class OrderRequest {
    private Long orderId;
    private List<OrderItem> items;      // 嵌套的 List
    private Address shippingAddress;    // 嵌套的對(duì)象
}

@PostMapping("/order")
public ResponseEntity<String> createOrder(@RequestBody OrderRequest orderRequest) {
    // 自動(dòng)解析嵌套的 JSON 結(jié)構(gòu)
    return ResponseEntity.ok("Order created with " + orderRequest.getItems().size() + " items");
}

3.5 @RequestBody 使用注意事項(xiàng)

• 不能用于 GET 請(qǐng)求：因?yàn)?GET 請(qǐng)求沒(méi)有請(qǐng)求體，用 @RequestBody 會(huì)報(bào)錯(cuò)
• 每個(gè) Controller 方法只能有一個(gè) @RequestBody：請(qǐng)求體的輸入流只能被讀取一次
• Content-Type 必須匹配：請(qǐng)求需要攜帶 Content-Type: application/json 等匹配的媒體類型
• 對(duì)象屬性缺失的處理：如果 JSON 中缺少實(shí)體類的某些屬性，這些屬性會(huì)被賦值為 null

3.6 @ResponseBody 小貼士

@ResponseBody 通常和 @RequestBody 成對(duì)出現(xiàn)，用于將 Java 對(duì)象序列化為 JSON 返回給前端。而 @RestController 注解實(shí)際上就是 @Controller 和 @ResponseBody 的結(jié)合體，所以我們?cè)谑褂?@RestController 時(shí)，所有方法的返回值會(huì)自動(dòng)被序列化為 JSON 響應(yīng)體，無(wú)需再單獨(dú)添加 @ResponseBody。

四、@ModelAttribute：模型屬性綁定

4.1 簡(jiǎn)介

@ModelAttribute 注解用于將多個(gè)請(qǐng)求參數(shù)綁定到一個(gè) Java 對(duì)象（命令對(duì)象）上，非常適用于處理表單提交場(chǎng)景。它可以出現(xiàn)在兩個(gè)位置：

1. 方法參數(shù)上：將請(qǐng)求參數(shù)綁定到對(duì)象的屬性上
2. 方法上（非請(qǐng)求處理方法）：在執(zhí)行 Controller 方法之前，預(yù)先將數(shù)據(jù)添加到模型中供視圖使用

4.2 方法參數(shù)中使用（最常用）

@Data
public class UserForm {
    private String username;
    private String password;
    private String email;
}

@PostMapping("/register")
public String register(@ModelAttribute UserForm userForm, Model model) {
    // userForm 的 username、password、email 屬性已自動(dòng)綁定表單數(shù)據(jù)
    userService.register(userForm);
    model.addAttribute("message", "注冊(cè)成功");
    return "result";
}

4.3 @ModelAttribute vs @RequestBody 的區(qū)別

這兩個(gè)注解很容易混淆，但本質(zhì)上有著完全不同的處理方式：

簡(jiǎn)單來(lái)說(shuō)：傳統(tǒng)表單用 @ModelAttribute，現(xiàn)代 REST API 用 @RequestBody。

4.4 接收表單數(shù)據(jù)的方式對(duì)比

在 Spring Boot 中接收表單數(shù)據(jù)有三種常見(jiàn)方式：

方式一：使用 @RequestParam 逐個(gè)接收

@PostMapping("/submit")
public String submit(@RequestParam("name") String name, @RequestParam("email") String email) {
    // 處理...
}

方式二：不加注解（Spring 自動(dòng)綁定）

@PostMapping("/submit")
public String submit(String name, String email) {
    // 處理...
}

方式三：使用 @ModelAttribute 封裝為對(duì)象

@PostMapping("/submit")
public String submit(@ModelAttribute User user) {
    // 處理...
}

當(dāng)參數(shù)較多時(shí)，使用 @ModelAttribute 封裝為對(duì)象是更優(yōu)雅的選擇。

五、其他常用注解

5.1 @RequestHeader：獲取請(qǐng)求頭

@RequestHeader 用于獲取 HTTP 請(qǐng)求頭中的信息。雖然業(yè)務(wù)代碼中不太常用，但在認(rèn)證鑒權(quán)、鏈路追蹤等基礎(chǔ)設(shè)施中不可或缺：

@GetMapping("/user")
public ResponseEntity<User> getUserList(
    @RequestHeader("Authorization") String authToken,
    @RequestHeader Map<String, String> allHeaders          // 獲取所有請(qǐng)求頭
) {
    // 驗(yàn)證 token 并返回?cái)?shù)據(jù)
    return ResponseEntity.ok(userRepo.findAll());
}

@RequestHeader 也支持 required 和 defaultValue 屬性，用法與 @RequestParam 類似。

5.2 @CookieValue：獲取 Cookie 值

當(dāng)需要與客戶端保持會(huì)話狀態(tài)時(shí)，@CookieValue 可以方便地讀取 Cookie 中的值：

@GetMapping("/welcome")
public String welcome(@CookieValue(name = "sessionId", defaultValue = "none") String sessionId) {
    return "Session ID: " + sessionId;
}

5.3 @MatrixVariable：矩陣變量

@MatrixVariable 是一種比較少見(jiàn)（但在某些國(guó)外系統(tǒng)中會(huì)遇到）的參數(shù)形式，參數(shù)使用 ; 分隔：

// 訪問(wèn)示例：GET /books/reviews;isbn=1234;topN=5
@GetMapping("/books/reviews")
public List<BookReview> getBookReviews(
    @MatrixVariable String isbn,
    @MatrixVariable Integer topN
) {
    return bookReviewsLogic.getTopNReviewsByIsbn(isbn, topN);
}

5.4 @RequestAttribute：獲取請(qǐng)求域?qū)傩?/h3>

@RequestAttribute 用于獲取通過(guò)請(qǐng)求轉(zhuǎn)發(fā)設(shè)置的 request 域?qū)傩灾?，主要用于?qǐng)求轉(zhuǎn)發(fā)（forward）場(chǎng)景：

// 在過(guò)濾器或攔截器中 setAttribute
request.setAttribute("userInfo", userInfo);

// 在 Controller 中獲取
@GetMapping("/profile")
public String getProfile(@RequestAttribute("userInfo") UserInfo userInfo) {
    return "user: " + userInfo.getUsername();
}

六、注解對(duì)比總結(jié)

快速選擇指南

• 路徑中的唯一標(biāo)識(shí)（如用戶 ID、訂單號(hào)）→ @PathVariable
• GET 請(qǐng)求的篩選/分頁(yè)參數(shù)（如 ?page=1&size=10）→ @RequestParam
• POST/PUT 請(qǐng)求的 JSON 數(shù)據(jù)（前后端分離）→ @RequestBody
• 傳統(tǒng)表單提交（參數(shù)多且分散）→ @ModelAttribute 或 @RequestParam
• 需要讀取請(qǐng)求頭中的元數(shù)據(jù)（如 Token）→ @RequestHeader
• 需要讀取瀏覽器 Cookie（如 Session ID）→ @CookieValue

七、多注解組合使用

在實(shí)際業(yè)務(wù)中，有時(shí)需要同時(shí)接收多種類型的參數(shù)，例如：從路徑中獲取用戶 ID、從查詢參數(shù)中獲取篩選條件、從請(qǐng)求體中獲取修改的數(shù)據(jù)：

@PutMapping("/users/{userId}/profile")
public ResponseEntity<User> updateUserProfile(
    @PathVariable Long userId,                    // 從路徑中獲取用戶 ID
    @RequestParam(required = false) String flag,  // 從查詢參數(shù)中獲取標(biāo)志
    @RequestBody UserProfileRequest request       // 從請(qǐng)求體中獲取更新數(shù)據(jù)
) {
    // 三個(gè)參數(shù)各司其職
    userService.updateProfile(userId, request, flag);
    return ResponseEntity.ok().build();
}

需要注意的是，@PathVariable、@RequestParam 和 @RequestBody 都是互不沖突的，可以根據(jù)需要在同一個(gè)方法中組合使用多個(gè)。

八、常見(jiàn)問(wèn)題與避坑指南

8.1 @RequestParam required=true 但參數(shù)缺失

現(xiàn)象：請(qǐng)求中沒(méi)有攜帶必填參數(shù)，返回 400 錯(cuò)誤。

解決：將 required 設(shè)為 false 或提供 defaultValue。

8.2 @RequestBody 接收的參數(shù)為 null

可能原因：

1. 請(qǐng)求的 Content-Type 不是 application/json
2. JSON 字段名與 Java 對(duì)象屬性名不匹配
3. 實(shí)體類缺少無(wú)參構(gòu)造方法或 Getter/Setter 方法

8.3 @PathVariable 參數(shù)中包含斜杠被截?cái)?/h3>

默認(rèn)情況下，路徑變量不能包含 URL 分隔符 /，如果需要接收包含斜杠的值，可以使用正則表達(dá)式：

@GetMapping("/files/{path:[a-zA-Z0-9/]+}")
public String getFile(@PathVariable String path) { ... }

8.4 基本數(shù)據(jù)類型與 required=false 的坑

當(dāng)參數(shù)為基本數(shù)據(jù)類型（如 int、long）且 required=false 時(shí)，如果請(qǐng)求中沒(méi)有該參數(shù)，會(huì)有空指針問(wèn)題。應(yīng)使用包裝類（Integer、Long）來(lái)接收可選參數(shù)。

8.5 defaultValue 與 required 同時(shí)使用的注意事項(xiàng)

設(shè)置 defaultValue 后，required 的設(shè)置會(huì)失效。也就是說(shuō)，即使你寫(xiě)了 required=true 并設(shè)置了 defaultValue，參數(shù)不傳時(shí)也不會(huì)報(bào)錯(cuò)，會(huì)直接使用默認(rèn)值。

結(jié)語(yǔ)

本文詳細(xì)介紹了 Spring Boot 中用于接收請(qǐng)求參數(shù)的核心注解，從最常用的 @PathVariable、@RequestParam、@RequestBody，到表單綁定的 @ModelAttribute，再到請(qǐng)求頭、Cookie 等相對(duì)進(jìn)階的注解，涵蓋了日常開(kāi)發(fā)中 90% 以上的參數(shù)接收?qǐng)鼍啊?/p>

在實(shí)際開(kāi)發(fā)中，建議大家：

1. 優(yōu)先使用 RESTful 風(fēng)格的 URL 設(shè)計(jì)，合理使用 @PathVariable 標(biāo)識(shí)資源
2. 前后端分離項(xiàng)目統(tǒng)一使用 @RequestBody 傳遞復(fù)雜數(shù)據(jù)
3. 大量且相似的表單參數(shù)，使用 @ModelAttribute 封裝為對(duì)象
4. 保持代碼可讀性，即使是簡(jiǎn)單參數(shù)也建議顯式使用注解

到此這篇關(guān)于從入門(mén)到精通詳解SpringBoot中請(qǐng)求參數(shù)注解的完全指南的文章就介紹到這了,更多相關(guān)SpringBoot請(qǐng)求參數(shù)注解內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論