Spring MVC 學習系列 (六)：JSR-303 Bean Validation 數據驗證完整接入指南

Spring MVC 數據綁定後，必須驗證合法性。本文以 Hibernate Validator (JSR-303/349/380 參考實現) 為例，從依賴引入、Validator Bean 配置、模型註解驗證、Controller @Valid + BindingResult、國際化訊息配置、JSP 表單錯誤顯示 六大步驟，提供可直接運行的完整範例。

一、Maven 依賴 (Hibernate Validator 6.x / Jakarta Bean Validation 2.x)

<dependencies>
  <!-- JSR-380 API -->
  <dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>2.0.2</version>
  </dependency>
  <!-- Hibernate Validator 實現 -->
  <dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.2.5.Final</version>
  </dependency>
  <!-- 表達式語言 (EL) 依賴，支援訊息插值 -->
  <dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>jakarta.el</artifactId>
    <version>3.0.3</version>
  </dependency>
</dependencies>

二、Spring MVC 配置啟用 Validator

<!-- spring-mvc.xml -->
<mvc:annotation-driven validator="validator" conversion-service="conversionService"/>

<bean id="validator" 
      class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean">
  <property name="providerClass" value="org.hibernate.validator.HibernateValidator"/>
  <property name="validationMessageSource" ref="messageSource"/>
</bean>

<bean id="messageSource"
      class="org.springframework.context.support.ReloadableResourceBundleMessageSource">
  <property name="basename" value="classpath:messages/validation"/>
  <property name="defaultEncoding" value="UTF-8"/>
  <property name="cacheSeconds" value="120"/>
</bean>

<bean id="conversionService"
      class="org.springframework.format.support.FormattingConversionServiceFactoryBean"/>

三、驗證模型 (JSR-303 註解)

public class UserForm {
  @NotBlank(message = "{user.name.notblank}")
  @Size(min = 2, max = 20, message = "{user.name.size}")
  private String name;

  @Min(value = 0, message = "{user.age.min}")
  @Max(value = 150, message = "{user.age.max}")
  private Integer age;

  @NotBlank(message = "{user.email.notblank}")
  @Email(message = "{user.email.invalid}")
  private String email;

  // getter/setter 省略
}

四、國際化訊息檔 (messages/validation.properties)

user.name.notblank=姓名不能為空
user.name.size=姓名長度需在 2-20 字符之間
user.age.min=年齡不能小於 0
user.age.max=年齡不能大於 150
user.email.notblank=電子郵件不能為空
user.email.invalid=電子郵件格式不正確

五、Controller 驗證入口

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

  @GetMapping("/register")
  public String showForm(Model model) {
    model.addAttribute("userForm", new UserForm());
    return "register";
  }

  @PostMapping("/register")
  public String register(@Valid @ModelAttribute("userForm") UserForm form, 
                         BindingResult result, Model model) {
    // 有錯誤回表單頁，錯誤訊息自動綁定到 result
    if (result.hasErrors()) {
      return "register";
    }
    // 業務邏輯...
    return "redirect:/user/success";
  }
}

六、JSP 表單錯誤顯示 (Spring Form 標籤庫)

<%@ taglib prefix="form" uri="https://www.springframework.org/tags/form" %>
<form:form modelAttribute="userForm" method="post">
  <!-- 全局錯誤 -->
  <form:errors path="*" cssClass="error-block" /><br/>

  姓名: <form:input path="name" />
  <form:errors path="name" cssClass="error-inline" /><br/>

  年齡: <form:input path="age" />
  <form:errors path="age" cssClass="error-inline" /><br/>

  郵箱: <form:input path="email" />
  <form:errors path="email" cssClass="error-inline" /><br/>

  <input type="submit" value="註冊" />
</form:form>

七、常用驗證註解速查表

八、進階：分組驗證、自定義註解、方法級驗證

• 分組驗證：@NotNull(groups = UpdateGroup.class)，Controller @Validated(UpdateGroup.class)。
• 自定義註解：實作 ConstraintValidator，註解標註 @Constraint(validatedBy = ...)。
• 方法級驗證：Service 方法加 @Validated，參數加 @NotNull 等，AOP 攔截驗證。

總結

Spring MVC + Hibernate Validator 以「註解聲明規則、@Valid 觸發驗證、BindingResult 收集錯誤、MessageSource 國際化訊息、form:errors 顯示」標準流程，實現聲明式數據驗證。**新專案請直接使用 Jakarta Bean Validation 3.0 (Hibernate Validator 8.x) + Spring Boot 3.x**，配置更簡潔 (@EnableValidation 自動裝配)。