06. 《Lombok 实战 —— @Builder》

《Lombok 实战 —— @Builder》

… and Bob’s your uncle: No-hassle fancy-pants APIs for object creation!

@Builder was introduced as experimental feature in lombok v0.12.0.

@Builder gained @Singular support and was promoted to the main lombok package since lombok v1.16.0.

@Builder with @Singular adds a clear method since lombok v1.16.8.

@Builder.Default functionality was added in lombok v1.16.16.

1. @Builder 实战使用

如果对建造者设计模式不太清楚的，可以先了解一下：建造这模式

@Builder注释为你的类生成相对略微复杂的构建器API。@Builder可以让你以下面显示的那样调用你的代码，来初始化你的实例对象：

Person.builder()
    .name("Adam Savage")
    .city("San Francisco")
    .job("Mythbusters")
    .job("Unchained Reaction")
    .build();

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

使用@Builder注释的方法可以帮助我们完成一下一些事情：

• 一个名为FooBuilder的内部静态类，并具有和实体类形同的属性（称为构建器）。
• 在构建器中：对于目标类中的所有的属性和未初始化的final字段，都会在构建器中创建对应属性；
• 在构建器中：创建一个无参的default构造函数。
• 在构建器中：对于实体类中的每个参数，都会对应创建类似于“setter”的方法，只不多方法名与该参数名相同。 并且返回值是构建器本身（便于链式调用），如上例所示。
• 在构建器中：一个build()方法，调用此方法，就会根据设置的值进行创建实体对象。
• 在构建器中：同时也会生成一个toString()方法。
• 在实体类中：会创建一个builder()方法，它的目的是用来创建构建器。

说的多了有点绕，我们还是先来使用一下试试，然后再详细说明：

@Builder
public class User {
   
    private String username;
    private String password;
}

// 编译后：
public class User {
   
    private String username;
    private String password;
    User(String username, String password) {
   
        this.username = username; this.password = password;
    }
    public static User.UserBuilder builder() {
   
        return new User.UserBuilder();
    }

    public static class UserBuilder {
   
        private String username;
        private String password;
        UserBuilder() {
   }

        public User.UserBuilder username(String username) {
   
            this.username = username;
            return this;
        }
        public User.UserBuilder password(String password) {
   
            this.password = password;
            return this;
        }
        public User build() {
   
            return new User(this.username, this.password);
        }
        public String toString() {
   
            return "User.UserBuilder(username=" + this.username + ", password=" + this.password + ")";
        }
    }
}

2. @Builder 中使用 @Singular 注释集合

2.1 @Singular 实战使用

@Builder也可以为集合类型的参数或字段生成一种特殊的方法。 它采用修改列表中一个元素而不是整个列表的方式，可以是增加一个元素，也可以是删除一个元素。 例如：

Person.builder()
    .job("Mythbusters")
    .job("Unchained Reaction")
    .build();

这样就可以轻松地将List <String>字段中包含2个字符串。 但是想要这样来操作集合，你需要使用@Singular来注释字段或参数。

在使用@Singular注释注释一个集合字段（使用@Builder注释类），lombok会将该构建器节点视为一个集合，并生成两个adder方法而不是setter方法。

• 一个向集合添加单个元素，
• 一个将另一个集合的所有元素添加到集合中。

将不生成仅设置集合（替换已添加的任何内容）的setter。 还生成了clear方法。 这些singular构建器相对而言是有些复杂的，主要是来保证以下特性：

• 在调用build()时，生成的集合将是不可变的。
• 在调用build()之后调用其中一个adder方法或clear方法不会修改任何已经生成的对象。如果对集合修改之后，再调用build()，则会创建一个基于上一个对象创建的对象实体。
• 生成的集合将被压缩到最小的可行格式，同时保持高效。

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

• java.util:
  • Iterable, Collection, 和List (一般情况下，由压缩的不可修改的ArrayList支持).
  • Set, SortedSet, and NavigableSet (一般情况下，生成可变大小不可修改的HashSet或者TreeSet).
  • Map, SortedMap, and NavigableMap (一般情况下，生成可变大小不可修改的HashMap或者TreeMap).