dart-tooling

Dart 工具与包工作流

目录

• 静态分析问题处理
• 解决包冲突
• 将测试迁移到 package:checks

静态分析问题处理

使用以下顺序工作流，识别、修复并验证 Dart 项目中的静态分析错误。

1. 运行静态分析器：dart analyze . --fatal-infos
2. 应用自动修复：
   • dart fix --dry-run
   • dart fix --apply
3. 手动解决：处理 dart fix 无法自动解决的类型不匹配、空安全或无效重写问题。
4. 性能诊断：使用 Analysis Server 诊断页面（分析器运行时可通过 http://localhost:8082 访问）追踪并诊断分析耗时较长的问题。
5. 验证：确保 dart analyze . 和 dart test 均通过。

解决包冲突

当 pub get 因包版本不兼容而失败时，请采用以下系统化方法。

了解 dart pub outdated

列	含义
Current	当前 pubspec.lock 中的版本
Upgradable	pubspec.yaml 约束允许的最新版本
Resolvable	与所有其他依赖项一起可解析的最新版本
Latest	已发布的最新版本（忽略约束）

dart pub outdated

Git LFS 支持

在 Dart 3.12 中引入

• dart pub 包管理命令原生支持 Git Large File Storage（LFS）。从包含 LFS 对象（例如资源、二进制文件和模型）的 Git 仓库获取的依赖项会自动解析，无需本地配置。

版本约束最佳实践

• 使用插入符语法：始终使用 ^1.2.3，允许更新到下一个主版本之前的非破坏性版本。
• 收紧开发依赖项：为 dev_dependencies 设置与当前版本完全一致的下限。
• 确保 CI 可复现：在 CI 中使用 dart pub get --enforce-lockfile，确保使用经过测试的确切版本。

升级依赖项

如果更新到“Upgradable”版本：

dart pub upgrade
dart pub upgrade --tighten  # Auto-update lower bounds in pubspec.yaml

如果更新到“Resolvable”版本（主版本）：

1. 手动编辑 pubspec.yaml 以提高版本约束。
2. 运行 dart pub upgrade。
3. 运行 dart analyze → 修复不兼容的 API 变更。
4. 运行 dart test → 修复回归问题。

定向移除锁文件内容

切勿删除整个 pubspec.lock。这会导致依赖关系图中的依赖项不受控地升级。

应仅移除冲突包对应的区块：

1. 打开 pubspec.lock。
2. 找到并仅删除冲突包的 YAML 区块。
3. 运行 dart pub get：仅获取该包的最新兼容版本。
4. 验证：运行 dart pub deps → 检查依赖关系图是否正确解析。

临时覆盖（最后手段）

dependency_overrides:
  shared_package: ^x.y.z  # Remove once direct deps support newer version

将测试迁移到 package:checks

将测试断言从 package:matcher 语法迁移到 package:checks 提供的易读 API。

• 依赖项：通过 dart pub add dev:checks 添加 dev_dependency checks。
• 基本相等性： 将 expect(actual, equals(expected)) 替换为 check(actual).equals(expected)。
• 类型检查： 将 expect(actual, isA<Type>()) 替换为 check(actual).isA<Type>()。
• 异步期望：
  • await check(Future.value(10)).completes((it) => it.equals(10));
• 工作流：
  1. 添加 package:checks 并导入 package:checks/checks.dart。
  2. 将 expect() 调用改写为 check()。
  3. 运行静态分析器和测试进行验证。