Flutter配置管理插件build_config的使用

build_config 插件在Flutter项目中主要用于定制构建行为，通过创建一个 build.yaml 文件来描述你的配置。这使得开发者可以更灵活地控制项目的构建过程，例如针对不同环境（开发、测试、生产）应用不同的构建选项，或者为特定文件集应用代码生成器等。本文将详细介绍如何使用 build_config 插件，并提供完整的示例demo。

一、自定义构建

要自定义包的构建行为，需要创建一个名为 build.yaml 的文件。该文件描述了你的配置。有关格式的完整说明，请参阅 docs/build_yaml_format.md。以下是关于如何具体使用此文件的一些场景：

1. 将包划分为构建目标

当一个 Builder 需要应用于包中的某些文件时，可以通过在 build.yaml 中配置多个“目标”来实现。每个目标都可以有自己的源文件集合和依赖项列表。例如：

targets:
  $default:
    sources:
      include:
        - lib/**/*.dart
    dependencies:
      - "package_name"
    builders:
      package_name:builder_name:
        enabled: true

2. 配置应用于你包的 Builder

每个目标都可以指定一个 builders 键来配置应用于该目标的构建器。你可以根据需要启用或禁用构建器，设置其作用范围，以及传递额外的配置参数。例如：

builders:
  json_serializable:
    import: "package:json_serializable/builder.dart"
    builder_factories: ["jsonSerializable"]
    build_extensions: {".dart": [".g.dart"]}
    auto_apply: dependents
    defaults:
      options:
        any_map_field: false

3. 全局配置 Builder

可以在 global_options 下覆盖所有包的目标级别构建器选项。这些选项会在所有构建器默认值和目标级别配置之后应用，在命令行参数之前应用。例如：

global_options:
  json_serializable:
    options:
      any_map_field: true

二、定义供依赖使用的 Builder

如果你希望其他依赖于你的包的用户能够自动应用一些代码生成逻辑到他们自己的项目中，则可以在 build.yaml 中定义并暴露 Builder。例如：

builders:
  my_builder:
    import: "package:my_package/builder.dart"
    builder_factories: ["myBuilder"]
    build_extensions: {".dart": [".my_package.dart"]}
    auto_apply: dependents
    defaults:
      release_options:
        some_key: "Some value the users will want in release mode"

三、定义 PostProcessBuilder

PostProcessBuilder 类似于普通的 Builder，但它们不能自动应用，必须总是构建到缓存中。例如：

post_process_builders:
  extract_archive_builder:
    import: "package:my_package/extract_archive_builder.dart"
    builder_factory: "myExtractArchiveBuilder"
    input_extensions: [".tar.gz"]

四、调整构建顺序

使用 required_inputs 和 runs_before 可以调整构建器之间的执行顺序。例如：

builders:
  my_builder:
    required_inputs: [".dart"]
    runs_before: ["another_builder"]

五、发布 build.yaml 文件

确保 build.yaml 文件随同你的包一起发布，并且检查到版本控制系统中。每当发布带有 build.yaml 的包时，应该标记对 build_config 的依赖，以确保使用该配置的包具有兼容版本。

示例 Demo

假设我们正在开发一个名为 flutter_example 的Flutter应用程序，并希望使用 json_serializable 包来自动生成JSON序列化代码。首先，我们需要在 pubspec.yaml 文件中添加对 json_serializable 和 build_runner 的依赖：

dependencies:
  flutter:
    sdk: flutter
  json_annotation: ^4.0.1

dev_dependencies:
  build_runner: ^2.0.0
  json_serializable: ^4.0.0

然后，在项目的根目录下创建一个名为 build.yaml 的文件，并添加以下内容：

targets:
  $default:
    builders:
      json_serializable:
        enabled: true
        generate_for:
          include:
            - lib/**/*.dart
        options:
          any_map_field: false

最后，在 lib 文件夹中创建一个 Dart 文件（如 model.dart），并在其中定义一个类，该类使用 @JsonSerializable() 注解：

import 'package:json_annotation/json_annotation.dart';

part 'model.g.dart';

@JsonSerializable()
class Model {
  final String name;
  final int age;

  Model({required this.name, required this.age});

  factory Model.fromJson(Map<String, dynamic> json) => _$ModelFromJson(json);
  Map<String, dynamic> toJson() => _$ModelToJson(this);
}

完成上述步骤后，运行 flutter pub run build_runner build 命令，即可看到自动生成的 JSON 序列化代码。

通过这种方式，我们可以轻松地利用 build_config 插件来管理和优化我们的Flutter项目的构建流程。