290 lines
13 KiB
Markdown
290 lines
13 KiB
Markdown
# 14. 工程规范与 CI 门禁
|
||
|
||
## 为什么单独一篇
|
||
|
||
这一篇是**建项目当天就要用上**的东西：lint 配置、格式化、生成产物是否入库、分支和提交规范、CI 卡什么。这些规则本身不难，难的是"没有在第一天定下来"——等到有 10 个人各写各的风格再统一，成本是第一天的几十倍。
|
||
|
||
## 一、SDK 版本锁定
|
||
|
||
```
|
||
# .fvmrc（仓库根目录，入库）
|
||
{ "flutter": "3.44.9" }
|
||
```
|
||
|
||
所有人用 [FVM](https://fvm.app/) 装同一个版本，命令统一走 `fvm flutter ...`。理由见 [01-project-structure.md](./01-project-structure.md)：monorepo 里 SDK 版本不一致会导致 `.dart_tool` 反复重建、生成代码差异、以及"我这跑得好好的"这类无法复现的问题。CI 也用 FVM 装同一版本，保证本地和 CI 完全一致。
|
||
|
||
`flutter --version` 的实测 Dart 版本要写进 README，因为 `environment.sdk` 的约束以它为准。
|
||
|
||
## 二、静态分析
|
||
|
||
### 选 `flutter_lints`，不选 `very_good_analysis`
|
||
|
||
| | `flutter_lints` 6.0.0 | `very_good_analysis` 10.3.0 |
|
||
|---|---|---|
|
||
| 维护方 | **Flutter 官方** | Very Good Ventures |
|
||
| 规则数量 | 适中，只收官方认为普遍适用的 | 非常多，包含大量风格约束 |
|
||
| 跟随 SDK | 随 Flutter 版本同步更新 | 独立节奏 |
|
||
|
||
`very_good_analysis` 更严格，但它在一个新项目上开箱会产生**成百上千条 warning**，其中很大一部分是纯风格问题（比如强制所有 public API 写文档注释、强制 `final` 局部变量）。团队的第一反应必然是批量 `// ignore:` 或者在 `analysis_options.yaml` 里关掉一半规则——最后既没享受到严格的好处，还多了一层配置负担。
|
||
|
||
**结论：以 `flutter_lints` 为底，手动加一小组"能抓真 bug"的规则，而不是"管风格"的规则。**
|
||
|
||
### 根级共享配置
|
||
|
||
```yaml
|
||
# analysis_options.yaml（仓库根目录）
|
||
include: package:flutter_lints/flutter.yaml
|
||
|
||
analyzer:
|
||
language:
|
||
strict-casts: true # 禁止 dynamic 隐式转型——最容易藏 bug 的一条
|
||
strict-raw-types: true # 禁止裸 List/Map，逼着写类型参数
|
||
strict-inference: true
|
||
errors:
|
||
invalid_annotation_target: ignore # json_serializable + 注解组合会误报
|
||
# 下面几条从 warning 提到 error，即 CI 直接失败
|
||
unused_import: error
|
||
dead_code: error
|
||
unawaited_futures: error
|
||
exclude:
|
||
- "**/*.g.dart"
|
||
- "**/*.freezed.dart"
|
||
- "**/generated/**" # pigeon 生成产物，见 07
|
||
plugins:
|
||
- custom_lint # riverpod_lint，见 03
|
||
|
||
formatter:
|
||
page_width: 100
|
||
|
||
linter:
|
||
rules:
|
||
# —— 能抓真 bug 的 ——
|
||
- always_declare_return_types
|
||
- avoid_dynamic_calls
|
||
- avoid_slow_async_io
|
||
- cancel_subscriptions # StreamSubscription 忘了 cancel 是常见内存泄漏
|
||
- close_sinks
|
||
- discarded_futures # 忘了 await 的异步调用
|
||
- unawaited_futures
|
||
- no_adjacent_strings_in_list # 少写一个逗号导致字符串被拼接
|
||
- test_types_in_equals
|
||
- throw_in_finally
|
||
- unnecessary_statements
|
||
# —— 团队约定 ——
|
||
- prefer_single_quotes
|
||
- require_trailing_commas # 配合 formatter，diff 更干净
|
||
- directives_ordering
|
||
- sort_pub_dependencies
|
||
```
|
||
|
||
各包的 `analysis_options.yaml` 只写一行继承，不允许在包级关规则（要关就在根上关，让所有人都看得见）：
|
||
|
||
```yaml
|
||
# packages/feature_xxx/analysis_options.yaml
|
||
include: ../../analysis_options.yaml
|
||
```
|
||
|
||
### `strict-casts` 值得单独说
|
||
|
||
它是这份配置里**唯一一条会真的挡住线上 bug** 的开关。没有它，`jsonDecode(...)` 返回的 `dynamic` 可以隐式赋给任何类型，类型错误要到运行时才炸；开了之后必须显式 `as Map<String, dynamic>`，写的人会被迫想一下"这里到底是什么类型"。
|
||
|
||
代价是接手 JSON 解析时要多写一些 `as`。这个代价值得付。
|
||
|
||
### `custom_lint` 在 workspace 下的接法
|
||
|
||
`riverpod_lint`（见 [03-state-management.md](./03-state-management.md)）通过 `custom_lint` 插件运行。在 pub workspace 下：
|
||
|
||
- `custom_lint` 和 `riverpod_lint` 加在**根 `pubspec.yaml` 的 `dev_dependencies`**（workspace 共享）。
|
||
- 检查命令是 `dart run custom_lint`，**它不包含在 `flutter analyze` 里**——两条命令都要跑，CI 里是两个独立步骤。这一点很多人不知道，结果 riverpod_lint 装了但从来没生效过。
|
||
|
||
## 三、格式化
|
||
|
||
```bash
|
||
dart format --set-exit-if-changed --line-length 100 .
|
||
```
|
||
|
||
- **行宽 100，不是默认的 80。** Dart 3.9 起可以写在 `analysis_options.yaml` 的 `formatter: page_width:` 里（上面已配），命令行参数是给 CI 用的双保险。80 在 Flutter 的 widget 嵌套下换行过于频繁，一个三层嵌套的 `Column` 就能占满整屏。100 是一个在宽屏和可读性之间比较平衡的值。
|
||
- **不允许手动排版**。`dart format` 的结果就是唯一正确的结果，不接受"我觉得这样更好看"。省下的是每次 review 里关于换行的争论。
|
||
- CI 用 `--set-exit-if-changed` 卡死。
|
||
|
||
## 四、生成产物是否入库
|
||
|
||
**这是一个必须明确的二选一，模糊处理会导致仓库里一半入库一半不入库。**
|
||
|
||
| 类型 | 结论 | 理由 |
|
||
|---|---|---|
|
||
| `*.g.dart`（riverpod / json_serializable / drift） | **不入库** | 这类文件改动频繁且巨大，几乎每个 PR 都会产生冲突，而冲突的正确解法永远是"重新生成"——那入库就没有意义。加进 `.gitignore` |
|
||
| pigeon 生成产物（Dart + Kotlin + Swift） | **入库** | 见 [07-native-integration.md](./07-native-integration.md)。原生侧的 Kotlin/Swift 文件要被 Gradle/Xcode 编译，而**这两条工具链不会跑 `build_runner`**。不入库的话原生构建直接失败 |
|
||
| `pubspec.lock` | 根目录**入库**，各 package 的**不入库** | workspace 模式下只有根 lock 生效 |
|
||
|
||
不入库 `.g.dart` 的代价是：**新克隆仓库后必须先跑一次生成，否则 IDE 满屏报错**。所以：
|
||
|
||
```yaml
|
||
# 根 pubspec.yaml 的 melos scripts
|
||
gen:
|
||
run: melos exec --depends-on=build_runner -- dart run build_runner build --delete-conflicting-outputs
|
||
gen:watch:
|
||
run: melos exec --depends-on=build_runner -- dart run build_runner watch --delete-conflicting-outputs
|
||
```
|
||
|
||
README 的"第一次跑起来"步骤必须是：`fvm flutter pub get` → `melos run gen` → `fvm flutter run`。**少写这一步，每个新人入职第一天都会卡住。**
|
||
|
||
CI 在 analyze 之前必须先 `melos run gen`。
|
||
|
||
**pigeon 产物入库需要一道防腐**：CI 里重新生成后 `git diff --exit-code`，确保有人改了 schema 但忘了提交生成结果时流水线会红（见 07）。
|
||
|
||
## 五、分支与提交
|
||
|
||
### 分支
|
||
|
||
```
|
||
main ← 生产，只接受来自 release/* 和 hotfix/* 的合并，打 tag 出包
|
||
develop ← 集成，日常合并目标
|
||
feature/<jira-id>-<短描述>
|
||
fix/<jira-id>-<短描述>
|
||
release/<version>
|
||
hotfix/<version>
|
||
```
|
||
|
||
`main`/`develop` **保护分支，禁止直接 push**，只能通过 MR 合入。
|
||
|
||
### 提交信息
|
||
|
||
用 [Conventional Commits](https://www.conventionalcommits.org/)：
|
||
|
||
```
|
||
feat(feature_purchase): 支持采购单批量提交
|
||
fix(core_network): 修复 401 并发刷新导致全端登出
|
||
docs(05): 补充上传失败重传约定
|
||
chore(deps): 升级 drift 到 2.34.5
|
||
```
|
||
|
||
`scope` 用**包名**（`feature_purchase`、`core_network`）或文档编号。monorepo 里没有 scope 的提交信息基本等于没有信息——`fix: 修复崩溃` 在半年后完全无法定位。
|
||
|
||
不引入自动化的 changelog 生成（首版没这个需求），但格式先立住，将来要加成本为零。
|
||
|
||
### MR 规范
|
||
|
||
- MR 标题同 commit 规范。
|
||
- 描述里必须有：**改了什么**、**为什么**、**怎么验证的**。
|
||
- **一个 MR 只做一件事。** 顺手格式化半个仓库的 MR 直接打回——它会让 review 变成不可能。
|
||
- 至少 1 人 approve。涉及 `core_*` 的改动需要 2 人（这些包被所有 feature 依赖，改错影响面最大）。
|
||
|
||
## 六、CI 门禁
|
||
|
||
```yaml
|
||
# .gitlab-ci.yml（App 部分，与 08-build-flavors.md 的构建 job 拼在一起）
|
||
stages: [setup, verify, test, build]
|
||
|
||
.flutter_base: &flutter_base
|
||
image: <内部 flutter 镜像，预装 FVM 3.44.9>
|
||
before_script:
|
||
- fvm flutter --version
|
||
- dart pub global activate melos 8.2.2
|
||
- melos bootstrap
|
||
- melos run gen # 生成产物不入库，必须先生成
|
||
cache:
|
||
key: "$CI_COMMIT_REF_SLUG"
|
||
paths: [.dart_tool/, .pub-cache/]
|
||
|
||
format:
|
||
<<: *flutter_base
|
||
stage: verify
|
||
script: dart format --set-exit-if-changed --line-length 100 .
|
||
|
||
analyze:
|
||
<<: *flutter_base
|
||
stage: verify
|
||
script:
|
||
- melos exec -- fvm flutter analyze --fatal-infos
|
||
- dart run custom_lint # riverpod_lint，analyze 不含它
|
||
|
||
pigeon_check:
|
||
<<: *flutter_base
|
||
stage: verify
|
||
script:
|
||
- melos run gen:pigeon
|
||
- git diff --exit-code || (echo "pigeon 生成产物未提交" && exit 1)
|
||
|
||
test:
|
||
<<: *flutter_base
|
||
stage: test
|
||
script:
|
||
- melos run test
|
||
- melos run coverage # 阈值 60%，见 09
|
||
coverage: '/lines\.*: \d+\.\d+\%/'
|
||
artifacts:
|
||
paths: [coverage/]
|
||
reports: { coverage_report: { coverage_format: cobertura, path: coverage/cobertura.xml } }
|
||
```
|
||
|
||
### 门禁清单
|
||
|
||
| 检查 | 卡点 | 说明 |
|
||
|---|---|---|
|
||
| `dart format` | **阻断** | |
|
||
| `flutter analyze --fatal-infos` | **阻断** | `--fatal-infos` 让 info 级别也算失败，否则 lint 规则形同虚设 |
|
||
| `dart run custom_lint` | **阻断** | |
|
||
| pigeon 产物一致性 | **阻断** | |
|
||
| 单元测试 + Widget 测试 | **阻断** | |
|
||
| 覆盖率 ≥ 60% | **阻断** | 见 [09-testing.md](./09-testing.md) |
|
||
| 集成测试 | **不卡 MR**，只在合入 develop/main 时跑 | 慢，见 09 |
|
||
| Android release 构建 | 只在 tag 上跑 | 见 [08-build-flavors.md](./08-build-flavors.md) |
|
||
|
||
`--fatal-infos` 值得强调：不加这个参数，`flutter analyze` 对 info 级别的问题只是打印一下就返回 0，CI 永远绿。半年后仓库里会积累几百条 info，然后没人再看 analyze 的输出。
|
||
|
||
### 关于 `melos bootstrap` 的缓存
|
||
|
||
`.pub-cache` 必须缓存，否则每次 CI 都要重新下载所有依赖，一个 monorepo 下来是几分钟。缓存 key 用 `$CI_COMMIT_REF_SLUG`（按分支），并配一个按 `pubspec.yaml` 哈希的 fallback key。
|
||
|
||
## 七、本地钩子（可选但推荐）
|
||
|
||
```yaml
|
||
# lefthook.yml
|
||
pre-commit:
|
||
parallel: true
|
||
commands:
|
||
format:
|
||
glob: "*.dart"
|
||
run: dart format --line-length 100 {staged_files} && git add {staged_files}
|
||
analyze:
|
||
glob: "*.dart"
|
||
run: fvm flutter analyze --fatal-infos {staged_files}
|
||
```
|
||
|
||
**只跑 format 和 analyze，不跑测试。** pre-commit 跑测试会让每次提交等几十秒，人的第一反应是 `--no-verify`，钩子就废了。测试留给 CI。
|
||
|
||
钩子是**建议不是强制**——CI 才是真正的门禁。钩子的价值只是让人少推一次红色流水线。
|
||
|
||
## 八、目录与命名速查
|
||
|
||
| 项 | 约定 |
|
||
|---|---|
|
||
| 包名 / 目录 / 文件 | `snake_case` |
|
||
| 类 / enum | `UpperCamelCase` |
|
||
| 变量 / 方法 | `lowerCamelCase`，私有加 `_` |
|
||
| 常量 | `lowerCamelCase`（Dart 惯例，不是 `SCREAMING_CASE`） |
|
||
| 文件名 | 与主类名对应：`OrderListPage` → `order_list_page.dart` |
|
||
| provider | `xxxProvider`，由 `@riverpod` 生成，不手写 |
|
||
| 测试文件 | `<被测文件>_test.dart`，目录镜像 `lib/src/` |
|
||
| 包的公共 API | 只从 `lib/<package>.dart` 导出，`lib/src/` 下的一律视为私有（见 01） |
|
||
|
||
import 顺序由 `directives_ordering` 强制：`dart:` → `package:`（外部）→ `package:`（本仓库）→ 相对路径。
|
||
|
||
**包内用相对路径 import，跨包用 `package:`。** 混用会导致同一个类被 Dart 认为是两个不同的类型（典型症状：`type 'X' is not a subtype of type 'X'`），这个错误看起来完全不可理喻，实际就是 import 路径不一致。
|
||
|
||
## 待确认项
|
||
|
||
- GitLab Runner 上是否已有可用的 Flutter 镜像，还是需要自建（与 [08-build-flavors.md](./08-build-flavors.md) 的 runner 问题一起解决）。
|
||
- JIRA（或其他）issue key 的格式，用于分支和提交信息里的 `<jira-id>`。
|
||
- 是否引入 lefthook（需要每个人本地 `lefthook install` 一次）。
|
||
|
||
## 参考链接
|
||
|
||
- [flutter_lints | Dart package](https://pub.dev/packages/flutter_lints)
|
||
- [Dart: Customizing static analysis](https://dart.dev/tools/analysis)
|
||
- [Dart linter rules 全量列表](https://dart.dev/tools/linter-rules)
|
||
- [FVM 官方文档](https://fvm.app/)
|
||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||
- [Melos 官方文档](https://melos.invertase.dev/)
|