Spring MVC 入門實戰：從零搭建、參數綁定、視圖解析到專案結構最佳實踐

Spring MVC 作為 Java Web 開發的經典框架，掌握其核心配置與請求處理流程是進階 Spring Boot 的基石。本文以「手動搭建無 Spring Boot 專案」為主線，完整呈現從建立專案、配置 web.xml、DispatcherServlet、ContextLoaderListener、視圖解析器、Controller 開發到參數傳遞的全流程。

一、專案建立與依賴 (Maven 結構)

src/main/java
  └─ org.swinglife.controller
       ├─ HomeController.java
       └─ UserController.java
src/main/webapp
  ├─ WEB-INF
  │   ├─ web.xml
  │   ├─ classes
  │   │   ├─ mvc-context.xml      <-- DispatcherServlet 載入
  │   │   └─ root-context.xml     <-- ContextLoaderListener 載入
  │   └─ page
  │       ├─ home.jsp
  │       └─ succ.jsp
  └─ index.html

核心 JAR (放入 WEB-INF/lib 或 Maven 依賴)：spring-webmvc、spring-context、spring-beans、spring-core、commons-logging、servlet-api、jstl、standard。

二、web.xml 雙容器配置詳解

<web-app xmlns="https://java.sun.com/xml/ns/javaee" version="3.0">
  <!-- 1. Spring 根容器 (Service、DAO、DataSource 等) -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>classpath:root-context.xml</param-value>
  </context-param>

  <!-- 2. Spring MVC 子容器 (Controller、ViewResolver、HandlerMapping 等) -->
  <servlet>
    <servlet-name>MVC</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>/WEB-INF/classes/mvc*.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>MVC</servlet-name>
    <url-pattern>*.html</url-pattern>
  </servlet-mapping>

  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
</web-app>

• 根容器：載入 root-context.xml，管理業務層 Bean，全應用單例。
• 子容器：DispatcherServlet 載入 mvc-context.xml，管理 Web 層 Bean，可引用根容器 Bean。
• 攔截路徑：*.html 只攔截以 .html 結尾的請求，靜態資源 (css/js/圖片) 需配置 <mvc:default-servlet-handler/> 或 Tomcat DefaultServlet 放行。

三、mvc-context.xml 核心配置

<beans xmlns="https://www.springframework.org/schema/beans"
       xmlns:context="https://www.springframework.org/schema/context"
       xmlns:mvc="https://www.springframework.org/schema/mvc"
       xmlns:p="https://www.springframework.org/schema/p"
       xsi:schemaLocation="...省略...">

  <!-- 引入根容器配置 -->
  <import resource="root-context.xml"/>

  <!-- 掃描 Controller 包 -->
  <context:component-scan base-package="org.swinglife.controller"/>

  <!-- 視圖解析器：/page/ + 方法回傳值 + .jsp -->
  <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver"
        p:prefix="/page/" p:suffix=".jsp"/>

  <!-- 靜態資源放行 (可選) -->
  <mvc:default-servlet-handler/>
  <mvc:annotation-driven/>
</beans>

四、Controller 開發與參數綁定

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

  @PostMapping("/login")
  public ModelAndView login(@RequestParam String username,
                            @RequestParam String password,
                            Model model) {
    // 1. 簡單驗證
    if (username == null || password == null) {
      return new ModelAndView("home"); // 回登入頁
    }
    // 2. 傳遞資料到視圖 (三種方式任選一)
    ModelAndView mav = new ModelAndView("succ");
    mav.addObject("username", username);           // 方式一：ModelAndView
    // model.addAttribute("password", password);   // 方式二：Model 參數
    // request.setAttribute("pwd", password);      // 方式三：原生 request
    return mav;
  }
}

五、視圖頁面

<!-- page/home.jsp -->
<form action="user/login.html" method="post">
  用戶名: <input name="username"/><br/>
  密碼: <input type="password" name="password"/><br/>
  <input type="submit" value="登入"/>
</form>

<!-- page/succ.jsp -->
登入成功！${username} / ${password} / ${pwd}

六、常見問題與最佳實踐

1. 編碼亂碼：在 web.xml 加入 CharacterEncodingFilter (UTF-8, forceEncoding=true)。
2. 靜態資源 404：配置 <mvc:default-servlet-handler/> 或 <mvc:resources mapping="/static/**" location="/static/"/>。
3. JSP EL 表達式不生效：確認 web.xml version="3.0"，JSP 頁面 isELIgnored="false"。
4. 參數綁定失敗：檢查表單 name 與 @RequestParam value 是否一致，必要時加 required=false。
5. 返回 String 視圖名：return "succ" 等同 new ModelAndView("succ")，更簡潔。

總結

手動搭建 Spring MVC 能深入理解「雙容器架構、DispatcherServlet 請求分發、HandlerMapping/Adapter、ViewResolver 視圖解析」完整鏈路。實務中新專案建議直接使用 Spring Boot 自動配置，但掌握底層原理對排查疑難雜症、理解框架演進極有幫助。