在 Spring 中綁定自訂驗證訊息

1. 簡介

企業 Java 開發高度依賴 Spring。它是一個強大的框架，可以簡化建立強大、可擴展應用程式的過程。我們可以使用 Spring 高效、簡潔地建立 REST API、微服務或全端 Web 應用程式。

然而，隨著應用程式規模的擴大，它們需要清晰易懂的驗證資訊。自訂驗證資訊解決了這個問題。開發者可以使用它們為用戶提供有用的回饋，而不是令人困惑的錯誤訊息。

在本教程中，我們將討論 Spring Boot 的驗證訊息系統，如何有效地配置它，簡化錯誤處理，並使訊息管理更加直觀。

2. 綁定自訂驗證訊息

為了引導用戶並保證資料完整性，驗證至關重要。 Spring Boot 使用 Java Bean 驗證框架 (JSR-380)，使開發人員能夠使用諸如@NotBlank 、 @Email和@Min等約束註解欄位。

但是，為了提高本地化和可維護性，我們可以將錯誤訊息綁定到外部屬性，而不是對其進行硬編碼。

2.1. 新增驗證依賴

要在 Spring Boot 應用程式中使用validation註解，我們需要新增 Spring Boot Starter Validation 依賴項。該 Starter 包裝了 Hibernate Validator，它是 Bean Validation API (JSR-380) 的參考實作。

對於 Maven 配置，我們將以下內容新增到我們的pom.xml中：

<dependency>

 <groupId>org.springframework.boot</groupId>

 <artifactId>spring-boot-starter-validation</artifactId>

 </dependency>

新增後，Spring Boot 將自動新增必要的元件來支援整個應用程式的驗證，包括 REST 控制器、服務層和表單輸入。

2.2. 使用訊息鍵註記 DTO

設定驗證依賴關係後，讓我們在資料傳輸物件（DTO）中新增註釋，以對傳入資料施加規則。

根據我們的配置，這些註解包含在jakarta.validation.constraints或javax.validation.constraints套件中。

讓我們使用約束註解和參考訊息鍵：

public class UserDTO {

 @NotBlank(message = "{user.name.notblank}")

 private String name;

 @Email(message = "{user.email.invalid}")

 private String email;

 @Min(value = 18, message = "{user.age.min}")

 private int age;

 // Getters and setters

 }

@NotBlank驗證 name 欄位不為空或 null。 @Email驗證 email 欄位的格式， @Min驗證此人是否年滿 18 歲。

我們將使用諸如user.name.notblank之類的訊息鍵來傳達錯誤訊息，而不是將它們直接硬編碼到註釋中（例如，message =「名稱不能為空」）。

在下一步中，我們將使用屬性檔案（ ValidationMessages.properties ）中的這些鍵。

2.3. 建立和建構驗證訊息

現在讓我們建立驗證訊息。 Spring Boot 自訂驗證訊息的核心是ValidationMessages.properties檔案。它透過將錯誤訊息從程式碼中外部化，實現了更清晰的邏輯、更簡單的維護和本地化支援。

我們需要將檔案放在專案的目錄路徑中：

our-project/

 └── src/

 └── main/

 └── resources/

 └── ValidationMessages.properties

如果命名正確並且放置在類別路徑中，Spring Boot 會自動偵測此檔案。

文件中的每個條目都將一條人類可讀的訊息與我們將在 DTO 註解中使用的訊息鍵關聯起來，如下例所示：

# ValidationMessages.properties

 user.name.notblank=Name must not be blank.

 user.email.invalid=Please provide a valid email address.

 user.age.min=Age must be at least 18.

這些鍵對應於DTO中的message屬性：

@NotBlank(message = "{user.name.notblank}")

 @Email(message = "{user.email.invalid}")

 @Min(value = 18, message = "{user.age.min}")

3. 可選訊息來源配置

預設情況下，Spring Boot 從類別路徑上的ValidationMessages.properties載入驗證訊息。

例如，如果我們想要支援多種語言、更改編碼或使用不同的檔案名，我們可以明確地設定MessageSource bean。以下步驟是可選的，但強烈建議您執行：

• Internationalization (I18n) ——支援多種語言環境
• Custom file naming – 使用messages.properties或其他名稱
• Advanced control ——配置回退行為、編碼等。

3.1. 什麼是消息來源？

此 Spring 介面使用.properties檔案中的鍵和語言環境檢索訊息。它是 Spring 國際化和驗證訊息系統的主要組件。

要設定MessageSource,我們將以下 bean 新增到 Spring Boot 應用程式類別或設定類別中：

@Bean

 public MessageSource messageSource() {

 ResourceBundleMessageSource source = new ResourceBundleMessageSource();

 source.setBasename("ValidationMessages"); // Name of your properties file (without .properties)

 source.setDefaultEncoding("UTF-8"); // Ensures proper character encoding

 source.setUseCodeAsDefaultMessage(true); // Optional: fallback to key if message not found

 return source;

 }

以下是主要屬性和用途：

財產	目的
setBasename(“…”)	指定訊息檔案的基本名稱（例如，ValidationMessages）
setDefaultEncoding(“UTF-8”)	確保正確呈現特殊字元和非英語文本
setUseCodeAsDefaultMessage()	如果未找到訊息，則返回密鑰（對於偵錯很有用）

3.2. 支援多種語言

為了支援國際用戶，我們將建立特定於語言環境的文件：

src/main/resources/

 ├── ValidationMessages_en.properties

 ├── ValidationMessages_fr.properties

 ├── ValidationMessages_ar.properties

Spring 會根據使用者的語言環境自動解析適當的文件，可以使用瀏覽器首選項、HTTP 標頭和設定進行設定。

例如， ValidationMessages_fr.properties用於法語本地化。

4. 在控制器中驗證

下一步是在我們使用驗證約束和綁定自訂訊息註釋我們的 DTO 後，啟動驗證並在我們的控制器中優雅地處理錯誤。

使用@Valid註解和BindingResult接口，Spring Boot 可以輕鬆實現這一點。讓我們討論一個 REST 控制器方法，它接受UserDTO物件並對其進行驗證：

@PostMapping("/register")

 public ResponseEntity<?> registerUser(@Valid @RequestBody UserDTO userDTO, BindingResult result) {

 if (result.hasErrors()) {

 List<String> errors = result.getFieldErrors()

 .stream()

 .map(FieldError::getDefaultMessage)

 .collect(Collectors.toList());

 return ResponseEntity.badRequest().body(errors);

 }

 // Proceed with registration logic

 return ResponseEntity.ok("User registered successfully");

 }

下表詳細說明了上述程式碼各個組成部分的作用：

成分	角色
@Valid	觸發傳入的 UserDTO 物件的驗證
BindingResult	捕獲驗證錯誤（如果有）
FieldError	表示單一欄位級錯誤
getDefaultMessage()	從 ValidationMessages.properties 中檢索自訂訊息

4.1. 為什麼要使用綁定結果？

如果我們不使用 BindingResult，Spring 會拋出錯誤。雖然 BindingResult 確實有效，但對於更改錯誤格式、聚合多個錯誤或產生結構化 JSON 回應來說，這並不是最佳選擇。

當我們使用 BindingResult 時，我們可以完全控制如何處理和顯示驗證錯誤。

讓我們舉一個當使用者提供不準確資料時 JSON 錯誤回應的例子。控制器可能會返回：

[

 "Name must not be blank.",

 "Please provide a valid email address.",

 "Age must be at least 18."

 ]

這是乾淨的、可讀的，並且直接與自訂訊息相關。

5. 結論

在本文中，我們討論如何在 Spring Boot 中綁定自訂驗證訊息以簡化使用者回饋。這是透過將錯誤訊息外部化到屬性檔案中來實現的。

此外，我們詳細說明如何透過幾個簡單的步驟創建一個簡潔、可維護且使用者友好的驗證流程。這包括新增驗證依賴項、註釋 DTO、配置訊息來源以及處理控制器中的錯誤。

這種方法除了提高清晰度之外，還進一步促進了本地化和可擴展的應用程式設計。

經過測試的程式碼可在 GitHub 上找到。