Flutist - Flutter 模块化架构管理框架

简单而系统地管理你的 Flutter 模块化结构

---

简介

随着我们的项目增长，模块化似乎势在必行，而我最近发现了一个比较新的Flutter模块化管理框架------Flutist。它是一个专为 Flutter 应用设计的强大项目管理框架，灵感来源于 iOS 开发生态中的 Tuist[1]。它为管理大型 Flutter 项目提供了一套结构化的方法，具备模块化架构、集中式依赖管理和代码生成能力。

为什么选择 Flutist？

模块化是大型 Flutter 项目的标准方案------独立构建、并行开发、测试隔离，优势显而易见。但随着模块数量增长，管理开销也随之攀升。Flutist 通过自动化消除了这些开销。

类型安全的依赖管理

当模块超过 10 个时，包版本不一致的问题极易出现。在 package.dart 中声明一次版本，flutist generate 会自动生成 flutist_gen.dart，所有模块都能通过 IDE 自动补全和类型检查安全地引用依赖。

    
    
    
  // 1. package.dart --- 只声明一次版本
Dependency(name: 'dio', version: '^5.3.0'),
Dependency(name: 'flutter_bloc', version: '^8.1.6'),

// 2. flutist_gen.dart --- 由 flutist generate 自动生成
Dependency get dio         => dependencies.firstWhere((d) => d.name == 'dio');
Dependency get flutterBloc => dependencies.firstWhere((d) => d.name == 'flutter_bloc');
Module     get authDomain   => modules.firstWhere((m) => m.name == 'auth_domain');

// 3. project.dart --- 类型安全引用（IDE 自动补全 ✅）
Module(
  name: 'auth_data',
  dependencies: [package.dependencies.dio, package.dependencies.flutterBloc],
  modules: [package.modules.authDomain],
),

集中式 pubspec.yaml 管理

每增加一个模块就多一个 pubspec.yaml。升级一个包的版本意味着要手动编辑每个引用它的文件。

Flutist 根据 project.dart 的声明自动同步所有 pubspec.yaml 文件。开发者只需编辑一个文件------project.dart。

    
    
    
  $ flutist generate
✓ pubspec.yaml synced: app, auth_domain, auth_data, auth_presentation,
                      product_interface, product_implementation ... (24 total)
✓ all architecture rules passed
✓ done (0.8s)

架构规则自动化

仅靠文档和代码审查很难持续保持架构规则的一致性。在开发压力下，domain 层最终会导入 http，或者一个功能模块直接引用了另一个功能模块的实现。这些违规很难被发现，等到发现时往往已经扩散开来。

Flutist 将架构规则转化为可执行代码 。在 strictMode: true（默认值）下，任何违规都会立即终止 generate。曾经只存在于文档中的原则，现在变成了构建关卡。

    
    
    
  $ flutist generate
✗ [B4] auth_domain → auth_data: 检测到反向依赖 --- domain 不应依赖 data
   → 请从 auth_domain 中移除 Dio 导入，仅声明 Repository 接口
✗ generate 已终止（strictMode: true）

即使是刚加入团队、对架构理解不深的新成员，在违反规则的那一刻也能获得清晰的反馈。架构违规不再依赖人工审查，工具会自动检查。

样板代码自动生成

模块化架构最大的痛点之一就是样板代码。每个新功能都需要创建 interface、implementation、testing、tests 和 example 包，每个包都有自己的 pubspec.yaml、lib/ 结构和 barrel 文件。

像 BLoC 这样的状态管理模式，每个功能都需要 event、state、BLoC、page 和 widget 文件。使用 flutist create 和 flutist scaffold，一条命令就能生成所有这些内容。

    
    
    
  # 以 micro 类型创建 todos 功能 --- 5 个包 + 完整结构自动化
$ flutist create --name todos --path features --options micro
✓ features/todos/todos_interface      已创建
✓ features/todos/todos_implementation 已创建
✓ features/todos/todos_testing        已创建
✓ features/todos/todos_tests          已创建
✓ features/todos/todos_example        已创建

# 使用 BLoC 脚手架生成所有文件
$ flutist scaffold --template bloc --name todos_overview --path features/todos/todos_implementation
✓ todos_overview_bloc.dart  已创建
✓ todos_overview_event.dart 已创建
✓ todos_overview_state.dart 已创建

核心特性

特性	说明
声明式	通过单一的 project.dart 文件声明整个项目结构
单一来源	所有依赖版本通过 package.dart 集中管理
规则即代码	架构违规会立即终止生成过程

安装

    
    
    
  dart pub global activate flutist

前置条件 ：Flutter SDK，并确保 ~/.pub-cache/bin 已添加到 PATH

快速开始

1. 初始化项目

    
    
    
  cd my_flutter_project
flutist init

Flutist 会根据上下文自动适配：

• • 无 pubspec.yaml：询问是否创建新的 Flutter 项目
• • 存在 pubspec.yaml：询问是新建项目还是迁移现有项目
• • • 新项目：创建 app 模块，添加到工作区，生成 lib/main.dart
  • • 现有项目：仅创建配置文件，保留现有代码结构

2. 创建模块

    
    
    
  # 创建 Clean 架构模块
flutist create --name login --path features --options clean

# 创建 Microfeature 架构模块
flutist create --name network --path packages --options micro

# 创建 Lite 模块
flutist create --name auth --path packages --options lite

# 创建单一包
flutist create --name utils --path core

3. 管理依赖

    
    
    
  # 添加包（自动解析版本）
flutist pub add http bloc flutter_bloc

# 同步依赖到所有模块
flutist generate

4. 从自定义模板生成代码

    
    
    
  # 列出可用模板
flutist scaffold list

# 从模板生成
flutist scaffold feature --name login
flutist scaffold feature --name login --path lib/features

命令一览

命令	描述	用法
init	初始化新项目或现有项目	flutist init
create	创建新模块	flutist create --name <name> --path <path> [--options <type>]
generate	同步依赖并重新生成文件	flutist generate
check	检查架构规则（CI 友好，不修改文件）	flutist check
test	并行运行所有模块的测试	flutist test [-m <module>]
scaffold	从模板生成代码	flutist scaffold <template> --name <name>
pub	管理依赖	flutist pub add <package>
graph	可视化模块依赖关系	flutist graph [--format <format>]
help	显示帮助信息	flutist help [command]

核心文件

文件	说明
package.dart	外部包版本和模块名称的单一真实来源，多行格式为解析必需
project.dart	声明模块依赖和模块间关系，由 flutist generate 读取
flutist_gen.dart	自动生成的类型安全访问器，提供 IDE 自动补全支持

项目结构

典型的 Flutist 项目结构：

    
    
    
  my_project/
├── project.dart              # 项目配置
├── package.dart              # 集中式依赖管理
├── pubspec.yaml              # 工作区配置
├── lib/                      # 根应用代码
│   └── main.dart
├── app/                      # 主应用模块
│   ├── lib/
│   │   └── app.dart
│   └── pubspec.yaml
├── features/                 # 功能模块
│   └── auth/
│       ├── auth_domain/
│       ├── auth_data/
│       └── auth_presentation/
├── packages/                 # 库模块
│   └── network/
│       ├── network_interface/
│       ├── network_implementation/
│       ├── network_testing/
│       ├── network_tests/
│       └── network_example/
└── flutist/
    ├── templates/            # 脚手架模板
    └── flutist_gen.dart      # 生成的代码

模块类型

flutist create 会生成层级包并自动在 project.dart 中配置依赖关系。

Clean 架构 (--options clean)

3 层 Clean Architecture，最适合需要清晰关注点分离的功能模块。

    
    
    
  features/login/
├── login_domain/          # 业务规则、实体、用例（无外部依赖）
├── login_data/            # 仓库、数据源、DTO
└── login_presentation/    # UI 和状态管理

自动配置依赖 ：presentation → domain，data → domain

规则 ：所有依赖箭头指向 domain，domain 不依赖任何东西。

Microfeature 架构 (--options micro)

5 层 Microfeature Architecture，最适合跨功能共享的可复用库。

    
    
    
  packages/network/
├── network_interface/         # 公共 API（抽象类、模型）
├── network_implementation/    # 具体实现
├── network_testing/           # 测试辅助、模拟对象
├── network_tests/             # 单元测试和集成测试
└── network_example/           # 模块演示应用

自动配置依赖 ：implementation/testing → interface，tests/example → implementation + testing

规则 ：消费者只依赖 interface，组合根注入实现。

Lite 架构 (--options lite)

4 层 Microfeature lite（无 example），最适合内部 API。

    
    
    
  packages/auth/
├── auth_interface/
├── auth_implementation/
├── auth_testing/
└── auth_tests/

单一包（省略 --options）

无层级，最适合工具类、共享模型或应用外壳。

    
    
    
  core/utils/
├── lib/
│   └── utils.dart
└── pubspec.yaml

架构验证

flutist generate 和 flutist check 自动执行以下规则：

规则	说明
实现引用	只有组合根（默认：app）和同功能测试/example 可以引用 _implementation 包
测试层隔离	_testing 包被排除在生产依赖之外
Example 独立性	_example 模块不能被任何生产代码引用
方向强制	同功能层级遵循声明的依赖方向
循环依赖	通过 DFS 遍历检测，绝不允许

配置选项

    
    
    
  // project.dart
ProjectOptions(
  strictMode: true,              // true（默认）：违规时终止 / false：仅警告
  compositionRoots: ['app'],     // 允许引用 _implementation 的模块
)

Scaffold 脚手架模板

将重复性工作保存为模板，通过 flutist scaffold 自动化生成代码。

模板变量

在 .template 文件和 path 值中使用 {{变量}} 进行替换：

| 变量 | 输入 login_feature | 输出 |
|----------|--------------------|---------------|-----------------|
| `{{name | snake_case}}` | login_feature | login_feature |
| `{{name | pascal_case}}` | login_feature | LoginFeature |
| `{{name | camel_case}}` | login_feature | loginFeature |
| `{{name | upper_case}}` | login_feature | LOGIN_FEATURE |

template.yaml 结构

    
    
    
  description: "BLoC Feature Template"

attributes:
  - name: name
    required: true
  - name: path
    required: false
    default: "lib/features"

items:
  - type: file
    path: "{{path}}/{{name | snake_case}}/{{name | snake_case}}_bloc.dart"
    templatePath: "bloc.dart.template"

  - type: string
    path: "{{path}}/{{name | snake_case}}/README.md"
    contents: |
      # {{name | pascal_case}}

Item 类型

类型	说明
file	读取 .template 文件，替换变量后生成
string	使用内联内容直接生成文件
directory	复制整个模板目录

实战示例：BLoC Feature 模板

bloc.dart.template

    
    
    
  import 'package:bloc/bloc.dart';

part '{{name | snake_case}}_event.dart';
part '{{name | snake_case}}_state.dart';

class {{name | pascal_case}}Bloc
    extends Bloc<{{name | pascal_case}}Event, {{name | pascal_case}}State> {
  {{name | pascal_case}}Bloc() : super(const {{name | pascal_case}}Initial()) {
    on<{{name | pascal_case}}Started>(_onStarted);
  }

  Future<void> _onStarted(
    {{name | pascal_case}}Started event,
    Emitter<{{name | pascal_case}}State> emit,
  ) async {}
}

event.dart.template

    
    
    
  part of '{{name | snake_case}}_bloc.dart';

sealed class {{name | pascal_case}}Event {
  const {{name | pascal_case}}Event();
}

final class {{name | pascal_case}}Started extends {{name | pascal_case}}Event {
  const {{name | pascal_case}}Started();
}

state.dart.template

    
    
    
  part of '{{name | snake_case}}_bloc.dart';

sealed class {{name | pascal_case}}State {
  const {{name | pascal_case}}State();
}

final class {{name | pascal_case}}Initial extends {{name | pascal_case}}State {
  const {{name | pascal_case}}Initial();
}

final class {{name | pascal_case}}Loading extends {{name | pascal_case}}State {
  const {{name | pascal_case}}Loading();
}

final class {{name | pascal_case}}Loaded<T> extends {{name | pascal_case}}State {
  final T data;
  const {{name | pascal_case}}Loaded(this.data);
}

final class {{name | pascal_case}}Error extends {{name | pascal_case}}State {
  final String message;
  const {{name | pascal_case}}Error(this.message);
}

运行生成

    
    
    
  $ flutist scaffold bloc_feature --name login --path lib/features

✓ lib/features/login/login_bloc.dart
✓ lib/features/login/login_event.dart
✓ lib/features/login/login_state.dart

实战示例：Riverpod Notifier 模板

notifier.dart.template

    
    
    
  import 'package:riverpod_annotation/riverpod_annotation.dart';
import '{{name | snake_case}}_state.dart';

part '{{name | snake_case}}_notifier.g.dart';

@riverpod
class {{name | pascal_case}}Notifier extends _${{name | pascal_case}}Notifier {
  @override
  {{name | pascal_case}}State build() => const {{name | pascal_case}}State.initial();

  Future<void> load() async {
    state = const {{name | pascal_case}}State.loading();
    try {
      state = const {{name | pascal_case}}State.loaded(null);
    } catch (e) {
      state = {{name | pascal_case}}State.error(e.toString());
    }
  }
}

state.dart.template

    
    
    
  import 'package:freezed_annotation/freezed_annotation.dart';

part '{{name | snake_case}}_state.freezed.dart';

@freezed
class {{name | pascal_case}}State with _${{name | pascal_case}}State {
  const factory {{name | pascal_case}}State.initial()            = _Initial;
  const factory {{name | pascal_case}}State.loading()            = _Loading;
  const factory {{name | pascal_case}}State.loaded(dynamic data) = _Loaded;
  const factory {{name | pascal_case}}State.error(String msg)    = _Error;
}

示例项目

Clean Architecture 示例

flutist_clean_architecture[2]

• • Domain、Data、Presentation 三层 Clean Architecture
• • 集中式依赖管理
• • 大型 Flutter 应用最佳实践

Microfeature Architecture 示例

flutist_microfeature_architecture[3]

• • Interface、Implementation、Tests、Testing 四层 Microfeature 架构
• • 完全隔离的可复用库模块
• • 集中式依赖管理

相关链接

资源	链接
📦 pub.dev	pub.dev/packages/fl...
📖 文档网站	deepwiki.com/seonwooke/f...
💻 GitHub	github.com/seonwooke/f...

引用链接

[1] Tuist: tuist.io/
[2] flutist_clean_architecture: github.com/seonwooke/f...
[3] flutist_microfeature_architecture: github.com/seonwooke/f...