Spring MVC RESTful 風格傳遞對象參數的正確姿勢

問題背景

Spring MVC 中使用 RESTful 風格 URL（如 /users/{id}）時，僅能接收單個路徑變量或請求參數。嘗試直接傳遞對象（JSON）給帶 @PathVariable 的方法，發現對象字段無法注入。

核心誤區

• @PathVariable 僅綁定 URL 路徑佔位符，不支援對象綁定。
• @RequestParam 僅綁定查詢字串/表單字段，不支援 JSON 體。

正確方案：@RequestBody + POST/PUT

1. 客戶端發送 JSON

POST /api/users
Content-Type: application/json

{
  "username": "zhangsan",
  "email": "zhang@example.com",
  "age": 25
}

2. 控制器接收

@PostMapping("/api/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // user 對象已自動反序列化，字段全部注入
    User saved = userService.save(user);
    return ResponseEntity.ok(saved);
}

3. 關鍵註解說明

• @RequestBody：告訴 Spring 將 HTTP 請求體（JSON/XML）反序列化為方法參數對象。需類路徑下有 Jackson/Gson 等 HttpMessageConverter（Spring Boot 默認已配置）。
• @Valid / @Validated：配合 JSR-303 註解（@NotNull, @Size 等）進行參數校驗。

RESTful 設計建議

進階：表單提交 (application/x-www-form-urlencoded)

若前端為傳統表單提交，去掉 @RequestBody，直接用對象參數，Spring 會自動按名稱綁定表單字段：

@PostMapping("/api/users/form")
public String createUserForm(User user) { ... } // 表單字段名需與 User 屬性名一致

常見坑點

• GET 請求不能帶 @RequestBody（HTTP 規範），查詢對象請用 @RequestParam 或 @ModelAttribute。
• 對象中包含日期類型，需配置 @JsonFormat(pattern="yyyy-MM-dd") 或全局 ObjectMapper 日期格式。
• 大文件上傳請用 MultipartFile，而非對象字段。

總結

Spring MVC RESTful 風格傳對象：POST/PUT 請求 + @RequestBody + JSON 體。路徑變量僅用於資源標識（ID），請求體承載完整對象數據，符合 REST 語義且框架原生支援。