Java的jakarta.validation自定义Constraint注解与实现：从入门到精通

本文系统讲解了如何在Java中使用jakarta.validation框架自定义Constraint注解与实现，从用途介绍到环境配置，再到快速上手和进阶实践，帮助编程小白在较短时间内掌握该技术栈的完整学习闭环。

像少年啦飞驰点、

329人浏览 · 2026-03-05 16:42:31

像少年啦飞驰点、 · 2026-03-05 16:42:31 发布

Java的jakarta.validation自定义Constraint注解与实现：从入门到精通

一、技术栈用途介绍

在现代软件开发中，数据校验是一个非常重要的环节。无论是用户输入表单、后端服务接收参数，还是数据库操作，都需要对数据的合法性进行校验。而jakarta.validation（原JSR 380）是Java平台上的标准数据校验框架，它提供了一套扩展性很强的校验机制，可以通过注解方便地完成数据验证。

能解决哪些问题？

简化数据校验逻辑：通过注解直接声明校验规则，无需在业务代码中编写繁琐的校验逻辑。
提高代码可读性：校验规则与数据模型绑定，使代码结构更加清晰。
支持自定义校验规则：除了内置的校验规则（如@NotNull、@Min），还可以扩展自定义校验注解。

典型应用场景

前端数据表单校验：校验用户输入是否符合要求。
后端接口参数校验：确保传入的参数合法性。
数据库操作校验：避免非法数据写入数据库。

示例业务场景

假设我们在开发一个用户注册系统，用户名需要满足以下规则：

必须为非空字符串。
长度在 5 到 20 个字符之间。
不允许包含特殊字符。

通过jakarta.validation，我们可以定义一个自定义注解来完成这些规则校验。

二、环境准备与安装配置

主要依赖

要使用jakarta.validation，需要引入以下依赖：

<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>7.0.0.Final</version>
</dependency>

环境配置步骤

安装JDK：确保已安装JDK 8及以上版本。
创建Maven项目：使用IDE（如IntelliJ IDEA或Eclipse）创建一个新的Maven项目。
添加依赖：将上述依赖加入pom.xml文件。
配置验证实现：jakarta.validation需要一个实现库，推荐使用Hibernate Validator。

常见问题与排查

依赖冲突：检查是否引入了多个版本的jakarta.validation或Hibernate Validator。
无法加载ValidatorFactory：确保META-INF/services目录下有相关配置文件。

三、入门实践（快速上手 Demo）

接下来我们将从零开始搭建一个简单的工程，完成自定义校验注解的功能。

示例工程结构

src/main/java/
  ├── com.example.validation/
      ├── annotation/
      │     └── ValidUsername.java
      ├── validator/
      │     └── ValidUsernameValidator.java
      ├── model/
      │     └── User.java
      └── MainApplication.java

步骤 1：定义自定义注解

创建ValidUsername.java，用于校验用户名：

package com.example.validation.annotation;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = ValidUsernameValidator.class)
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidUsername {
    String message() default "用户名非法";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

步骤 2：实现校验逻辑

创建ValidUsernameValidator.java，实现校验逻辑：

package com.example.validation.validator;

import com.example.validation.annotation.ValidUsername;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class ValidUsernameValidator implements ConstraintValidator<ValidUsername, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null || value.isEmpty()) {
            return false;
        }
        return value.matches("^[a-zA-Z0-9]{5,20}$");
    }
}

步骤 3：创建数据模型

创建User.java，应用注解：

package com.example.validation.model;

import com.example.validation.annotation.ValidUsername;

public class User {

    @ValidUsername
    private String username;

    // Getter and Setter
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }
}

步骤 4：运行验证逻辑

创建MainApplication.java，测试校验：

package com.example.validation;

import com.example.validation.model.User;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.ValidatorFactory;

public class MainApplication {
    public static void main(String[] args) {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();

        User user = new User();
        user.setUsername("abc!");

        validator.validate(user).forEach(violation -> {
            System.out.println(violation.getMessage());
        });
    }
}

运行后将输出：

用户名非法

四、进阶与原理（高级用法或深入机制）

支持国际化

可以通过资源文件实现错误信息的国际化：

# messages.properties
ValidUsername=用户名必须是5到20个字符的字母或数字

并在注解中指定属性：

String message() default "{ValidUsername}";

与Spring集成

在Spring项目中，可以直接使用@Validated注解结合jakarta.validation实现参数校验：

@RestController
public class UserController {

    @PostMapping("/register")
    public ResponseEntity<String> register(@RequestBody @Valid User user) {
        // 业务逻辑
        return ResponseEntity.ok("注册成功");
    }
}