Custom Validation Message Binding in Spring Boot: A Comprehensive Guide

Custom Validation Message Binding in Spring Boot: A Comprehensive Guide

Custom validation messages in Spring Boot enhance user feedback by externalizing error messages from code, improving maintainability, and supporting localization. This guide outlines the process of configuring validation, annotating DTOs, and handling errors effectively.

1. Key Concepts and Benefits

• Purpose: Spring Boot’s validation system (via JSR-380/Bean Validation) ensures data integrity and provides user-friendly error messages.
• Impact: Reduces code clutter, simplifies localization, and improves scalability for multilingual applications.
• Core Components:
  • Validation Annotations: @NotBlank, @Email, @Min, etc.
  • Message Keys: Externalized error messages via ValidationMessages.properties.
  • MessageSource Configuration: Enables internationalization and advanced message handling.

2. Implementation Steps

2.1. Add Validation Dependency

• Maven Configuration:

  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>

• Purpose: Enables Bean Validation (Hibernate Validator) for annotations like @NotBlank.

2.2. Annotate DTO with Message Keys

• Example DTO:

  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
  }

• Explanation:
  • Uses message keys (e.g., {user.name.notblank}) instead of hard-coded strings.
  • Ensures validation rules are decoupled from message logic.

2.3. Create ValidationMessages.properties

• File Structure:

  our-project/
  └── src/
      └── main/
          └── resources/
              └── ValidationMessages.properties

• Content Example:

  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.

• Purpose: Maps message keys to human-readable error messages.

2.4. Configure MessageSource for Internationalization

• Bean Configuration:

  @Bean
  public MessageSource messageSource() {
      ResourceBundleMessageSource source = new ResourceBundleMessageSource();
      source.setBasename("ValidationMessages");
      source.setDefaultEncoding("UTF-8");
      source.setUseCodeAsDefaultMessage(true);
      return source;
  }

• Key Properties:
  • setBasename("ValidationMessages"): Specifies the properties file name (without .properties).
  • setDefaultEncoding("UTF-8"): Ensures correct character rendering for non-English locales.
  • setUseCodeAsDefaultMessage(true): Falls back to the key if a message is missing.

2.5. Handle Validation Errors in Controllers

• Controller Example:

  @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);
      }
      return ResponseEntity.ok("User registered successfully");
  }

• Error Response Example:

  [
    "Name must not be blank.",
    "Please provide a valid email address.",
    "Age must be at least 18."
  ]

• Purpose: Captures and returns validation errors using BindingResult.

---

Working Example

DTO with Validation Annotations

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
}

Validation Messages File

# src/main/resources/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.

Controller with Error Handling

@RestController
public class UserController {
    @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);
        }
        return ResponseEntity.ok("User registered successfully");
    }
}

---

Recommendations

• Use MessageSource for Localization: Create locale-specific files like ValidationMessages_fr.properties for multilingual support.
• Avoid Hard-Coded Messages: Always reference message keys in DTOs to centralize error management.
• Test with BindingResult: Use BindingResult to handle errors gracefully, avoiding unhandled exceptions.
• Set Proper Encoding: Ensure UTF-8 encoding to support non-English characters.
• Fallback Handling: Enable setUseCodeAsDefaultMessage(true) for debugging missing messages.

---

Potential Pitfalls

• Incorrect File Placement: Ensure ValidationMessages.properties is in src/main/resources.
• Missing MessageSource Configuration: Without it, Spring may not resolve custom messages.
• Locale Mismatch: Ensure the application’s locale matches the properties file names (e.g., ValidationMessages_fr.properties for French).
• Ignoring BindingResult: Forgetting to check BindingResult can lead to unhandled validation errors.

---

Reference

Bind Custom Validation Message in Spring | Baeldung