跨平台开发 / 系统课时

制定文件和类命名规则

制定文件和类命名规则

当项目开始出现页面、状态、模型、服务和测试文件时,常见的维护成本不是代码写不出来,而是同一种职责被起了不同名字。本课给出一套可落地的 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,文件名、类型名和职责保持一致:

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));
}

在项目根目录运行:

bash
dart run lib/features/order/order_service.dart

预期输出:

text
已支付

如果后续为它增加测试,优先创建 test/features/order/order_service_test.dart,而不是 service_test.dart 或 order_test.dart,因为后两者无法稳定指向具体被测对象。

把命名规则变成团队约束

命名规则的重点是稳定,而不是追求唯一正确。团队至少应明确几条可执行约束:同一职责只选一个后缀;避免只有内部成员才懂的缩写;文件名与主类型保持语义对应;测试文件与被测文件保持可追踪关系。

代码评审时,如果一个新文件无法仅凭名称判断职责,应优先修改名称或重新划分职责。这样随着目录规模扩大,搜索和定位成本仍然可控,命名规则才真正发挥工程价值。

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

目录与阅读设置

阅读设置

17

记录一个想法

制定文件和类命名规则

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

登录哪都通