Spring MVC 核心註解深度解析：@Controller、@RequestMapping、參數綁定、類型轉換、ModelAttribute、SessionAttributes 完全指南

Spring MVC 以註解驅動簡化 Web 開發。本文系統講解 @Controller、@RequestMapping (含 URI 模板、通配符、限制條件)、參數綁定註解 (@RequestParam/@PathVariable/@CookieValue/@RequestHeader)、處理器方法參數/返回值類型、@ModelAttribute/@SessionAttributes 數據共享、自定義類型轉換器 (@InitBinder/WebBindingInitializer)，附帶實戰代碼與最佳實踐。

一、@Controller 與 組件掃描

@Controller
public class MyController { ... }

需在 Spring MVC 配置中掃描：

<context:component-scan base-package="com.example.controller">
  <context:exclude-filter type="annotation" expression="org.springframework.stereotype.Service"/>
</context:component-scan>

或在 Java Config 中 @ComponentScan。

二、@RequestMapping 映射請求

1. 類級別 + 方法級別 = 相對路徑

@Controller
@RequestMapping("/user")
public class UserController {
    @RequestMapping("/list")
    public String list() { ... } // 訪問 /user/list
}

2. URI 模板與 @PathVariable

@RequestMapping("/{userId}/profile")
public String profile(@PathVariable String userId, @PathVariable("nickName") String nick) { ... }
// 訪問 /123/profile?nickName=abc -> userId=123, nick=abc

• 參數名與模板變量同名時可省略 @PathVariable("name")（需編譯保留參數名 -parameters）。
• 支持簡單類型自動轉換 (String, int, long, Date 等)。

3. 通配符

@RequestMapping("/api/*/version") // 匹配 /api/v1/version, /api/test/version
@RequestMapping("/resources/**")  // 匹配多級路徑

4. 限制條件：params、method、headers

@RequestMapping(value="/save", method=RequestMethod.POST, params="action=save", headers="content-type=application/json")
public String save() { ... }

三、參數綁定註解

注意：非 required=false 且參數缺失會拋 400 錯誤。

四、處理器方法參數與返回值

支持的參數類型

• 原生 Servlet API：HttpServletRequest, HttpServletResponse, HttpSession, Principal, Locale, InputStream, OutputStream, Reader, Writer。
• Spring 封裝：WebRequest, Model, ModelMap, Map, Errors/BindingResult (緊跟 @Valid 實體後)。
• 實體對象：自動綁定請求參數到屬性 (命令對象)。
• 文件上傳：MultipartFile, Part。

支持的返回值類型

五、@ModelAttribute 與 @SessionAttributes 數據共享

1. @ModelAttribute 標註方法：預先放入模型/Session

@Controller
@RequestMapping("/demo")
@SessionAttributes(names="user", types=User.class) // 指定哪些屬性存入 Session
public class DemoController {
    @ModelAttribute("initData")
    public String init() { return "hello"; } // 執行於每個 @RequestMapping 方法前

    @RequestMapping("/show")
    public void show(@ModelAttribute("initData") String data, Writer w) throws IOException {
        w.write(data); // 獲得 "hello"
    }
}

• 方法返回值放入模型，屬性名用 @ModelAttribute("name") 指定，否則用返回類型首字母小寫。
• 若類上標註 @SessionAttributes，匹配的屬性會在請求結束後存入 Session，下次請求從 Session 取出。

2. @ModelAttribute 標註參數：從模型/Session 取值

@RequestMapping("/edit")
public String edit(@ModelAttribute("user") User user) { ... } // 從模型/Session 獲取 user

3. @SessionAttributes 核心規則

• value/names：指定屬性名。
• types：指定類型，屬性名為類型首字母小寫。
• 並集關係：value ∪ types。
• 首次請求結束後才寫入 Session，第二次請求可讀取。
• 清除 Session 屬性：SessionStatus.setComplete()。

六、自定義類型轉換器

1. 局部：@InitBinder (Controller 內)

@Controller
public class MyController {
    @InitBinder
    public void binder(WebDataBinder binder) {
        binder.registerCustomEditor(Date.class, new CustomDateEditor(new SimpleDateFormat("yyyyMMdd"), true));
        binder.registerCustomEditor(User.class, new PropertyEditorSupport() {
            @Override public void setAsText(String text) { setValue(new User(text)); }
            @Override public String getAsText() { return ((User)getValue()).getName(); }
        });
    }
}

2. 全局：WebBindingInitializer

@Component
public class GlobalBinder implements WebBindingInitializer {
    @Override public void initBinder(WebDataBinder binder, WebRequest request) {
        binder.registerCustomEditor(Date.class, new CustomDateEditor(new SimpleDateFormat("yyyy-MM-dd"), true));
    }
}
// Spring MVC 配置注入
<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
  <property name="webBindingInitializer">
    <bean class="com.example.GlobalBinder"/>
  </property>
</bean>

觸發時機

每個帶 @RequestParam/@PathVariable/@RequestHeader/@CookieValue/@ModelAttribute 的參數都會觸發一次 initBinder。

Spring MVC 註解體系極其豐富，核心掌握：請求映射 → 參數綁定 → 模型構建 → 視圖解析 → 響應輸出。善用 @ModelAttribute/@SessionAttributes 簡化跨請求數據流轉，@InitBinder 解決特殊格式綁定，@ResponseBody 構建 REST API。