Spring MVC 實作 RESTful 風格 API：統一介面設計與 PUT/DELETE 請求支援完整指南

什麼是 RESTful API？

REST（Representational State Transfer）是一種軟體架構風格，而非嚴格標準。其核心在於：資源導向、統一介面、無狀態、可快取。在 RESTful 設計中，同一 URL 代表同一資源集合，透過 HTTP Method 語義區分操作：

範例：使用者資源統一端點

基礎 URL：https://localhost:8080/User

• GET /User?id=1001 → 查詢 ID 1001 使用者
• POST /User (Body: name=zhangsan) → 新增使用者
• PUT /User (Body: id=1001&name=lisi) → 整體更新 ID 1001
• DELETE /User?id=1001 → 刪除 ID 1001

Spring MVC 實作步驟

1. 控制器設計

@Controller
@RequestMapping("/User")
public class UserController {

    @RequestMapping(method = RequestMethod.GET)
    @ResponseBody
    public User getUser(@RequestParam Long id) { ... }

    @RequestMapping(method = RequestMethod.POST)
    @ResponseBody
    public String createUser(@RequestBody User user) { ... }

    @RequestMapping(method = RequestMethod.PUT)
    @ResponseBody
    public String updateUser(@RequestBody User user) { ... }

    @RequestMapping(method = RequestMethod.DELETE)
    @ResponseBody
    public String deleteUser(@RequestParam Long id) { ... }
}

2. 前端 jQuery AJAX 呼叫

// 新增
$.ajax({ url: "/User", type: "POST", data: {name: "zhangsan"}, ... });

// 更新 - 關鍵點：瀏覽器原生 form 不支援 PUT/DELETE
$.ajax({ url: "/User", type: "POST", data: {_method: "PUT", id: 1001, name: "lisi"}, ... });

// 刪除
$.ajax({ url: "/User", type: "POST", data: {_method: "DELETE", id: 1001}, ... });

核心難點：瀏覽器與 Servlet 容器對 PUT/DELETE 的原生不支援

HTML 標單僅支援 GET/POST；Servlet API 雖定義 doPut/doDelete 但容器預設不路由。Spring MVC 提供 HiddenHttpMethodFilter 解決：攔截含 _method 參數的 POST 請求，轉換為對應的 HTTP Method。

web.xml 配置關鍵 Filter

<filter>
  <filter-name>hiddenHttpMethodFilter</filter-name>
  <filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>hiddenHttpMethodFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

注意： 此 Filter 必須在 DispatcherServlet 之前註冊（web.xml 順序靠前）。

完整 web.xml 參考

<web-app version="3.0" ...>
  <!-- 1. HiddenHttpMethodFilter 必須最先 -->
  <filter>
    <filter-name>hiddenHttpMethodFilter</filter-name>
    <filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>hiddenHttpMethodFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

  <!-- 2. Spring MVC DispatcherServlet -->
  <servlet>
    <servlet-name>spring</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>spring</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
  ...
</web-app>

替代方案對比

測試驗證

配置完成後，前端 AJAX 以 type: "POST" 發送，攜帶 _method: "PUT" 或 "DELETE"，Spring MVC 會自動路由至對應 @RequestMapping(method=RequestMethod.PUT/DELETE) 方法，且請求參數正常綁定。

最佳實踐小結

1. 資源導向 URL 設計，名詞複數、層級關係清晰
2. 善用 HTTP Method 語義，避免 /deleteUser 這類動詞式端點
3. 統一錯誤回應格式（HTTP Status + 錯誤碼 + 訊息）
4. 版本號放在 URL (/v1/User) 或 Header 中
5. 啟用 HiddenHttpMethodFilter 解決瀏覽器限制，保持 Controller 純淨

掌握這套機制，即可在 Spring MVC 中建構符合 REST 原則、前後端分離友好的 API 介面。