Spring MVC 實戰：表單資料驗證與檔案上傳完整指南

一、表單資料驗證（Bean Validation）

Spring MVC 整合 JSR-303 Bean Validation，讓驗證邏輯以註解形式宣告於領域模型，Controller 僅需加上 @Valid 即可自動觸發驗證。

1. 依賴引入

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>1.1.0.Final</version>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>5.2.4.Final</version>
</dependency>

注意：validation-api 只定義介面，必須搭配實作（如 hibernate-validator），否則啟動會報錯。

2. 常用驗證註解

3. 實體類別範例

public class User implements Serializable {
    @Size(min = 1, max = 32, message = "帳號長度應在 1-32 字元")
    private String username;

    @NotEmpty(message = "密碼不得為空")
    private String password;

    @NotEmpty(message = "Email 不得為空")
    @Email(message = "Email 格式錯誤")
    private String email;

    @Size(min = 11, max = 11, message = "手機號碼必須 11 碼")
    private String cellphone;
    // getter/setter 省略
}

4. Controller 處理驗證結果

@Controller
@RequestMapping("/user")
public class UserController {
    @Autowired private UserService userService;

    @PostMapping("/register")
    public String register(@Valid User user, Errors errors) {
        if (errors.hasErrors()) {
            return "register"; // 返回表單頁，錯誤訊息自動綁定
        }
        // 业务逻辑...
        return "redirect:/user/" + user.getUsername();
    }
}

5. JSP 顯示錯誤訊息

<%@ taglib prefix="sf" uri="https://www.springframework.org/tags/form" %>
<sf:form method="POST" commandName="user">
    <!-- 顯示所有欄位錯誤 -->
    <sf:errors path="*" element="div" cssClass="errors" />
    <table>
        <tr><td>帳號:</td><td><sf:input path="username" cssErrorClass="errors" /></td></tr>
        <tr><td>密碼:</td><td><sf:password path="password" cssErrorClass="errors" /></td></tr>
        <tr><td>Email:</td><td><sf:input path="email" cssErrorClass="errors" /></td></tr>
        <tr><td>手機:</td><td><sf:input path="cellphone" cssErrorClass="errors" /></td></tr>
    </table>
    <input type="submit" value="註冊" />
</sf:form>

二、檔案上傳

Spring MVC 透過 MultipartResolver 支援檔案上傳，建議使用 Servlet 3.0+ 容器原生支援（StandardServletMultipartResolver）。

1. 設定上傳限制（DispatcherServlet 初始化）

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
    @Override
    protected void customizeRegistration(ServletRegistration.Dynamic registration) {
        // 單檔 2MB，總請求 4MB，暫存目錄 /tmp/uploads
        registration.setMultipartConfig(
            new MultipartConfigElement("/tmp/uploads", 2_097_152, 4_194_304, 0)
        );
    }
}

2. 註冊 MultipartResolver Bean

@Bean
public MultipartResolver multipartResolver() throws IOException {
    return new StandardServletMultipartResolver();
}

3. Controller 接收上傳檔案

@PostMapping("/{username}/avatar")
public String uploadAvatar(@PathVariable String username,
                           @RequestPart("icon") MultipartFile icon) throws IOException {
    // 建議使用唯一檔名避免衝突
    String destPath = "/var/www/uploads/" + username + "_" + System.currentTimeMillis() + ".jpg";
    icon.transferTo(new File(destPath));
    return "userProfile";
}

4. 前端表單（需設定 enctype）

<form method="post" enctype="multipart/form-data">
    <label>上傳頭像：</label>
    <input type="file" name="icon" accept="image/jpeg, image/png" />
    <button type="submit">上傳</button>
</form>

進階：多檔上傳與驗證整合

• 多檔：Controller 參數改為 List<MultipartFile> 或 MultipartFile[]，前端 name 相同且加上 multiple 屬性。
• 檔案類型/大小驗證：可在 Controller 中手動檢查 icon.getContentType()、icon.getSize()，或自訂 Validator 註解（如 @ValidFile）搭配 @Valid 使用。

常見問題排查

1. 400 Bad Request：通常是 enctype 遺漏、或檔案大小超過 MultipartConfig 限制。
2. 驗證不生效：確認 hibernate-validator 依賴存在、@Valid 正確標註、Errors/BindingResult 緊跟在 @Valid 參數之後。
3. 中文檔名亂碼：Tomcat 8+ 需在 server.xml 的 Connector 加 URIEncoding="UTF-8"；或使用 UUID 重命名檔案。