Flu-CLI 下一阶段演进规划：全能型脚手架 (Dio/BLoC/HarmonyOS)

最后更新：2026-01-16

本文档详细阐述了 Flu-CLI 在 M1 (稳定性) 之后的重大功能演进路线。目标是将 Flu-CLI 从一个"项目生成器"升级为覆盖网络层、状态管理及多端适配的全能型生产力工具。

---

📅 阶段一：Dio 网络层标准化 (Network Module)

痛点：每次新建项目都需要手动封装 Dio、拦截器、统一异常处理，重复劳动且团队间规范不统一。

目标：提供开箱即用的企业级网络请求封装，支持配置化生成。

1. Core 层升级 (@flu-cli/core)

• 新增 NetworkGenerator：
  • 负责生成统一的网络层目录结构：lib/core/network/。
  • 核心组件：
    • DioClient: 单例模式封装，支持 baseUrl、connectTimeout 等配置注入。
    • ApiResult<T>: 统一的泛型响应实体。
    • Interceptors：
      • AuthInterceptor: 自动从本地存储读取 Token 并注入 Header。
      • LogInterceptor: 基于环境 (Dev/Prod) 自动开关的请求日志打印。
      • ErrorInterceptor: 统一错误解析，将 HTTP 状态码转换为业务异常 (AppException)。
• 升级 ServiceGenerator：
  • 增强 flu add service 命令。
  • 逻辑：生成 Service 类时，自动注入 DioClient 依赖，并生成标准的 GET/POST 示例方法。

2. CLI 交互对齐

• 新命令：flu add network
  • 功能：为现有项目一键注入上述网络层代码。
• 向导增强：flu new 流程中增加 "是否包含 Dio 网络模块" 的询问项（默认 Yes）。

---

📅 阶段二：BLoC 状态管理支持 (State Management)

痛点：BLoC 是 Flutter 社区最主流的状态管理方案之一（尤其在大型项目中），目前 Flu-CLI 仅支持 Provider/GetX，缺失了这一重要拼图。

目标：补全 BLoC 支持，遵循 flutter_bloc 最佳实践。

1. Core 层升级 (@flu-cli/core)

• 升级 StateManagerGenerator：
  • 依赖注入：自动添加 flutter_bloc 和 equatable 到 pubspec.yaml。
  • 全局注入：在 main.dart 或 app.dart 中自动包裹 MultiBlocProvider，实现全局 BLoC 注入。
  • 基类生成：
    • BaseBloc: 封装通用的 loading/error/success 状态处理逻辑。
    • BaseEvent / BaseState: 统一基类，强制遵循 Equatable 比较。
• 升级 PageGenerator：
  • 支持命令：flu add page home --state-manager bloc。
  • 生成结构：

    lib/features/home/
    ├── view/
    │   └── home_page.dart       (使用 BlocBuilder/BlocListener)
    └── bloc/
    ├── home_bloc.dart       (逻辑核心)
    ├── home_event.dart      (事件定义)
    └── home_state.dart      (状态定义)

2. VSCode 插件适配

• 向导更新：在 New Project 向导的状态管理下拉框中增加 BLoC 选项。
• Snippet 增强：
  • 新增 flu-bloc: 快速生成 Bloc 类骨架。
  • 新增 flu-cubit: 快速生成 Cubit 类骨架。
  • 新增 flu-bloc-builder: 快速生成 BlocBuilder 模板代码。

---

📅 阶段三：鸿蒙系统 (HarmonyOS) 适配

痛点：随着鸿蒙生态的崛起，越来越多的 Flutter 项目需要适配 HarmonyOS Next。目前缺乏统一的工程化适配工具。

策略：采用 "Flu-CLI 原生创建 + CLI 注入适配" 模式。不依赖鸿蒙版 Flutter SDK 创建项目，而是让 Flu-CLI 具备跨 SDK 的脚手架能力。

1. Core 层升级 (@flu-cli/core)

• 新增 template-ohos 资源包：
  • 在 CLI 内部维护一份标准的 ohos 平台工程模板（包含 entry, har, build-profile.json5 等配置文件）。
• 新增 PlatformGenerator：
  • 功能：为现有 Flutter 项目注入鸿蒙支持。
  • 逻辑：
    1. 检测项目根目录下的 pubspec.yaml 获取项目名称。
    2. 将 template-ohos 完整复制到项目根目录下的 ohos/ 文件夹。
    3. 自动修改鸿蒙工程中的包名、工程名以匹配当前 Flutter 项目。
    4. (可选) 修改 pubspec.yaml，注入鸿蒙相关的 dev_dependencies（如 flutter_flutter 等，视技术方案而定）。

2. CLI 交互对齐

• 新命令：flu add platform ohos
  • 效果：检测当前目录，注入 ohos 文件夹，输出 "请使用 DevEco Studio 打开 ohos 目录进行构建" 的提示。
• 新建项目：flu new my_app --platforms android,ios,ohos
  • 在创建标准项目后，自动执行 ohos 注入流程。

3. VSCode 插件适配

• 可视化操作：在 "Add Capability" (添加能力) 面板中增加 "Add HarmonyOS Support" 按钮。
• 环境检测：
  • 检测是否安装鸿蒙 SDK (DevEco Studio)。
  • 检测当前 Flutter 环境是否支持鸿蒙构建（如提示需切换到鸿蒙版 Flutter SDK 或配置相关环境变量）。

---

✅ 实施路线图 (Roadmap)

阶段	周期	核心任务	交付物
Phase 1	Week 1	Dio 网络层标准化	NetworkGenerator, flu add network 命令
Phase 2	Week 2	BLoC 状态管理支持	flutter_bloc 模板, VSCode BLoC Snippets
Phase 3	Week 3	鸿蒙适配调研与实现	template-ohos, PlatformGenerator, flu add platform ohos
Phase 4	Week 4	VSCode 插件集成与发布	VSCode UI 更新, v2.1 版本发布

风险评估

1. 鸿蒙 Flutter SDK 变动频繁：鸿蒙适配方案（ohos 目录结构）可能会随官方 SDK 更新而变化。
   • 对策：将 template-ohos 独立维护，支持通过 CLI 在线更新模板，而不绑定死在 CLI 版本中。
2. BLoC 样板代码过多：BLoC 模式文件较多，可能会让简单项目显得臃肿。
   • 对策：提供 Cubit (简化版 BLoC) 作为可选项，或提供 feature_bloc (将 event/state/bloc 合并为一个文件) 的生成模式。