Java 常用注解扩展对比

Java 常用注解扩展对比（2025–2026 主流实践视角）

Java 生态中注解（Annotation）是现代开发的核心，几乎所有框架都依赖注解驱动开发。不同框架/库的同类功能注解经常重名、冲突或功能相似，导致开发者容易混淆。

下面按功能分类，把最常用的注解进行横向对比，覆盖 Spring Boot、Jakarta EE（原 Java EE）、Lombok、JPA/Hibernate、Jackson、MyBatis、Validation 等主流场景。

1. 实体类 / DTO 字段简化注解（Lombok vs Record vs 原生）

功能需求	Lombok 注解	Java Record (JDK 14+)	原生 / 手动写法	推荐场景（2025+）	注意事项 / 坑点
getter + setter	@Getter @Setter 或 @Data	自动生成（不可变）	手动写	DTO → Lombok / Record Entity → 慎用	@Data 在 JPA Entity 上极易出 equals/hashCode 问题
equals / hashCode	@EqualsAndHashCode	自动生成（基于所有字段）	手动实现	值对象用 Record Entity 慎用 Lombok	Entity 不要包含关系字段，否则 Hibernate 死循环
toString()	@ToString	自动生成	手动	DTO 可 Lombok Entity 用 @ToString.Exclude	排除懒加载字段，否则 N+1 或栈溢出
全字段 final + getter	@Value	天然 Record	—	不可变值对象首选 Record	@Value 不生成 setter，适合 DTO / VO
构造函数	@RequiredArgsConstructor @AllArgsConstructor	自动全参构造	手动	Record 自动 Lombok 灵活	JPA Entity 慎用全参构造（可能破坏代理）
Builder 模式	@Builder	—（可配合 @Builder 插件）	手动 Lombok 或 Builder 类	复杂对象初始化首选 Lombok @Builder	与 @Data 组合使用时注意 equals 一致性

小结：

• DTO/VO/参数对象 → Lombok @Data / @Value / @Builder 或 Record
• JPA Entity → 不要用 @Data，推荐 @Getter @Setter @ToString(exclude = {"lazyFields"}) 或只用 getter + 手动 equals/hashCode（基于 id）
• 不可变值对象 → 优先 Java Record（类型安全、简洁、无需依赖）

2. 校验注解对比（jakarta.validation vs Spring vs Hibernate）

注解	来自包	功能描述	典型使用位置	常用替代 / 扩展	备注 / 区别
@NotNull	jakarta.validation.constraints	不能为 null	字段、参数	Spring @NonNull	允许空字符串、空集合
@NotEmpty	jakarta.validation.constraints	不能为 null 且长度/大小 > 0	String/集合/数组	—	字符串不允许 “”
@NotBlank	jakarta.validation.constraints	不能为 null 且 trim 后长度 > 0	String	—	最常用字符串非空校验
@Valid	jakarta.validation	触发嵌套对象校验	Controller 参数、字段	Spring @Validated（支持分组）	@Valid 不支持分组
@Validated	org.springframework.validation	Spring 扩展，支持分组校验	Controller 类、方法	—	必须用在类/方法上，支持 @Valid 嵌套
@Size(min,max)	jakarta.validation.constraints	长度/大小范围	String/集合/数组	—	包含边界
@Min / @Max	jakarta.validation.constraints	数值最小/最大值	数字类型	—	支持 BigDecimal 等
@Email	jakarta.validation.constraints	邮箱格式	String	正则自定义	依赖 hibernate-validator
@Pattern	jakarta.validation.constraints	正则表达式	String	—	最灵活

小结：

• Controller 方法参数 → 用 @Valid 或 @Validated
• 嵌套对象校验 → 字段上加 @Valid
• 需要分组校验（如创建/更新不同规则） → 用 @Validated + groups

3. 序列化/反序列化注解（Jackson 最常用）

注解	功能	典型场景	替代方案	注意事项
@JsonProperty	指定 JSON 字段名	前后端字段名不一致	@JsonAlias	最常用
@JsonIgnore	忽略字段序列化/反序列化	密码、敏感字段	@JsonIgnoreProperties	—
@JsonInclude	控制 null/空值是否输出	减少 JSON 体积	NON_NULL / NON_EMPTY / NON_DEFAULT	类或字段级别
@JsonFormat	日期/时间格式化	LocalDateTime 输出格式	—	pattern = “yyyy-MM-dd HH:mm:ss”
@JsonNaming	全局命名策略（蛇形、驼峰等）	统一命名风格	—	PropertyNamingStrategies
@JsonUnwrapped	展开嵌套对象字段	扁平化 DTO	—	—
@JsonView	按视图控制字段输出	不同接口返回不同字段	—	常与 @JsonView 接口配合

4. Spring 核心注解对比

注解	作用	主要使用场景	常见替代 / 扩展	注意事项
@Component / @Service / @Repository / @Controller	声明 Spring Bean	组件扫描	@ComponentScan	分层语义不同
@Autowired	自动注入	字段/构造器/方法	推荐构造器注入	字段注入不推荐（测试困难）
@Qualifier	指定注入的 Bean 名称	同类型多个 Bean	@Primary	—
@Value	读取配置属性	${} / :default	@ConfigurationProperties	简单值用 @Value，复杂对象用 @ConfigurationProperties
@ConfigurationProperties	批量绑定配置前缀	配置类	@EnableConfigurationProperties	支持前缀、校验、转换器
@Transactional	声明式事务	service 方法	propagation / isolation / rollbackFor	类/方法级别
@Async	异步执行	方法	@EnableAsync	需要配置线程池

5. JPA / MyBatis 常用注解对比

功能	JPA / Hibernate 注解	MyBatis 注解	场景选择建议
实体映射	@Entity @Table @Id @Column @GeneratedValue	@Table @Results @ResultMap	复杂关系 → JPA SQL 灵活 → MyBatis
一对多 / 多对多	@OneToMany @ManyToOne @ManyToMany	手动 ResultMap / 嵌套查询	JPA 更自动，MyBatis 更可控
动态 SQL	Criteria / QueryDSL / Specification	@SelectProvider / XML	MyBatis 动态 SQL 最强
缓存	@Cacheable / 二级缓存	@CacheNamespace	—

总结：2025–2026 推荐组合

• 实体类（Entity）：JPA + @Entity @Getter @Setter @ToString(exclude=...)（慎用 @Data）
• DTO / VO：Record 或 Lombok @Value @Builder
• 校验：jakarta.validation + Spring @Validated
• JSON：Jackson + @JsonProperty @JsonInclude
• 配置：@ConfigurationProperties > @Value
• 事务：@Transactional（rollbackFor = Exception.class）
• Lombok 使用原则：DTO 大量使用，Entity 谨慎使用

如果你想针对某个具体场景（如 Spring Boot + JPA + Lombok 最佳实践、Jackson 与 Record 配合、校验分组等）做更深入对比或代码示例，欢迎告诉我！