Project Lombok 介绍

我们不鼓励直接从类中访问 AtomicReference transactions 字段。我们建议使用getTransactions() 方法来访问该字段。

因此，如果我们在同一个类中使用另一个 Lombok 注解，例如ToString，它将使用getTransactions() 而不是直接访问该字段。

6. 单字段修改的不可变 Setter

此外，我们可以使用@With 注解自动生成一个方法，该方法可以克隆一个只有一个字段更改的对象。例如，当我们要克隆一个带有新age值的User对象时，我们可以用@With注解该字段

@AllArgsConstructor
public class User implements Serializable {

    private @Id Long id;  

    private final String firstName;
    private final String lastName;
    @With private final int age;

}

随后，我们可以使用自动生成的withAge(int newAge) 实例方法来克隆一个User，但使用不同的年龄

User user = new User("John","Smith",40);
User user_updated = user.withAge(41);

7. 值类/DTO

在许多情况下，我们希望定义一种数据类型，其唯一目的是表示复杂的“值”作为“数据传输对象”，。大多数时候以我们构建一次并且不想更改的不可变数据结构的形式。

我们设计一个类来表示成功的登录操作。我们希望所有字段都是非空的，并且对象是不可变的，以便我们可以线程安全地访问它们的属性

public class LoginResult {

    private final Instant loginTs;

    private final String authToken;
    private final Duration tokenValidity;
    
    private final URL tokenRefreshUrl;

    // constructor taking every field and checking nulls

    // read-only accessor, not necessarily as get*() form
}

再次强调，我们为注释部分编写的代码量将比我们想要封装的信息所需要的代码量要大得多。我们可以使用 Lombok 来改进这一点

@RequiredArgsConstructor
@Accessors(fluent = true) @Getter
public class LoginResult {

    private final @NonNull Instant loginTs;

    private final @NonNull String authToken;
    private final @NonNull Duration tokenValidity;
    
    private final @NonNull URL tokenRefreshUrl;

}

一旦我们添加了@RequiredArgsConstructor 注解，我们将为类中的所有 final 字段获得一个构造函数，就像我们声明的那样。将 @NonNull 添加到属性会使我们的构造函数检查空值，并相应地抛出 NullPointerExceptions。如果字段是非 final 的，并且我们为它们添加了 @Setter，也会发生这种情况。

我们想要为我们的属性使用枯燥的旧 get*() 形式吗？由于我们在此示例中添加了 @Accessors(fluent=true)，因此“getter” 将与属性具有相同的方法名； getAuthToken() 简单地变为 authToken()。

这种“流畅”形式也将应用于非 final 字段的属性 setter，并允许进行链式调用

// Imagine fields were no longer final now
return new LoginResult()
  .loginTs(Instant.now())
  .authToken("asdasd")
  // and so on

8. 核心 Java 样板代码

当我们生成 toString()、equals() 和 hashCode() 方法时，我们最终需要编写和维护代码的另一个情况。 IDE 尝试通过提供自动生成这些方法的模板来提供帮助，以便基于我们的类属性进行操作。

我们可以使用其他 Lombok 类级注解来自动化此过程

• @ToString：将生成一个 toString() 方法，其中包含所有类属性。无需自己编写并维护它，因为我们丰富了数据模型。
• @EqualsAndHashCode：默认情况下，将生成 equals() 和 hashCode() 方法，同时考虑所有相关字段，并根据 经过深思熟虑的语义。

这些生成器提供了非常方便的配置选项。例如，如果我们的注释类参与了层次结构，我们可以只使用 callSuper=true 参数，父结果将在生成方法代码时被考虑。

8.1. 一个演示

为了演示这一点，假设我们的 User JPA 实体示例包含对与该用户关联的事件的引用

@OneToMany(mappedBy = "user")
private List<UserEvent> events;

我们不希望每次调用 User 的 toString() 方法时都转储整个事件列表，仅仅因为我们使用了 @ToString 注解。相反，我们可以像这样对其进行参数化， @ToString(exclude = {“events”})，这样就不会发生。这也有助于避免循环引用，例如，如果 UserEvent 具有对 User 的引用。

对于 LoginResult 示例，我们可能只想根据 token 本身来定义相等性和哈希码计算，而不是类中的其他 final 属性。然后，我们可以简单地写成 @EqualsAndHashCode(of = {“authToken”})。

如果到目前为止我们所审查的注解中的特性引起了您的兴趣，我们还可能需要检查 @Data 和 @Value 注解，因为它们的行为就像将一组注解应用于我们的类一样。毕竟，这些讨论过的用法在许多情况下经常被放在一起。

8.2. (不) 在 JPA 实体中使用 @EqualsAndHashCode

是否应该使用默认的 equals() 和 hashCode() 方法，或者为 JPA 实体创建自定义方法，是开发人员经常讨论的话题。我们可以遵循 多种方法，每种方法都有其优缺点。

默认情况下，@EqualsAndHashCode 包含实体类中的所有非 final 属性。 我们可以尝试通过使用 @EqualsAndHashCode 的 onlyExplicitlyIncluded 属性，让 Lombok 仅使用实体的 primary key 来“修复”此问题。尽管如此，生成的 equals() 方法可能会导致一些问题。Thorben Janssen 在 他的博客文章之一 中更详细地解释了这种情况。

总的来说，我们应该避免使用 Lombok 生成 JPA 实体中的 equals() 和 hashCode() 方法。

9. Builder 模式

以下内容可以作为 REST API 客户端的示例配置类

public class ApiClientConfiguration {

    private String host;
    private int port;
    private boolean useHttps;

    private long connectTimeout;
    private long readTimeout;

    private String username;
    private String password;

    // Whatever other options you may thing.

    // Empty constructor? All combinations?

    // getters... and setters?
}

我们可以采用一种初始方法，基于使用类默认的空构造函数，并为每个字段提供 setter 方法；然而，我们理想情况下希望配置在构建（实例化）后不再被重置，从而使其成为不可变的。因此，我们希望避免使用 setter，但编写这样一个潜在的冗长参数构造函数是一种反模式。

相反，我们可以告诉工具生成一个 builder 模式，这避免了我们编写额外的 Builder 类和相关的流畅 setter 类方法，只需在我们的 ApiClientConfiguration 上添加 @Builder 注解即可：

@Builder
public class ApiClientConfiguration {

    // ... everything else remains the same

}

将类定义保留如上（不声明构造函数或 setter + @Builder），我们可以将其用作

ApiClientConfiguration config = 
  ApiClientConfiguration.builder()
    .host("api.server.com")
    .port(443)
    .useHttps(true)
    .connectTimeout(15_000L)
    .readTimeout(5_000L)
    .username("myusername")
    .password("secret")
    .build();

10. 已检查异常的负担

许多 Java API 被设计为抛出一个或多个已检查异常；客户端代码被迫要么捕获异常，要么声明抛出异常。我们有多少次将我们知道不会发生的这些异常变成如下代码：

public String resourceAsString() {
    try (InputStream is = this.getClass().getResourceAsStream("sure_in_my_jar.txt")) {
        BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8"));
        return br.lines().collect(Collectors.joining("\n"));
    } catch (IOException | UnsupportedCharsetException ex) {
          // If this ever happens, then its a bug.
          throw new RuntimeException(ex); <--- encapsulate into a Runtime ex.
    }
}

如果我们想避免这种代码模式，因为编译器会不高兴（并且我们知道这些已检查错误不会发生），可以使用恰如其分的 @SneakyThrows

@SneakyThrows
public String resourceAsString() {
    try (InputStream is = this.getClass().getResourceAsStream("sure_in_my_jar.txt")) {
        BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8"));
        return br.lines().collect(Collectors.joining("\n"));
    } 
}

11. 确保释放我们的资源

Java 7 引入了 try-with-resources 块，以确保由实现 java.lang.AutoCloseable 实例持有的资源在退出时被释放。

Lombok 提供了一种替代且更灵活的方式来实现这一点，即通过 @Cleanup。 我们可以将其用于任何我们想要确保释放其资源的局部变量。它们不需要实现任何特定的接口，我们将只是调用 close() 方法

@Cleanup InputStream is = this.getClass().getResourceAsStream("res.txt");

我们的释放方法有不同的名称？没问题，我们只需自定义注解即可

@Cleanup("dispose") JFrame mainFrame = new JFrame("Main Window");

12. 注解我们的类以获取 Logger

我们中的许多人通过创建我们选择的框架的 Logger 实例，在我们的代码中谨慎地添加日志语句。 假设 SLF4J

public class ApiClientConfiguration {

    private static Logger LOG = LoggerFactory.getLogger(ApiClientConfiguration.class);

    // LOG.debug(), LOG.info(), ...

}

这是一种非常常见的模式，Lombok 开发人员已经为我们简化了它

@Slf4j // or: @Log @CommonsLog @Log4j @Log4j2 @XSlf4j
public class ApiClientConfiguration {

    // log.debug(), log.info(), ...

}

许多 日志框架 都受支持，当然，我们可以自定义实例名称、主题等。

13. 编写线程安全的方法

在 Java 中，我们可以使用 synchronized 关键字来实现临界区；但是，这并不是一种 100% 安全的方法。 其他客户端代码最终也可能同步到我们的实例，从而可能导致意外的死锁。

这就是 @Synchronized 的用武之地。 我们可以使用它来注解我们的方法（实例方法和静态方法），我们将获得一个自动生成的、私有的、未暴露的字段，我们的实现将使用它来进行锁定:

@Synchronized
public /* better than: synchronized */ void putValueInCache(String key, Object value) {
    // whatever here will be thread-safe code
}

但是，在使用 Java 21 引入的 虚拟线程 时，我们应该使用 @Locked、@Locked.Read 和 @Locked.Write 注解来获取一个 ReentrantLock。

14. 自动化对象组合

Java 没有语言级别的构造来平滑“优先组合继承”的方法。其他语言具有内置的概念，如 Traits 或 Mixins，以实现此目的。