4.0.1

一、版本定位

4.0.1 是一次文档与模板质量的优化发布，聚焦三份功能模块砖的 data_sources 目录说明完善，以及一处 Mason 变量渲染 bug 的修复。4.0.0 已完成 Dart 3.13 与 BlocAwaitMixin 的全面对齐，本版本在既有架构上做「补课」：让 feature / feature_bloc / feature_cubit 三份砖生成的数据源 README 对初学者更友好，并修正生成后 README 中类名占位符被错误渲染为空的问题。模板其余 Dart 代码、依赖与架构均保持不变。

---

二、核心亮点

• data_sources 目录文档增强：三份 feature 系列砖的 data_sources/README.md 各新增两节（+105 行），内容一致：
  • 「何时需要填充本目录」：明确空目录是正常占位、并非漏写文件；给出三类触发条件——后端未就绪（先 接口 + _fake + _remote 三元组，就绪后切 remote）、含本地存储（纯 local 场景无需抽象接口与 fake）、Repository 含编排逻辑（缓存优先 / 远程兜底 / 多源合并）；并提示 fake 接缝也可直接落在 Repository 层（FakeXxxRepository 更简单），仅当需测试 Repository 编排逻辑时才下沉到本目录。
  • 「最小示例（编写 / 注册 / 引用）」：以中性的「分页拉取用户列表」为例，演示「数据源 → 仓储」完整链路——抽象接口 XxxUserDataSource + 远程实现 XxxUserRemoteDataSource + Module 中按 kDebugMode 切换 fake/remote + Repository 只做 DTO→领域实体映射。示例全程采用 Dart 3.13 new 主构造语法（new(this._dio) / new({required super.dio, ...})）。
• 修复 Mason 变量渲染 bug：原 README 中类名占位符误用 {{Name}}。
• template_registry.json 新增 4.0.1 条目：发布地址指向 4.0.1 的 bricks.zip，fluzer create 可拉取本版本。

---

三、破坏性变更

无。

• 仅修改 Mason 砖内的 .md 文档与 registry 条目，不涉及任何 Dart 运行时代码、pubspec 依赖或 API 变更。
• 已生成的历史项目无需任何改动；本变更只影响后续 fluzer new 生成的新模块 README，对已运行项目零影响（不重新生成不会触发）。

---

四、使用指南

1. 用 fluzer create 创建新项目将直接获得 4.0.1 模板（含增强后的 data_sources/README.md）。
2. 已有项目无需改动代码：本次仅调整 Mason 砖模板文档与 registry，不影响已生成项目运行时代码。
3. 生成功能模块后，features/<name>/data/data_sources/ 目录会自带更完整的说明与示例，新手可直接照「最小示例」在本地实现数据源（抽象接口 + 远程/本地实现 + Module 注册），无需再翻外部文档。

---

五、相关说明

• 模板与 CLI 版本独立发布、互不绑定。本版本兼容基线与 4.0.0 一致（CLI 2.2.0+），template_registry.json 的 4.0.1 条目不设置 minCliVersion（该字段当前未被 CLI 读取），无需升级 CLI 即可使用 fluzer create 拉取。
• 完整变更记录见仓库 CHANGELOG.md 。

4.0.0

4.0.0 是一次面向 Dart 3.13 的全面对齐发布：

• 模板全部代码迁移到 Dart 3.13 的 new 主构造语法；
• 核心操作等待机制 BlocAwaitMixin 真正落地为「事件即身份 + AwaitResolution 密封类」架构（与 3.0.0 文档描述一致）；
• 同步了大量核心模块（effect / result / notifiers / theme / network / storage 等）的最新实现；
• 升级了 SDK 与一揽子依赖（freezed 4.x、very_good_analysis 11.x 等）。

---

重大变更

1. 核心操作等待机制：事件即身份 + AwaitResolution

lib/core/bloc/bloc_await_mixin.dart 整体重构（约 589 行改动）。

• runAwait<E extends Event>(E event) 现在返回固定的 Future<AwaitResolution<State>>，不再依赖字符串 key 或异常来区分结局。
• 等待结局由密封类 AwaitResolution<T> 的四个子类表征，调用端用 switch / is 收窄判断：
  • AwaitCompleted：handler 执行层成功（跑完且未抛异常）。不代表业务逻辑成功，业务成败请通过 AwaitCompleted.value（即当前/emit 后的 state）自行判断。
  • AwaitErrored：handler 执行层失败（handler 抛异常，或派发前 add() 就失败，如未注册 handler / bloc 已关闭）。
  • AwaitDropped：调度层——事件被 transformer 丢弃（droppable 丢弃 / restartable 顶替），handler 根本未执行。
  • AwaitCancelled：生命周期——bloc 关闭导致等待被废弃。
• 事件即身份：相同事件处于进行中时自动合并（single-flight），不同参数的事件各自独立执行；超时的等待只清理自身，不影响同事件的其他等待方。

2. 全部迁移到 Dart 3.13 主构造语法（new）

project 与三个 feature 系列 brick（feature / feature_bloc / feature_cubit）中所有默认构造函数改为 new 主构造写法：

• BLoC / Cubit：XxxBloc({required this.repository}) : super(const XxxState()) → new({required this.repository}) : super(const XxxState())
• Repository：const XxxRepository({required super.dio}) → const new({required super.dio})
• Page / Body：const XxxPage({super.key, this.bloc}) / const _XxxBody() → const new({...}) / const new()
• App 根组件：const App({super.key}) → const new({super.key})

3. 模板状态 / 模块骨架调整

• freezed 状态的默认工厂改为 const factory() = _XxxState; 形式（去掉冗余类名，与 flutter_zero_app 验证项目一致）。
• 模块私有构造函数由 XxxModule._() 改为 new _();，保持「仅通过 register() 静态方法注册、外部不可实例化」的语义不变。

4. SDK 与依赖升级

pubspec.yaml 关键变化：

项	旧	新
SDK 最低版本	^3.12.2	^3.13.0
freezed（dev）	^3.2.5	^4.0.1
very_good_analysis	^10.3.0	^11.0.0
flutter_secure_storage	^10.3.1	^11.0.0
flutter_easyloading	^3.0.5	^4.0.2
go_router	^17.3.0	^18.0.1

• 新增显式 bloc、test 依赖。
• 依赖按「层」分组并补充分组注释（Flutter SDK / 状态管理 / 网络 / 路由 / 依赖注入 / 本地存储 / UI 组件 / 代码生成 / 国际化 / 日志 / 基础工具）。
• fluzer.yaml 模板版本号 3.0.0 → 4.0.0。

5. 静态分析与工程配置

• analysis_options.yaml 新增 sort_pub_dependencies: ignore（依赖按层分组而非字母序，避免该 lint 噪音）。
• pubspec.yaml 新增 dependency_overrides 与 assets / fonts 注释模板，便于按需启用。

---

升级指引（从 3.1.0 → 4.0.0）

模板是代码生成器，升级方式取决于你已有的项目：

1. 新项目：直接用 fluzer create 拉取 4.0.0 即可，无需额外操作。
2. 已有项目、想同步模板改进：模板不提供自动升级脚本，推荐手动对齐以下要点：
   • 将 BlocAwaitMixin 相关代码替换为 4.0.0 版本（runAwait 改为返回 Future<AwaitResolution<State>>，调用端用 switch 收窄结果）。
   • 构造函数写法可渐进迁移到 new 主构造（非必须，旧写法仍可编译）。
   • 升级 pubspec.yaml 依赖版本至上表「新」列，并执行：
     • dart pub upgrade
     • dart run build_runner build（freezed 3→4 生成的 *.freezed.dart 有差异，必须重跑）
   • 执行 dart analyze，处理 very_good_analysis 11 可能新增的 lint 提示（多为 info 级，按需修复）。

主要破坏性风险点

• runAwait 返回值类型变更：若旧代码以「等待是否抛异常」判断成败，需改为检查 AwaitResolution 结果 / state。
• freezed 4.x：生成的freezed 代码与 3.x 不完全兼容，务必重跑 build_runner 重新生成。
• flutter_secure_storage 11 / go_router 18 / flutter_easyloading 4 各自可能带来 API 微调，请核对编译报错。

---

兼容性说明

• 与 CLI 版本关系：模板版本与 flutter_zero_cli 版本独立发布，但 4.0.0 的实际适配落在 CLI 2.2.0（含 NewV3V4Adapter 区间扩展到 [3.1.0, 5.0.0) 承接 new、GenL10nV4Adapter 接管 gen-l10n 的 Dart 3.13 生成）。template_registry.json 的 minCliVersion 字段当前未被 CLI 读取（历史遗留/死数据），故本版本 4.0.0 条目不设置该字段，旧 CLI 不会被自动拦截。
• 旧 CLI 的残留风险（靠发布顺序规避）：若用户用 ≤2.1.0 的 CLI 且拿到了 4.0.0 模板，fluzer new 会因适配器不认领 4.0.0 而明确报「unsupported version」错误；但 fluzer gen-l10n 在旧 CLI 中可能由无上界的 GenL10nV1V2Adapter 接管控并用旧 v3 生成器产出不兼容代码（静默失败，无 CLI 侧拦截）。

---

完整变更记录

详细变更见仓库 CHANGELOG.md 的 ## [4.0.0] - 2026-09-09 条目。

3.1.0

flutter_zero_template 3.1.0 发布说明

一、版本定位

3.1.0 围绕「功能模块生成模板按状态管理范式拆分」展开。此前 fluzer new 只提供一种 feature 砖（MVI / BLoC 范式），当项目采用 MVVM / Cubit 范式时，开发者需要手动改写事件、状态与 Bloc 样板。本版本新增 feature_bloc 与 feature_cubit 两份功能模块砖，分别面向 BLoC 与 Cubit 两种范式，并将旧 feature 砖的页面组织方式统一为 part of + 私有 _Body，使三份砖的代码风格保持一致。同时 project 砖内置 easy_refresh 依赖，使生成的项目开箱即可搭建下拉刷新 / 上滑加载列表。

模板其余部分（网络层、Effect 系统、依赖注入、等待机制）保持不变。

二、核心亮点

• 新增 feature_bloc 砖（MVI / BLoC）：生成基于「事件 + 状态」的 BLoC 功能模块骨架，与原 feature 砖目录结构一致，供偏好经典 MVI 模式的团队使用。
• 新增 feature_cubit 砖（MVVM / Cubit）：生成基于 Cubit 的功能模块骨架，以 presentation/cubit/ 取代 presentation/bloc/，无事件、UI 直接调用方法，更贴合 MVVM 轻量状态管理场景。
• 旧 feature 砖页面重构：{{name}}_page.dart 与 {{name}}_body.dart 改为 part of 关联，_Body 设为私有类，统一三份 feature 系列砖的代码组织风格，并降低跨模块脱离 BlocProvider 误用页面 Body 的风险。
• project 砖内置下拉刷新能力：pubspec.yaml 新增 easy_refresh: ^3.5.1，生成项目无需手动添加即可使用下拉刷新 / 上滑加载。

三、破坏性变更（Breaking Changes）

无。

• 旧 feature 砖的入口文件名（{{name}}_page.dart / {{name}}_body.dart）未变，旧 CLI 用 fluzer new 仍可正常生成；本次仅调整砖内部文件组织（改为 part of），对已生成的历史项目无影响（不重新生成不会触发）。
• 新增两份砖为可选，不影响既有 feature 砖的行为。

四、使用指南

1. 用 fluzer create 创建新项目将直接获得 3.1.0 模板（包含 feature / feature_bloc / feature_cubit 三份功能模块砖）。
2. 已有项目无需改动代码：本次变更仅涉及 Mason 砖模板，不影响已生成项目的运行时代码。
3. 生成功能模块：
   • 默认 fluzer new 仍使用 feature 砖（MVI / BLoC）。
   • 选用 Cubit 范式：待 CLI new 命令支持砖选择后，可指定 feature_cubit 砖生成 MVVM 模块（详见下文「相关说明」）。
4. feature_bloc / feature_cubit 均为功能模块骨架，首屏加载、分页等初始化逻辑由开发者在 Bloc / Cubit 中按需调用 init() / refresh() 实现；模板不强制首屏自动加载，保持最小可用。

五、相关说明

• 模板版本与 CLI 版本独立发布、互不绑定。本版本 minCliVersion 保持 2.0.0，无需升级 CLI 即可使用 fluzer create 获取本模板。
• 功能模块砖命名约定：feature（MVI / BLoC，历史默认）、feature_bloc（MVI / BLoC，与 feature 同结构，便于后续 CLI 按范式选砖）、feature_cubit（MVVM / Cubit）。三者页面均使用 part of + 私有 _Body 组织。
• 完整变更记录见仓库 CHANGELOG.md。

3.0.0

flutter_zero_template 3.0.0 发布说明

一、版本定位

3.0.0 是一次围绕「操作等待机制」的语义重构。2.0.0 及更早版本要求开发者为每个等待点手写字符串标识，这类标识没有编译期校验，写错的表现是运行时长时间等待后才超时，排查成本很高。本版本把等待标识改为事件本身，并补齐了重复触发合并、超时隔离、页面关闭时的收尾行为，等待 API 因此从五个参数收敛为三个入口。

模板其余部分（网络层、Effect 系统、依赖注入、功能模块生成结构）保持不变。

二、核心亮点

• 等待标识由字符串改为事件本身：不再需要手写和记忆等待标识，事件即操作身份。标识传错或类型不匹配会在编译期暴露，而不是等到运行时才发现等待无人唤醒。
• 相同事件自动合并等待：同一事件正在处理时再次触发，只会合并到同一趟操作上等待，不会重复发送事件、不会重复执行请求。重复下拉刷新、连续点击这类操作天然只跑一次。
• 不同参数的事件互不干扰：参数不同的同类事件（例如携带不同 id 的查询事件）各自独立执行、各自唤醒自己的等待方，粒度由事件的值相等性自动决定。
• 超时只影响单个等待方：每个等待方持有独立计时，超时仅结束自己并从等待队列中移除，不影响同一事件下的其他等待方，也不会把等待残留到页面销毁。
• 页面关闭时等待正常结束：BLoC 关闭时所有未完成的等待以正常方式结束，不再抛出异常。下拉刷新后立即退出页面不会再触发未捕获错误。
• API 收敛为三个入口：等待事件、注册自动收尾的事件处理器、手动完成等待，没有多余参数可选错。

三、破坏性变更（Breaking Changes）

以下变更需要已有项目手动跟进：

1. 等待事件的 key 参数已移除：runAwait(event: X, key: 'xxx') 需改为 runAwait(event: X)，合并粒度由事件值自动决定。
2. 注册事件处理器的 key 参数已移除：onAwait<E>(handler, key: 'xxx') 需改为 onAwait<E>(handler)，收尾时按触发的事件值自动唤醒对应等待方。
3. 并发策略透传参数已移除：事件处理器不再支持传入事件流调度策略。需要排队、丢弃、重启等特殊调度时，改用原生的 on 注册，并在处理器中手动完成等待。
4. 手动完成等待的参数类型由字符串改为事件：completeAwait('xxx') 需改为 completeAwait(event)，传错类型会在编译期报错。
5. 重复触发的行为变更：此前相同事件重复触发会各自发送一次并各跑一遍处理器；现在合并为一次执行，所有等待方共享同一结果。若你的业务依赖「重复触发就重复执行」，需改为使用不同参数的事件表达。
6. 跨事件类型合并不再支持：此前提字符串标识时，可以把不同事件类型归并到同一个等待标识下；现在每个事件类型各自等待各自的结果。确有需要时，让其中一个事件的处理器内部转发触发另一个事件。
7. 页面关闭时不再抛出异常：原本会向等待方抛出状态异常，现改为正常结束。若有代码依赖捕获该异常做清理，需改为在等待返回后自行判断状态。

四、从 2.0.0 升级指南

1. 将项目根目录 fluzer.yaml 的 version 改为 "3.0.0"，使 fluzer new 与 fluzer gen-l10n 按新版本模板执行本项目。

2. 用本版本模板中的 lib/core/bloc/bloc_await_mixin.dart 覆盖项目同名文件（该文件为本次变更的全部内容）。

3. 全局改造手写调用：

   • runAwait(event: X, key: 'xxx') → runAwait(event: X)
   • onAwait<E>(handler, key: 'xxx') → onAwait<E>(handler)
   • completeAwait('xxx') → completeAwait(event)
   • 删除用于保存等待标识的字符串常量

4. 检查事件是否具备值相等性：使用 freezed 定义的事件天然支持，无需改动；手写的普通类事件若未实现 == 与 hashCode，合并等待会退化为不合并（行为与旧版一致，不会报错），需要合并时请补上值相等性实现。

5. 若此前依赖并发策略参数做排队、丢弃或重启调度，改为原生 on 注册，并在处理器结束处手动调用完成等待。

6. 跑一遍单元测试：等待相关的用例若断言了「重复触发会执行多次」或「关闭时抛出异常」，需按新语义更新断言。

五、相关说明

• 模板版本与 CLI 版本独立发布、互不绑定。本版本的 minCliVersion 保持 2.0.0，无需升级 CLI：fluzer 的功能模块生成与本地化生成命令可处理任何不低于 1.0.0 的项目模板版本。
• 使用 fluzer create 创建新项目将直接获得 3.0.0 模板；已有项目按上一节步骤升级。
• 功能模块生成结构（presentation / application / domain / data）与业务代码生成逻辑本版本未改动，功能模块模板不产生等待相关代码，升级影响面仅限开发者手写的等待调用。
• 完整变更记录见仓库 CHANGELOG.md。

2.0.0

flutter_zero_template 2.0.0 发布说明

一、版本定位

2.0.0 是一次「去框架封装、零业务假设、开发者全权接管」的范式重构。我们移除了整套异常体系与网络封装层，把网络请求、错误与解析的决定权交还给开发者，让模板回归「干净的架构骨架」本身。

二、核心亮点

• 框架零异常封装：删除 AppException 及全部子类、错误码体系、服务端消息提取器。网络异常原样外抛，由 BLoC 经 Exception → ToastEffect 链路直接上报，不再由框架二次翻译。
• 网络层极简化：BaseRepository 仅保留 Dio 持有能力（super.dio），不再提供 parseList / parseSingle 等解析助手，开发者按自己的响应结构自由解析。
• Dio 由你掌控：删除 DioClient 封装类与 ApiConstants.baseUrl。Dio 实例在各环境入口（main / main_dev / main_staging）手动注册并注入拦截器，baseUrl 随之灵活配置。
• 多环境开箱即用：新增 main_dev.dart（开发）与 main_staging.dart（测试）入口，配合 flutter run -t lib/main_dev.dart 一行切换环境。
• 配置更名：flutter_zero_config.yaml 更名为 fluzer.yaml，结构精简为 version + template_name。
• 示例范式升级：test_repository.dart 演示 mixin XxxRepositoryMixin on BaseRepository + 私有请求方法 + 公开业务方法的零封装仓储写法；feature brick 改为用 README 说明模型约定，不再生成示例 Model。

三、破坏性变更（Breaking Changes）

以下变更需要已有项目手动跟进：

1. AppException 已删除：所有 import '.../app_exception.dart'、捕获 AppException、构造 AppException 的代码需改为使用 Dart 原生 Exception（或你自定义的异常类型）。
2. ErrorHandler / handleError / runWithErrorHandling 已删除：BlocErrorHandlerMixin 改为只提供 runCatching，异常包装规则为 e is Exception ? Failure(e) : Failure(Exception(...))。
3. DioClient 已删除：原 getIt<DioClient>() / DioClient().get(...) 需改为 getIt<Dio>() 并直接调用 dio.get(...) 等。
4. ApiConstants.baseUrl 已删除：baseUrl 改在各环境 main 中配置。
5. BaseRepository 导入路径变更：由 core/storage/base_repository.dart 改为 core/network/base_repository.dart；super.client 改为 super.dio。
6. result.dart API 变更：runToResult 重命名为 runCatching；Failure.exception 类型为 Exception。
7. default_toast_effect_handle.dart 移除错误码映射：原 error400~504 等映射整段删除，Toast 优先级统一为 message → l10nCode → code → Unknown。
8. l10n 错误码文案精简：app_zh.arb / app_en.arb 移除 20+ 条错误码文案，仅保留 unknownError；如你的业务 handle 引用了被删的 l10n key，需同步清理。

四、从 1.0.1 升级指南

1. 将项目根目录 flutter_zero_config.yaml 重命名为 fluzer.yaml，并删除其中 minCliVersion 字段（保留 version 与 template_name）。
2. 全局替换：
   • AppException → 原生 Exception（或自定义异常）
   • DioClient → Dio，getIt<DioClient>() → getIt<Dio>()
   • super.client → super.dio，并修正 BaseRepository 导入路径
   • runToResult → runCatching
   • handleError(e) / runWithErrorHandling(...) → runCatching(...)
3. 删除对 core/error/*、core/network/dio_client.dart、core/constants/api_constants.dart 的引用。
4. 如需多环境，参照 main_dev.dart / main_staging.dart 复制入口并配置各自 baseUrl。
5. 重新运行 flutter gen-l10n 等必要命令，确认无残留错误码引用。

五、相关说明

• 模板版本与 CLI 版本独立发布、互不绑定；CLI 相关命令的版本约束以 fluzer.yaml 与 template_registry.json 为准。
• 本版本不改动业务代码生成逻辑，feature brick 生成的模块结构（presentation / application / domain / data）保持不变。

1.0.1

flutter_zero_template 1.0.1 发版说明

概述

本版本为模板小幅更新（PATCH），主要完善错误提示文档，并新增模板版本与 CLI 的兼容性声明字段。未改动任何生成代码结构，对已有项目无破坏性影响。

新增

• flutter_zero_config.yaml 新增 minCliVersion 字段（当前值 "1.1.0"），声明该模板版本所要求的最低 CLI（fluzer）版本，供 fluzer new / fluzer gen-l10n 的版本门禁使用。

变更

• 更新核心文件 lib/core/effect/effect_handle/default_toast_effect_handle.dart 的文档注释：
  • 说明当 ToastEffect.l10nCode 未被默认处理器处理时，可执行 fluzer gen-l10n 自动生成 L10nCode 值对象、L10nToastType 扩展与 L10nToastEffectHelper，将 l10nCode 映射为本地化文案，避免手写大量 switch 分发代码。
• 因文档引用了 fluzer gen-l10n（该命令由 CLI 1.1.0 引入），本模板版本的 minCliVersion 相应提升至 1.1.0。

兼容性

• 要求 fluzer（CLI）≥ 1.1.0。
• CLI 1.1.0 以下版本在执行 fluzer new / fluzer gen-l10n 时，会因版本门禁明确报错提示升级，而非静默生成不兼容代码。
• 使用 CLI 1.0.0 创建的新项目仍基于 1.0.0 模板，不受影响。

升级方式

1. CLI ≥ 1.1.0 时重新执行 fluzer create 将获得 1.0.1 模板；
2. 已有项目执行 fluzer new <feature> / fluzer gen-l10n 前，请确保本地 fluzer 已升级至 1.1.0。

相关文档

• 版本约束规则：见 flutter_zero_doc「版本约束规则」页
• 模板版本规范：见 flutter_zero_doc「模板版本管理」页

1.0.0

Flutter Zero Template 1.0.0 发行说明

企业级 Flutter MVI 模板首个正式版本。基于 Flutter 3.44.4 / Dart 3.12.2（stable）。

概述

flutter_zero_template 是一套开箱即用的 Flutter 企业级 MVI 模板，通过 Mason Brick 分发，配套 fluzer CLI 生成项目与功能模块。约定：Event=Intent、Bloc=ViewModel、State=ViewState、Page=View。

核心特性

• 四 BLoC Mixin：BlocAwaitMixin（可等待）、BlocCancelTokenMixin（取消/去重/生命周期绑定）、BlocEffectMixin（副作用流）、BlocErrorHandlerMixin（错误归一化）。
• Effect 与 Notifiers 系统：开放 UIEffect 基类（ToastEffect/DialogEffect/LoadingEffect），EffectListener 责任链 + 框架默认 handle，桥接 Notifiers 弹层，副作用不污染 State。
• 错误归一化：AppException 抽象体系 + Result<T>（Success/Failure/Cancel）+ ErrorHandler 单一转换点；BaseRepository.parseBusinessResponse<T,B> 结构化解析业务响应。
• 三文件依赖注入：get_it_instance（全局）/ injection_base（脚本自动维护 registerFeatureModules）/ injection（手写业务注册）。
• 技术栈：flutter_bloc、dio、go_router、get_it、freezed+json_serializable、very_good_analysis（禁用 4 条 lint）。

快速开始

# 安装 CLI
dart pub global activate fluzer

# 创建项目
fluzer create my_app --org com.example

# 新增功能模块
fluzer new login