原创 冯希才 / 叫叫技术团队

前言

在 Dart 中，build_runner 是一个强大的静态编译工具，它提供了一种简单而灵活的方式来自动化构建过程。通过使用 build_runner ，开发者可以轻松地生成代码、资源文件和其他构建输出，从而提高开发效率。 build_runner 的命令需要与使用 Dart 编译系统 从输入文件生成输出文件的生成器 Package 配合使用。例如， json_serializable 与 built_value_generator 这两个 Package 共同定义了生成 Dart 代码的生成器。

正文

安装配置

安装build_runner： 在项目的pubspec.yaml文件中添加以下依赖项：

dev_dependencies:
  # ···
  build_runner: ^2.4.6
  build_test: ^2.2.0

基本用法

dart run build_runner build

flutter pub run build_runner build

• dart run build_runner build ：这个命令用于在 Dart 项目中运行 build_runner，执行构建操作。通常在纯 Dart 项目中使用，例如 Dart 库或控制台应用程序。
• flutter pub run build_runner build ：这个命令用于在 Flutter 项目中运行 build_runner，执行构建任务。Flutter 项目通常使用这个命令来进行代码生成、资源管理或其他构建任务，因为它包含了 Flutter 所需的配置和依赖。

构建配置 build.yaml说明

先来看下 github.com/google/json… json_serializable配置

# Read about `build.yaml` at https://pub.dev/packages/build_config
targets:
  $default:
    builders:
      source_gen|combining_builder:
        options:
          ignore_for_file:
          - lines_longer_than_80_chars
          # Only for the JSON literal output file
          - text_direction_code_point_in_literal
          # Too much work in generated code
          - inference_failure_on_function_invocation
          # Need to update sourcegen_helper to generate List/Map with the right type params
          - inference_failure_on_collection_literal

      json_serializable:
        generate_for:
        - example/*
        - test/default_value/*
        - test/field_matrix_test.field_matrix.dart
        - test/generic_files/*
        - test/integration/*
        - test/kitchen_sink/*
        - test/literal/*
        - test/supported_types/*
        - tool/readme/*
        ...

build.yaml 文件是一个用于配置 Dart 构建系统（Build System）的文件，它用于定义 Dart 项目的构建过程中各种构建任务的行为、规则和配置。这个文件通常用于构建 Dart 项目时指定代码生成器的配置、构建行为、文件处理规则等。 以下是 build.yaml 文件的一些主要配置选项：

1. 构建器（Builders）

构建器定义了在构建过程中执行的任务，例如代码生成、文件处理等。在 builders 部分配置了构建器的名称和相关的配置信息。

builders:
  some_builder:
    target: ":some_target"
    options:
      # 配置选项

2. 构建目标（Targets）

构建目标是指定构建器应用于哪些文件或目录的规则。它可以指定构建器所需处理的文件路径、输入和输出文件等信息。

targets:
  some_target:
    builders:
      - some_builder
    sources:
      - "lib/**/*.dart"
      # 其他源文件规则

3. 构建扩展（Post Processors）

构建扩展允许您在构建结束后对输出结果进行处理，比如压缩、优化等。

post_process_builders:
  some_post_processor:
    builder: some_builder
    # 配置选项

4. 构建配置（Build Configurations）

构建配置允许您为不同的构建模式指定不同的配置，比如开发模式、生产模式等。

configurations:
  some_configuration:
    builders:
      some_builder:
        generate_for:
          - "lib/main.dart"

5. 其他选项

除了上述主要部分外，build.yaml 还可以包含其他选项和配置，比如 targets_sources、global_options、auto_apply 等，用于对构建行为和配置进行更详细的控制和定制。 请注意，build.yaml 的具体配置内容会根据项目的需求和使用的构建工具而有所不同。配置过程可能会有一些技术细节和特定的构建器/工具要求。因此，在编写 build.yaml 文件时，最好参考 github.com/dart-lang/b… 和实际需求进行详细配置。 如果您需要了解更多关于 build.yaml 文件的详细信息和具体配置选项，可以参考 Dart 构建系统的官方文档或相关的构建工具的文档，以便更好地了解如何配置和使用这些选项。

自定义构建器

参考： github.com/google/json… 新建一个 package 要自定义一个 build_runner 的构建器（Builder），您需要做以下几个步骤：

1. 创建构建器

创建一个 Dart 类，这个类将作为自定义构建器的实现。您可以在其中定义处理文件的逻辑、生成代码或执行其他任务。

dart create test_builder

2. 配置构建系统

在项目的 build.yaml 文件中配置您的构建器。在 builders 部分指定您的构建器，并定义其行为和相关选项。

builders:
  my_custom_builder:
    target: ":some_target"
    options:
      # 配置选项

3. 定义构建目标

在 targets 部分定义目标，指定构建器应用于哪些文件或目录。

targets:
  some_target:
    builders:
      - my_custom_builder
    sources:
      - "lib/**/*.dart"
      # 其他源文件规则

4. 编写构建器的代码逻辑

在构建器类中，实现处理文件、生成代码或其他任务的逻辑。这可能涉及读取文件、分析内容、执行特定的操作，并根据需求生成代码或完成其他任务。

5. 运行 build_runner

运行 flutter pub run build_runner build 命令来触发 build_runner 执行构建过程。这将根据您的配置文件和自定义构建器来处理文件、执行任务并生成所需的输出。

注意事项：

• 构建器的编写和配置需要根据具体的需求和项目情况。这可能涉及到文件处理、代码生成、资源处理等。
• 在编写自定义构建器时，建议参考 build_runner 的相关文档和示例，以了解构建器的生命周期、输入输出规范等。
• 调试构建器时，您可以使用 --verbose 或 --delete-conflicting-outputs 等选项来进行详细的构建输出和解决可能的输出冲突。

这些步骤可以帮助您开始创建自定义的 build_runner 构建器。确保理解构建器的生命周期和相关规范，以便根据您的需求和项目特点来完善和定制构建器的功能。

构建缓存

Flutter 中的 build_runner 工具在运行时会维护一个构建缓存，以加快后续的构建过程。这个缓存存储了每个构建过程的结果，使得在没有变更的情况下，可以直接重用之前构建的结果，而不必重新执行整个构建过程。 构建缓存通常位于项目目录的隐藏文件夹 .dart_tool/build 中。在这个文件夹下，build 工具会保存构建过程中生成的临时文件、生成的代码以及其他构建所需的数据。 这个缓存文件夹有助于提高后续构建的速度，因为如果没有源码变更，build_runner 可以直接从缓存中获取所需的结果，而不必重新计算和生成。这在大型项目中尤其有用。 如果您希望清除 build_runner 的缓存，可以执行以下命令：

flutter pub run build_runner clean

这会清除构建过程中生成的所有缓存，下次构建时将重新生成所有必要的内容。这可能会导致第一次构建时间变长，但可以确保获得最新的结果。

高级用法

build_runner 支持增量构建和并行构建，这些功能可以提高构建效率和速度。

增量构建

增量构建允许在代码或资源文件发生更改时只重新构建受影响的部分，而不是重新构建整个项目。这是通过比较文件的修改时间戳和内容哈希来实现的。build_runner 会自动检测文件更改，并只重新构建有变化的部分，从而加快构建速度。

并行构建

build_runner 还支持并行构建，允许多个任务同时运行，提高了构建的效率。默认情况下，build_runner 会尝试根据可用的系统资源并行运行多个构建任务。 您可以通过以下方式启用或配置这些功能：

1. 增量构建： 增量构建是 build_runner 的默认行为，因此您不需要额外的设置。只要文件没有更改，build_runner 将重用已构建的内容。
2. 并行构建： build_runner 默认会根据系统资源并行运行构建任务。但是，您可以通过以下方式对并行度进行配置：

flutter pub run build_runner build --parallel

上述命令中的 --parallel 参数将允许 build_runner 尽可能地并行执行多个构建任务，以提高构建速度。 请注意，尽管增量构建和并行构建可以显著提高构建效率，但某些情况下可能会导致一些问题，例如资源竞争或依赖关系的复杂性。确保您的项目适合使用这些功能，并根据需要进行适当的配置。

结尾

叫叫在 flutter 项目中使用 build_runner JSON to dart 最佳实践

在 Flutter 项目的实际开发中，肯定会遇到后端返回json数据的情况，但是dart本身并没有json 格式的数据，所以我们需要使用工具将后端返回的数据转为dart对象，来做到像使用dart对象一样方便。

借助插件 Freezed

freezed 的安装方式可以参考官方文档：github.com/rrousselGit…，大体和json_serializable类似，这里我们主要介绍freezed的使用。 我们按照freezed的方式写一下person.dart。

import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:flutter/foundation.dart';
part 'person.freezed.dart';
part 'person.g.dart';

@freezed
class Person with _$Person {
  const factory Person({
    String? name,
    int? age,
    String? gander,
    String? birthday,
  }) = _Person;

  factory Person.fromJson(Map<String, Object?> json) => _$PersonFromJson(json);
}

代码就这么多，是不是超级简单，我们只需要关注我们用到的属性字段和类型就好，其他的交给工具来生成，也可以有效避免重复代码所带来的问题。 运行 flutter pub run build_runner build 会在当前目录生成 person.freezed.dart和 person.g.dart 生成出来的部分代码截图：

可以用 build_runner 来做哪些增效

• img build , 新增图片，自动生成图片引入相关 dart
• 页面模板。基础页面模板创建等

命令又臭又长如何优雅使用

flutter 相关命令，每次都要来翻小本本查 安装 build runner 插件： 项目中使用示例，愉快的新增数据 model

附言

常用命令：

清除缓存

flutter pub run build clean

强制合并覆盖

flutter pub run build_runner build --delete-conflicting-outputs

只运行指定文件&指定脚本

flutter pub run build_runner build --delete-conflicting-outputs --build-filter 'json_serializable|lib/models/*'

官方文档

• github.com/dart-lang/b…