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 层嵌套，超出时必须拆分成独立组件。

// ❌ 层级过深
 

// ✅ 拆分为独立 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!();
AI运行代码
dart
1
5.3 图片加载
使用 ImageLoader 封装，必须提供 placeholder 和 errorBuilder。
禁止直接使用 Image.network。
6. 文案与多语言规范
所有文案必须走 i18n.t，禁止写死字符串：

❌ "Deposit"
✅ t('deposit', defaultValue: 'Deposit')
defaultValue 必须有，防止 key 缺失报错。

7. 代码风格细节
7.1 import 顺序
按以下顺序分组，组之间空一行：

Dart/Flutter 官方包
第三方依赖包
本项目内包
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 { ... }
AI运行代码
dart
1
2
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 时主要关注：

命名是否语义化
是否存在重复代码
Obx 使用是否合理
UI 层是否有业务逻辑（不允许）
11.日志与调试
禁止 print，统一 LoggerUtil。
禁止记录用户的敏感信息，所有上传的日志必须脱敏。
日志必须带上下文：
LoggerUtil.i(msg: 'Deposit click', params: {'coin': coin});
AI运行代码
dart
1
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