跨平台开发 / 系统课时
用 dart format 统一代码格式
用 dart format 统一代码格式
多人维护 Dart 项目时,缩进、换行和空格差异会制造大量无意义的代码审查噪声。dart format 用统一规则重写 Dart 源码,让团队把注意力放在行为变化上,并可在提交或 CI 阶段检查格式是否一致。
学习目标
- 使用
dart format格式化单个文件或整个目录 - 用只检查不改写的模式把格式要求接入质量门禁
- 区分自动格式化与静态分析各自负责的问题
format 解决的是一致性
dart format 负责源代码布局,例如空格、缩进、换行和表达式排版。它的目标不是让每个人保留自己的风格偏好,而是把同一份代码归一化成稳定格式。
它不会替代 dart analyze:未使用变量、类型问题、lint 规则和潜在错误仍由分析器处理。格式化也不会替你决定类名、目录结构或业务抽象,因此应把“格式”和“代码质量规则”分开管理。
执行格式化
片段示例:假设 lib/calculator.dart 当前内容如下,只用于观察格式变化。
int add(int a,int b){
return a+b;
}在项目根目录执行:
dart format lib/calculator.dart预期输出
Formatted lib/calculator.dart
Formatted 1 file (1 changed) in <TIME> seconds.<TIME> 是动态耗时,实际值可能不同。格式化后文件会变成:
int add(int a, int b) {
return a + b;
}如果要格式化当前目录及其子目录中的 Dart 文件,可以把路径换成 .。默认模式会直接写回文件,因此在大范围执行前应确保改动已由版本控制记录或可恢复。
在质量门禁中只检查不改写
CI 更适合检查格式,而不是替开发者自动修改仓库。-o none 让 formatter 不写回文件,--set-exit-if-changed 则在发现需要格式化的内容时返回非零退出码。
dart format -o none --set-exit-if-changed .预期结果
退出码 0:所有目标 Dart 文件都无需格式化。
退出码 1:至少一个目标 Dart 文件格式化后会发生变化。这样 CI 可以把退出码直接当作门禁条件。开发者本地先运行 dart format . 修正格式,再重新提交;CI 只负责验证仓库是否已经处于规范状态。
自动格式化的边界
不要通过手工补空格或对齐来“对抗” formatter,因为下一次格式化仍会按工具规则重排。团队更应该统一 Dart SDK 使用策略,避免不同环境反复产生仅由格式器版本差异带来的变更。
格式检查通过也不代表代码质量检查完成。一个常见的提交顺序是先运行 dart format .,再执行 dart analyze 与 dart test。前者消除排版差异,后两者分别检查静态问题和运行行为,三者职责清晰且可以独立失败。
当格式规则被工具自动执行后,代码审查就无需讨论缩进和换行偏好;真正需要人工判断的内容会回到命名、边界、可读性和行为正确性上。