Lombok 速查指南：从基础注解到避坑实录

在 Java 工程化开发中，Lombok 几乎是标配工具。它通过编译时字节码修改（JSR 269 Pluggable Annotation Processing API），极大地精简了样板代码（Boilerplate Code）。

然而，很多同学仅停留在 @Data 一把梭的阶段。因 Lombok 误用导致的空指针、死循环和 JPA 性能问题很常见。本文不仅是一份速查表，更是基于实战经验的避坑指南。

这部分注解主要用于精准控制类成员的访问能力。

作用范围：类、字段。
生成的代码：标准的 getter/setter 方法。
架构师提示 ：
- 类级别：为所有非静态字段生成方法。
- 字段级别：仅针对特定字段。
- 访问控制 ：可以使用 AccessLevel 参数控制生成方法的可见性。例如 @Setter(AccessLevel.PROTECTED)，这在设计领域模型（Domain Model）时非常有用，防止外部随意修改内部状态。

java 复制代码

public class User {
    @Getter @Setter
    private String name;

    @Setter(AccessLevel.NONE) // 不生成 Setter，保证 id 不可变
    private Long id;
}

Spring 4.3+ 推荐使用构造器注入，Lombok 的构造器注解配合 Spring 使用简直是天作之合。

作用：生成包含特定字段的构造器。
1. final 修饰的未初始化字段。
2. 被 @NonNull 注解修饰的字段。
最佳实践 ：替代 @Autowired 。在 Spring Bean 中，使用此注解配合 final 字段，可以实现优雅的构造器注入，无需写臃肿的构造函数。

java 复制代码

@Service
@RequiredArgsConstructor // 自动生成包含 userMapper 的构造器
public class UserService {
    private final UserMapper userMapper; // Spring 会自动注入
}

这是 Lombok 最强大但也最危险的区域。

作用：生成 toString() 方法，默认包含所有非静态字段。
避坑：
- 循环引用 ：如果 A 类引用 B，B 类引用 A，直接用 @ToString 会导致 StackOverflowError。必须使用 @ToString.Exclude 排除掉造成循环引用的字段。

作用：生成 hashCode() 和 equals() 方法。
避坑：
- 继承陷阱 ：如果类有父类，默认 callSuper = false，即比较时忽略父类字段。这可能导致两个逻辑上不同的对象被判定为相等。建议显式声明 @EqualsAndHashCode(callSuper = true)。

作用：这是一个"全家桶"注解。
- 相当于：@Getter + @Setter + @RequiredArgsConstructor + @ToString + @EqualsAndHashCode。
注意：对于 final 字段，@Data 不会生成 Setter。
严重警告 ：严禁在 JPA/Hibernate 的 Entity 类上使用 @Data 。
- 原因 1：toString 可能触发懒加载（Lazy Loading），导致严重的性能问题（N+1）或 LazyInitializationException。
- 原因 2：hashCode 可能包含可变字段，导致对象在 Set 或 Map 中丢失。

等价代码：

java 复制代码

private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(TargetClass.class);

虽然提问中未提及，但以下两个注解在构建健壮系统时至关重要。

作用：@Data 的不可变版本。
效果：所有字段默认 private final，不生成 Setter，类本身也是 final。这非常适合用于定义 DTO（数据传输对象）或值对象（Value Object）。

为了方便记忆，我整理了以下决策逻辑：

核心原则：Lombok 是为了让代码更清晰，而不是让逻辑更隐晦。如果你发现 Lombok 的某个注解让你失去了对代码的控制权（比如 JPA 中的 equals/hashCode 问题），请果断切回手动编写。

现在，去检查一下你的 JPA 实体类，看看是不是误用了 @Data？