Flutter 企业级规范总结（命名+目录+代码+工程化）

Flutter 企业级规范总结（命名+目录+代码+工程化）

本文档整合 Flutter 官方规范+企业实际落地标准，涵盖命名、目录、代码、工程化核心要求，统一开发标准、提升协作效率，适配日常开发、团队协作及上线交付，与前端工程化规范对齐，易记、易落地。

一、核心命名规范（官方强制+企业通用）

核心原则：统一风格、语义清晰、避免歧义，严禁中文、拼音、杂乱符号，优先遵循 Dart 官方规范，与第三方库不规范写法区分开。

1. 类名 / 枚举 / 结构体 / Widget

✅ 规范：大驼峰（UpperCamelCase），每个单词首字母大写，无下划线、无小写开头

✅ 示例：

• 页面类：HomePage、LoginPage、UserCenterPage

• 组件类：LoadingWidget、UserItem、CustomButton

• 模型类：PostItem、UserInfo、OrderModel

• 枚举类：Status、LoginType

❌ 错误：homePage、post\_item、Loginpage、登陆页面

2. 变量 / 方法 / 参数

✅ 规范：小驼峰（lowerCamelCase），第一个单词小写，后续单词首字母大写，无下划线

✅ 示例：

• 变量：userId、userName、isLoading、apiUrl

• 方法：fetchData、getUserInfo、showLoading

• 参数：context、userId、onTap

❌ 错误：UserId、user\_name、get\_user\_info

3. 常量 / 静态常量

✅ 规范：小驼峰（lowerCamelCase）（Dart 2+ 官方推荐，放弃旧版全大写写法）

✅ 示例：const int maxCount = 10;、const String baseUrl = \&\#34;https://xxx\&\#34;;

❌ 错误：const int MAX\_COUNT = 10;、const String BASE\_URL = \&\#34;https://xxx\&\#34;;

4. 文件命名

✅ 规范：小写 + 下划线（snake_case），语义与类名对应，后缀为\.dart

✅ 示例（与类名对应）：

• home\_page\.dart→ 对应类HomePage

• user\_item\.dart→ 对应类UserItem

• post\_model\.dart→ 对应类PostModel

• http\_util\.dart→ 对应类HttpUtil

❌ 错误：HomePage\.dart、userInfo\.dart、login\-page\.dart

5. 文件夹命名

✅ 规范：小写 + 下划线（snake_case），按功能划分，不嵌套过深（最多3层）

✅ 示例：pages、widgets、models、api、utils

❌ 错误：Pages、Widgets、userCenter

二、标准目录结构规范（工程化落地版）

核心原则：功能分区清晰、可扩展、可维护，适配小中型项目到大型项目，与前端工程化目录对齐，便于团队协作和后期迭代。

✅ 标准目录结构（lib 目录下，最常用、最通用）：

lib/ ├── main.dart # 入口文件（唯一入口） ├── pages/ # 页面目录（所有页面存放） │ ├── home/ # 首页模块（单个页面单独建文件夹，存放页面及私有组件） │ │ ├── home_page.dart # 首页主文件 │ │ └── widgets/ # 首页私有组件（仅首页使用） │ ├── login/ # 登录模块 │ │ └── login_page.dart │ └── user/ # 用户模块 │ ├── user_center_page.dart │ └── user_detail_page.dart ├── widgets/ # 公共组件目录（全项目复用） │ ├── loading_widget.dart │ ├── custom_button.dart │ └── user_item.dart ├── models/ # 数据模型目录（接口JSON转模型） │ ├── post_model.dart │ ├── user_model.dart │ └── base_model.dart # 基础模型（统一处理JSON解析） ├── api/ # 接口请求目录（统一管理接口） │ ├── api_service.dart # 接口服务（统一请求拦截、配置） │ ├── home_api.dart # 首页接口 │ └── user_api.dart # 用户接口 ├── router/ # 路由目录（统一管理路由） │ └── app_router.dart # 路由配置（go_router 推荐） ├── utils/ # 工具类目录（通用工具） │ ├── http_util.dart # 网络工具 │ ├── storage_util.dart # 本地存储工具 │ └── format_util.dart # 格式化工具（时间、字符串等） ├── assets/ # 静态资源目录（图片、字体、音频等） │ ├── images/ # 图片资源 │ └── fonts/ # 字体资源 └── config/ # 配置目录（全局配置） ├── app_config.dart # 应用配置（版本、环境等） └── constants.dart # 全局常量（接口地址、固定参数等）

目录规范补充：

• 单个页面单独建文件夹（如home/），避免单个文件代码过多（不超过500行）。

• 私有组件（仅单个页面使用）放在页面文件夹下的widgets/，公共组件放在根目录widgets/。

• 接口按模块划分（如home\_api\.dart），统一由api\_service\.dart管理请求拦截、异常处理。

• 静态资源按类型划分（图片、字体），避免杂乱堆放。

三、核心代码规范（官方推荐+企业落地）

1. 基础代码规范

• 缩进：统一 4 空格（或 2 空格，团队统一即可），禁止混合缩进。

• 语句：末尾不加分号（Dart 官方推荐，非强制，但团队需统一）。

• 字符串：优先使用单引号\&\#39;\&\#39;，复杂字符串使用三引号\&\#39;\&\#39;\&\#39; \&\#39;\&\#39;\&\#39;。

• 空行：方法之间、类之间留 1 空行，逻辑块之间留 1 空行，避免过多空行。

• 注释：关键逻辑、复杂方法必须加注释，类和公共方法加文档注释（/// 开头）。

2. Widget 开发规范

• 页面 Widget 统一继承StatelessWidget（无状态）或StatefulWidget（有状态），命名后缀为Page。

• 公共组件命名后缀为Widget（如LoadingWidget），优先封装为无状态组件，减少状态冗余。

• 布局嵌套不超过 4 层，复杂布局拆分多个小 Widget，避免嵌套过深导致卡顿和维护困难。

• 状态管理：简单状态用setState，复杂状态用Provider/GetX，避免全局状态滥用。

3. 模型类规范（JSON 转对象）

• 模型类命名后缀为Model或直接用业务名称（如PostItem）。

• JSON 转对象必须使用factory fromJson（Dart 官方规范），禁止用 static 方法。

• 字段与接口 JSON 字段一致，类型明确，避免 dynamic 类型滥用。

• 示例（标准模型类）：

classPostItem{finalint userId;finalint id;finalStringtitle;finalStringbody;// 构造函数（required 必传参数）PostItem({requiredthis.userId,requiredthis.id,requiredthis.title,requiredthis.body,});// 官方规范：JSON 转对象，必须用 factoryfactoryPostItem.fromJson(Map<String,dynamic>json){returnPostItem(userId:json['userId']??0,// 避免空值报错id:json['id']??0,title:json['title']??'',body:json['body']??'',);}}

4. 路由规范

• 正式项目必须使用go\_router（Flutter 官方推荐），统一管理路由，禁止分散使用Navigator\.push。

• 路由路径使用小写 + 斜杠（如/home、/login），与页面文件夹对应。

• 路由守卫：加载页、登录拦截统一用redirect配置，实现“加载完成再跳首页”等场景。

四、工程化配套规范（团队协作必备）

1. Git 规范

• 分支命名：main（生产环境）、dev（开发环境）、feature/xxx（功能开发）、bugfix/xxx（bug修复）。

• Commit 格式（强制）：

  • feat: 添加首页功能（新增功能）

  • fix: 修复列表接口报错（修复bug）

  • style: 格式化代码（代码格式调整，不改变逻辑）

  • refactor: 重构首页布局（代码重构，不新增功能、不修复bug）

  • docs: 修改规范文档（文档修改）

2. 工具配套规范

• 代码检查：使用ESLint（Dart 版），拦截不规范代码。

• 自动格式化：使用Prettier，统一代码格式。

• 依赖管理：pubspec\.yaml依赖版本固定，避免版本冲突，新增依赖需团队确认。

• 打包规范：release 模式关闭混淆（minifyEnabled false），保证稳定性。

五、常见误区 & 注意事项

• 误区1：模仿第三方库的小驼峰类名 → 第三方库多为历史遗留问题，自身代码必须遵循大驼峰类名规范。

• 误区2：文件命名用大驼峰或小驼峰 → 必须用小写+下划线，避免跨系统（Windows/macOS）报错。

• 误区3：JSON 转对象用 static fromJson → 违反 Dart 官方规范，必须用 factory fromJson。

• 注意事项：团队必须统一规范，避免“各自为政”；新增规范需同步给所有成员，定期检查代码规范。

六、终极总结（必背核心）

1. 命名：类名大驼峰、变量/方法小驼峰、文件/文件夹小写+下划线；

2. 目录：按功能分区（pages/widgets/models/api），单个页面单独建文件夹；

3. 代码：Widget 拆分合理、模型用 factory fromJson、路由用 go_router；

4. 工程化：Git 规范、工具配套，统一标准，提升协作效率和代码可维护性。