Java参数校验需定义自定义注解（@Target、@Retention、@Constraint等元注解）、实现ConstraintValidator校验器（覆盖initialize和isValid）、支持分组与消息定制，并在Controller中用@Valid/@Validated触发验证。

Java 注解在参数校验框架中实现严谨的字段格式校验，核心在于：定义语义清晰的自定义注解 + 实现可复用的校验逻辑 + 与 Jakarta Bean Validation（原 javax.validation）标准无缝集成。不是简单加个注解就完事，关键在约束声明、验证器绑定和运行时触发三者协同。

明确注解作用域与生命周期

自定义注解必须用标准元注解标注，否则框架无法识别或反射读取：

• @Target({ElementType.FIELD, ElementType.PARAMETER})：确保既能用于实体类字段（如 DTO），也能用于 Controller 方法参数（如 @RequestBody UserDTO user）
• @Retention(RetentionPolicy.RUNTIME)：只有保留到运行时，AOP 或验证器才能通过反射获取注解值
• @Constraint(validatedBy = YourValidator.class)：显式绑定校验器实现类，这是校验逻辑落地的关键一环
• @Documented：便于生成 API 文档时自动包含校验说明

编写符合规范的校验器（ConstraintValidator）

校验器必须实现 ConstraintValidator<YourAnnotation, T> 接口，并严格覆盖两个方法：

• initialize()：用于提取注解参数（如正则 pattern、日期格式等），只在首次加载时调用一次
• isValid()：执行实际校验，返回 true 表示通过；注意对 null 值的处理策略（通常允许 null，由 @NotNull 单独控制）

例如校验身份证号格式：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

立即学习“Java免费学习笔记（深入）”；

public class IdCardValidator implements ConstraintValidator<ValidIdCard, String> {
  private static final String REGEX_18 = "^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$";
  @Override
  public boolean isValid(String value, ConstraintValidatorContext context) {
    if (value == null) return true;
    return value.matches(REGEX_18);
  }
}

支持分组校验与错误消息定制

严谨校验需适配不同业务场景，不能一刀切：

• 在注解中声明 groups() default {} 和 payload() default {}，使其兼容 @Validated 的分组机制（如 CreateGroup / UpdateGroup）
• message 属性避免硬编码，改用占位符（如 message = "{user.password.weak}"），配合 MessageSource 实现多语言提示
• 在 isValid() 中使用 ConstraintValidatorContext#buildConstraintViolationWithTemplate() 可动态构造更精准的错误信息（比如指出“第5位应为大写字母”）

让校验自动生效：Controller 层集成

仅定义注解和校验器还不够，必须触发验证流程：

• Controller 方法参数加 @Valid（针对对象）或 @Validated（支持分组）
• Spring Boot 项目确保已引入 spring-boot-starter-validation（自动配置了 MethodValidationPostProcessor）
• 若校验失败，默认抛出 MethodArgumentNotValidException，可通过 @ControllerAdvice 统一捕获并转成标准错误响应

不复杂但容易忽略