您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Project Lombok 實戰指南：消除 Java 樣板代碼，讓實體類更優雅

編輯：Java 相關知識

前言

Java 被詬病冗長的樣板代碼：每個字段都要寫 getter/setter、equals/hashCode、toString、構造方法。Project Lombok 通過編譯期註解處理器，在不修改源碼語義前提下自動生成這些代碼，並完美集成 IDE（Eclipse/IntelliJ IDEA/VS Code），實現「寫時即見」的開發體驗。

一、安裝與配置

1. IDE 安裝

IntelliJ IDEA：Settings → Plugins → Marketplace 搜索 "Lombok" 安裝 → 勾選 "Enable annotation processing" → 重啟。
Eclipse：下載 lombok.jar → 執行 `java -jar lombok.jar` → 指定 Eclipse 路徑 → Install/Update → 重啟。
VS Code：安裝 "Extension Pack for Java" 內含 Lombok 支持，或單獨安裝 "Lombok Annotations Support for VS Code"。

2. 專案依賴

<!-- Maven -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope> <!-- 編譯期提供，運行期不打包 -->
</dependency>

<!-- Gradle -->
compileOnly 'org.projectlombok:lombok:1.18.30'
annotationProcessor 'org.projectlombok:lombok:1.18.30'

二、核心註解速查表

註解	生成內容	典型場景
`@Data`	getter/setter、`equals/hashCode`、`toString`、`requiredArgsConstructor`	標準 JavaBean/DTO/VO
`@Value`	不可變類：final 字段、getter、`equals/hashCode`、`toString`、`allArgsConstructor`	領域值對象、事件
`@Getter/@Setter`	單字段或類級別生成訪問器	精細控制、非標準命名
`@NoArgsConstructor`	無參構造方法	JPA 實體、反序列化
`@RequiredArgsConstructor`	包含所有 final/@NonNull 字段的構造方法	不可變依賴注入
`@AllArgsConstructor`	全參構造方法	建造者模式替代
`@Builder`	流式建造者模式（`User.builder().name("A").age(18).build()`）	參數多、可選參數構造
`@ToString`	可排除字段、調用 super、格式化	避免循環引用、隱藏敏感信息
`@EqualsAndHashCode`	可排除字段、調用 super、緩存 hashCode	實體類僅比較 ID
`@Slf4j/@Log4j2/@Log`	靜態日誌字段 `log`	替代手動 `LoggerFactory.getLogger()`
`@Cleanup`	自動關閉實現 `Closeable` 的資源（類 try-with-resources）	舊版 JDK/非標準 close() 方法
`@Synchronized`	鎖定私有實例/類鎖（`$lock/$LOCK`），避免 `synchronized(this)` 洩露鎖	線程安全方法
`@NonNull`	參數/字段非空檢查，拋出 `NPE`	防禦性編程

三、實戰範例：從冗長到優雅

Before（手寫 60+ 行）

public class User {
    private Long id;
    private String username;
    private String email;
    private String password; // 敏感，不想進 toString
    private LocalDateTime createdAt;

    // 構造方法、getter/setter、equals/hashCode、toString... 省略
}

After（Lombok 10 行）


@Getter
@Setter
@ToString(exclude = "password")           // 隱藏密碼
@EqualsAndHashCode(of = "id")             // 僅按 ID 比較
@NoArgsConstructor                        // JPA 需要
@RequiredArgsConstructor(staticName = "of") // User.of(id, username, email)
@Builder                                  // User.builder().id(1L).username("a").build()
public class User {
    @NonNull private Long id;
    @NonNull private String username;
    @NonNull private String email;
    private String password;
    private LocalDateTime createdAt;
}

四、進階技巧與避坑指南

@Builder + 繼承：父類需 @Builder(toBuilder = true)，子類同樣標註，Lombok 會生成兼容的建造者。
@Data + final 字段：@Data 包含 @RequiredArgsConstructor，final 字段會進構造方法，無 setter（正確）。

JPA 實體最佳實踐：


@Entity
@Getter @Setter @ToString(exclude = "orders") @EqualsAndHashCode(of = "id")
@NoArgsConstructor(access = AccessLevel.PROTECTED) // 防止外部無參構造
public class Customer {
    @Id @GeneratedValue Long id;
    @OneToMany(mappedBy = "customer") @ToString.Exclude Set orders = new HashSet<>();
}

序列化：Lombok 生成的方法不影響序列化，但 @Builder 類需實現 Serializable 並聲明 serialVersionUID。
Delombok：Maven 插件 `lombok-maven-plugin` 可將註解展開為源碼，用於無 Lombok 環境構建或代碼審查。

五、爭議與替代方案

觀點	說明
支持者	極大減少樣板碼，專注業務邏輯，IDE 支持完美，生態成熟穩定。
反對者	「魔法」行為不透明，調試時堆棧幀不對應源碼行，破壞封裝（產生 setter），構建鏈依賴註解處理器。
原生替代	JDK 14+ `record`（不可變數據載體）、JDK 15+ `sealed class`、IDE 代碼生成模板、`AutoValue`/`Immutables`（編譯期生成不可變類）。

結語

Lombok 是 Java 生態「以註解元編程消除樣板代碼」的標杆之作。合理使用 @Data/@Builder/@Slf4j 等核心註解，配合 @ToString.Exclude、@EqualsAndHashCode.Include 等精細控制，能讓實體類代碼量減少 70% 以上，同時保持語義清晰。團隊若接受「編譯期魔法」，它是提升開發效率的利器；若追求純粹標準，record 是面向未來的原生選擇。