@RequestParam 注解詳解

@RequestParam 是 Spring MVC 中最常用的注解之一，用于從 HTTP 請求中提取查詢參數（Query String）或表單數據。它主要處理 application/x-www-form-urlencoded 類型的請求（如 GET 請求或 POST 表單提交）。

---

一、核心作用

1. 參數綁定
   將請求中的參數值綁定到控制器方法的參數上。

   // 示例：獲取請求中的 `name` 參數
   @GetMapping("/user")
   public String getUser(@RequestParam String name) {return "User: " + name;
   }
   

   • 訪問 /user?name=Alice → 輸出 User: Alice

2. 處理可選參數
   通過 required 屬性控制參數是否必須。

   @GetMapping("/search")
   public String search(@RequestParam(required = false) String keyword) {return keyword != null ? "Results for: " + keyword : "All items";
   }
   

   • 訪問 /search → 輸出 All items
   • 訪問 /search?keyword=spring → 輸出 Results for: spring

---

二、關鍵屬性

屬性	說明	默認值
value / name	指定請求參數的名稱	方法參數名
required	參數是否必須	true (必須)
defaultValue	參數缺失時的默認值	無

示例：

@PostMapping("/register")
public String register(@RequestParam("username") String user,  // 綁定到"username"參數@RequestParam(name = "age", defaultValue = "18") int age, // 缺省時默認為18@RequestParam(required = false) String hobby // 可選參數
) {// 業務邏輯
}

---

三、使用場景

1. 獲取單個參數

   @GetMapping("/detail")
   public String detail(@RequestParam Long id) { ... }
   

2. 獲取多個同名參數（如復選框）

   @PostMapping("/submit")
   public String submit(@RequestParam List<String> interests) {// interests 接收如 ?interests=music&interests=sports 的值
   }
   

3. 映射到 Map 對象

   @GetMapping("/filters")
   public String applyFilters(@RequestParam Map<String, String> filters) {// 接收所有參數，如 ?category=books&price=100
   }
   

---

四、注意事項

1. 參數名匹配規則

   • 默認根據方法參數名匹配請求參數（需編譯時開啟 -parameters 或顯式指定 @RequestParam("param")）。
   • 若參數名未指定且編譯未保留參數名，會拋出 MissingServletRequestParameterException。

2. 類型轉換
   Spring 自動將 String 類型的參數轉為目標類型（如 int, LocalDate 等）。

   • 轉換失敗 → 拋出 TypeMismatchException。

3. 與 @PathVariable 區別

   特性	@RequestParam	@PathVariable
   來源	查詢字符串（?key=value）	URL 路徑（/users/{id}）
   是否可選	可通過 required=false 設為可選	通常是必須的
   示例	/api?page=1	/api/users/123

4. 與 @RequestBody 區別

   • @RequestParam：處理 URL 編碼數據（簡單鍵值對）。
   • @RequestBody：處理 JSON/XML 等復雜數據（如 POST 請求體）。

---

五、常見問題解決方案

1. 參數缺失異常

   // 方案1: 設置 required=false
   @RequestParam(required = false) String param// 方案2: 提供默認值
   @RequestParam(defaultValue = "default") String param
   

2. 參數名沖突
   顯式指定參數名避免歧義：

   public String query(@RequestParam("from") Date startDate,  // 使用"from"作為參數名@RequestParam("to") Date endDate
   ) { ... }
   

3. 接收數組/列表

   // 前端傳參: ?ids=1,2,3 或 ?ids=1&ids=2
   public String getItems(@RequestParam List<Long> ids) { ... }
   

---

六、最佳實踐

1. 簡單查詢：優先用 @RequestParam 處理過濾條件（如分頁、排序）。
2. RESTful 路徑：資源標識用 @PathVariable（如 /users/{id}），附加參數用 @RequestParam（如 /users?role=admin）。
3. 明確命名：避免依賴編譯參數名，顯式聲明 @RequestParam("paramName")。
4. 設置默認值：對分頁參數等推薦使用 defaultValue：

   @GetMapping("/posts")
   public Page<Post> getPosts(@RequestParam(defaultValue = "0") int page,@RequestParam(defaultValue = "10") int size
   ) { ... }
   

總結：@RequestParam 是 Spring 中處理請求參數的基石級注解，適用于大多數簡單數據綁定場景。掌握其用法能高效處理 URL 編碼數據，但復雜 JSON 數據應使用 @RequestBody。