企业级Flutter模块化架构：多包分层+状态管理+路由实战

1. 项目概述与架构设计的核心思路

1.1 企业级 Flutter 项目到底缺什么

聊这个话题之前，先说个我自己的经历。早年间做过一个 Flutter 项目，功能不复杂，就十几个页面，当时图省事，所有代码全塞在lib下面，按pages、widgets、models、services分目录。前三个月开发速度确实快，团队五个人，一人负责一块，谁都不耽误谁。

等到了第六个月，业务开始叠加，支付、推送、埋点、IM、分享，页面从十几个涨到五十几个，问题就暴露了。最明显的是合并代码的冲突率直线上升，几乎每个 PR 都要手动解决冲突。今天你把user_service.dart重命名了，明天同事又在里面加了新方法，Git 合并记录里全是同一个文件的碰撞。其次是改动的影响面完全失控，改一个公共组件的内部实现，跑完所有回归测试要两个小时，而且永远不知道有没有漏掉哪个页面。

这其实就是典型的架构缺失症状。Flutter 的setState和Provider用起来太舒服了，很多项目开发前三个月都是顺风顺水的，问题全在业务复杂之后才爆发。所以我一直在跟团队强调一个观点：模块化不是给现在的爽开发的，是给六个月之后的你开发的。

1.2 这套架构要解决的核心问题

基于标题里“最新且稳定的企业级模块化架构”这个定位，我先明确几个核心目标。第一是并行开发，多个业务线之间不能互相阻塞，A 组改支付模块的时候，B 组做订单模块不应该受影响。第二是边界清晰，模块之间的依赖关系必须有明确规则，你不能让业务模块直接去改一个底层组件的公共数据，要在架构层面就堵死这种操作。第三是可持续发展，新来的同事看完架构文档之后，能够快速定位某个功能属于哪个模块，并且在不需要资深工程师手把手带的情况下完成开发。

这里我选型的核心是：多包结构 + 严格的分层依赖 + 单一数据源管理。说白了就是像搭积木一样，把项目拆成若干个独立编译、独立测试、独立演进的小模块，然后用一套规则把它们组合起来。

1.3 为什么说“最新且稳定”很重要

Flutter 的技术栈更新非常快。你去看 2024 年之前的 Flutter 架构文章，很多还在用BLoC加flutter_bloc，或者说Provider是官方推荐的状态管理方案。但到了现在这个版本，情况已经发生了明显变化。

我用的是 Flutter 3.27 之后的版本（LTS 稳定分支），状态管理采用 Riverpod 3.x，路由直接上go_router，数据层用Drift做本地持久化。为什么这套组合是当前时间点上最稳的方案？第一，Riverpod 3.x 已经解决了之前 1.x、2.x 时代代码生成不够稳定、ProviderScope覆盖逻辑容易出的问题，编译期校验能力大幅增强，很多错误在开发阶段就能暴露。第二，go_router 早就被官方纳入了示例推荐的范畴，对 Web 和移动端的浏览器路由深链支持非常成熟。第三，Drift 在类型安全的 SQL 操作和流式查询这两端都做得很到位。

当然，“最新”不代表“最激进”。我把一些还在实验阶段的功能挡在门外，比如未发布正式版的perfect_freehand之类无关库，或者某些依赖原生代码且社区活跃度一般的新插件。架构追求的是可预期的稳定性，不能在核心链路上放太多不确定因素。

2. 整体分层设计与模块划分

2.1 三层架构：core、shared、feature

我最终采用的方案是典型的 clean architecture 思想放到 Flutter 工程中的实践，但做了一些裁剪，避免过度设计。总共分成三层：core、shared、feature。

先说core。这一层是底座，不依赖任何业务模块，只依赖 Flutter SDK 和第三方基础设施类库。里面放的东西包括网络请求封装、日志系统、埋点 SDK 封装、主题与设计令牌（Design Token）、本地存储基础服务等。举个例子，网络层我不直接让业务模块去初始化 Dio 实例，而是封装一个ApiClient类，提供几个标准方法，比如带 Token 自动附加的getRequest、postRequest，业务模块只需要调ApiClient.instance.get('/order/list')就行。这样做的好处是，将来如果要把 Dio 换成别的网络库，只需要在core层改一个文件，所有业务模块完全不受影响。

shared层是中间层，主要放一些跨模块共享的纯 UI 组件和工具方法。比如全局统一的「空状态组件」「错误页」「骨架屏」，以及时间格式化、金额计算之类没有业务含义的工具函数。这一层跟core的区别在于，它可以依赖core，但不能依赖feature。放在这一层要非常克制，千万别把业务相关的东西塞进来，否则会慢慢腐化。

最顶层是feature层，也就是业务包装。每个业务域独立成一个包，比如feature_auth、feature_order、feature_scan、feature_profile。它们可以依赖core，也可以依赖shared，但不允许互相依赖。如果支付模块需要读取订单模块的某种数据，必须通过路由跳转加参数，或者通过统一的通信机制解决，不可以在代码里直接 import 对方的文件。

project_root/ packages/ core/ shared/ feature_auth/ feature_order/ feature_payment/ pubspec.yaml melos.yaml

整个目录结构在物理上就把依赖关系锁死了。

2.2 为什么不用单仓多目录，而是起多包

我知道很多人会问，你在一个 Flutter 项目里直接建目录不也能分层吗？非要拆成多个 package 是不是有点小题大做。

我做过对比，结论是：物理边界的强制力远大于约定。在单仓多目录模式下，“业务模块不准 import 其他业务模块”只能靠 code review 去推动，人一多、MR 一密集，总有漏网之鱼。但拆成 packages 之后，Dart 的 import 规则是硬性的——你根本 import 不到不存在的包，也没有业务模块会因为图省事去加一条feature_auth的依赖。一旦发现自己需要跨模块访问什么，就必须走约定的通信机制，这就迫使你提前想清楚模块之间的边界。

其次，多包结构对编译缓存特别友好。因为feature_order单独编译之后，只要它没有改动，后续增量编译可以直接跳过。在大型项目里，我实测过完整冷启动编译时间减少了 35%~45% 左右（取决于依赖链的长度），热重载速度也明显快一截。

2.3 模块间通信：统一的路由与事件总线机制

模块之间不能直接 import，但不代表它们完全不能通信。我设计了两条通道。

第一条是路由通道，用于页面跳转。feature_auth想展示订单详情页，做法是构建一个OrderDetailRoute的路径字符串，通过context.push()跳过去，参数通过路由参数传递，返回值通过pop()返回。所有 feature 模块需要在公共注册表（放在core里）注册自己的路由配置块。

第二条是事件总线，用于非页面场景的数据同步。比如用户退出登录时，feature_auth会发一个LoggedOutEvent，订单列表页收到事件后清空自己的缓存。我用的是一个轻量的事件总线实现，底层基于StreamController.broadcast()，事件类型统一放在core/event包下面。注意事项是：只放业务领域事件，不放 UI 细节事件，不然事件多了之后很难维护。

3. 核心基础设施：路由、依赖注入与状态管理

3.1 用 go_router 实现模块化路由注册

go_router 4.0 之后的版本用起来非常顺手，原生支持ShellRoute来搭 Tab 导航框架，也支持子树级别的Navigator，很适合做模块化。

我在core层定义了一个顶层路由配置文件，但不会把所有页面的路径都写死在这里。每个 feature 模块自己导出一个GoRoute数组，然后在主路由文件里把它们合并进去。

// feature_order/order_routes.dart final orderRoutes = <GoRoute>[ GoRoute( path: '/order/list', builder: (context, state) => OrderListPage( orderStatus: state.uri.queryParameters['status'], ), ), GoRoute( path: '/order/detail/:id', builder: (context, state) => OrderDetailPage( orderId: state.pathParameters['id']!, ), ), ];

// core/router/app_router.dart final appRouter = GoRouter( initialLocation: '/splash', routes: [ ...authRoutes, ...orderRoutes, ...paymentRoutes, ], errorBuilder: (context, state) => const NotFoundPage(), );

这样做的核心好处是：每新增一个页面模块，只需要在 feature 内部写 route，然后追加到合并列表里。主路由文件永远只有几行，不需要随页面数量增长。如果团队里有人忘了注册，误跳转的时候会进 404 页面，这个问题可以在联调阶段快速暴露。

路径命名上我推荐统一用模块简称/功能/动作的格式，比如/auth/login、/order/detail/:id、/pay/confirm，这样既避免冲突，后期上 Web 端做深链时也不需要改路径。

3.2 依赖注入：Riverpod 的 ProviderScope 与 override

依赖注入这块，我选 Riverpod 作为核心容器。Riverpod 本身就自带依赖注入能力，它不需要额外的GetIt、kiwi之类的库，而且它在编译期有更强的类型校验。

整个应用入口长这样：

void main() async { WidgetsFlutterBinding.ensureInitialized(); final container = ProviderContainer( overrides: [ apiClientProvider.overrideWithValue( ApiClient( baseUrl: AppConfig.apiBaseUrl, tokenStore: const SecureTokenStore(), ), ), ], ); runApp( UncontrolledProviderScope( container: container, child: const App(), ), ); }

为什么不用默认的runApp(ProviderScope(child: App()))？因为我在启动阶段需要先做异步初始化，比如读取本地 Token、动态获取平台配置，这些数据需要注入到 Provider 里才能在后续页面里读到。用UncontrolledProviderScope可以让我持有container的引用，在必要的时候手动刷新状态或做测试断言。

3.3 状态管理分层策略

状态管理我建议分成三个层级，各有各的用途，不要一个StateProvider通吃天下。

第一层叫本地 UI 状态，就是某个页面内部临时用的状态，比如 Tab 切换下标、搜索框文字、弹窗显示隐藏。这种直接用StatefulWidget自带的setState就可以了，不需要引入任何重量级方案。有些人喜欢把每个 UI 状态都搞成全局 Provider，我见过很多项目因此埋下状态污染、难以 Watch 的隐患。实话说，这种状态搞全局化非常消耗维护成本。

第二层叫页面级业务状态，比如订单列表的加载中/加载成功/加载失败，购物车的商品清单。这种状态适合放到 Riverpod 的AsyncNotifier或者FutureProvider里，支持自动刷新和手动重试。

第三层叫应用级全局状态，比如登录态、用户权限、主题模式。这种状态需要被多个模块共享，而且要求任何模块都能读、能写、能监听。我用Notifier配合NotifierProvider来做，登录模块会调用logout()、刷新 Token 时会统一更新authStateProvider。

class AuthController extends Notifier<AuthState> { @override AuthState build() { final token = ref.watch(tokenStoreProvider).getToken(); return AuthState(isLoggedIn: token != null, user: null); } Future<void> login(String username, String password) async { final result = await ref.read(authRepositoryProvider).login(username, password); if (result.success) { state = AuthState(isLoggedIn: true, user: result.user); } } Future<void> logout() async { await ref.read(tokenStoreProvider).clear(); state = const AuthState(isLoggedIn: false, user: null); } }

这里要提一个体验上的技巧：Riverpod 3.x 的Notifier.build默认是 lazy 初始化的，但全局状态你往往希望在应用启动时就加载好，给所有依赖方一个确定性的初始快照。做法是在某一个被长期 Watch 的 Provider 里，显式读一次目标 Provider，比如在根组件里ref.watch(authControllerProvider)，确保它在首帧渲染前完成初始化。

3.4 跨模块共享数据的“最终解释权”

模块化之后，很容易遇到一个尴尬场景：用户信息到底是属于feature_auth还是core？我的答案是：领域数据放业务模块，契约接口放 core 或 shared。

也就是说，User这个实体类属于feature_auth，其他模块读用户信息时，不直接 import，而是通过core提供的一个标准接口UserInfoProvider（本质是Provider<User?>）去读。这样feature_order里写的是“从UserInfoProvider读当前用户”，它完全不知道feature_auth内部怎么实现登录的。如果将来要换一套登录体系，只要在启动阶段 override 掉UserInfoProvider的实现即可，feature_order一行不改。

4. 数据层与网络层设计

4.1 Repository 模式：业务与数据的隔离层

模块化架构里，业务模块不应该直接调用ApiClient或者数据库表，中间必须包一层Repository。这是整个架构里我认为最值得花时间打磨的一层。

严谨地说，Repository是业务模块的数据仓库，它内部知道自己从哪里拿数据（网络还是本地缓存），外部只需要告诉它“我需要什么数据”以及“缓存策略是什么”。这样业务逻辑完全感知不到底层数据来源。

// feature_order/domain/order_repository.dart class OrderRepository { OrderRepository({ required this.apiClient, required this.localOrderDao, }); final ApiClient apiClient; final LocalOrderDao localOrderDao; Future<OrderList> fetchOrders({bool forceRefresh = false}) async { if (!forceRefresh) { final localOrders = await localOrderDao.getAll(); if (localOrders.isNotEmpty) { return localOrders; } } final remoteOrders = await apiClient.get('/order/list'); await localOrderDao.replaceAll(remoteOrders); // 更新本地缓存 return remoteOrders; } }

注意，OrderRepository是依赖core层提供的ApiClient和相关接口，它本身不关心 ApiClient 是怎么实现的，也不直接操作Drift数据库的具体表结构，只是通过 DAO 对接到本地存储逻辑。这样做单元测试时就非常轻松：Mock 掉apiClient和localOrderDao，直接验证 repository 的缓存策略、异常分支。

4.2 网络层封装：拦截器、重试与缓存策略

我再展开讲网络层的细节。ApiClient是基于 Dio 的二次封装，核心设计集中在拦截器上面。

第一个拦截器是认证拦截器。它负责在请求发出之前，从 secure storage 里读 Token，附加到请求头Authorization: Bearer xxx。响应回来之后，如果遇到 401 错误，说明 Token 过期，这时要立刻触发 Token 刷新，并处理并发请求的重放逻辑。这个刷新流程很容易踩坑——多个请求同时收到 401，你不能每个都去调刷新接口，否则会把刷新 Token 也搞坏掉。正确做法是用一个单独的Future保存刷新任务，其他等待的请求都await同一个 Future。

class AuthInterceptor extends Interceptor { String? _refreshFuture; @override Future<void> onError(DioException err, ErrorInterceptorHandler handler) async { if (err.response?.statusCode != 401) { return handler.next(err); } await _ensureFreshToken(); // 用新 Token 重放原始请求 final newRequest = await _cloneRequestWithNewToken(err.requestOptions); final response = await dio.fetch(newRequest); return handler.resolve(response); } Future<void> _ensureFreshToken() async { // 如果已经有刷新任务，就等它 if (_refreshFuture != null) { return _refreshFuture; } // 否则发起刷新 final future = refreshToken(); _refreshFuture = future; try { await future; } finally { _refreshFuture = null; } } }

第二个是缓存拦截器。针对部分 GET 接口，比如配置信息、城市列表、公告文案，我会在响应成功之后把它存进内存和本地文件双重缓存。下次请求时如果网络异常，直接返回缓存兜底，减少因为弱网导致的空白页和失败提示。

第三个是错误统一封装。业务模块里不应该到处猜测 Dio 的异常类型，我把它们统一包装成AppException：网络不可达、超时、服务端返回错误码、数据解析失败，分别对应不同的用户提示文案。

这些都是企业级应用必须处理的地基问题。

4.3 本地持久化：用 Drift 管理结构化缓存

最近很流行的一句话是“离线优先”，企业级 App 尤其是 To B 场景，经常会遇到信号差、断网的环境。我推荐用Drift来管理本地数据库。它基于 SQLite，支持类型安全的表结构，还可以配合Stream做响应式查询。

模块化架构下，每个 feature 模块可以建自己的数据库表，但注意不要直接在业务逻辑里写 SQL，隔离方式跟网络层一样：通过 DAO 封装。

// feature_order/data/local_order_dao.dart import 'package:drift/drift.dart'; class OrderItems extends Table { IntColumn get id => integer().autoIncrement()(); TextColumn get orderId => text()(); TextColumn get title => text()(); RealColumn get amount => real()(); DateTimeColumn get createdTime => dateTime()(); }

关于数据库迁移，我强烈建议在项目早期就定好迁移策略，不要拖到发版后再补。Drift 的迁移方案是在MigrationStrategy里写onUpgrade逻辑，每加一张表或改一个字段，必须同步更新版本号，并写对应的createTable或alterTable语句。我在项目里会写一个schema_version单例，每次启动时比对当前版本和目标版本，做增量迁移。

4.4 数据同步时序：避免架构里最常见的“脏读”问题

最后聊一个我在多模块项目里踩过的大坑——不同业务模块同时修改同一份用户数据，导致内容不一致。

举例：用户在修改头像页面（属于feature_profile）上传了新头像，但订单列表页（属于feature_order）展示的收货人信息还是旧头像，因为订单页面的缓存是新建的，只存了本地旧快照。这个问题的根源是订单模块和用户模块各维护了一份用户信息的副本。

解决思路：统一数据入口和状态广播。用户信息只允许通过UserInfoProvider读取，任何模块修改了用户信息，必须调用统一的UserController.updateUserInfo()，这个 Controller 会同步刷新本地保存在 SQLite 里的用户表，同时通过事件总线发出UserInfoChangedEvent。所有监听该事件的模块收到通知后，自动重新读取最新数据、刷新界面。这样物理上不可能出现两块副本各自演进的情况。

5. 自动化构建、测试与持续集成

5.1 模块化带来的编译优化技巧

多包结构下，编译优化有几个可以立刻见效的点。

第一，使用 melos 管理多包。melos 是 Flutter 社区里最流行的 monorepo 工具，可以批量执行各包的pub get、analyze、test，还能自动生成包之间的依赖图。我常用的命令是melos bootstrap，它会把 packages 下所有模块连接起来，省去手动逐个flutter pub get的麻烦。

第二，让 feature 包尽量不使用相对路径之外的文件系统资源。如果你的每个 feature 包依赖core，在pubspec.yaml里一定要写成core: { path: ../core }。这样 melos 可以识别依赖关系，构建系统能按顺序编排，避免增量构建时重复编译。

第三，开启 Dart 的编译缓存和增量构建。Flutter 本身有--obfuscate和--split-debug-info这些用于发布包的参数，但开发模式下，记得合理配置忽略文件，保证flutter run时能使用上次的增量产物。

第四，比较大的项目可以考虑在 CI 上为每个 feature 包单独跑构建任务，这样能快速定位到底是哪个模块的编译报错。

5.2 测试金字塔：从单元测试到端到端测试

模块化架构的另一个红利是测试更好写了。因为每个模块的依赖都是通过抽象接口注入的，单元测试根本不需要去启动整个 App。

我自己习惯按相对优先级分配测试资源：

• 单元测试：覆盖 Repository 逻辑、状态管理 Controller 的输入输出、工具函数。这些测试跑得最快，适合放在 MR 合并前。
• Widget 测试：覆盖页面组件的渲染结果、按钮交互回调，尤其是core层封装的基础组件，像ErrorPage、SkeletonLoader。
• 集成测试：在真机或模拟器上跑核心链路（登录、下单、支付回调），这层最贵，所以只覆盖高价值流程。

这里有个经验，给新写的状态管理 Controller 写测试时，不要直接去setState里初始化一个虚拟的数据快照，而是用ProviderContainer加上 override 的方式注入真实的 Repository 假实现，这样断言逻辑才真正覆盖到了状态流转。写起来也更接近业务语义。

5.3 持续集成与持续交付的配置示例

CI/CD 我用的是 GitHub Actions。模块化项目在 CI 上最大的优势是并行：每个 feature 包可以单独跑 lint 和 test，不用像单仓那样等所有测试跑完。

下面是一个核心 workflow 的关键配置片段，权重是把项目里各个包拆开并行检查：

name: CI on: pull_request: types: [opened, synchronize] jobs: melos_bootstrap: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: subosito/flutter-action@v2 with: channel: 'stable' flutter-version: '3.27.4' - uses: bluefireteam/melos-action@v3 - name: Run tests working-directory: . run: melos run test:ci

注意flutter-version要固定到你经过验证的版本，不要用 latest，这能避免 Flutter SDK 自动升级引发的构建产物不一致问题。发版流程我用语义化版本号：feature 包的pubspec.yaml版本号递增，CI 检测到版本变化后自动打 Git Tag，生成变更日志，并触发 Android 和 iOS 的构建发布。

5.4 一个真实的坑：Android 构建环境问题

标题相关的热词里有一条提到“unable to find suitable visual studio toolc”，虽然这个词组更多是 Windows 桌面端 C++ 工具链的问题，但我在 Android 构建上遇到过类似症状，这里一并分享。

现象是flutter build apk报错，提示找不到某些 NDK/CMake 相关工具，或者是 Gradle 配置冲突。根因往往是 Flutter 版本升级后，Android Gradle Plugin（AGP）与 SDK 版本不匹配，或者项目里某些原生插件依赖了较老的 NDK。

排查思路如下：

1. 先看android/settings.gradle里面声明的 AGP 版本和 Gradle wrapper 版本是否在当前 Flutter SDK 的兼容范围内。
2. 确认android/app/build.gradle里的namespace已正确配置，没有拼写错误。
3. 如果项目引用了自定义原生代码，检查 NDK 版本是否显式指定，不要依赖全局环境的默认值。

android { namespace "com.example.myapp" compileSdk 35 defaultConfig { applicationId "com.example.myapp" minSdk 23 targetSdk 35 versionCode flutterVersionCode.toInteger() versionName flutterVersionName ndkVersion "27.0.12077973" // 显式指定 } }

这个问题排查过之后，你会发现 Flutter 的错误提示其实很有引导性，但前提是要有清晰的模块间依赖管理，否则升级 Flutter SDK 会变成噩梦——你不知道哪个功能包会对构建环境产生未知影响。

6. 常见问题与排查技巧实录

6.1 路由注册遗漏导致的 404

模块多了之后非常容易出现一个问题：你信心满满地写完一个新页面，跳转时却进了错误页。先确认两点：第一，AppRouter的合并 route 列表里是否追加了对应的GoRoute；第二，路径名是否与其他模块产生了冲突。

我建议在core/router里维护一张路由注册清单表，每个 feature 模块加一个 README 或者在注释里说明自己注册了哪些 path。人肉记忆不可靠，有清单之后，CI 甚至可以做自动检测，对比实际注册的 route 数量与清单中的预期数量，不匹配直接失败。

6.2 Riverpod 的 Provider 覆盖顺序问题

Riverpod 3.x 的overrideWithValue特性比较灵活，但多人协作时容易出现“我以为覆盖了，其实被别人的 override 抢先了”的情况。

举例：feature_order的测试里，你可能想把orderRepositoryProvider替换成 fake 实现，但测试入口文件里已经全局 override 了一个真实实现，导致你的 override 被忽略。这背后其实是 Riverpod 的作用域优先级策略，默认情况下，越后覆盖的优先级越高，而不是调用栈越深越高。

解决方案是在测试里显式创建独立的ProviderContainer，不要去动全局容器。同时把测试入口的 override 逻辑抽到单独方法里，通过参数控制哪些被禁用。

6.3 多包版本冲突：两个 feature 依赖不同版本的同一库

模块化项目最头疼的依赖横纵链是：feature_auth用了flutter_screenutil: 5.8.0，feature_order用了flutter_screenutil: 6.0.0。虽然 Flutter 的 pub 会尝试解析共同的兼容版本，但如果两个版本之间真的不兼容，编译阶段就会爆炸。

我的处理建议是：在pubspec.yaml根目录统一锁定核心第三方库的版本，所有 feature 包只允许引用根配置里的版本，不允许各自指定不同的 major 版本。而melos run dependencies-check可以扫描各包的依赖树，发现版本冲突立刻上报。

6.4 性能与内存：模块化不是忽略性能的借口

有些人觉得模块化之后，很多 Provider、Controller 常驻内存，反正全局态要是多次创建又销毁会更浪费。这里要澄清一个概念：能用局部 state 管理就不要升格为全局 Provider。

在订单列表页里，一个PageController管理列表翻页就是局部状态，搞成全局的纯属给自己埋炸弹。模块化架构的高阶玩法是给不同模块设置不同的生命周期，比如核心登录态模块随 App 启动而常驻，某个业务页面模块在退出后自动 dispose。

6.5 热重载与热重启的玄学问题

模块化之后有一个让团队反复困惑的事：改完某个 feature 包里的代码，点了r热重载，发现改了等于没改，或者产生完全不可预期的界面状态。

这个问题多是热重载的保守策略导致的。前面提到有状态数据存在StatefulWidget或全局 Provider 里，热重载并不会销毁重建它们，于是旧状态残留覆盖了新逻辑。我的建议是：涉及数据模型变更、Provider 顶层覆盖变更时，不要用r，直接用R（热重启）。涉及 UI 微调纯样式时，才放心用r。

6.6 常见错误速查表

这些坑基本覆盖了从模块化改造到日常维护的绝大多数情况。我见过不少团队，架构设计的时候信心满满，最后死在不经意的版本冲突和状态残留上，所以整理成表格放在这里，项目接入时可以当一份自查清单用。

经验收尾：这套架构落地时最值得坚持的三件事

开头聊过项目从混乱走向结构化的过程，这里我想以个人体会把最关键的几条建议说透。

第一件事，强制模块边界比追求最新技术更重要。Riverpod、go_router 这些工具选型当然重要，但真正让架构活下来的是“业务模块之间不互相 import”这条硬规矩。可以借助多包结构在物理上做强制校验，再通过 CI 自动化检查来兜底，光靠自觉迟早破功。

第二件事，从一个最小闭环开始改造，不要尝试一次性重构全部代码。如果一个老项目里已经有 60 个页面，别想着一个月内全部迁到新架构。我通常的路径是：先把core和shared抽出来，然后挑一个改动最少的业务模块（比如订单列表）做 Pilot，验证编译时间、开发体验、测试友好度都达到预期后，再逐步把其他模块迁移进来。这种方式能显著降低推行阻力——毕竟团队不看到实际收益，很难接受架构层面的折腾。

第三件事，重视失败路径的设计。模块化架构里面的成功路径往往很容易写通，真正的复杂度在网络异常、Token 过期、数据库迁移这些分支里。建议把异常处理策略、重试机制、缓存兜底策略用文档固定下来。我看到过不少项目，主流程流畅，一遇弱网就满是白屏和闪退，很大程度上就是忽略了失败路径的精细化设计。

这套架构在我目前负责的两个企业级 Flutter 项目里已经稳定运行了半年以上，并行开发效率和线上故障率都有明显改善。如果你正在考虑 Flutter 项目的模块化改造，可以从标题里这个“企业级”定位出发，先搭好 core 层，再把路由与状态管理统一起来，不用追求一步到位，迭代着完善就好。