构建者设计模式：构建复杂对象的一种更有效的方法

Builder的应用示例：一个使用Builder的工厂模式

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:carouselslider/carousel_slider.dart' as n;

class CarouselWidgetFactory {
  static CustomCarouselBuilder showCarouselAds(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read().dashboardAds.length,
          itemBuilder: (context, index, realIndex) => DashboardAdsList(
            dto: context.read().dashboardAds[index],
          ),
          options: CarouselOptions(
            height: 200,
            viewPortFraction: 0.97,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.easeIn,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );

  static CustomCarouselBuilder showCarouselAccountBalance(
    BuildContext context, {
    void Function(int, n.CarouselPageChangedReason)? onPageChanged,
  }) =>
      CustomCarouselBuilder().setArgs(
        context,
        CarouselArgs(
          itemCount: context.read().allBalances.length,
          itemBuilder: (context, index, realIndex) => BalanceList(
            dto: context.read().allBalances[index],
          ),
          options: CarouselOptions(
            height: 230,
            viewPortFraction: 1,
            enableInfiniteScroll: false,
            autoplayCurve: Curves.decelerate,
            enlargeCenterPage: true,
            pauseAutoPlayOnManualNavigate: true,
            onPageChanged: onPageChanged,
            autoplay: false,
          ),
        ),
      );
}

CarouselWidgetFactory就相当于“导演”角色。它清楚地知道该如何为每种特定的轮播组件配置相应的构建器。关于信息面板广告轮播组件的具体样式（高度为200像素，视口比例为0.97，过渡曲线为easeIn类型），这些信息都集中存储在一个地方；而关于账户余额轮播组件的具体样式（高度为230像素，视口比例为1，过渡曲线为decelerate类型），相关数据也同样保存在同一个地方。

如果开发者需要添加新的轮播组件类型，他们只需向CarouselWidgetFactory添加一个静态方法即可。他们无需了解CustomCarouselBuilder或CustomCarousel的内部实现机制，只需利用这个工厂类来描述自己所需的功能即可。

使用方法

class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // 工厂类会生成正确的构建器配置，
        // 然后通过构建器生成最终的组件。
        CarouselWidgetFactory.showCarouselAds(context).buildCarousel,
        const SizedBox(height: 16),
        CarouselWidgetFactory.showCarouselAccountBalance(context).buildCarousel,
      ],
    );
  }
}

这里只需要两行代码就能创建两个轮播组件，而调用这些代码的开发者完全不需要了解任何关于轮播组件配置的细节——他们既不知道视口比例的具体数值，也不了解自动播放曲线的类型，更不了解各个组件的构建机制。他们只需调用工厂类，工厂类会使用相应的构建器来生成最终的结果。每一层代码都只负责完成自己需要完成的任务而已。

现实世界中的第二个例子：HTTP请求构建器

第一个例子展示了如何使用构建器来创建UI组件，而这个第二个例子则说明了如何利用构建器来生成非UI对象，比如HTTP请求。这种设计模式在数据层和API客户端中非常常见。

最终产物

class ApiRequest {
  final String url;
  final String method;
  final Map headers;
  final Map? body;
  final Duration timeout;
  final int maxRetries;

  // 私有构造函数——只有构建器才能创建ApiRequest对象
  ApiRequest._({
    required this.url,
    required this.method,
    required this.headers,
    this.body,
    required this.timeout,
    required this.maxRetries,
  });
}

ApiRequest类包含了生成HTTP请求所需的所有信息。它的私有构造函数确保了这个对象总是通过构建器来创建的，在创建过程中会应用默认值并进行验证。

构建器

class ApiRequestBuilder {
  String? _url;
  String _method = 'GET';
  final Map _headers = {};
  Map? _body;
  Duration _timeout = const Duration(seconds: 30);
  int _maxRetries = 0;

  ApiRequestBuilder url(String url) {
    _url = url;
    return this;
  }

  ApiRequestBuilder method(String method) {
    _method = method;
    return this;
  }

  ApiRequestBuilder header(String key, String value) {
    _headers[key] = value;
    return this;
  }

  ApiRequestBuilder bearerToken(String token) {
    _headers['Authorization'] = 'Bearer $token';
    return this;
  }

  ApiRequestBuilder contentType(String type) {
    _headers['Content-Type'] = type;
    return this;
  }

  ApiRequestBuilder body(Map body) {
    _body = body;
    return this;
  }

  ApiRequestBuilder timeout(Duration timeout) {
    _timeout = timeout;
    return this;
  }

  ApiRequestBuilder withRetries(int maxRetries) {
    _maxRetries = maxRetries;
    return this;
  }

  ApiRequest build() {
    if (_url == null || _url!.isEmpty) {
      throw ArgumentError('生成ApiRequest对象时必须提供URL地址');
    }

    return ApiRequest._(
      url: _url!,
      method: _method,
      headers: Map.unmodifiable(_headers),
      body: _body,
      timeout: _timeout,
      maxRetries: _maxRetries,
    );
  }
}

需要注意的是，`_method`、`_timeout`和`_maxRetries`这些属性都配备了合理的默认值。除非用户有意覆盖这些默认值，否则无需手动指定它们。这正是Builder模式相比构造函数的一大优势：可选配置确实是可选项，不存在需要进行空值检查或使用默认参数之类的麻烦。

使用方法

// 一个标准的、经过身份验证的POST请求
final createUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users')
    .method('POST')
    .bearerToken(authToken)
    .contentType('application/json')
    .body({'name': 'Oluwaseyi', 'email': 'seyi@example.com'})
    .timeout(const Duration(seconds: 15))
    .build();

// 一个带有重试机制的GET请求
final getUserRequest = ApiRequestBuilder()
    .url('https://api.example.com/users/$userId')
    .bearerToken(authToken)
    .withRetries(3)
    .build();

// 一个为第三方服务设置自定义头的请求
final webhookRequest = ApiRequestBuilder()
    .url('https://webhook.example.com/events')
    .method('POST')
    .header('X-API-Key', apiKey)
    .header('X-Webhook-Secret', webhookSecret)
    .contentType('application/json')
    .body(eventPayload)
    .timeout(const Duration(seconds: 5))
    .build();

每条请求的描述都非常清晰：包括URL、请求方法、认证方式、请求体以及超时设置。只要阅读这些信息，就能立刻了解这条请求的具体类型及其包含的内容。

相比之下，直接使用构造函数来创建请求对象就会显得很不方便：

// 不使用Builder模式——代码可读性差，参数顺序也很重要
final request = ApiRequest._(
  url: 'https://api.example.com/users',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $authToken',
    'Content-Type': 'application/json',
  },
  body: {'name': 'Oluwaseyi', 'email': 'seyi@example.com'},
  timeout: const Duration(seconds: 15),
  maxRetries: 0,
);

使用构造函数时，你必须清楚所有参数及其排列顺序；而Builder模式则允许你只指定所需的配置项，其代码结构更像文档说明。

C#中的构建器模式

C#中也同样采用了这种构建器模式，这进一步证明了这是一种通用的设计原则，并非Dart语言所特有的技术。由于C#支持方法链机制，因此在实现构建器模式时，它的表达能力尤为强大。

C#中的HTTP请求构建器

在C#中使用它

// 经过身份验证的POST请求
var createUserRequest = ApiRequest.Create()
    .Url("https://api.example.com/users")
    .Method("POST")
    .BearerToken(authToken)
    .ContentType("application/json")
    .Body(new { name = "Oluwaseyi", email = "seyi@example.com" })
    .Timeout(TimeSpan(seconds(15))
    .Build();

// 带有重试逻辑的GET请求
var getUserRequest = ApiRequest.Create()
    .Url($"https://api.example.com/users/{userId}")
    .BearerToken(authToken)
    .WithRetries(3)
    .Build();

这种编写模式是完全相同的。方法名称遵循C#的约定，都是大写的。`Build()`方法是整个请求处理流程的最后一步。同时，也强制使用了私有构造函数。其代码结构与Dart语言中的对应实现完全一致。

C#（ASP.NET）中的UI构建器

在.NET中，构建模式也被广泛用于后端系统中创建复杂的对象。下面是一个用于生成通知信息的示例：

public class Notification
{
    public string Title { get; }
    public string Body { get; }
    public string? ImageUrl { get; }
    public NotificationPriority Priority { get; }
    public Dictionary Data { get; }
    public bool Silent { get; }

    private Notification(
        string title,
        string body,
        string? imageUrl,
        NotificationPriority priority,
        Dictionary data,
        bool silent)
    {
        Title = title;
        Body = body;
        ImageUrl = imageUrl;
        Priority = priority;
        Data = data;
        Silent = silent;
    }

    public static NotificationBuilder Builder(string title, string body)
        => new NotificationBuilder(title, body);
}

public class NotificationBuilder
{
    private readonly string _title;
    private readonly string _body;
    private string? _ImageUrl;
    private NotificationPriority _priority = NotificationPriority.Default;
    private readonly Dictionary _data = new();
    private bool _silent = false;

    internal NotificationBuilder(string title, string body)
    {
        _title = title;
        _body = body;
    }

    public NotificationBuilder WithImage(string imageUrl)
    {
        _ImageUrl = imageUrl;
        return this;
    }

    public NotificationBuilder WithPriority(NotificationPriority priority)
    {
        _priority = priority;
        return this;
    }

    public NotificationBuilder WithData(string key, string value)
    {
        _data[key] = value;
        return this;
    }

    public NotificationBuilder AsSilent()
    {
        _silent = true;
        return this;
    }

    public Notification Build() => new Notification(
        _title,
        _body,
        _ImageUrl,
        _priority,
        new Dictionary(_data),
        _silent
    );
}

// 使用示例
var notification = Notification
    .Builder("新交易", "您收到了50,000奈拉")
    .WithPriority(NotificationPriority.High)
    .WithData("transaction_id", "txn_001")
    .WithData("type", "credit")
    .Build();

var silentNotification = Notification
    .Builder("后台同步", "")
    .AsSilent()
    .WithData("sync_type", "full")
    .Build();

构建器、构造函数与工厂模式

要了解何时该使用构建器，而非构造函数或工厂方法，就必须明白它们各自能解决什么问题。

当一个对象的结构足够简单，其所有参数都能一目了然，并且可选配置项也很少时，构造函数才是合适的选择。例如，一个仅包含id、name和email字段的用户对象，就不需要使用构建器。

当你需要控制创建的对象类型，或者对象的创建过程需要根据某些逻辑来决定具体使用哪种类型时，工厂方法就是最佳选择。比如Repository.create()方法会根据当前环境返回SqlRepository或HiveRepository中的某一种。

当一个对象具有许多可选配置参数，其创建过程需要多个步骤完成，或者你希望确保在所有必要参数都准备好之后才进行对象的创建，从而避免生成无效对象时，构建器才是合适的选择。此外，当你希望构建代码结构清晰、易于理解时，构建器也是个不错的选择。

在carousel示例中，我们有意同时使用了构建器和工厂模式。工厂方法提供了一些预先配置好的接口方法（如showCarouselAds、showCarouselAccountBalance），而构建器则负责完成这些复杂配置的逐步构建过程。这两种模式各司其职，共同完成了任务。

何时使用构建器模式

构建器模式有着许多适用的场景。

当需要创建的对象包含许多参数，尤其是许多可选参数时，就应该使用构建器模式。那些带有十个可选参数的构造函数往往难以阅读，也容易被错误配置。

如果你希望构建代码本身就能清晰地说明其功能，那么构建器模式也是个不错的选择。使用描述性强的方法名进行链式调用，可以让代码像文档一样易于理解。读者无需了解内部实现细节，就能明白这段代码的作用。

何时不应使用它

当一个对象的结构很简单，其构造函数也已经非常清晰易懂时，就应避免使用构建器模式。对于那些只需要两个必要参数的类来说，添加构建器只会增加复杂性，而并不会带来任何实际价值。

当不变性不是需要考虑的因素，且对象可以在创建后通过属性设置方法进行配置时，这种设计方式也不是一个理想的选择。对于某些对象来说，创建后的简单配置反而比使用构建者模式更为合适。

此外，当构建步骤之间存在严格的顺序要求，而线性构建者模式无法满足这些要求时，最好避免使用这种模式。如果某一步骤在执行之前必须知道前一步的结果，那么采用其他设计模式可能会更加合适。

结论

构建者设计模式解决了随着对象结构变得越来越复杂，每个开发人员都会遇到的问题。参数众多的构造函数会导致代码难以阅读、维护困难，且容易出现配置错误；可选参数还需要进行空值检查以及设置默认值，这些操作往往会使代码的意图变得模糊不清。

构建者模式将复杂对象的构建过程与对象本身分离开来。配置信息是通过一系列描述性的方法调用逐步累积起来的，而最终的构建步骤则会验证这些配置并生成最终的对象。产品的私有构造函数确保了无法绕过构建者模式来创建对象。

在一个真实的Flutter金融科技应用中，轮播组件的实现就很好地体现了这一设计模式：构建者负责收集各种组件的配置信息，工厂方法为特定类型的轮播组件提供预先配置好的构建步骤，而产品本身只能通过构建者模式来创建。每当添加新的轮播组件类型时，就需要为工厂方法添加相应的代码；当需要修改轮播组件的配置时，也只需调整对应的工厂方法即可。调用代码根本不需要直接接触轮播组件的内部实现细节。

HTTP请求构建器在数据层也体现了同样的设计模式：通过方法链逐步进行配置设置，为可选参数提供了合理的默认值，在构建之前会进行验证检查，最终生成的状态一定是不可变的。

方法链的存在使得构建者模式的代码具有很高的可读性。每次方法调用都会返回构建者对象，从而使得后续的调用能够依次进行。这种链式调用方式从左到右或从上到下地执行，就像是在描述整个构建过程一样。这不仅仅是一种美观的设计手法，更是让构建者模式代码具备自文档说明能力和长期维护性的关键所在。

复杂对象的构建是每个代码库都会遇到的问题，而构建者模式正是经验丰富的工程师们解决这一问题的有效手段。