深入理解 Lombok 配置系统

2. 配置概述

Lombok 是一个能帮我们消除 Java 项目中几乎全部样板代码的库。要开始配置，首先添加依赖：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

Lombok 的配置系统提供了许多实用设置，通常在整个项目中保持一致。它允许我们自定义行为，甚至限制某些功能的使用。例如，我们可以设置当使用实验性功能时显示警告或错误。

要定义配置，需要创建 lombok.config 文件。该文件可放在项目根目录、源码目录或任意包中。子目录中的源文件会继承配置，且支持多级配置文件。例如：

当出现配置冲突时，离类文件最近的配置优先级最高。

3. 基本配置

Lombok 的配置选项非常多，这里只介绍最常用的。要查看完整选项，执行以下命令：

java -jar lombok.jar config -g --verbose

典型的 lombok.config 文件示例：

config.stopBubbling = true
lombok.anyconstructor.addconstructorproperties = false
lombok.addLombokGeneratedAnnotation = true
lombok.experimental.flagUsage = WARNING

# ... 更多属性

关键属性说明：

config.stopBubbling：禁止向上级目录查找配置文件（建议项目根目录设置）
默认值为 false（会向上查找）

4. 主要属性

4.1. 全局配置键

这些配置会影响整个系统行为：

lombok.anyConstructor.addConstructorProperties

为所有参数化构造器添加 @java.beans.ConstructorProperties 注解
依赖反射的框架（如 Spring）需要此注解映射属性顺序

@AllArgsConstructor
@NoArgsConstructor
@Getter
@Setter
public class Account {
    private double balance;
    private String accountHolder;
}

生成代码：

public class Account {
    private double balance;
    private String accountHolder;

    @ConstructorProperties({"balance", "accountHolder"})
    @Generated
    public Account(double balance, String accountHolder) {
        this.balance = balance;
        this.accountHolder = accountHolder;
    }
 
    @Generated
    public Account() {}

    // 默认生成的 getter/setter
}

lombok.addLombokGeneratedAnnotation

为所有生成方法添加 @lombok.Generated 注解
便于在代码覆盖率工具中排除 Lombok 生成的方法

lombok.addNullAnnotations

支持多种空检查注解：javax(JSR305)、Eclipse、JetBrains 等
自定义注解格式：CUSTOM:com.example.NonNull:example.Nullable

lombok.addSuppressWarnings

设为 false 时，停止生成 @SuppressWarnings("all") 注解
适用于静态代码分析场景

4.2. 其他配置键

lombok.accessors.chain

设为 true 时，setter 方法返回 this 支持链式调用

@Test
void should_initialize_account() {
    Account myAccount = new Account()
      .setBalance(2000.00)
      .setAccountHolder("John Snow");

    assertEquals(2000.00, myAccount.getBalance());
    assertEquals("John Snow", myAccount.getAccountHolder());
}

lombok.accessors.fluent

移除 getter/setter 的 get/set 前缀，直接使用属性名

lombok.log.fieldName

自定义日志字段名（默认为 log）

# 日志字段名自定义
lombok.log.fieldName = domainLog

使用示例：

@AllArgsConstructor
@NoArgsConstructor
@Getter
@Setter
@Log
public class Account {

    // ... 其他字段定义

   public Account withdraw(double amount) {
        if (this.balance - abs(amount) < 0) {
            domainLog.log(Level.INFO, "Transaction denied for account holder: %s", this.accountHolder);
            throw new IllegalArgumentException(String.format("Not enough balance, you have %.2f", this.balance));
        }

        this.balance -= abs(amount);
        return this;
    }
}

lombok.(featureName).flagUsage

控制特性使用权限：warning/error/allow

示例：禁止实验性功能

lombok.experimental.flagUsage = WARNING

使用时会输出警告：

/home/dev/project/src/main/java/com/example/TransactionLog.java:9:
warning: Use of any lombok.experimental feature is flagged according to lombok configuration.
@Accessors(prefix = {"op"})

4.3. 特殊配置键

lombok.copyableAnnotations

将字段上的注解复制到相关构造器/getter/setter
典型场景：Spring 的 @Qualifier 和 @Value 注解传播

添加方式：

lombok.copyableAnnotations += com.example.MyAnnotation

使用示例：

@NoArgsConstructor
@AllArgsConstructor
@Getter
@Setter
@Log
public class Account {

    @NonNull
    private Double balance = 0.;
    @NonNull
    private String accountHolder = "";

    // ... 其他方法
}

生成代码：

public class Account {

    @Generated
    private static final Logger domainLog = Logger.getLogger(Account.class.getName());
    @NonNull
    private Double balance = 0.0D;
    @NonNull
    private String accountHolder = "";

    @ConstructorProperties({"balance", "accountHolder"})
    @Generated
    public Account(@NonNull Double balance, @NonNull String accountHolder) {
        if (balance == null) {
            throw new NullPointerException("balance is marked non-null but is null");
        } else if (accountHolder == null) {
            throw new NullPointerException("accountHolder is marked non-null but is null");
        } else {
            this.balance = balance;
            this.accountHolder = accountHolder;
        }
    }

    @NonNull
    @Generated
    public Double getBalance() {
        return this.balance;
    }

    @NonNull
    @Generated
    public String getAccountHolder() {
        return this.accountHolder;
    }

    // ... 其他成员
}

clear lombok.(anyConfigKey)

重置配置键为默认值
忽略父配置文件中的同名设置

clear lombok.addNullAnnotations

4.4. 文件指令

导入外部配置文件：

必须放在文件顶部
支持相对路径和绝对路径

## 相对或绝对路径  
import lombok_feature.config

config.stopBubbling = true
lombok.anyconstructor.addconstructorproperties=false
lombok.addLombokGeneratedAnnotation = true
lombok.addSuppressWarnings = false

被导入的 lombok_feature.config 文件：

# lombok_feature.config 文件

lombok.experimental.flagUsage = warning

5. 总结

本文深入探讨了 Lombok 的配置系统及其关键属性。虽然只覆盖了最常用的配置，但这些已足够应对大多数开发场景。更多高级配置可参考 Lombok 官方文档。

文中所有代码示例可在 GitHub 仓库获取。踩坑提示：配置文件路径错误是常见问题，建议使用相对路径时以项目根目录为基准。

Persistence

REST

Security