张赫尔开头
聊到 Flutter 项目结构，很多人第一反应是“这不就是个文件夹摆放问题吗”，但真正经历过两三个版本迭代、团队从一个人变五六个人、业务从单一模块拆成十几个功能域之后，就会明白——项目结构直接决定了每一次需求从提出来到上线要付出多少代价。我在过去的几年里接手过好几个 Flutter 项目，有的三个月就乱到不敢动，有的迭代两年多依然能保持一天多次发版且几乎零回归。区别不在于谁写代码更猛，而在于一开始有没有把结构当回事。
这篇文章就围绕 Flutter 项目结构怎么设计这件事展开，结合我实际踩坑和重构的经验，聊聊从目录分层、状态管理、依赖注入到模块解耦的一整套思路。无论你是刚入坑 Flutter 的新手，还是已经在维护一个中大型 Flutter 项目的老手，这篇文章里的内容都能帮你在下次重构或者新项目冷启动时少走不少弯路。尤其是标题里那四个字——“长期迭代”，这四个字才是关键，因为短期能跑通的结构很多，能撑住两年不崩的结构却不多。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
1. 项目结构设计的底层逻辑
1.1 先搞清楚，我们到底在防什么
很多开发者在设计项目结构的时候，第一反应是“照着一个开源项目抄”，或者“按我之前做 Java Web 的习惯套过来”。这种做法不能说错，但很容易忽略一个根本问题——项目结构不是一个静态的文件摆放方案，它本质上是一套应对业务变化和团队协作的规则。你防的是什么？是需求变更带来的连锁修改，是新同学加入后乱放文件，是某个模块膨胀后拖垮整个项目的编译和维护效率。
在 Java Web 的标准目录结构里，我们习惯于按技术层次来划分，controller、service、dao、entity 各归各的。这样分在纯后端的场景下没太大毛病，因为业务对象相对稳定，请求-处理-存储的链路也相对固定。但 Flutter 是一个 UI 框架，它的核心产出是界面和交互，如果你照搬后端的“按层分包”思路，很快就会发现自己陷入了无穷无尽的跨目录跳转。有时候改一个按钮的点击逻辑，要同时打开 model、viewmodel、service、widget 四个目录里的文件，而它们之间又没有强关联，纯粹是靠命名去“意会”。
所以设计 Flutter 项目结构的第一步，不是急着建文件夹，而是先想清楚你的业务形态是什么。你是做一个工具类 App，功能独立且界限清晰；还是做一个业务复杂的电商或者社交类 App，功能之间交叉引用非常多？不同形态对应的最优结构是完全不一样的。
1.2 长期迭代的核心矛盾
长期迭代的项目，本质上要解决四个核心矛盾。第一个是业务复杂度和代码可读性的矛盾，业务越做越多，如果结构不做收敛，代码就会像滚雪球一样越滚越乱；第二个是团队协作效率和代码所有权之间的矛盾，多人开发时每个人都希望有自己的一块“领地”，但领地分得太碎又会导致接口不一致；第三个是技术升级和存量代码之间的矛盾，Flutter 版本一年升级好几次，你的结构如果不支持渐进式迁移，每次升级 Flutter SDK 都是一次爆肝；第四个是复用需求和耦合风险之间的矛盾，你希望公共组件和工具方法能被复用，但如果设计不好，这些公共部分就会变成一个什么都能往里塞的“垃圾场”，最终被大量业务代码反向依赖，牵一发而动全身。
一个好的项目结构，应该在设计之初就给这四个矛盾给出明确的答案。而不是等问题出现后再靠重构去补课。补课不是不行，但补一次课的成本往往是你想象不到的高，尤其在业务压力很大的团队里，重构优先级永远排在需求后面。
2. 主流结构方案对比与选型
2.1 按层分包（layer-first）的适用场景
按层分包是最容易理解的一种结构，根目录下面建 screens、widgets、models、services、utils 这样的文件夹，所有页面丢在 screens 里，所有组件丢在 widgets 里，所有接口请求丢在 services 里。这种方案对小型项目、原型验证、工具类 App 来说完全够用，因为它足够简单，团队成员不需要任何培训就能找到文件。
但它的致命问题在于，一旦业务量上来，每个层里的文件数量会急剧膨胀。比如一个电商 App，screens 目录里可能堆了一百多个页面文件，它们之间到底什么关系，路由怎么流转，完全看不出来。更糟糕的是，按层分包天然鼓励跨层依赖，screens 里的页面可以直接 new 任意一个 models 或 services 里的东西，没有任何边界约束，最终所有代码纠缠成一团乱麻。
我见过不少从初创期走过来的项目，都是这种结构，到后期几乎没人敢动里面的代码。因为每个文件都可能被十几个其他地方引用，改了一个 model 字段，编译的时候会炸出一片错误，而且这些错误分散在不同层里，根本没有规律可循。所以我的结论是：如果项目预计生命周期只有几个月，或者纯做概念验证，用 layer-first 没问题；但只要你想让它活过一年以上，趁早放弃。
2.2 按功能分包（feature-first）为何成为主流
按功能分包，也叫做 feature-first 或者 module-per-feature，核心思路是围绕业务功能而不是技术类型来组织目录。每个功能（比如登录、首页、购物车、个人中心）拥有自己独立的一套目录，内部再可以按需要细分为 widgets、models、pages、providers 等子目录。这种结构带来的最大好处是高内聚、低耦合。修改购物车功能时，你基本只需要在购物车目录内部操作，不需要跳来跳去，也不会误伤到登录功能。
feature-first 还有一个Hidden benefit，就是它天然支持多人并行开发，每个团队成员可以认领一个或几个功能模块，互相之间不需要频繁改同一个目录下的文件，合并冲突的概率大幅降低。而且后续做模块化拆分、独立编译、甚至插件化的时候，按功能划分的目录结构都有一个自然的演进路径。
主流开源项目里，Very Good Ventures 的 very_good_cli 推荐的 Flutter 项目模板、flutter community 里大量中大型项目的实践，几乎都采用了 feature-first 的变体。可以说按功能分包已经成为了 Flutter 社区里中大型项目的事实标准。
2.3 我偏好的混合模式：feature-first 为骨架，core 层收拢公共能力
纯 feature-first 也不是没有缺点。如果处理得不好，容易走向另一个极端：每个 feature 里都有一套自己的网络请求封装、自己的工具函数、自己的页面基类，造成大量重复代码。所以我们不能机械地把所有东西都塞进 feature 里，必须有一个横向的公共层来收拢这些通用能力。
我常用的结构，简单概括就是 feature-first 为骨架，加上一个 core（或者叫 common、shared）层来收拢公共能力。Feature 目录里放跟业务强相关的代码，core 目录里放跟业务无关的代码。这个取舍的标准是：如果这段代码换个 App 还能直接用，那它就应该放 core；如果它换一个场景就不好用了，说明它跟业务绑得太紧，应该留在 feature 里。
这个混合模式不是我的发明，它在很多成熟的 Flutter 项目里都有应用，包括一些大厂开源的项目。它的核心价值在于既保持了 feature 的独立性，又避免了公共逻辑的无序分散，长期迭代下来，整个项目的可维护性会非常好。
3. 一套可直接落地的目录结构
3.1 顶层目录划分与职责说明
下面这个是我经过多轮实战验证后，目前比较推荐的一套目录结构，适合中大型 Flutter 项目：
text复制lib/
├── main.dart
├── app.dart
├── core/
│ ├── constants/
│ ├── errors/
│ ├── extensions/
│ ├── network/
│ ├── router/
│ ├── theme/
│ ├── utils/
│ └── widgets/
├── features/
│ ├── auth/
│ ├── home/
│ ├── profile/
│ └── ...
├── shared/
│ ├── data/
│ ├── domain/
│ └── presentation/
└── bootstrap/
每个顶层目录的职责必须非常清晰：
- core/：跟业务无关的底层能力层。网络封装、路由表、主题、通用组件、工具函数都放这里。core 绝对不允许反向依赖 features 里的任何代码。
- features/：按业务功能拆分的一等公民目录，每个 feature 是一个完整的业务闭环。什么时候一个功能配得上一个独立目录呢？我的标准是，当这个功能有自己独立的 UI、业务逻辑和模型，并且预计会持续迭代时，就直接给它建一个 feature 目录。
- shared/：介于 core 和 features 之间的一层。有些代码跟业务有关系，但又被多个 feature 共享，比如登录用户模型、通用的列表页组件、分页逻辑等，这些放 shared 里比放 core 里合适，因为放 core 会导致 core 也慢慢被业务污染。
- bootstrap/：负责启动初始化和环境配置。实际项目中我会把环境配置（开发、测试、生产）相关的代码单独拆出来，避免 main.dart 变成一个大杂烩。
这套结构并不是说你必须原样照搬，很多人会根据自己项目的实际情况做调整。比如有的团队会把 network 从 core 里拿出来，做成一个独立的 package；有的团队会引入 melos 做多 package 管理，每个 feature 独立成 package。但万变不离其宗，核心思想是一样的：业务聚合，公共下沉，依赖单向。
3.2 feature 内部的文件组织规则
Feature 目录内部怎么组织，是另一个容易踩坑的点。我给 feature 内部定的规则是，不强制统一二级目录，而是根据这个 feature 的复杂度来决定。一个比较通用的做法是每个人建议保持以下结构：
text复制features/
└── profile/
├── data/
│ ├── models/
│ ├── repositories/
│ └── datasources/
├── domain/
│ ├── entities/
│ └── repositories/
└── presentation/
├── pages/
├── widgets/
└── controllers/
data 层负责跟远程或本地数据源打交道，domain 层定义业务实体和仓库接口，presentation 层放页面、组件和状态控制。这个分层其实借鉴了 clean architecture 的思想，但我不建议在小 feature 里硬套完整的三层结构。比如一个只有两个页面、一个网络请求的简单 feature，你硬给它建 data/domain/presentation 三层，反而会让简单的事情变复杂。我自己的原则是，对简单的 feature 允许直接平铺放四个文件（page、controller、model、repository），等它复杂度上来了再做分层重构。
所以在实际工作里，我会在团队规范里写清楚：每个 feature 内部结构“按需分层”，但任何 feature 都不允许出现文件夹里只有一个文件的“空壳目录”，也不允许出现文件数量超过 15 个还全部平铺在根目录下的情况。这两个约束一加，基本就不会出乱子。
3.3 core 层应该放什么，不该放什么
Core 层是长期迭代中维护成本最高的一层。很多项目死在 core 层变成了一个“垃圾回收站”，什么东西都没有归属感，就丢进 core 里。我在设计 core 层的规范时，有一条铁律：core 层只放跟业务零相关的代码，凡是包含业务语义的东西，一律下沉到 feature 或 shared 层。
举例说明，一个通用的网络请求封装，它只负责发起 HTTP 请求、处理超时、序列化响应，不关心请求的是用户信息还是商品列表，那它应该放 core/network/。但是如果你在 network 封装里直接写了一个获取用户信息的 API——这就会导致 core 层出现业务概念，比如 User 模型。一旦出现这种苗头，要立刻把它挪到对应的 feature 里。长期以往，core 层的稳定度就会非常高，因为它没有任何业务变化能触及到它，天然地符合“稳定依赖”的原则。
Core 层通常我会放这几个大块内容：常量管理（比如 API base URL、缓存 key、正则表达式），错误处理体系（统一的异常类型和错误码映射），扩展方法（String、BuildContext、DateTime 的扩展），路由配置（全局路由表），主题系统（颜色、字体、间距），通用组件库（空状态、错误页、加载组件），以及工具函数（日期转换、文件大小格式化等）。每一块都应该是无状态的，或者说只跟 Flutter 框架本身有关，跟业务无关。
3.4 命名规范与常量管理
项目结构光有目录还不够，命名规范同样决定了一个项目的长期可维护性。我见过最让人痛心的代码不是逻辑写得烂，而是命名毫无章法，打开一个目录，文件夹的名字有英文有拼音有缩写，文件命名有的下划线有的驼峰，根本看不出来它是什么功能。
我在实际项目中强推的命名规范是这样的：目录和 Dart 文件用小写字母加下划线的 snake_case，类名和类型名用大驼峰 UpperCamelCase，变量和方法用小驼峰 lowerCamelCase。这些都是 Dart 社区的标准规范，但我们团队在文件层级上做了更严格的约定——每个 feature 内部的子目录，必须能直接反映出这个文件的职责层次。比如 presentation 目录下只放页面和组件，data 目录下只放跟数据源相关的代码，不允许把数据请求的代码写到 presentation 下的某个文件里。
常量管理也是一个值得聊的事情。很多项目里，同样的状态码、错误提示、接口路径，出现在十几个文件里，每次改动都要全局搜索替换。我们现在的做法是，所有常量按功能域收拢到 core/constants 目录下，并且用类的静态常量来组织，比如 AppConstants、NetworkConstants、CacheConstants 三个类，每个类里再用 const 定义具体值。这里的核心原则是：常量如果有业务含义，就不要直接裸定义在文件里，而是通过常量类来引用，方便后续修改时集中管理。
3.5 路由注册的演进路线
路由是一个很容易被低估的设计点。小项目里用 Navigator.push 直接传一个 MaterialPageRoute，看起来没什么问题，但一旦页面数量超过二十个，这种写法会让页面之间的跳转关系变得极其散乱。再加上 deep link、Web 端 URL 支持、状态恢复这些需求，手写 Navigator 的方式根本顶不住。
我们目前的方案是使用 go_router 做统一的路由管理。在使用 go_router 时，路由表集中在 core/router 目录下，每个 feature 注册自己的路由路径。这里有一个实战经验：不要在路由表里直接 import feature 内部的页面文件，应该通过 feature 提供的一个路由扩展类来间接注册。这样 core 和 feature 的依赖关系就只能是 feature 依赖 core，core 绝对不会反向依赖 feature，架构的依赖方向就被守住了。
如果你底子薄一点，还没上 go_router，那我建议尽早做迁移。实测下来 go_router 对 deep link、Web 端 URL 的支持、重定向逻辑、嵌套路由的支持都很成熟。从 Navigator 迁移到 go_router，基本上不是“要不要”的问题，而是“什么时候做”的问题。越早做，改动成本越低。
4. 状态管理与响应式数据流设计
4.1 状态管理选型不只是技术偏好
聊 Flutter 项目结构，有一个绕不开的话题就是状态管理。很多人把状态管理单纯看作一个技术选型问题，用什么库、怎么写更酷，但实际上状态管理的选择会深刻影响你的项目结构——因为它决定了你的页面、业务逻辑、数据层之间怎么流转数据。
Flutter 的状态管理方案五花八门，从最早的 setState、InheritedWidget，到 Provider、Riverpod、Bloc、GetX，每个方案都有自己的拥护者。我对这些方案的理解是，纯 setState + InheritedWidget 适合非常小的项目，Provider 适合中小型项目，Riverpod 和 Bloc 适合中大型项目。GetX 虽然用起来爽，但它的全局性太强（Controller 混乱挂载、依赖全局状态），在多人团队里会让代码的可读性和可维护性急剧下降，我一般不推荐在需要长期迭代的项目里使用。
如果你问我个人偏好，我会选 Riverpod。它比 Bloc 轻量，但比 Provider 更安全和可测试，编译期就能发现大部分依赖问题。Riverpod 的 Provider 是全局声明、按需读取的，这种模式天然鼓励你把状态跟 UI 解耦，同时不会像 Bloc 那样要写大量的 event/state 样板代码。选它的另一个原因是 Riverpod 对 Flutter 的“重建优化”做得很细，粒度可以控制到单个组件，这在长期迭代、UI 越来越复杂的阶段会节省很多性能优化成本。
4.2 数据流方向：单向还是双向
项目结构设计得再好看，如果数据流方向是乱的，一样会被过快改死。我观察到的大量 Flutter 项目，在早期都觉得“这个页面自己管自己的状态就好”，但后续一旦出现页面间共享数据、跨模块通信，整个数据流就开始失控。UI 直接修改全局状态、页面相互监听别人的 controller、数据在多个地方被缓存，这些问题一旦蔓延，排查问题的难度是指数级上升的。
我在项目中强制推行的是单向数据流。简单来说，界面只负责展示和触发事件，事件通过 controller 或 notifier 去调用业务层方法，业务层负责更新状态，状态变化后再通过 Riverpod 或 Bloc 的监听机制反向驱动界面刷新。这个循环的方向永远是一致的，不允许出现页面 A 直接修改页面 B 状态的写法。
为了落地这个约束，我们在结构上做了配套设计：每个 feature 的 presentation 层只关注“怎么展示”和“用户做了什么”，真正的数据处理放在 data 和 domain 层，并且通过 controller 或 provider 暴露给 UI。如果 UI 层需要访问其他 feature 的数据，必须通过该 feature 对外暴露的 provider 接口来获取，不能直接去操作对方的内部状态。这样的好处是，任何一个数据变化，你都能顺藤摸瓜找到起点的位置，不会陷入“依赖地狱”。
4.3 领域模型 vs 页面模型，别混为一谈
在长期迭代中，模型设计是另一个大坑。很多团队的项目没有领域模型和页面模型的区分，接口返回的数据结构直接拿来即用，页面渲染时直接在 model 上做各种加工和展示逻辑。这种写法在接口不稳定的情况下（而现实是接口几乎一定会变）会导致非常高的修改成本——后端改一个字段名，前端所有用到这个字段的页面、组件、状态、缓存，全要跟着改。
我们的做法是，在 data 层定义一个领域模型，在 presentation 层按页面需要定义展示模型（view model / dto）。页面不要直接用领域模型做渲染，而是通过一个 mapper / adapter 把领域模型转换成页面需要的展示模型。数据结构和 UI 需求之间必然存在不一致，比如一个接口返回了一个时间戳，页面要显示成“x分钟前”，这个转化逻辑就应该放在 mapper 里，而不是散落在各个页面的 build 方法里。
这个设计让后端接口改动对 UI 的影响降到了最低。只要领域模型和展示模型之间的映射关系还成立，后端怎么改字段、怎么调整嵌套结构，UI 基本可以不受影响。尤其在后端由不同团队维护、接口频繁升级的背景下，这套结构的价值会越用越明显。
5. 依赖注入与模块解耦
5.1 为什么不用手动传参来构建依赖
很多 Flutter 初学者习惯在页面构造函数里手动传入需要的 service 或 repository，一个页面 new 一个 ApiService。这种方式在小项目里没问题，但一旦项目复杂起来，手动传参会带来两个问题。第一个是构造函数会越来越长，一个页面可能要接收十几个参数，可读性和可维护性都会很差；第二个是对象的生命周期很难管理。多个页面共享同一个 Repository，如果每个页面都各自 new 一个，状态就没法共享，缓存也没法统一管理。
依赖注入（DI）就是为了解决这个问题存在的。Flutter 社区里最常用的两个方案是 get_it 和 Riverpod 自带的 Provider 容器。get_it 是一个服务定位器，可以在全局注册和获取对象实例，配合 injectable 注解和 build_runner 可以自动生成注册代码，非常方便。Riverpod 则不需要额外的路由注册，它的 Provider 本身就是依赖注入的实现，异步初始化、懒加载、状态覆写这些能力都很成熟。
我个人的做法是，小项目直接用 Riverpod 的 Provider 就够了，不引入额外的 DI 容器。但项目一旦超过几个 feature，需要一些全局单例（比如数据库实例、认证管理器）的时候，我就会引入 get_it 来管理这些生命周期较长的依赖。两者并不冲突，可以共存。
5.2 get_it 注册的模块化布局
在用 get_it 的时候，我见过很多项目把全部注册代码写在 main.dart 里，然后 main.dart 变得越来越长，几百行甚至上千行的服务注册。这种写法既不美观，也不方便定位问题。我们的做法是，每个 feature 提供一个自己的注册函数，函数接收一个 GetIt 实例，负责把该 feature 需要对外暴露的依赖注册进去。最后在 main.dart 或者 bootstrap 层统一调用这些注册函数。
代码结构大概长这样：
dart复制// features/auth/di.dart
void registerAuthDependencies(GetIt getIt) {
getIt.registerLazySingleton<AuthRepository>(() => AuthRepositoryImpl());
getIt.registerLazySingleton<AuthController>(() => AuthController(getIt()));
}
// bootstrap/dependencies.dart
void configureDependencies(GetIt getIt) {
registerCoreDependencies(getIt);
registerAuthDependencies(getIt);
registerHomeDependencies(getIt);
registerProfileDependencies(getIt);
}
这样的注册方式有两个好处：第一是每个 feature 的依赖关系只在自己的模块内部管理，新增依赖时不需要去翻 main.dart；第二是单元测试的时候，可以只注册被测模块的依赖，不需要把整个 App 的依赖都加载进来，测试速度会快不少。
这里有一个容易忽略的细节：依赖注入的注册生命周期。用 get_it 注册的时候，要清楚地区分 registerLazySingleton、registerSingleton 和 registerFactory 的差别。被多个页面共享且希望有全局唯一状态的用 singleton，每次调用都希望拿到全新实例的用 factory。如果生命周期没想清楚，很容易出现状态串掉的 bug，而且这类 bug 特别难排查。
5.3 模块化拆分的临界点与时机
模块化是架构设计的较高追求，但盲目模块化也是项目灾难的源头。我在实际项目中见过有团队一开始就把每个 feature 都拆成独立的 Flutter package，然后用 melos 管理多包仓库。听起来很酷，但实际开发中每个 package 间的依赖升级、版本对齐、编译时间都是额外成本，对小团队来说非常不友好。
我的建议是，不要一开始就上多包。先从单包的 feature-first 目录结构做起，等项目的 feature 数量超过八九个、团队人数超过六人、编译时间明显变长的时候，再考虑把最独立、复用价值最高的 feature 拆成独立 package。拆分时优先拆那些依赖关系最清晰、被其他模块引用极少的功能，比如登录、埋点SDK封装、设计系统组件库。通过 melos 做多包的依赖管理和统一命令，项目依然能保持整体的一致性。
这里补充一个判断依据：如果你发现修改一个 feature 内部的代码，经常需要同步修改另一个 feature 的文件，说明这两个 feature 之间的边界划错了。要么合并成一个 feature，要么把共享部分往上提取到 shared 或 core。模块化拆分的真正目标不是“每个功能一个包”，而是让模块间的依赖关系简单、明确、可预期。
6. 常见反模式与避坑清单
6.1 让 App 越来越难改的典型问题
长期维护 Flutter 项目，有几个反模式几乎每个团队都会踩到。第一个是单向依赖变成双向依赖，开始的时候 feature A 依赖 feature B 的某个方法，后来 feature B 也需要调用 feature A 的东西，在某些团队里为了图省事，直接在两个 feature 里互相 import，形成了一个环。Flutter/Dart 编译器对这种循环依赖的检查能力有限，一开始不会报错，但随着两边代码越写越深，你会发现自己改 A 的时候总是要担心 B 那边会不会炸。
第二个反模式是全局状态泛滥。很多项目为了省事，什么东西都放到全局 Provider 里。用户信息、语言设置、主题模式、当前页面状态、临时弹窗标记，全部塞进几个全局单例里。这样做的结果是任何状态的改动都可能触发大量页面的 rebuild，性能急剧下降，而且你根本不知道到底是谁改了那个全局状态。正确的做法是尽量缩小状态的作用域，能用局部状态不用全局，能在 feature 内部共享不上提到全局。
第三个反模式是“临时性”代码的残留。比如为了调试某个接口，临时在某个页面里写了一段解析 JSON 的逻辑、放了一个调试按钮，或者为了方便测试屏蔽了某个登录逻辑。这些代码因为没有归属感，也很难复用，后续又没人清理，时间一长就变成垃圾代码的温床。我们的做法是，所有临时调试代码必须带一个统一的 // TODO: remove before release 标记，code review 阶段发现这类代码直接一票否决。
6.2 排查与重构切入方法
如果项目已经乱成一团，该怎么切入重构？我的经验是，绝对不要火急火燎地全面推翻重来，那是灾难。先做体检，搞清楚目前的依赖关系。Dart 生态里有几个好用的工具，比如 depend_on_analyzer 可以帮你分析模块间的依赖方向，dcdg 可以生成类依赖图。先通过这些工具把全项目最糟糕的依赖环找出来，从破坏依赖方向的部分开始切。
然后是从“稳定层”开始整理，先把 core 层彻底隔离出来，保证它不再依赖任何 features 层的代码，再把所有页面级的业务逻辑下放到对应的 feature 里。这个阶段可以重命名、移动目录，但不要动具体功能和 UI，保持行为一致。每做完一次移动，跑一遍全量测试和编译，确保没有破坏任何东西。维持“可编译”状态的回购，在团队里更容易得到支持。
实际上，重构的本质不是把文件移动到正确的地方，而是把依附关系调整到合理的状态。只要依赖是清晰、单向的，文件放哪个文件夹其实影响不大。所以重构的操作顺序永远是：先修依赖，再动目录。
6.3 团队协作中的 Git 与代码规范
影响项目长期迭代的另一个隐形因素是团队协作规范。项目结构是骨架，协作规范就是血液。我们在使用 Git 时，会约定每个 feature 对应一个独立分支，分支名称用 feature/auth-login 或者 feature/profile-page 这样的格式，方便后期的回溯和查找。合并请求里必须要说明这个 MR 改了哪些 feature、影响了哪些潜在模块，并且尽量做到一个 MR 只改一个 feature，避免把不相关的改动混在一起，导致 code review 困难、回归风险上升。
代码规范方面，我们会在项目根目录放一个 analysis_options.yaml，把 flutter_lints 或者 very_good_analysis 的规范全部打开，同时自定义了几个额外的 lint 规则，比如禁止 import 其他 feature 内部的实现文件（只能 import 其公开的 provider 或接口）、禁止在 core 层出现 features 相关字符串等。这些规则靠人来记是记不住的，必须通过 CI 上的静态检查自动化卡住。
不少团队一开始图省事，对 lint 和格式化不管不顾，到了后期代码风格五花八门，新同学看老代码跟看天书一样。我的建议是，项目创建的第一天就加上严格的 lint 配置和 CI 校验，宁可前期开发稍微慢一点，也要把约束尽早建立起来。习惯一旦形成，后续维护成本会低很多。
7. 从零到一落地的实操路线
7.1 新项目冷启动的结构搭建步骤
如果你是零基础启动一个新的 Flutter 项目，我建议按下面的顺序搭结构。第一步，利用 very_good_cli 或者 flutter create 创建一个空白项目，然后手动调整 lib 目录为前面说的 feature-first 加 core 的结构。第二步，先不写任何业务代码，把 core 层的基础框架搭好，包括网络客户端的封装、统一的错误类型、主题文件、通用组件库、路由表和 get_it 的注册骨架。第三步，跑通一个最小可运行的流程，比如一个非常简单的 splash 页面和一个 home 页面，把路由、状态管理、依赖注入全链路打通。
这前三步做完，你的项目已经是一个“空壳”了，但它的地基是稳的。在这个阶段做改动成本最低，等业务真正进来的时候，你只需要往 features 里塞新的目录，不需要再动底层的框架代码。第四步才是把第一个真实业务 feature 完整地落地，包括它的 data 层、展示层、状态管理、测试，尽量把这个 feature 写得足够规范，作为后面所有新 feature 的模板。
整个过程看起来很简单，但我见过很多团队在新项目启动时，连前三步都耐不住性子，直接就开始写页面代码，结果一个月以后发现网络请求散落在各个页面里，主题颜色满天飞，项目已经隐隐散发出“难维护”的味道了。前期花两三天搭的框架，后期会几十倍地回馈你。
7.2 存量项目如何在不伤筋动骨的前提下演进
如果不是新项目，而是一个已经跑了一阵子、结构已经有点乱的项目，怎么让它平滑地演进到更合理的结构？我的经验是分四步走。第一步，先识别并隔离 core 层，把那些纯工具类、网络封装、通用组件从业务目录里抽出来，放到新 core 目录下，这个过程中不改变任何业务行为。第二步，把散落在各处的页面按业务功能归拢到 feature 目录下，这一步可能会遇到大量的移动文件和修 import 路径，但操作上并不复杂，只是需要细心。
第三步，处理重复代码，把多个页面都使用到的公共服务、共享模型、通用组件提取到 shared 层，同时注意不要让 shared 继续膨胀。第四步，也是最难的一步，逐步收敛依赖方向，把跨 feature 的直接调用改成通过 provider 或接口来间接调用。这四步做完，项目结构基本就焕然一新了。
这个过程不要期望一两个星期就完成。在业务开发的间隙，每周抽出一两个下午做一次小幅度的结构优化，持续一两个月，效果远比某一天突然推倒重来要好。因为小幅度的重构有充分的验证时间，不会出太严重的回归，而且团队成员也更能接受这种渐进式变化。
7.3 我踩过的坑与最终的体会
文章最后，说几个我记忆深刻的踩坑经历。第一个坑是早期在一个电商项目里，我信心满满地按 clean architecture 的分层来建整个项目，每个 feature 都建了 data/domain/presentation 三层，接口抽象、实现类、实体类写得非常标准。但业务跑起来之后才发现，很多简单功能根本不需要这么复杂的结构，每个网络请求都要写 entity、model、mapper、repository interface、repository impl 那一大堆代码，开发效率被拉低了很多。最后我们不得不在团队里定了一个规则，简单 feature 允许简化结构，等复杂了再补。
第二个坑是路由表集中管理带来的“过度集中”。一开始把全部路由定义在一个文件里，后面页面数量到了五六十个，一个文件里全是路由配置和 redirect 逻辑，看任何一个路由的完整事件流都要翻好久。后来改成每个 feature 自维护一个 routes.dart，只在核心路由文件里统一聚合，才彻底解决了这个问题。
第三个坑跟命名有关。有一段时间团队成员为了体现“业务边界”，在目录命名上花了大量时间琢磨，比如用户中心叫 user_center 还是 profile 还是 personal，首页叫 home 还是 dashboard，反复调整。最后我们靠一条约定终结了这个争论：目录命名以业务领域的通用词汇为准，不搞花样、不追求标新立异，符合团队习惯即可。项目结构最重要的是所有人都能一眼看懂，与其花精力在命名艺术上，不如把精力放在真正的依赖治理上。
这些坑的背后，其实都指向同一句话：项目结构是为业务和团队服务的，不是用来展示架构能力的。设计的时候多想一步，维护的时候勤快一点，长期迭代就不再是一句口号。你每写一行代码，都在给这个项目的未来投票，是让它越来越容易改，还是越来越难改，全在结构和规范这些“一开始有点烦、后面真香”的细节里。