跨平台开发 / 系统课时

用 dart format 统一代码格式

用 dart format 统一代码格式

多人维护 Dart 项目时,缩进、换行和空格差异会制造大量无意义的代码审查噪声。dart format 用统一规则重写 Dart 源码,让团队把注意力放在行为变化上,并可在提交或 CI 阶段检查格式是否一致。

学习目标

  • 使用 dart format 格式化单个文件或整个目录
  • 用只检查不改写的模式把格式要求接入质量门禁
  • 区分自动格式化与静态分析各自负责的问题

format 解决的是一致性

dart format 负责源代码布局,例如空格、缩进、换行和表达式排版。它的目标不是让每个人保留自己的风格偏好,而是把同一份代码归一化成稳定格式。

它不会替代 dart analyze:未使用变量、类型问题、lint 规则和潜在错误仍由分析器处理。格式化也不会替你决定类名、目录结构或业务抽象,因此应把“格式”和“代码质量规则”分开管理。

执行格式化

片段示例:假设 lib/calculator.dart 当前内容如下,只用于观察格式变化。

dart
int add(int a,int b){
return a+b;
}

在项目根目录执行:

bash
dart format lib/calculator.dart

预期输出

text
Formatted lib/calculator.dart
Formatted 1 file (1 changed) in <TIME> seconds.

<TIME> 是动态耗时,实际值可能不同。格式化后文件会变成:

dart
int add(int a, int b) {
  return a + b;
}

如果要格式化当前目录及其子目录中的 Dart 文件,可以把路径换成 .。默认模式会直接写回文件,因此在大范围执行前应确保改动已由版本控制记录或可恢复。

在质量门禁中只检查不改写

CI 更适合检查格式,而不是替开发者自动修改仓库。-o none 让 formatter 不写回文件,--set-exit-if-changed 则在发现需要格式化的内容时返回非零退出码。

bash
dart format -o none --set-exit-if-changed .

预期结果

text
退出码 0:所有目标 Dart 文件都无需格式化。
退出码 1:至少一个目标 Dart 文件格式化后会发生变化。

这样 CI 可以把退出码直接当作门禁条件。开发者本地先运行 dart format . 修正格式,再重新提交;CI 只负责验证仓库是否已经处于规范状态。

自动格式化的边界

不要通过手工补空格或对齐来“对抗” formatter,因为下一次格式化仍会按工具规则重排。团队更应该统一 Dart SDK 使用策略,避免不同环境反复产生仅由格式器版本差异带来的变更。

格式检查通过也不代表代码质量检查完成。一个常见的提交顺序是先运行 dart format .,再执行 dart analyze 与 dart test。前者消除排版差异,后两者分别检查静态问题和运行行为,三者职责清晰且可以独立失败。

当格式规则被工具自动执行后,代码审查就无需讨论缩进和换行偏好;真正需要人工判断的内容会回到命名、边界、可读性和行为正确性上。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 dart format 统一代码格式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通