Lombok 通過編譯期字節碼增強，自動生成 Getter/Setter/toString/equals/hashCode/構造器/Builder 等樣板代碼，減少 60%+ 實體類代碼量，讓領域模型聚焦業務邏輯。本文覆蓋 IDEA 插件安裝、Annotation Processor 啟用、核心注解詳解、對比生成代碼、常見坑點與最佳實踐。
Settings → Plugins → Marketplace → 搜索 "Lombok" → Install → Restart IDE。Settings → Plugins → ⚙️ → Install Plugin from Disk... 選擇 zip → Restart。Settings → Build, Execution, Deployment → Compiler → Annotation Processors → ✅ Enable annotation processing → Apply → 再次 Restart IDEA。
未啟用時，IDE 不會識別 Lombok 生成的方法，導致紅錯、無法跳轉、重構失效。
| 注解 | 生成內容 | 典型場景 | 關鍵屬性 |
|---|---|---|---|
@Getter / @Setter | 所有非靜態字段的訪問器/修改器 | 實體類、DTO | AccessLevel、lazy、onMethod |
@ToString | toString()，含所有字段 | 調試、日誌 | exclude、of、callSuper |
@EqualsAndHashCode | equals()/hashCode() | 集合去重、Map Key | exclude、callSuper、onlyExplicitlyIncluded |
@NoArgsConstructor | 無參構造器 | JPA/Hibernate 實體、反序列化 | access、force |
@RequiredArgsConstructor | 包含 final / @NonNull 字段的構造器 | 不可變對象、依賴注入 | access |
@AllArgsConstructor | 全參構造器 | Builder 模式、測試構造 | access |
@Data | 組合注解：@Getter+@Setter+@ToString+@EqualsAndHashCode+@RequiredArgsConstructor | 普通 POJO/VO | 慎用於 JPA 實體（hashCode 含可變字段） |
@Builder | Builder 模式構建器（鏈式調用） | 參數多、可選參數多的構造 | builderMethodName、buildMethodName、toBuilder |
@Slf4j | 靜態 log 字段（SLF4J） | 日誌記錄 | topic |
@Cleanup | 自動 close()（try-with-resources 替代） | 流/連接資源管理 | value 指定關閉方法名 |
@SneakyThrows | 拋出受檢異常無需 throws 聲明 | 簡化異常處理 | value 指定異常類型 |
@Synchronized | 鎖對象同步（非 this） | 細粒度鎖 | value 指定鎖字段 |
@NonNull | 參數非空檢查（生成 if-null-throw） | 防禦性編程 | |
@Value | 不可變類：final 字段 + @Getter + @AllArgsConstructor + @ToString + @EqualsAndHashCode | DTO、事件對象 |
// Lombok 源碼（約 20 行）
@Data @Slf4j @AllArgsConstructor
public class Something {
private String name;
private final String country;
private final Object lockObj = new Object();
public void sayHello(@NonNull String target) {
String content = String.format("hello,%s", target);
System.out.println(content);
log.info(content);
}
@SneakyThrows(IOException.class)
public void closeBalabala() {
@Cleanup InputStream is = new ByteArrayInputStream("hello world".getBytes());
System.out.println(is.available());
}
@Synchronized("lockObj")
public void lockMethod() { System.out.println("test lock method"); }
}
⬇ 編譯後等效代碼（約 120 行，含 Getter/Setter/toString/equals/hashCode/構造器/Builder/日誌/同步/清理）
完整生成代碼見原文，核心點：@Data生成的equals/hashCode包含所有非 static/transient 字段，JPA 實體請改用 @Getter/@Setter/@ToString/@EqualsAndHashCode(of="id") 組合，避免實體脫管/合併時 hashCode 變化導致集合異常。
| 現象 | 原因 | 解決 |
|---|---|---|
| IDE 紅錯「Cannot resolve method getXxx()」 | Annotation Processing 未啟用 | 按上文啟用並 Restart IDEA |
| Maven 編譯報錯「cannot find symbol」 | 未添加 lombok 依賴或版本衝突 | <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.30</version><scope>provided</scope></dependency> |
| Gradle 編譯不生效 | 缺少 annotationProcessor 配置 | annotationProcessor 'org.projectlombok:lombok' (Gradle 5.6+) 或 compileOnly + annotationProcessor |
| 反序列化失敗（Jackson/Gson） | 無無參構造器 | 添加 @NoArgsConstructor 或 @Data 隱含 |
| Builder 不生成 | 類為 final 或字段為 final 無 setter | Builder 需配合非 final 字段或手動定義 setter |
| @SneakyThrows 異常被 IDE 標紅 | IDE 靜態分析不識別 | 忽略或設置 Settings → Inspections → Unhandled exceptions |
@Getter @Setter @ToString @EqualsAndHashCode(of="id") @NoArgsConstructor（JPA 友好）。@Data 或 @Value（不可變）。@Builder + @AllArgsConstructor(access=PRIVATE)。@Slf4j，使用 log.info()。try-with-resources，簡單場景用 @Cleanup。
