2. 当构造方法参数过多时使用 builder 模式

Effective java

为什么要使用 builder 模式?

静态工厂和构造方法都有一个限制：它们不能很好地扩展到很多可选参数的情景。请考虑一个代表包装食品上的营养成分标签的例子。这些标签有几个必需的属性——每次建议的摄入量，每罐的份量和每份卡路里 ，以及超过 20个可选的属性——总脂肪、饱和脂肪、反式脂肪、胆固醇、钠等等。大多数产品都有非零值，只有少数几个可选属性。

应该为这样的类编写什么样的构造方法或静态工厂？传统上，程序员使用了可伸缩（telescoping constructor）构造方法模式，在这种模式中，只提供了一个只所需参数的构造函数，另一个只有一个可选参数，第三个有两个可选参数，等等，最终在构造函数中包含所有可选参数。

多可选参数的情景

class NutritionFacts {
        private final int servingSize; // (mL) required
        private final int servings; // (per container) required
        private final int calories; // (per serving) optional
        private final int fat; // (g/serving) optional
        private final int sodium; // (mg/serving) optional
        private final int carbohydrate; // (g/serving) optional

        public NutritionFacts(int servingSize, int servings) {
            this(servingSize, servings, 0);
        }

        public NutritionFacts(int servingSize, int servings,
                int calories) {
            this(servingSize, servings, calories, 0);
        }

        public NutritionFacts(int servingSize, int servings,
                int calories, int fat) {
            this(servingSize, servings, calories, fat, 0);
        }

        public NutritionFacts(int servingSize, int servings,
                int calories, int fat, int sodium) {
            this(servingSize, servings, calories, fat, sodium, 0);
        }

        public NutritionFacts(int servingSize, int servings,
                int calories, int fat, int sodium, int carbohydrate) {
            this.servingSize = servingSize;
            this.servings = servings;
            this.calories = calories;
            this.fat = fat;
            this.sodium = sodium;
            this.carbohydrate = carbohydrate;
        }

       /**
        * 当想要创建一个实例时，可以使用包含所有要设置的参数的最短参数列表的构造方法：
        */
       NutritionFacts cocaCola = new NutritionFacts(240, 8, 100, 0, 35, 27);

通常情况下，这个构造方法的调用需要许多你不想设置的参数，但是你不得不为它们传递一个值。 在这种情况下，我们为 fat 属性传递了 0 值。「只有」六个参数可能看起来并不那么糟糕，但随着参数数量的增加，它会很快失控。
简而言之，可伸缩构造方法模式是有效的，但是当有很多参数时，很难编写客户端代码，而且很难读懂它。读者不知道这些值是什么意思，并且必须仔细地计算参数才能找到答案。一长串相同类型的参数可能会导致一些细微的bug。如果客户端意外地反转了两个这样的参数，编译器并不会抱怨，但是程序在运行时会出现错误行为 。
当在构造方法中遇到许多可选参数时，另一种选择是 JavaBeans 模式，在这种模式中，调用一个无参数的构造函数来创建对象，然后调用 setter 方法来设置每个必需的参数和可选参数：

    /*
     * 这种模式没有伸缩构造方法模式的缺点。有点冗长，但创建实例很容易，并且易于阅读所生成的代码:
     * 
     */
    class NutritionFacts {
        // Parameters initialized to default values (if any)
        private int servingSize = -1; // Required; no default value
        private int servings = -1; // Required; no default value
        private int calories = 0;
        private int fat = 0;
        private int sodium = 0;
        private int carbohydrate = 0;

        public NutritionFacts () {
        }

        // Setters
        public void setServingSize(int val) {
            servingSize = val;
        }

        public void setServings(int val) {
            servings = val;
        }

        public void setCalories(int val) {
            calories = val;
        }

        public void setFat(int val) {
            fat = val;
        }

        public void setSodium(int val) {
            sodium = val;
        }

        public void setCarbohydrate(int val) {
            carbohydrate = val;
        }
		
        NutritionFacts cocaCola = new NutritionFacts ();
        cocaCola.setServingSize(240);
        cocaCola.setServings(8);
        cocaCola.setCalories(100);
        cocaCola.setSodium(35);
        cocaCola.setCarbohydrate(27);
    }

使用 Builder 模式

它结合了可伸缩构造方法模式的安全性和 JavaBean 模式的可读性。
它是 Builder模式[Gamma95] 的一种形式。客户端不直接调用所需的对象，而是调用构造方法 (或静态工厂)，并使用所有必需的参 数，并获得一个 builder 对象。然后，客户端调用 builder 对象的 setter 相似方法来设置每个可选参数。最后客户端调用一个无参的 build 方法来生成对象，该对象通常是不可变的。Builder 通常是它所构建的类的一个静态成员类。

//NutritionFacts 类是不可变的，所有的参数默认值都在一个地方。
//builder 的 setter 方法返回 builder 本身，这样调用就可以被链接起来，从而生成一个流畅的 API
class NutritionFacts {
    
    private final int servingSize;
    private final int servings;
    private final int calories;
    private final int fat;
    private final int sodium;
    private final int carbohydrate;

    public static class Builder {
        // Required parameters
        private final int servingSize;
        private final int servings;
        // Optional parameters - initialized to default values
        private int calories = 0;
        private int fat = 0;
        private int sodium = 0;
        private int carbohydrate = 0;

        public Builder(int servingSize, int servings) {
			//检查参数有效性，如果检查失败，则抛出 IllegalArgumentException 异常
            if (servingSize <= 0 || servings <= 0)
                throw new IllegalArgumentException("Serving size/servings must be positive");
            this.servingSize = servingSize;
            this.servings = servings;
        }

        public Builder calories(int val) {
            calories = val;
            return this;
        }

        public Builder fat(int val) {
            fat = val;
            return this;
        }

        public Builder sodium(int val) {
            sodium = val;
            return this;
        }

        public Builder carbohydrate(int val) {
            carbohydrate = val;
            return this;
        }

        public NutritionFacts build() {
            return new NutritionFacts (this);
        }
    }

    private NutritionFacts (Builder builder) {
        servingSize = builder.servingSize;
        servings = builder.servings;
        calories = builder.calories;
        fat = builder.fat;
        sodium = builder.sodium;
        carbohydrate = builder.carbohydrate;
    }

	//这个客户端代码很容易编写，更重要的是易于阅读。 Builder 模式模拟 Python 和 Scala 中的命名可选参数。
    NutritionFacts cocaCola = new NutritionFacts.Builder(240, 8)
            .calories(100).sodium(35).carbohydrate(27).build();
}

Builder 模式类层次结构

使用平行层次的 builder，每个嵌套在相应的类中。 抽象类有抽象的builder；具体的类有具体的 builder

/**
 * Builder 模式非常适合类层次结构。 使用平行层次的 builder，每个嵌套在相应的类中。 抽象类有抽象的
 * builder；具体的类有具体的 builder。 例如，考虑代表各种比萨饼的根层次结构的抽象类：
 * 
 */
abstract class Pizza { // 抽象的Pizza类，作为披萨类层次结构的根

    public enum Topping { // 内部枚举类，定义了所有可用的披萨配料选项
        HAM, MUSHROOM, ONION, PEPPER, SAUSAGE // 火腿、蘑菇、洋葱、辣椒、香肠
    }

    final Set<Topping> toppings; // 最终的配料集合，一旦初始化后不可修改

    // 抽象的Builder类，使用了泛型递归模式(T extends Builder)来支持方法链
    abstract static class Builder<T extends Builder<T>> {
        // 使用EnumSet存储配料，初始化为空集合
        EnumSet<Topping> toppings = EnumSet.noneOf(Topping.class);

        // 添加配料的方法，返回Builder实例以支持链式调用
        public T addTopping(Topping topping) {
            toppings.add(Objects.requireNonNull(topping)); // 添加配料并检查是否为null
            return self(); // 返回this，但通过self()方法实现，支持子类重写
        }

        // 抽象方法：构建最终的Pizza对象
        abstract Pizza build();

        // 抽象方法：返回当前Builder的实例(this)
        // 这个设计允许子类重写并返回自己的类型，是实现方法链的关键
        protected abstract T self();
    }

    // Pizza构造函数，接收Builder作为参数
    Pizza(Builder<?> builder) {
        toppings = builder.toppings.clone(); // 克隆builder中的配料集合，确保安全性
    }
}

/**
 * 这里有两个具体的 Pizza 的子类，其中一个代表标准的纽约风格的披萨，另一个是半圆形烤乳酪馅饼。
 * 前者有一个所需的尺寸参数，而后者则允许指定酱汁是否应该在里面或在外面：
 * 
 */
class NyPizza extends Pizza {

    public enum Size {
        SMALL, MEDIUM, LARGE
    }

    private final Size size;

    public static class Builder extends Pizza.Builder<Builder> {

        private final Size size;

        public Builder(Size size) {
            this.size = Objects.requireNonNull(size);
        }

        @Override
        public NyPizza build() {
            return new NyPizza(this);
        }

        @Override
        protected Builder self() {
            return this;
        }
    }

    private NyPizza(Builder builder) {
        super(builder);
        size = builder.size;
    }

    NyPizza pizza = new NyPizza.Builder(SMALL).addTopping(SAUSAGE).addTopping(ONION).build();

}

class Calzone extends Pizza {

    private final boolean sauceInside;

    public static class Builder extends Pizza.Builder<Builder> {

        private boolean sauceInside = false; // Default

        public Builder sauceInside() {
            sauceInside = true;
            return this;
        }

        @Override
        public Calzone build() {
            return new Calzone(this);
        }

        @Override
        protected Builder self() {
            return this;
        }
    }

    private Calzone(Builder builder) {
        super(builder);
        sauceInside = builder.sauceInside;
    }

    Calzone calzone = new Calzone.Builder().addTopping(HAM).sauceInside().build();
}

总结

处理复杂对象创建：当对象构造过程复杂，包含多个步骤或参数时特别有用
避免构造函数参数过多：解决了"望远镜构造函数"问题
提供更清晰的代码：使创建过程更直观，代码可读性更强
实现参数的可选性：可以只设置需要的参数，其他使用默认值
分步骤构建对象：允许逐步构建，而非一次性提供所有参数
封装对象创建细节：客户端不需要了解对象的具体构建过程
提高代码的可维护性：当需要修改对象创建过程时，只需修改Builder类而不影响客户端代码