@Builder

......鲍勃是你的叔叔：用于创建对象的无懈可击的花式裤子！
@Builder 在lombok v0.12.0中作为实验特征介绍。
@Builder获得了@Singular支持，并lombok从lombok v1.16.0 升级到主程序包。
@Builder与@Singular增加，因为龙目岛v1.16.8一个明确的方法。
@Builder.Default 功能已在lombok v1.16.16中添加。

Overview

该@Builder标注生产络合剂的API为你的类。

@Builder 允许您使用以下代码自动生成使您的类可实例化所需的代码：
Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build();

@Builder可以放在类，构造函数或方法上。虽然“在类上”和“在构造函数上”模式是最常见的用例，但@Builder最容易用“方法”用例来解释。

用@Builder（从现在开始调用目标）注释的方法会导致生成以下7件事：

• 一个名为的内部静态类*Foo*Builder，具有与静态方法相同的类型参数（称为构建器）。
• 在构建器中：目标的每个参数的一个私有非静态非最终字段。
• 在构建器中：一个包私有no-args空构造函数。
• 在构建器中：对于目标的每个参数，类似于“setter”的方法：它具有与该参数相同的类型和相同的名称。它返回构建器本身，以便可以链接setter调用，如上例所示。
• 在构建器中：build()调用方法的方法，传入每个字段。它返回与目标返回的相同类型。
• 在构建器中：一个明智的toString()实现。
• 在包含目标的类中：一种builder()方法，它创建构建器的新实例。

如果该元素已经存在，则将以静默方式跳过每个列出的生成元素（忽略参数计数并仅查看名称）。这包括构建器本身：如果该类已经存在，则lombok将简单地开始在此已存在的类中注入字段和方法，除非当然要存在要注入的字段/方法。您可能不会在构建器类上放置任何其他方法（或构造函数）生成lombok注释; 例如，您不能放置@EqualsAndHashCode构建器类。

@Builder可以为集合参数/字段生成所谓的“奇异”方法。它们采用1个元素而不是整个列表，并将该元素添加到列表中。例如：Person.builder().job("Mythbusters").job("Unchained Reaction").build();将导致该List<String> jobs字段中包含2个字符串。要获得此行为，需要使用注释字段/参数@Singular。该功能有自己的文档。

既然“方法”模式已经清楚了，那么@Builder在构造函数上添加注释的功能类似; 实际上，构造函数只是具有特殊语法来调用它们的静态方法：它们的“返回类型”是它们构造的类，它们的类型参数与类本身的类型参数相同。

最后，应用于@Builder类就好像您已添加@AllArgsConstructor(access = AccessLevel.PACKAGE)到类中并将@Builder注释应用于此all-args构造函数。这仅适用于您自己没有编写任何显式构造函数的情况。如果您确实有一个显式构造函数，请将@Builder注释放在构造函数而不是类上。

如果使用@Builder生成构建器来生成自己的类的实例（除非添加@Builder到不返回自己类型的方法，否则总是如此），您可以使用@Builder(toBuilder = true)在类中生成实例方法调用toBuilder(); 它会创建一个以该实例的所有值开头的新构建器。您可以将@Builder.ObtainVia注释放在参数（如果是构造函数或方法）或字段（如果@Builder是类型）上，以指示从该实例获取该字段/参数的值的替代方法。例如，您可以指定要调用的方法：@Builder.ObtainVia(method = "calculateFoo")。

构建器类的名称是*Foobar*Builder，其中Foobar是目标返回类型的简化，标题框形式- 即@Builder构造函数和类型的类型名称，以及@Builderon方法的返回类型的名称。例如，如果@Builder应用于名为的类com.yoyodyne.FancyList<T>，则构建器名称将为FancyListBuilder<T>。如果@Builder应用于返回的方法，void则将命名构建器VoidBuilder。

构建器的可配置方面是：

• 该生成器的类名（默认：返回类型+“生成器”）
• 该版本（）方法的名称（默认："build"）
• 该生成器（）方法的名称（默认："builder"）
• 如果你想toBuilder()（默认：否）

所有选项均从其默认值更改的示例用法：
@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)

@Builder.Default

如果在构建会话期间从未设置某个字段/参数，则它始终为0 / null/ false。如果您已经放置@Builder了一个类（而不是方法或构造函数），则可以直接在该字段上指定默认值，并使用以下内容对该字段进行注释@Builder.Default：
@Builder.Default private final long created = System.currentTimeMillis();

@Singular

通过使用注释注释其中一个参数（如果使用方法或构造函数进行注释@Builder）或字段（如果使用注释类@Builder）@Singular，lombok将该构建器节点视为集合，并生成2个“加法器”方法而不是“ setter'方法。一个向集合添加单个元素，另一个将另一个集合的所有元素添加到集合中。将不生成仅设置集合（替换已添加的任何内容）的setter。还生成了“清晰”方法。这些“单一”构建器非常复杂，以保证以下属性：

• 调用时build()，生成的集合将是不可变的。
• 在调用之后调用“adder”方法之一或“clear”方法build()不会修改任何已生成的对象，并且如果build()稍后再次调用，则会生成自生成构建器以来添加了所有元素的另一个集合。
• 生成的集合将被压缩到最小的可行格式，同时保持高效。

@Singular只能应用于lombok已知的集合类型。目前，支持的类型是：

• java.util：
  • Iterable，Collection和List（ArrayList在一般情况下由压缩的不可修改的支持）。
  • Set，SortedSet和NavigableSet（由一个聪明的大小不可修改HashSet或TreeSet在一般情况下支持）。
  • Map，SortedMap和NavigableMap（由一个聪明的大小不可修改HashMap或TreeMap在一般情况下支持）。
• 番石榴的com.google.common.collect：
  • ImmutableCollection和ImmutableList（由构建器功能支持ImmutableList）。
  • ImmutableSet和ImmutableSortedSet（由这些类型的构建器功能支持）。
  • ImmutableMap，ImmutableBiMap和ImmutableSortedMap（由这些类型的构建器功能支持）。
  • ImmutableTable（由构建器功能支持ImmutableTable）。

如果您的标识符是用通用英语编写的，则lombok假定其上的任何集合的名称@Singular是英语复数，并将尝试自动单独化该名称。如果可以，add-one方法将使用此名称。例如，如果调用了您的集合statuses，则会自动调用add-one方法status。您还可以通过将单数形式作为参数传递给注释来明确指定标识符的单数形式，如下所示：@Singular("axis") List<Line> axes;。
如果lombok无法单独标识您的标识符，或者它不明确，则lombok将生成错误并强制您明确指定单数名称。

下面的代码段没有显示lombok为@Singular字段/参数生成的内容，因为它相当复杂。您可以在此处查看代码段。

With Jackson

您可以自定义构建器类的自定义部分，例如向构建器类添加另一个方法，或者在构建器类中注释方法。Lombok将生成您不手动添加的所有内容，并将其放入此构建器类中。例如，如果您尝试将jackson配置为对集合使用特定子类型，则可以编写如下内容：

@Value @Builder
@JsonDeserialize(builder = JacksonExample.JacksonExampleBuilder.class)
public class JacksonExample {
    @Singular private List<Foo> foos;
    
    @JsonPOJOBuilder(withPrefix = "")
    public static class JacksonExampleBuilder implements JacksonExampleBuilderMeta {
    }
    
    private interface JacksonExampleBuilderMeta {
        @JsonDeserialize(contentAs = FooImpl.class) JacksonExampleBuilder foos(List<? extends Foo> foos)
    }
}

With Lombok

import lombok.Builder;
import lombok.Singular;
import java.util.Set;

@Builder
public class BuilderExample {
  @Builder.Default private long created = System.currentTimeMillis();
  private String name;
  private int age;
  @Singular private Set<String> occupations;
}

Vanilla Java

import java.util.Set;

public class BuilderExample {
  private long created;
  private String name;
  private int age;
  private Set<String> occupations;
  
  BuilderExample(String name, int age, Set<String> occupations) {
    this.name = name;
    this.age = age;
    this.occupations = occupations;
  }
  
  private static long $default$created() {
    return System.currentTimeMillis();
  }
  
  public static BuilderExampleBuilder builder() {
    return new BuilderExampleBuilder();
  }
  
  public static class BuilderExampleBuilder {
    private long created;
    private boolean created$set;
    private String name;
    private int age;
    private java.util.ArrayList<String> occupations;
    
    BuilderExampleBuilder() {
    }
    
    public BuilderExampleBuilder created(long created) {
      this.created = created;
      this.created$set = true;
      return this;
    }
    
    public BuilderExampleBuilder name(String name) {
      this.name = name;
      return this;
    }
    
    public BuilderExampleBuilder age(int age) {
      this.age = age;
      return this;
    }
    
    public BuilderExampleBuilder occupation(String occupation) {
      if (this.occupations == null) {
        this.occupations = new java.util.ArrayList<String>();
      }
      
      this.occupations.add(occupation);
      return this;
    }
    
    public BuilderExampleBuilder occupations(Collection<? extends String> occupations) {
      if (this.occupations == null) {
        this.occupations = new java.util.ArrayList<String>();
      }

      this.occupations.addAll(occupations);
      return this;
    }
    
    public BuilderExampleBuilder clearOccupations() {
      if (this.occupations != null) {
        this.occupations.clear();
      }
      
      return this;
    }

    public BuilderExample build() {
      // complicated switch statement to produce a compact properly sized immutable set omitted.
      Set<String> occupations = ...;
      return new BuilderExample(created$set ? created : BuilderExample.$default$created(), name, age, occupations);
    }
    
    @java.lang.Override
    public String toString() {
      return "BuilderExample.BuilderExampleBuilder(created = " + this.created + ", name = " + this.name + ", age = " + this.age + ", occupations = " + this.occupations + ")";
    }
  }
}

Supported configuration keys:

lombok.builder.flagUsage = [warning | error] (default: not set)
lombok.singular.useGuava = [true | false] (default: false)
lombok.singular.auto = [true | false] (default: true)

Small print

@Singular支持java.util.NavigableMap/Set仅在您使用JDK1.8或更高版本进行编译时才有效。

您无法手动提供@Singular节点的部分或全部部分; Lombok生成的代码太复杂了。如果要手动控制（部分）与某个字段或参数关联的构建器代码，请不要@Singular手动使用和添加所需的所有内容。

排序集合（java.util中：SortedSet，NavigableSet，SortedMap，NavigableMap，番石榴：ImmutableSortedSet，ImmutableSortedMap）要求该集合的类型参数有自然顺序（实现java.util.Comparable）。无法Comparator在构建器中传递显式内容。

如果目标集合来自包，则 An ArrayList用于将添加的元素存储为@Singular标记字段的调用方法java.util，即使集合是集合或映射也是如此。由于lombok确保生成的集合被压缩，因此无论如何都必须构建集合或映射的新后备实例，并且ArrayList在构建过程中将数据存储为将其存储为映射或集合更有效。此行为不是外部可见的，是当前实现java.util配方的实现细节@Singular @Builder。

随着toBuilder = true应用到方法，注解的方法的任何类型的参数本身也必须在返回类型出现。

@Builder.Default删除字段 上的初始化程序并将其存储在静态方法中，以确保在构建中指定值时，根本不会执行此初始化程序。这是否意味着初始化不能引用this，super或任何非静态成员。如果lombok为您生成构造函数，它还将使用初始化程序初始化此字段。

各种众所周知的关于nullity的注释会导致插入空检查，并将其复制到构建器的'setter'方法的参数中。有关详细信息，请参阅Getter / Setter文档的小字体。