Lombok中的@Builder

1
2
3
4
5
　　一般在构造一个javaBean对象时，有三种写法：
　　1、直接通过构造函数传参的方式设置属性，但属性过多的话会让构造函数十分臃肿，而且不能灵活的选择只设置某些参数。
　　2、采用重叠构造器模式，先写第一个只有必要参数的构造器，第二个构造器有一个可选参数，第三个构造器有两个可选参数，以此类推；如果参数比较多时，类里面会出现一堆构造方法，容易出错。
　　3、采用Javabean的写法，写一堆属性的setter方法，通过调用setter方法给属性赋值。  这种方法有个劣势就是构造的过程被分到几个调用中，在构造中可能处于不一致状态，无法保证一致性。
　　而Lombok 插件中的@Builer，可以放在类、构造函数或方法上，它可以帮我们快速实现一个builder模式，builder模式既解决了重叠构造器容易出错，也解决了Javabean的不一致问题

简述：Builder 使用创建者模式又叫建造者模式。简单来说，就是一步步创建一个对象，它对用户屏蔽了里面构建的细节，但却可以精细地控制对象的构造过程。

基础使用

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

1
2
3
4
5
6
Student.builder()
               .sno( "001" )
               .sname( "admin" )
               .sage( 18 )
               .sphone( "110" )
               .build();

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

那么@Builder内部帮我们做了什么？

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

说这么多，不如让我们通过下面这个例子来理解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@Builder
public class User {
    private final Integer code = 200;
    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 + ")";
        }
    }
}

组合用法

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

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

1
2
3
4
5
6
Student.builder()
               .sno( "001" )
               .sname( "admin" )
               .sage( 18 )
               .sphone( "110" ).sphone( "112" )
               .build();

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

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

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

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

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

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

  • java.util:
    • Iterable, Collection, 和List (一般情况下，由压缩的不可修改的ArrayList支持).
    • Set, SortedSet, and NavigableSet (一般情况下，生成可变大小不可修改的HashSet或者TreeSet).
    • Map, SortedMap, and NavigableMap (一般情况下，生成可变大小不可修改的HashMap或者TreeMap).
  • Guava’s com.google.common.collect:
    • ImmutableCollection and ImmutableList
    • ImmutableSet and ImmutableSortedSet
    • ImmutableMap, ImmutableBiMap, and ImmutableSortedMap
    • ImmutableTable

来看看使用了@Singular注解之后的编译情况：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@Builder
public class User {
    private final Integer id;
    private final String zipCode = "123456";
    private String username;
    private String password;
    @Singular
    private List<String> hobbies;
}

// 编译后：
public class User {
    private final Integer id;
    private final String zipCode = "123456";
    private String username;
    private String password;
    private List<String> hobbies;
    User(Integer id, String username, String password, List<String> hobbies) {
        this.id = id; this.username = username;
        this.password = password; this.hobbies = hobbies;
    }

    public static User.UserBuilder builder() {return new User.UserBuilder();}

    public static class UserBuilder {
        private Integer id;
        private String username;
        private String password;
        private ArrayList<String> hobbies;
        UserBuilder() {}
        public User.UserBuilder id(Integer id) { this.id = id; return this; }
        public User.UserBuilder username(String username) { this.username = username; return this; }
        public User.UserBuilder password(String password) { this.password = password; return this; }

        public User.UserBuilder hobby(String hobby) {
            if (this.hobbies == null) {
                this.hobbies = new ArrayList();
            }
            this.hobbies.add(hobby);
            return this;
        }

        public User.UserBuilder hobbies(Collection<? extends String> hobbies) {
            if (this.hobbies == null) {
                this.hobbies = new ArrayList();
            }
            this.hobbies.addAll(hobbies);
            return this;
        }

        public User.UserBuilder clearHobbies() {
            if (this.hobbies != null) {
                this.hobbies.clear();
            }
            return this;
        }

        public User build() {
            List hobbies;
            switch(this.hobbies == null ? 0 : this.hobbies.size()) {
            case 0:
                hobbies = Collections.emptyList();
                break;
            case 1:
                hobbies = Collections.singletonList(this.hobbies.get(0));
                break;
            default:
                hobbies = Collections.unmodifiableList(new ArrayList(this.hobbies));
            }
            return new User(this.id, this.username, this.password, hobbies);
        }
        public String toString() {
            return "User.UserBuilder(id=" + this.id + ", username=" + this.username + ", password=" + this.password + ", hobbies=" + this.hobbies + ")";
        }
    }
}

其实，lombok的创作者还是很用心的，在进行build()来创建实例对象时，
并没有直接使用Collections.unmodifiableList(Collection)此方法来床架实例，而是分为三种情况。

  • 第一种，当集合中没有元素时，创建一个空list
  • 第二种情况，当集合中存在一个元素时，创建一个不可变的单元素list
  • 第三种情况，根据当前集合的元素数量创建对应合适大小的list

当然我们看编译生成的代码，创建了三个关于集合操作的方法：

  • hobby(String hobby)：向集合中添加一个元素
  • hobbies(Collection<? extends String> hobbies)：添加一个集合所有的元素
  • clearHobbies()：清空当前集合数据
2. @Singular 注解配置value属性

我们先来看看 @Singular 注解的详情：

1
2
3
4
5
6
@Target({FIELD, PARAMETER})
@Retention(SOURCE)
public @interface Singular {
    // 修改添加集合元素的方法名
    String value() default "";
}
  • 测试如何使用注解属性value
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Builder
public class User {
    private final Integer id;
    private final String zipCode = "123456";
    private String username;
    private String password;
    @Singular(value = "testHobbies")
    private List<String> hobbies;
}

// 测试类
public class BuilderTest {
    public static void main(String[] args) {
        User user = User.builder()
                .testHobbies("reading")
                .testHobbies("eat")
                .id(1)
                .password("admin")
                .username("admin")
                .build();
        System.out.println(user);
    }
}

说明，当我们使用了注解属性value之后，我们在使用添加集合元素时的方法名发生相应的改变。但是，同时生成的添加整个集合的方法名发生改变了吗？我们再来看看编译后的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// 编译后：
public class User {
    // 省略部分代码，只看关键部分
    public static class UserBuilder {
        public User.UserBuilder testHobbies(String testHobbies) {
            if (this.hobbies == null) {
                this.hobbies = new ArrayList();
            }
            this.hobbies.add(testHobbies);
            return this;
        }

        public User.UserBuilder hobbies(Collection<? extends String> hobbies) {
            if (this.hobbies == null) {
                this.hobbies = new ArrayList();
            }
            this.hobbies.addAll(hobbies);
            return this;
        }
        
        public User.UserBuilder clearHobbies() {
            if (this.hobbies != null) {
                this.hobbies.clear();
            }
            return this;
        }
    }
}

可以看到，只有添加一个元素的方法名发生了改变。

3. @Builder.Default 的使用

比如有这样一个实体类：

1
2
3
4
5
6
7
8
9
10
@Builder
@ToString
public class User {
    @Builder.Default
    private final String id = UUID.randomUUID().toString();
    private String username;
    private String password;
    @Builder.Default
    private long insertTime = System.currentTimeMillis();
}

在类中在id和insertTime上都添加注解@Builder.Default，当在使用这个实体对象时，就不需要在为这两个字段进行初始化值，如下面这样：

1
2
3
4
5
6
7
8
9
10
11
12
public class BuilderTest {
    public static void main(String[] args) {
        User user = User.builder()
                .password("admin")
                .username("admin")
                .build();
        System.out.println(user);
    }
}

// 输出内容：
//User(id=416219e1-bc64-43fd-b2c3-9f8dc109c2e8, username=admin, password=admin, insertTime=1546869309868)

lombok在实例化对象时就为我们初始化了这两个字段值。

当然，你如果再对这两个字段进行设值的话，那么默认定义的值将会被覆盖掉，如下面这样：

1
2
3
4
5
6
7
8
9
10
11
12
public class BuilderTest {
    public static void main(String[] args) {
        User user = User.builder()
                .id("admin")
                .password("admin")
                .username("admin")
                .build();
        System.out.println(user);
    }
}
// 输出内容
//User(id=admin, username=admin, password=admin, insertTime=1546869642151)
4. @Builder 详细配置

下面再来详细看看@Builder这个注解类地详细实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@Target({TYPE, METHOD, CONSTRUCTOR})
@Retention(SOURCE)
public @interface Builder {
    // 如果@Builder注解在类上，可以使用 @Builder.Default指定初始化表达式
    @Target(FIELD)
    @Retention(SOURCE)
    public @interface Default {}
    // 指定实体类中创建 Builder 的方法的名称，默认为: builder (个人觉得没必要修改)
    String builderMethodName() default "builder";
    // 指定 Builder 中用来构件实体类的方法的名称，默认为：build (个人觉得没必要修改)
    String buildMethodName() default "build";
    // 指定创建的建造者类的名称，默认为：实体类名+Builder
    String builderClassName() default "";
    // 使用toBuilder可以实现以一个实例为基础继续创建一个对象。（也就是重用原来对象的值）
    boolean toBuilder() default false;
    
    @Target({FIELD, PARAMETER})
    @Retention(SOURCE)
    public @interface ObtainVia {
        // 告诉lombok使用表达式获取值
        String field() default "";
        // 告诉lombok使用表达式获取值
        String method() default "";

        boolean isStatic() default false;
    }
}

以上注解属性，测试一个比较常用的toBuilder，因为我们在对实体对象进行操作时，往往会存在对某些实体对象的某个字段进行二次赋值，这个时候就会用到这一属性。但是，这会创建一个新的对象，而不是原来的对象，原来的对象属性是不可变的，除非你自己想要给这个实体类再添加上@Data或者@setter方法。下面就来测试一下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@Builder(toBuilder = true)
@ToString
public class User {
    private String username;
    private String password;
}
// 测试类
public class BuilderTest {
    public static void main(String[] args) {
        User user1 = User.builder()
                .password("admin")
                .username("admin")
                .build();
        System.out.println(user1);

        User user2 = user1.toBuilder().username("admin2").build();
        // 验证user2是否是基于user1的现有属性创建的
        System.out.println(user2);
        // 验证对象是否是同一对象
        System.out.println(user1 == user2);
    }
}
// 输出内容
//User(username=admin, password=admin)
//User(username=admin2, password=admin)
//false
5. @Builder 全局配置
1
2
3
4
5
6
# 是否禁止使用@Builder
lombok.builder.flagUsage = [warning | error] (default: not set)
# 是否使用Guaua
lombok.singular.useGuava = [true | false] (default: false)
# 是否自动使用singular，默认是使用
lombok.singular.auto = [true | false] (default: true)
  • 总的来说@Builder还是很好用的。
  • 但当实体对象有继承关系的时候，再使用Builder注解就会发现，在子类中无法通过builder方法构造父类中的成员变量。Builder注解只管承接注解的这个类，而不会管他的父类或者子类。这个问题在lombokv1.18.2 版本之前其实很难办，但是在这个版本官方引入了一个新的注解@SuperBuilder，无法build父类的问题迎刃而解.

　　查阅官方文档发现，若想使用build方法，只需要在子类和父类上都加@SuperBuilder。

@Builder 和SuperBuilder

lombok.javac.handlers.HandleBuilder#handle这个方法中

1
2
3
4
5
6
7
8
9
10
11
12
13
14
JavacNode parent = annotationNode.up();
if (parent.get() instanceof JCClassDecl) {
   job.parentType = parent;
   JCClassDecl td = (JCClassDecl) parent.get();
   
   ListBuffer<JavacNode> allFields = new ListBuffer<JavacNode>();
   boolean valuePresent = (hasAnnotation(lombok.Value.class, parent) || hasAnnotation("lombok.experimental.Value", parent));
  // 取出所有的成员变量
   for (JavacNode fieldNode : HandleConstructor.findAllFields(parent, true)) {
      JCVariableDecl fd = (JCVariableDecl) fieldNode.get();
      JavacNode isDefault = findAnnotation(Builder.Default.class, fieldNode, false);
      boolean isFinal = (fd.mods.flags & Flags.FINAL) != 0 || (valuePresent && !hasAnnotation(NonFinal.class, fieldNode));
      // 巴拉巴拉，省略掉
}

这里的annotationNode就是Builder注解，站在抽象语法树的角度，调用up方法得到的就是被注解修饰的类，也就是需要生成builder方法的类。

通过查看源代码，@Builder注解是可以修饰类，构造函数和方法的，为了简单起见，上面的代码只截取了@Builder修饰类这一种情况，这段代码关键的地方就在于调用HandleConstructor.findAllFields方法获得类中所有的成员变量：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public static List<JavacNode> findAllFields(JavacNode typeNode, boolean evenFinalInitialized) {
   ListBuffer<JavacNode> fields = new ListBuffer<JavacNode>();
  // 从抽象语法树出发，遍历类的所有的成员变量
   for (JavacNode child : typeNode.down()) {
      if (child.getKind() != Kind.FIELD) continue;
      JCVariableDecl fieldDecl = (JCVariableDecl) child.get();
      //Skip fields that start with $
      if (fieldDecl.name.toString().startsWith("$")) continue;
      long fieldFlags = fieldDecl.mods.flags;
      //Skip static fields.
      if ((fieldFlags & Flags.STATIC) != 0) continue;
      //Skip initialized final fields
      boolean isFinal = (fieldFlags & Flags.FINAL) != 0;
      if (evenFinalInitialized || !isFinal || fieldDecl.init == null) fields.append(child);
   }
   return fields.toList();
}

这段代码比较简单，就是对类中的成员变量做了过滤，比如说，静态变量就不能被@Builder方法构造。有一个有意思的点，尽管$可以合法的出现在java的变量命名中，但是Lombok对这种变量做了过滤，因此变量名以$开始的也不能被@Builder构造，经过我们的验证确实是这样的。

发现Java的抽象语法树设计的确是每个类只包含显式声明的变量而不包括父类的成员变量（该插件支持点击语法树节点可以和源文件联动，且数量只有4个和ItemDTO声明的成员变量数量一致）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
lombok.javac.handlers.HandleSuperBuilder#handle
// 巴拉巴拉省略
JCClassDecl td = (JCClassDecl) parent.get();
// 获取继承的父类的抽象语法树
JCTree extendsClause = Javac.getExtendsClause(td);
JCExpression superclassBuilderClass = null;
if (extendsClause instanceof JCTypeApply) {
   // Remember the type arguments, because we need them for the extends clause of our abstract builder class.
   superclassTypeParams = ((JCTypeApply) extendsClause).getTypeArguments();
   // A class name with a generics type, e.g., "Superclass<A>".
   extendsClause = ((JCTypeApply) extendsClause).getType();
}
if (extendsClause instanceof JCFieldAccess) {
   Name superclassName = ((JCFieldAccess) extendsClause).getIdentifier();
   String superclassBuilderClassName = superclassName.toString() + "Builder";
   superclassBuilderClass = parent.getTreeMaker().Select((JCFieldAccess) extendsClause, parent.toName(superclassBuilderClassName));
} else if (extendsClause != null) {
   String superclassBuilderClassName = extendsClause.toString() + "Builder";
   superclassBuilderClass = chainDots(parent, extendsClause.toString(), superclassBuilderClassName);
}
// 巴拉巴拉省略
复制代码

可以看到，这里拿到了继承的父类的抽象语法树，并在后面的逻辑中进行了处理。

文章参考自：https://blog.csdn.net/weixin_41540822/article/details/86606562