表單驗證這樣處理才優雅！深入掌握 Spring Boot 3.3 中的 MessageCodesResolver 錯誤處理技巧
在 Web 應用開發中，表單驗證是確保數據正確性和安全性的重要步驟。當用戶提交表單時，服務器端驗證可以防止惡意輸入、缺失數據或格式錯誤。而在 Spring Boot 中，表單驗證機制已經非常成熟，特別是通過注解驅動的驗證方法，例如 @Valid 和 @NotBlank 等，能夠方便地驗證用戶提交的數據。
然而，僅僅依靠默認的驗證機制，可能不足以提供豐富的用戶體驗，特別是在處理多層次、多語言支持的錯誤提示時。這里就需要引入 MessageCodesResolver，這是 Spring 提供的一種用于生成驗證錯誤碼的接口。它允許我們通過靈活的錯誤碼映射來為不同的字段生成不同層次的錯誤信息，從而實現多級驗證提示。使用 MessageCodesResolver，可以根據不同字段和錯誤類型生成不同的錯誤碼，支持更細粒度的錯誤反饋和國際化的處理。
運行效果：
圖片
圖片
若想獲取項目完整代碼以及其他文章的項目源碼，且在代碼編寫時遇到問題需要咨詢交流，歡迎加入下方的知識星球。
本篇文章將詳細介紹如何使用 MessageCodesResolver，并結合 Spring Boot 3.3 中的其他驗證機制，構建優雅且靈活的表單驗證錯誤處理方案。
環境準備
首先，確保我們有一個 Spring Boot 項目，并添加了必要的依賴，如 spring-boot-starter-web、spring-boot-starter-validation、spring-boot-starter-thymeleaf 以及 lombok。
項目依賴（pom.xml 配置）
<?xml versinotallow="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.4</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.icoderoad</groupId>
<artifactId>spring-boot-messagecodes</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>spring-boot-messagecodes</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<!-- Spring Boot Web Starter -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Validation -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- Thymeleaf -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>配置文件（application.yml）
server:
port: 8080
spring:
thymeleaf:
cache: false
messages:
basename: messagesMessageCodesResolver 概述
MessageCodesResolver 是 Spring 提供的一個非常靈活的接口，專門用于為驗證錯誤生成消息代碼。它的核心功能是根據字段名、對象名和驗證錯誤類型生成多個候選的錯誤消息碼，開發者可以為不同的字段和驗證類型配置特定的錯誤消息。
在默認情況下，Spring 的驗證框架會為每個字段生成多條錯誤信息碼，這些碼會按優先級依次匹配配置的消息文件。例如，假設你在表單中有一個 email 字段未通過 @NotBlank 驗證，那么默認生成的錯誤碼可能包括：
- userForm.email.notblank
- email.notblank
- notblank
這三個不同層次的錯誤碼分別表示字段級別、全局級別和驗證類型級別的錯誤信息。通過 MessageCodesResolver，我們可以靈活地控制這些錯誤碼的生成方式，使得錯誤提示更加具有針對性。例如，在國際化（i18n）應用中，不同語言可以針對不同的錯誤碼配置特定的消息提示。
通過自定義 MessageCodesResolver，我們可以精確地控制錯誤碼生成的規則，提供更優雅的驗證反饋方案。
代碼實現
實體類定義
我們使用 Lombok 來簡化實體類的編寫，通過 @ConfigurationProperties 讀取表單配置屬性。
package com.icoderoad.messagecodes.entity;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Data
@Component
@ConfigurationProperties(prefix = "user")
public class UserForm {
@NotBlank(message = "{user.name.notblank}")
private String name;
@NotBlank(message = "{user.email.notblank}")
private String email;
}控制器實現
在 Spring Boot 中，表單驗證通常通過 @Valid 注解和 BindingResult 一起使用。@Valid 注解用于觸發對綁定對象（例如表單對象）的驗證，而 BindingResult 則用于捕獲驗證結果。
@Valid 注解
@Valid 是 Java Bean Validation 中常用的注解，標記在控制器的方法參數上時，Spring 框架會自動執行驗證。它結合 JSR-303 和 Hibernate Validator 可以為實體字段進行注解式的驗證。比如在我們的 UserForm 中，字段 name 和 email 分別使用了 @NotBlank 注解，當提交的表單中這些字段為空時，@Valid 會捕獲并生成相應的驗證錯誤。
BindingResult 詳解
BindingResult 是 Spring 中用于存儲驗證結果的對象，它包含了所有驗證失敗的字段和對應的錯誤信息。通常情況下，BindingResult 作為 @Valid 參數的后一個參數，用來判斷表單提交的數據是否存在錯誤。在控制器中，我們通過 BindingResult 來檢查是否有驗證錯誤，如果有，則可以返回相應的錯誤提示。
package com.icoderoad.messagecodes.controller;
import com.icoderoad.messagecodes.entity.UserForm;
import jakarta.validation.Valid;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
@Controller
public class UserController {
@GetMapping("/")
public String showForm(UserForm userForm) {
return "index";
}
@PostMapping("/submit")
public String submitForm(@Valid UserForm userForm, BindingResult result, Model model) {
// 使用 BindingResult 檢查是否有驗證錯誤
if (result.hasErrors()) {
model.addAttribute("errors", result.getAllErrors());
return "index";
}
// 如果沒有錯誤，返回成功頁面
return "success";
}
}自定義 MessageCodesResolver
接下來，我們將自定義一個 MessageCodesResolver 來生成多級錯誤碼，使錯誤消息更靈活。
package com.icoderoad.messagecodes.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.DefaultMessageCodesResolver;
import org.springframework.validation.MessageCodesResolver;
@Configuration
public class ValidationConfig {
@Bean
public MessageCodesResolver messageCodesResolver() {
DefaultMessageCodesResolver resolver = new DefaultMessageCodesResolver();
resolver.setMessageCodeFormatter(DefaultMessageCodesResolver.Format.POSTFIX_ERROR_CODE);
return resolver;
}
}Thymeleaf 模板前端代碼
表單頁面通過 Thymeleaf 模板引擎渲染，并使用 jQuery 和 Bootstrap 實現前端樣式和表單驗證。
在 src/main/resources/templates 目錄下創建 index.html 文件：
<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>表單驗證</title>
<link rel="stylesheet">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</head>
<body>
<div class="container">
<h2>用戶注冊表單</h2>
<form action="#" th:action="@{/submit}" th:object="${userForm}" method="post">
<div class="form-group">
<label for="name">姓名</label>
<input type="text" class="form-control" th:field="*{name}" placeholder="請輸入姓名">
<small th:if="${#fields.hasErrors('name')}" th:errors="*{name}" class="form-text text-danger"></small>
</div>
<div class="form-group">
<label for="email">郵箱</label>
<input type="email" class="form-control" th:field="*{email}" placeholder="請輸入郵箱">
<small th:if="${#fields.hasErrors('email')}" th:errors="*{email}" class="form-text text-danger"></small>
</div>
<button type="submit" class="btn btn-primary">提交</button>
</form>
<div th:if="${errors != null}">
<ul class="text-danger">
<li th:each="error : ${errors}" th:text="${error.defaultMessage}"></li>
</ul>
</div>
</div>
</body>
</html>創建 success.html
首先，在 src/main/resources/templates/ 目錄下創建一個名為 success.html 的文件。其內容可以如下：
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>表單提交成功</title>
<link rel="stylesheet">
</head>
<body>
<div class="container">
<h2>表單提交成功</h2>
<p>恭喜！表單已成功提交。</p>
<p>姓名：<span th:text="${user.name}"></span></p>
<p>郵箱：<span th:text="${user.email}"></span></p>
<a href="/" class="btn btn-primary">返回首頁</a>
</div>
</body>
</html>國際化錯誤消息配置
在 src/main/resources 目錄下，創建 messages.properties 文件，存放國際化錯誤消息。
user.name.notblank=姓名不能為空
user.email.notblank=郵箱不能為空運行效果
運行項目后，訪問 http://localhost:8080/，將看到一個用戶注冊表單。提交表單時，如果未填寫姓名或郵箱，系統會顯示對應的錯誤信息。錯誤信息是通過 MessageCodesResolver 生成的多層次錯誤碼，并根據配置文件中的 messages.properties 中的消息碼映射到具體的提示文本。
我們在前端的 Thymeleaf 模板中使用 th:errors 來顯示錯誤信息，并通過 #fields.hasErrors() 方法來判斷表單字段是否存在錯誤。整個表單驗證過程非常流暢，并且錯誤提示靈活且易于維護。
總結
在這篇文章中，我們詳細講解了如何通過 Spring Boot 3.3 中的 MessageCodesResolver 實現更加優雅的表單驗證錯誤處理。通過自定義 MessageCodesResolver，我們能夠為每個字段生成多級別的錯誤碼，使得驗證錯誤的處理更加靈活。在國際化場景下，開發者可以輕松為不同的語言配置不同的錯誤消息，提升用戶體驗。
通過結合 @Valid 注解和 BindingResult 對驗證結果的捕獲與處理，開發者可以輕松地實現后端數據驗證。同時，通過 Thymeleaf 渲染前端模板，配合 jQuery 和 Bootstrap，我們能夠構建出用戶體驗良好的表單驗證機制。
在實際開發中，合理的表單驗證不僅能夠提升用戶體驗，還能有效防止惡意數據輸入，為應用的安全性和穩定性提供保障。
