【Flutter】APP 部门 Flutter 代码规范

👇🏻👇🏻👇🏻关于状态管理的最佳实践与避坑指南可以看这篇文章👇🏻👇🏻👇🏻
🔥🔥🔥 【Flutter】GetX最佳实践与避坑指南 🔥🔥🔥

1. 总体原则

• 可读性第一：写给人看的代码，其次才是机器。变量、方法、类的命名要表达清晰含义。
• 一致性：团队成员必须遵循统一的代码风格，避免风格冲突。
• 可维护性：尽量模块化、减少重复代码，优先可维护性高于短期开发效率。
• 性能意识：注意 Obx、ListView、TabBar、Image 等性能敏感点，避免不必要的 rebuild。
• 项目框架：APP架构设计与代码规范 【这里面是内部文档，就不给大家共享了，但是可以共享之前我写的《【钱包】WEB3钱包APP框架的设计》】

---

2. 命名规范

2.1 文件命名

• 文件一律使用 小写+下划线，例如：

  • ✅ utures_account_page.dart
  • ✅ anycoin_buttons_view.dart

2.2 类命名

• 类名使用 大驼峰 (PascalCase)：

  • ✅ FuturesAccountPage
  • ✅ AnyCoinButtonsView
  • ❌ futuresaccountpage

2.3 方法命名

• 方法名使用 小驼峰 (camelCase)：

  • ✅ onRefresh(), buildOverviewAssets()
  • ❌ On_Refresh()

2.4 变量命名

• 使用 语义化命名，避免无意义缩写：

  • ✅ financeController, searchKeyword
  • ❌ fc, skw

2.5 常量命名

• 常量和枚举使用 大写下划线：

  • ✅ static const String path = 'futures_account_overview';
  • ✅ enum AnyCoinButtonsViewType { normal, futures }

---

3. 布局与样式规范

3.1 Widget 树层级

• Widget 树层级不超过 4 层嵌套，超出时必须拆分成独立组件。

  // ❌ 层级过深
  Column(
    children: [
      Row(
        children: [
          Expanded(
            child: GestureDetector(
              child: Container(...),
            ),
          )
        ],
      )
    ],
  );
  
  // ✅ 拆分为独立 Widget
  class ActionButton extends StatelessWidget { ... }
  

3.2 Padding / Margin

• 使用统一的间距变量（如 pt4, pt16），保持全局一致。

3.3 文本样式

• 所有文字必须使用 themeData.colors 中的样式，禁止直接写死 TextStyle。

• 禁止写死颜色值，例如：

  • ❌ TextStyle(color: Colors.red)
  • ✅ themeData.colors.textPrimary.textRegular14

---

4. 控制器与状态管理

👇🏻👇🏻👇🏻关于状态管理的最佳实践与避坑指南可以看这篇文章👇🏻👇🏻👇🏻
🔥🔥🔥 【Flutter】GetX最佳实践与避坑指南 🔥🔥🔥

4.1 GetX 控制器

• 控制器必须通过 XGet.find<T>() 获取，禁止手动 new。

• 控制器内方法命名必须体现语义：

  • ✅ onClickDeposit()
  • ✅ toggleHideMoney()
  • ❌ do1()

4.2 Obx 使用

• Obx 仅包裹 需要响应式更新的最小单元，禁止整页包裹。
• 复杂计算逻辑放到 Controller 中处理，UI 层只负责展示。

---

5. 组件开发规范

5.1 可复用性

• 公用组件必须抽到 views/ 或 widgets/ 文件夹。
• 组件必须可配置，禁止写死逻辑。

5.2 按钮组件

• 所有按钮必须统一为 GestureDetector / InkWell 包裹。

• 点击回调必须判空：

  if (onPressed != null) onPressed!();
  

5.3 图片加载

• 使用 ImageLoader 封装，必须提供 placeholder 和 errorBuilder。
• 禁止直接使用 Image.network。

---

6. 文案与多语言规范

• 所有文案必须走 i18n.t，禁止写死字符串：

  • ❌ "Deposit"
  • ✅ t('deposit', defaultValue: 'Deposit')

• defaultValue 必须有，防止 key 缺失报错。

---

7. 代码风格细节

7.1 import 顺序

• 按以下顺序分组，组之间空一行：

  1. Dart/Flutter 官方包
  2. 第三方依赖包
  3. 本项目内包

  import 'dart:async';
  import 'package:flutter/material.dart';
  
  import 'package:get/get.dart';
  
  import 'package:finance/src/assets/views/asset_header.dart';
  

7.2 注释

• 类、方法必须写 文档注释：

  /// Futures Account 概览页面
  class FuturesAccountPage extends StatelessWidget { ... }
  

7.3 函数长度

• 函数不超过 80 行，否则必须拆分。

7.4 空行与排版

• 逻辑块之间用 空行分隔。
• 禁止连续多余空行。

---

8. 性能优化建议

• 尽量用 const 修饰 静态 Widget，减少 rebuild。
• 图片资源本地化时统一放 assets/，并在 pubspec.yaml 声明。
• 长列表使用 SliverList 或 ListView.builder，禁止一次性渲染。

---

9. 错误处理与安全性

• 所有回调必须判空 (onTap?() 或 if != null)。
• 金额类必须使用 AmountText 组件，禁止直接拼接字符串。
• 所有网络/异步调用必须带 try/catch。

---

10. 代码评审要求

• 每个 PR 必须通过 lint 检查。

• 必须有至少 1 名同事 review。

• review 时主要关注：

  1. 命名是否语义化
  2. 是否存在重复代码
  3. Obx 使用是否合理
  4. UI 层是否有业务逻辑（不允许）

---

11.日志与调试

• 禁止 print，统一 LoggerUtil。
• 禁止记录用户的敏感信息，所有上传的日志必须脱敏。
• 日志必须带上下文：

LoggerUtil.i(msg: 'Deposit click', params: {'coin': coin});

---

12.安全性规范

• 禁止写死秘钥/私有 URL。
• 金额使用 BigInt/Decimal，禁止 double。
• 表单输入必须校验，禁止信任用户输入。

---

13.文档与知识库

• 每个模块必须有 README.md，说明功能、依赖、调用方式。
• Wiki 记录：常见 Bug、模块依赖图、规范更新历史。

---

🔥 最终目标：

• 让 APP 部门所有代码看起来像是一个人写的。
• 统一的代码规范，减少后期维护成本。
• 保证代码可读性、健壮性和可扩展性。

---

📌 关于作者(ZFJ_张福杰)

• 官网：https://zfjsafe.com
• 博客：https://zfj1128.blog.csdn.net
• Github：https://github.com/zfjsyqk
• Gitee：https://gitee.com/zfj1128
• 打赏：https://zfjsafe.com/paycode

---