lombok-patterns

Lombok 模式

此技能介绍如何使用 Project Lombok 减少 Java 应用中的样板代码，涵盖注解、最佳实践和集成模式。

注意：本指南适用于 Java 21+ 项目。由于 Java 的现代特性（Records、var、try-with-resources），部分 Lombok 功能现已过时。请参阅下文的 Java 21+ 注意事项。

概述

Lombok 是一个 Java 库，可在编译期间自动生成 getter、setter、构造函数、构建器等常见代码。它有助于编写更简洁、更易维护的代码。

Java 21+ 注意事项

部分 Lombok 功能与 Java 的现代特性重复：

Lombok 功能	Java 替代方案	建议
val/var	var（Java 10+）	使用 Java var
@Value	record（Java 16+）	简单值对象优先使用 record
@Data	record（Java 16+）	简单 DTO 优先使用 record
@Cleanup	try-with-resources（Java 7+）	使用 try-with-resources
@With	record 的 wither 方法	Record 可以定义 wither 方法

Lombok 仍有价值的场景

• JPA 实体：Record 不适用于 JPA（需要无参构造函数和可变状态）
• @Builder：Record 不内置构建器支持
• @Slf4j：Java 没有生成日志记录器的对应功能
• @RequiredArgsConstructor：适用于 Spring 依赖注入
• 继承：Record 不能扩展类

注解类别

核心注解（仍有价值）

注解	用途	使用场景
@Getter/@Setter	访问器方法	JPA 实体、可变类
@NoArgsConstructor	无参构造函数	JPA 实体、序列化
@AllArgsConstructor	全字段构造函数	依赖注入
@RequiredArgsConstructor	为 final/@NonNull 字段生成构造函数	Spring 服务
@Builder	构建器模式实现	复杂对象构造

考虑改用 Java Record

Lombok	适用 Java Record 的场景
@Value	简单的不可变数据载体
@Data	不涉及继承的简单 DTO

// ✅ Prefer Java Record for simple value objects
public record Money(BigDecimal amount, String currency) {}

// ✅ Prefer Java Record for simple DTOs
public record CustomerDTO(String name, String email) {}

// ✅ Use Lombok for JPA entities (records don't work with JPA)
@Entity
@Getter
@Setter
@NoArgsConstructor
public class Customer {
    @Id private Long id;
    private String name;
}

日志注解

注解	日志记录器类型
@Slf4j	SLF4J（推荐）
@Log4j2	Log4j 2
@Log	java.util.logging
@CommonsLog	Apache Commons Logging

字段和方法注解

注解	用途
@NonNull	对参数/字段进行空值检查
@With	不可变 setter（创建新实例）
@SneakyThrows	无需声明即可抛出受检异常
@Synchronized	方法同步，确保线程安全
@ToString	可自定义 toString() 生成方式
@EqualsAndHashCode	可自定义 equals/hashCode

快速参考

JPA 实体（推荐使用 Lombok）

@Entity
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(onlyExplicitlyIncluded = true)
public class Product {
    @Id
    @EqualsAndHashCode.Include
    private Long id;

    private String name;
    private BigDecimal price;
}

Spring 服务

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentService paymentService;

    public Order process(Order order) {
        log.info("Processing order: {}", order.getId());
        return orderRepository.save(order);
    }
}

构建器模式（Lombok 能带来价值）

// Records don't have builder support - use Lombok
@Builder
public record Email(
    String to,
    String subject,
    String body,
    @Singular List<String> attachments
) {}

// Usage
Email email = Email.builder()
    .to("[email protected]")
    .subject("Hello")
    .body("Content")
    .attachment("file1.pdf")
    .build();

最佳实践

✅ 推荐

• 对于简单的值对象和 DTO，使用 Java Records
• 使用 @RequiredArgsConstructor 和 final 字段进行依赖注入
• 使用 @Slf4j 记录日志，而不是手动创建日志记录器
• 对包含许多可选字段的类使用 @Builder
• 对 JPA 实体显式使用 @EqualsAndHashCode

❌ 避免

• 在 Java Record 足以胜任时使用 @Data 或 @Value
• 在 JPA 实体上使用 @Data（请使用单独的注解）
• 将 @EqualsAndHashCode 用于延迟加载的 JPA 关系
• 过度使用 @SneakyThrows（会使异常处理不清晰）

常见陷阱

陷阱	问题	解决方案
实体上使用 @Data	包含可变的 setter，且 equals/hashCode 存在问题	使用 @Getter、@Setter，并显式使用 @EqualsAndHashCode
缺少 @NoArgsConstructor	JPA/Jackson 需要无参构造函数	始终与 @AllArgsConstructor 一起添加
循环引用的 @ToString	双向关系会导致 StackOverflow	在一侧使用 @ToString.Exclude
对简单 DTO 使用 Lombok	引入了不必要的依赖	改用 Java Records

Cookbook 索引

核心注解

• data-annotation - @Data（建议改用 Records）
• value-annotation - @Value（建议改用 Records）
• getter-setter - @Getter 和 @Setter
• constructor-annotations - 构造函数生成
• builder-annotation - 使用 @Builder 的建造者模式
• logging-annotations - 日志记录器生成

字段和方法注解

• non-null - 使用 @NonNull 进行空值检查
• with-annotation - 使用 @With 创建不可变 setter
• sneaky-throws - 检查型异常处理
• synchronized-annotation - 线程安全

集成模式

• entity-patterns - JPA/Hibernate 最佳实践
• equals-hashcode-jpa - 实体标识
• dependency-injection - Spring 构造函数注入
• configuration-properties - Spring Boot 配置