Flutter开发工具插件dart_dev的使用

Flutter开发工具插件dart_dev的使用

dart_dev 是一个用于 Dart 项目的集中式工具。它提供了一致的接口，并且易于配置。

目录

• 快速开始
• 动机与目标
• 项目级配置
• 扩展/组合功能
• 共享配置
• 保存时格式化

快速开始

升级自v2？请查看v3升级指南。

查找可用工具的详细指南？请参阅附加文档。

在项目中添加 dart_dev 作为开发依赖：

dart pub add --dev dart_dev

默认情况下，这提供了三个核心任务：

• analyze
• format
• test

通过 dart_dev 命令行应用程序运行这些工具之一：

$ dart run dart_dev analyze
[INFO] Running subprocess:
dart analyze .
--------------------------
Analyzing dart_dev...
No issues found!

我们建议添加一个 ddev 别名：

alias ddev='dart run dart_dev'

可以添加额外的 Dart 开发者工具并配置它们。为此，创建一个 tool/dart_dev/config.dart 文件，如下所示：

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';

final config = {
  // 查看"共享配置"部分以获取更多信息。
  ...coreConfig,

  // 覆盖或添加新工具并按所需进行配置。
  'analyze': AnalyzeTool(),
  'format': FormatTool(),
  'test': TestTool(),
  'serve': WebdevServeTool()
    ..webdevArgs = ['example:8080'],
};

动机与目标

大多数 Dart 项目最终会共享一组共同的开发需求（例如静态分析、格式化、测试运行等）。Dart SDK 和一些核心包提供了必要的工具来完成这些开发者任务（例如 dart analyze、dart format 或 dart test）。

虽然核心工具已经足够强大，但仍然存在两个问题：

1. 在不同项目中如何使用这些工具来完成常见的开发者任务存在不一致性。
2. 对于更复杂的用例，工具的功能不足。

通过 dart_dev，我们尝试解决 #1 通过提供一种方法来在项目级别配置所有这些常见的开发者任务，解决 #2 通过围绕现有工具组合附加功能。

此包以可配置性和可扩展性为设计目标，希望您和您的团队能够在创建自己的工具和共享配置中找到价值。理想情况下，您或您的团队可以确定一个共享配置，单个项目可以消费该配置；具有独特需求的项目可以根据需要调整配置；开发人员可以依赖简单的、一致的命令行界面，无论他们在哪个项目中工作。

项目级配置

每个任务都应该能够在项目级别上进行配置，以便跨项目的任何变化成为不需要记忆或引用的配置细节。

以格式化为例。默认情况下，对文件进行格式化的做法是运行 dartfmt -w .。但是，某些项目可能想要排除某些文件，这些文件将被此命令格式化。或者，某些项目可能想要使用 pub run dart_style:format 而不是 dart format。目前，格式器不支持项目级别的配置，因此这些事情只能记录在 README.md 或 CONTRIBUTING.md 中。

通过 dart_dev，可以这样实现：

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';
import 'package:glob/glob.dart';

final config = {
  'format': FormatTool()
    ..exclude = [Glob('lib/src/**.g.dart')]
    ..formatter = Formatter.dartStyle,
};

$ ddev format
[INFO] Running subprocess:
dart run dart_style:format -w <3 paths>
--------------------------------------
Unchanged ./lib/foo.dart
Unchanged ./lib/src/bar.dart
Formatted ./lib/src/baz.dart

扩展/组合功能

使用由 Dart 社区提供的现有工具（或约定）始终是目标，但现实情况是存在差距。某些用例可以变得更方便，新的用例可能会出现。

以测试运行为例。对于简单的项目，dart test 已经足够。事实上，测试包通过 dart_test.yaml 支持大量的项目级配置，这意味着对于正确配置的项目，dart test 就能正常工作。

不幸的是，当前，依赖于构建者的项目必须通过 dart run build_runner test 运行测试。基于项目，你需要知道应该运行哪个测试命令。

通过 dart_dev，TestTool 可以自动检查项目的 pubspec.yaml 是否包含 build_test 依赖。如果存在，则测试将通过 dart run build_runner test 运行，否则回退到默认的 dart test。

# 在没有 `build_test` 依赖的项目中：
$ ddev test
[INFO] Running subprocess:
dart test
----------------------------
00:01 +75: All tests passed!

# 在有 `build_test` 依赖的项目中：
$ ddev test
[INFO] Running subprocess:
dart run build_runner test
----------------------------
[INFO] Generating build script completed, took 425ms
[INFO] Creating build script snapshot... completed, took 13.6s
[INFO] Building new asset graph completed, took 960ms
[INFO] Checking for unexpected pre-existing outputs. completed, took 1ms
[INFO] Running build completed, took 12.4s
[INFO] Caching finalized dependency graph completed, took 71ms
[INFO] Creating merged output dir `/var/folders/vb/k8ccjw095q16jrwktw31ctmm0000gn/T/build_runner_testBkm6gS/` completed, took 260ms
[INFO] Writing asset manifest completed, took 3ms
[INFO] Succeeded after 12.8s with 1276 outputs (2525 actions)
Running tests...

00:00 +75: All tests passed!

此外，TestTool 自动应用 --build-filter 选项到 dart run build_runner test 命令中，以帮助减少构建时间和加快开发迭代速度，当运行可用测试的一部分时。

一般来说，这些 Dart 工具抽象提供了填补底层工具功能差距的地方，或者使某些用例更方便或高效。

共享配置

此包提供 coreConfig 作为 dart_dev 工具的最小基本配置。如果你的项目没有 tool/dart_dev/config.dart，这是默认配置。

此共享配置包含以下目标：

• ddev analyze
• ddev format
• ddev test

这些目标的实际配置可以在这里找到： lib/src/core_config.dart

coreConfig 只是一个返回 Map<String, DevTool> 对象的 getter，因此扩展它或自定义它就像创建自己的 Map，展开共享配置，然后添加自己的条目一样简单：

// tool/dart_dev/config.dart
import 'package:dart_dev/dart_dev.dart';

final config = {
  ...coreConfig,

  // 通过在 `...coreConfig` 后包括它来覆盖一个目标：
  'format': FormatTool()
    ..formatter = Formatter.dartFormat,

  // 添加一个自定义目标：
  'github': ProcessTool(
      'open', ['https://github.com/Workiva/dart_dev']),

  // 等等。
};

保存时格式化

dart_dev 可以用于在 JetBrains IDE 中实现保存时格式化。以下是设置说明。

VS Code 的注意事项

有一个 VS Code 扩展可以在保存时运行 dartfmt 或 over_react_format。更多信息请参阅 其项目。然而，该 VS Code 扩展不运行 dart_dev，而是有自己的逻辑来运行格式化命令。

JetBrains IDEs (WebStorm, IntelliJ 等)

WebStorm 提供了一个文件监视器实用程序，可以在文件保存时运行命令。对于这种方法，你只需要设置文件监视器。感谢 @patkujawa-wf 创建了此解决方案的原始灵感！

注意： 在设置监视器之前，使用它时存在三个基本限制：

1. dart_dev 的最低版本必须至少为 3.6.0。
2. 仅支持 dart_dev 的 FormatTool 和 OverReact Format 的 OverReactFormatTool。
3. 配置格式化器时尽可能使用字面量。这主要适用于格式化器工具本身及其负责行长度的属性。例如：

   // 正确
   final Map<String, DevTool> config = {
     // ...其他配置选项
     'format': FormatTool()
       ..formatter = Formatter.dartStyle
       ..formatterArgs = ['-l', '120'],
   };
   
   // 错误
   
   // 示例1：行长度作为变量
   const lineLength = 120;
   
   final Map<String, DevTool> config = {
     // ...其他配置选项
     'format': FormatTool()
       ..formatter = Formatter.dartStyle
       ..formatterArgs = ['-l', lineLength],
   };
   
   // 示例2：参数作为变量
   const formatterArgs = ['-l', '120'];
   
   final Map<String, DevTool> config = {
     // ...其他配置选项
     'format': FormatTool()
       ..formatter = Formatter.dartStyle
       ..formatterArgs = formatterArgs,
   };
   
   // 示例3：格式化器作为变量
   final formatter = FormatTool()
       ..formatter = Formatter.dartStyle
       ..formatterArgs = ['-l', '120'];
   
   final Map<String, DevTool> config = {
     // ...其他配置选项
     'format': formatter,
   };