Java EE/Jakarta EE 三大规范详解：CDI、JPA 与 Bean Validation

@ApplicationScoped
public class GreetingService {
    public String greet(String name) {
        return "Hello, " + name;
    }
}

@RequestScoped
public class UserController {

    @Inject
    private GreetingService greetingService;

    public void handleRequest() {
        System.out.println(greetingService.greet("Alice"));
    }
}

public class Resources {
    @Produces
    @RequestScoped
    public EntityManager produceEntityManager() {
        return Persistence.createEntityManagerFactory("myPU").createEntityManager();
    }
}

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    private int age;

    // Getters & Setters
}

@ApplicationScoped
public class UserRepository {

    @Inject
    private EntityManager em;

    public User findById(Long id) {
        return em.find(User.class, id);
    }

    public void save(User user) {
        em.getTransaction().begin();
        em.persist(user);
        em.getTransaction().commit();
    }
}

@Entity
public class User {

    @Id
    @GeneratedValue
    private Long id;

    @NotNull
    @Size(min = 2, max = 20)
    private String name;

    @Min(18)
    private int age;

    @Email
    private String email;
}

@Path("/users")
@RequestScoped
public class UserResource {

    @Inject
    private UserRepository userRepo;

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response createUser(@Valid User user) {
        userRepo.save(user);
        return Response.status(201).build();
    }
}

@Provider
public class ConstraintViolationMapper implements ExceptionMapper<ConstraintViolationException> {

    @Override
    public Response toResponse(ConstraintViolationException ex) {
        List<String> errors = ex.getConstraintViolations().stream()
            .map(cv -> cv.getPropertyPath() + ": " + cv.getMessage())
            .collect(Collectors.toList());

        return Response.status(Response.Status.BAD_REQUEST)
                       .entity(errors)
                       .build();
    }
}

@Path("/register")
@RequestScoped
public class RegistrationResource {

    @Inject
    private UserRepository repo;

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response register(@Valid User user) {
        repo.save(user);
        return Response.status(201).entity("User registered!").build();
    }
}

<dependencies>
    <!-- CDI -->
    <dependency>
        <groupId>jakarta.enterprise</groupId>
        <artifactId>jakarta.enterprise.cdi-api</artifactId>
        <version>4.0.1</version>
        <scope>provided</scope>
    </dependency>

    <!-- JPA -->
    <dependency>
        <groupId>jakarta.persistence</groupId>
        <artifactId>jakarta.persistence-api</artifactId>
        <version>3.1.0</version>
    </dependency>

    <!-- Bean Validation -->
    <dependency>
        <groupId>jakarta.validation</groupId>
        <artifactId>jakarta.validation-api</artifactId>
        <version>3.0.2</version>
    </dependency>

    <!-- Hibernate Validator 实现 -->
    <dependency>
        <groupId>org.hibernate.validator</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>8.0.1.Final</version>
    </dependency>

    <!-- H2 数据库（开发用） -->
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <version>2.2.224</version>
    </dependency>
</dependencies>

// Jakarta EE 9+ 正确写法
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.validation.constraints.NotNull;

@ApplicationScoped
public class ModernService {

    @Inject
    private LegacyRepository repo;

    public void create(@NotNull String name) {
        repo.save(name);
    }
}

// 命名查询定义
@Entity
@NamedQueries({
    @NamedQuery(
        name = "User.findByNameLike",
        query = "SELECT u FROM User u WHERE u.name LIKE :pattern"
    )
})
public class User { /* ... */ }

// 使用命名查询
public List<User> searchUsers(String keyword) {
    TypedQuery<User> query = em.createNamedQuery("User.findByNameLike", User.class);
    query.setParameter("pattern", "%" + keyword + "%");
    return query.getResultList();
}

public List<User> findUsersByAgeRange(int minAge, int maxAge) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<User> cq = cb.createQuery(User.class);
    Root<User> root = cq.from(User.class);

    Predicate ageBetween = cb.between(root.get("age"), minAge, maxAge);
    cq.where(ageBetween);
    cq.orderBy(cb.desc(root.get("id")));

    return em.createQuery(cq).getResultList();
}

public List<Object[]> getUserStats() {
    String sql = """
        SELECT u.department, COUNT(*), AVG(u.age)
        FROM users u
        GROUP BY u.department
        HAVING COUNT(*) > 5
        ORDER BY COUNT(*) DESC
        """;
    Query query = em.createNativeQuery(sql);
    return query.getResultList();
}

public List<User> findPage(int page, int size) {
    TypedQuery<User> query = em.createQuery("SELECT u FROM User u", User.class);
    query.setFirstResult(page * size);  // 起始偏移量
    query.setMaxResults(size);          // 每页数量

    // 启用查询缓存（需配合 ehcache 或 Caffeine 等缓存实现）
    query.setHint("org.hibernate.cacheable", true);
    return query.getResultList();
}

// 定义领域事件
public class OrderCreatedEvent {
    private final Long orderId;
    private final BigDecimal amount;

    public OrderCreatedEvent(Long orderId, BigDecimal amount) {
        this.orderId = orderId;
        this.amount = amount;
    }
    // getters ...
}

// 事件生产者
@ApplicationScoped
public class OrderService {

    @Inject
    private Event<OrderCreatedEvent> event;

    public void createOrder(Long orderId, BigDecimal amount) {
        // 执行业务逻辑 ...
        event.fire(new OrderCreatedEvent(orderId, amount));
    }
}

// 事件消费者
@ApplicationScoped
public class NotificationHandler {

    public void onOrderCreated(@Observes OrderCreatedEvent event) {
        System.out.println("订单已创建: " + event.getOrderId()
            + ", 金额: " + event.getAmount());
    }
}

// 自定义限定符
@Qualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
public @interface AsyncProcessing { }

// 生产者带限定符触发
@Inject
@AsyncProcessing
private Event<OrderCreatedEvent> asyncEvent;

// 消费者仅响应该限定符事件
public void asyncHandle(@Observes @AsyncProcessing OrderCreatedEvent event) {
    // 异步邮件发送逻辑
}

// 异步触发事件（fireAsync 返回 CompletionStage）
public void createOrderAsync(Long orderId, BigDecimal amount) {
    event.fireAsync(new OrderCreatedEvent(orderId, amount))
         .thenRun(() -> System.out.println("异步事件处理完成"));
}

// 异步消费者
public void asyncObserver(@ObservesAsync OrderCreatedEvent event) {
    // 在独立线程中执行
}

// 事务性事件：仅在事务提交成功后触发
public void onTxSuccess(@Observes(during = TransactionPhase.AFTER_SUCCESS)
                        OrderCreatedEvent event) {
    // 确保订单已持久化后再发邮件，避免事务回滚导致不一致
}

// 定义约束注解
@Constraint(validatedBy = PhoneNumberValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface PhoneNumber {
    String message() default "手机号格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// 验证器实现
public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {

    private static final Pattern PATTERN = Pattern.compile("^1[3-9]\\d{9}$");

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null || value.isEmpty()) {
            return true; // 使用 @NotNull 处理空值
        }
        return PATTERN.matcher(value).matches();
    }
}

// 类级别约束注解
@Constraint(validatedBy = DateRangeValidator.class)
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidDateRange {
    String message() default "结束日期必须晚于开始日期";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// 需要验证的实体
@Entity
@ValidDateRange
public class EventPlan {

    @Id
    @GeneratedValue
    private Long id;

    private LocalDate startDate;
    private LocalDate endDate;

    // getters & setters
}

// 类级别验证器
public class DateRangeValidator implements ConstraintValidator<ValidDateRange, EventPlan> {

    @Override
    public boolean isValid(EventPlan plan, ConstraintValidatorContext context) {
        if (plan.getStartDate() == null || plan.getEndDate() == null) {
            return true;
        }
        boolean valid = plan.getEndDate().isAfter(plan.getStartDate());

        if (!valid) {
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(context.getDefaultConstraintMessageTemplate())
                   .addPropertyNode("endDate")
                   .addConstraintViolation();
        }
        return valid;
    }
}

public interface OnCreate { }
public interface OnUpdate { }

@Entity
public class Product {

    @Id
    @GeneratedValue
    private Long id;

    @NotNull(groups = OnCreate.class)
    @Size(min = 2, max = 50, groups = {OnCreate.class, OnUpdate.class})
    private String name;

    @NotNull(groups = OnCreate.class)
    @Min(value = 0, groups = {OnCreate.class, OnUpdate.class})
    private BigDecimal price;
}

// 仅在创建时校验 id 存在性
public Response create(@Validated(OnCreate.class) Product product) { ... }
public Response update(@Validated(OnUpdate.class) Product product) { ... }

// Quarkus 控制器示例（Jakarta REST + CDI + Bean Validation）
import jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/api/users")
public class UserResource {

    @Inject
    UserService userService;

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response create(@Valid UserDto dto) {
        User user = userService.create(dto);
        return Response.status(201).entity(user).build();
    }

    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public User getById(@PathParam("id") Long id) {
        return userService.findById(id);
    }
}

// 实体与验证 DTO
import jakarta.validation.constraints.*;

public class UserDto {

    @NotBlank(message = "用户名不能为空")
    @Size(max = 30)
    private String username;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Min(1)
    @Max(150)
    private int age;
}

// Micronaut Repository（兼容 JPA 实体）
import io.micronaut.data.annotation.*;
import io.micronaut.data.repository.CrudRepository;
import jakarta.validation.constraints.NotNull;

@Repository
public interface UserRepository extends CrudRepository<User, Long> {

    // Micronaut Data 自动生成查询实现
    List<User> findByNameContaining(String name);

    @Query("SELECT u FROM User u WHERE u.age > :minAge")
    List<User> findAdults(@NotNull int minAge);
}

// Micronaut 控制器中的 Bean Validation
import io.micronaut.http.annotation.*;
import jakarta.validation.Valid;

@Controller("/users")
public class UserController {

    @Post
    public HttpResponse<User> create(@Body @Valid UserDto dto) {
        // 校验失败时自动返回 400 Bad Request
        return HttpResponse.ok();
    }
}