聊一聊在 Spring Boot 项目中自定义 Validation 注解

在Spring Boot项目中自定义Validation注解，可按以下步骤实现，以手机号格式校验（支持多地区）为例：

一、定义自定义注解

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;@Target({ElementType.FIELD, ElementType.PARAMETER}) // 作用于字段和方法参数
@Retention(RetentionPolicy.RUNTIME) // 运行时生效
@Constraint(validatedBy = PhoneValidator.class) // 关联校验器
public @interface Phone {String message() default "手机号格式错误"; // 错误提示Class<?>[] groups() default {}; // 分组校验（如新增、更新）Class<? extends Payload>[] payload() default {}; // 负载信息（可选）String region() default "CN"; // 自定义属性：地区（默认中国）
}

二、实现校验逻辑（ConstraintValidator）

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;public class PhoneValidator implements ConstraintValidator<Phone, String> {private String region; // 存储注解的region属性@Overridepublic void initialize(Phone constraintAnnotation) {this.region = constraintAnnotation.region(); // 初始化，获取地区配置}@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {if (value == null) return true; // 允许为空（若必填需额外处理，如@NotBlank配合使用）// 根据地区校验格式switch (region) {case "CN": // 中国手机号：11位，以1开头，第二位3-9return value.matches("^1[3-9]\\d{9}$");case "US": // 美国手机号：+1开头，后跟10位数字return value.matches("^\\+1\\d{10}$");default:return false; // 未知地区，校验失败}}
}

三、应用自定义注解

1. 在DTO中使用

public class UserDTO {@NotBlankprivate String username;@Phone(region = "CN") // 校验中国手机号private String phone;// 若需校验美国手机号，可设置region="US"// @Phone(region = "US")// private String usPhone;// getters/setters
}

2. 在Controller中触发校验

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;@RestController
public class UserController {@PostMapping("/register")public String register(@Validated @RequestBody UserDTO dto) {// 校验通过，执行注册逻辑return "注册成功";}
}

四、处理校验异常（全局异常处理器）

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;@ControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(MethodArgumentNotValidException.class)public ResponseEntity<ErrorResponse> handleValidationError(MethodArgumentNotValidException ex) {BindingResult result = ex.getBindingResult();StringBuilder errorMsg = new StringBuilder();for (FieldError error : result.getFieldErrors()) {errorMsg.append(error.getField()).append(": ").append(error.getDefaultMessage()).append("; ");}return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new ErrorResponse(HttpStatus.BAD_REQUEST.value(), errorMsg.toString()));}static class ErrorResponse {private int code;private String message;public ErrorResponse(int code, String message) {this.code = code;this.message = message;}// getters}
}

五、扩展功能

1. 分组校验（如新增和更新场景）

// 定义分组接口
public interface CreateGroup {}
public interface UpdateGroup {}// 在DTO中指定分组
@Phone(region = "CN", groups = CreateGroup.class) // 新增时校验手机号
private String phone;// Controller中使用分组
@PostMapping("/create")
public String create(@Validated(CreateGroup.class) @RequestBody UserDTO dto) { ... }@PutMapping("/update")
public String update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) { ... }

2. 国际化错误消息

在src/main/resources下创建ValidationMessages.properties：

Phone.message=手机号格式错误（中文）
Phone.message_en=Invalid phone number format（英文）

Spring Boot会根据Accept-Language头自动匹配语言。

3. 复杂业务校验（如手机号唯一性）

// 校验器中注入Service（需将校验器标记为@Component，由Spring管理）
@Component
public class PhoneValidator implements ConstraintValidator<Phone, String> {@Autowiredprivate UserService userService; // 假设UserService提供手机号唯一性查询@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {// 先校验格式，再校验唯一性if (!isFormatValid(value)) return false;return !userService.existsByPhone(value); // 假设existsByPhone查询数据库}private boolean isFormatValid(String value) {// 复用之前的格式校验逻辑return value.matches("^1[3-9]\\d{9}$");}
}

六、验证效果

• 合法请求：phone=13812345678，校验通过，正常处理。
• 非法请求：phone=123（格式错误），返回：

  {"code": 400,"message": "phone: 手机号格式错误; "
  }
  

总结

自定义Validation注解的关键步骤为：

1. 定义注解：通过@Constraint关联校验器，设置属性（如地区、错误消息）。
2. 实现校验逻辑：在ConstraintValidator中编写具体规则（格式、唯一性等）。
3. 应用注解：在DTO/参数上标注，结合@Validated触发校验。
4. 处理异常：通过全局异常处理器返回标准化错误，提升用户体验。

这种方式可灵活扩展Spring Boot的校验能力，满足复杂业务需求（如多地区格式、业务规则校验），确保输入数据的合法性，是微服务架构中参数校验的重要实践。