Spring MVC @RequestMapping 六大核心用法深度解析：從基礎映射到 REST 風格與正則匹配

前言

@RequestMapping 是 Spring MVC 中最核心的註解之一，負責將 HTTP 請求映射到控制器方法。掌握其六大基本用法，能讓你靈活應對各種 URL 設計需求。本文通過實戰代碼示例，系統梳理從簡單路徑映射到 REST 風格參數綁定、多變量綁定乃至正則表達式匹配的完整用法。

一、基礎路徑映射

@RequestMapping(value = "/departments")
public String simplePattern() {
    System.out.println("simplePattern method was called");
    return "someResult";
}

效果： 訪問 https://localhost:8080/xxx/departments 觸發該方法。
要點： value 可省略直接寫 @RequestMapping("/departments")；默認支持所有 HTTP 方法（GET/POST/PUT/DELETE 等）。

二、請求參數綁定 @RequestParam

@RequestMapping(value = "/departments")
public String findDepartment(@RequestParam("departmentId") String departmentId) {
    System.out.println("Find department with ID: " + departmentId);
    return "someResult";
}

效果： 訪問 /departments?departmentId=23 觸發。
進階： 可用 required=false 設為可選，defaultValue="1" 設置默認值；基本類型參數自動類型轉換。

三、REST 風格路徑變量 @PathVariable（單變量）

@RequestMapping(value = "/departments/{departmentId}")
public String findDepartment(@PathVariable String departmentId) {
    System.out.println("Find department with ID: " + departmentId);
    return "someResult";
}

效果： 訪問 /departments/23，路徑中的 23 自動綁定到參數。
規約： 路徑佔位符 {departmentId} 與參數名一致時，@PathVariable 可省略 value。

四、REST 風格參數重命名綁定

@RequestMapping(value = "/departments/{departmentId}")
public String findDepartmentAlternative(@PathVariable("departmentId") String someDepartmentId) {
    System.out.println("Find department with ID: " + someDepartmentId);
    return "someResult";
}

場景： 路徑變量名與業務參數名不一致時（如避免與成員變量衝突），通過 @PathVariable("departmentId") 顯式指定映射關係。

五、多路徑變量綁定

@RequestMapping(value = "/departments/{departmentId}/employees/{employeeId}")
public String findEmployee(@PathVariable String departmentId, @PathVariable String employeeId) {
    System.out.println("Find employee: " + employeeId + " from department: " + departmentId);
    return "someResult";
}

效果： 訪問 /departments/10/employees/100，同時綁定兩個路徑變量。
擴展： 可結合 @RequestParam 處理同一請求中的 Query 參數。

六、正則表達式精確匹配

@RequestMapping(value = "/{textualPart:[a-z-]+}.{numericPart:[\\d]+}")
public String regularExpression(@PathVariable String textualPart, @PathVariable String numericPart) {
    System.out.println("Textual: " + textualPart + ", Numeric: " + numericPart);
    return "someResult";
}

效果： 匹配 /sometext.123 這類「字母連字符.數字」格式。
語法： {參數名:正則}，正則中反斜杠需雙重轉義（Java 字符串 + 正則雙層轉義）。

七、實戰最佳實踐建議

1. 方法級註解配合類級註解：類上加 @RequestMapping("/api/v1") 統一前綴，方法上只寫相對路徑。
2. 明確 HTTP 方法：推薦使用 @GetMapping、@PostMapping 等組合註解（Spring 4.3+），語義更清晰。
3. 參數校驗：結合 @Valid + JSR-303 註解（@NotNull、@Size 等）做參數校驗。
4. 路徑設計規範：資源名用複數名詞（/users），層級關係用路徑體現（/users/{id}/orders），避免動詞出現在 URL 中。

八、總結

@RequestMapping 的六大用法層層遞進，覆蓋了從傳統 RPC 風格到現代 RESTful API 的主流需求。實際開發中，建議優先使用組合註解（@GetMapping 等）並配合參數校驗，構建清晰、健壯的 Web API。