用途:为 Flutter 应用按统一规范搭起一个可导航功能模块。功能是一个文件夹而非新 package,位于 lib/features/<feature>/,采用 lower_snake_case 并按屏幕命名,如 tasks、task_detail、settings、onboarding。资料注明单 package 目录树由 project-structure-and-packages 负责,app package 不使用 lib/src/。
主要能力:固定解剖结构,presentation/ 下含 <feature>_screen.dart(dumb View)、<feature>_notifier.dart(1:1 Notifier/AsyncNotifier ViewModel)、widgets/ 叶子视图、<feature>_providers.dart 作用域 provider;可选 domain/<feature>.dart 存放功能本地模型。View 只读一个 controller 并渲染,逻辑放 ViewModel;依赖只向下指向 core/data 基础层,禁止横向导入其他 feature。读数据经 repository provider,.watch() 包在作用域 StreamProvider 中;写入统一走一个 repository 方法(单写路径,先持久化再发布);派生状态在读取时计算;错误为类型化 Result/Failure 映射到 AsyncValue;时间通过注入 Clock 获取;路由注册到唯一 go_router,标识放 path params。
使用方式:运行 scripts/scaffold_feature.sh <feature> 生成骨架,PR 前运行 scripts/verify_feature.sh。生成器无法完成的两步需手动做:在单一 go_router 中注册类型化路由并用 build_runner 重新生成;先在模板 ARB 添加字符串,再同步到各语言 ARB 并保持占位符一致,然后跑校验与代码生成。若功能需要读取新持久化记录,先补齐 value type → Drift 表 → DAO → repository 方法链,再接入。参考资料包括 anatomy-and-wiring.md、routing-and-l10n.md、add-persisted-record.md。
适用场景与限制:适合以 Riverpod-first 方式统一 Flutter 功能模块结构、评审与测试。限制与反模式明确:不得新建 package、不得跨 feature 导入、不得在 build() 中调用 repository 或写业务 try/catch、不得乐观重发或手动改缓存、不得存储派生计数、不得使用无 key 的“当前实体”provider、不得在 feature 中调用 DateTime.now()、不得用 state.extra 承载可深链身份、不得硬编码左右几何或内联 UI 文案、测试中应伪造 repository 而非 mock Notifier。资料未提供收费、价格、平台支持范围等信息。