在 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 上找到。