跨平台开发 / 系统课时
制定文件和类命名规则
制定文件和类命名规则
当项目开始出现页面、状态、模型、服务和测试文件时,常见的维护成本不是代码写不出来,而是同一种职责被起了不同名字。本课给出一套可落地的 Flutter 命名规则,让文件名便于搜索、类名表达职责、测试文件能够快速对应被测对象。
学习目标
- 统一 Dart 文件、类型和测试文件的命名方式
- 用职责后缀快速判断页面、状态、模型和服务的角色
- 避免缩写、重复语义和同名文件造成的检索困难
先统一文件名与类型名
Dart 文件统一使用 lower_snake_case.dart,类型统一使用 UpperCamelCase。文件名优先描述“业务对象 + 职责”,而不是个人习惯或实现细节。
| 职责 | 文件名示例 | 类型名示例 |
|---|---|---|
| 页面 | order_detail_page.dart |
OrderDetailPage |
| 状态 | order_state.dart |
OrderState |
| 模型 | order.dart |
Order |
| 服务 | order_service.dart |
OrderService |
| 测试 | order_service_test.dart |
与被测对象对应 |
页面如果是完整路由入口,统一使用 Page;可复用的局部 UI 使用描述性组件名,如 OrderSummaryCard。不要同时混用 Screen、View、Page 表示同一种角色,否则搜索文件时仍然需要猜名字。
用职责后缀降低查找成本
职责后缀的价值是让文件列表本身就能传递结构信息。看到 *_service.dart,应当能预期其中封装业务调用或外部能力;看到 *_state.dart,应当能预期其中描述状态数据,而不是网络请求。
避免 utils.dart、common.dart、manager.dart 这类过宽名称。它们初期方便,后期容易变成无法判断边界的杂物箱。如果一个工具只负责订单金额格式化,order_price_formatter.dart 就比 utils.dart 更容易定位和维护。
让测试文件一眼找到被测对象
单元测试文件通常与被测文件保持同名,并追加 _test。例如 lib/features/order/order_service.dart 对应 test/features/order/order_service_test.dart。测试目录尽量镜像实现目录,这样从实现跳到测试时不需要重新猜路径。
下面的示例保存为 lib/features/order/order_service.dart,文件名、类型名和职责保持一致:
enum OrderStatus { pending, paid }
class OrderService {
String labelFor(OrderStatus status) {
// 让状态到展示文案的映射集中在服务职责内。
return switch (status) {
OrderStatus.pending => '待支付',
OrderStatus.paid => '已支付',
};
}
}
void main() {
final service = OrderService();
print(service.labelFor(OrderStatus.paid));
}在项目根目录运行:
dart run lib/features/order/order_service.dart预期输出:
已支付如果后续为它增加测试,优先创建 test/features/order/order_service_test.dart,而不是 service_test.dart 或 order_test.dart,因为后两者无法稳定指向具体被测对象。
把命名规则变成团队约束
命名规则的重点是稳定,而不是追求唯一正确。团队至少应明确几条可执行约束:同一职责只选一个后缀;避免只有内部成员才懂的缩写;文件名与主类型保持语义对应;测试文件与被测文件保持可追踪关系。
代码评审时,如果一个新文件无法仅凭名称判断职责,应优先修改名称或重新划分职责。这样随着目录规模扩大,搜索和定位成本仍然可控,命名规则才真正发挥工程价值。