我是怎么把一个 Flutter 项目从“大文件堆积”重构到“可维护结构”的

前言最近我对一个 Flutter 相册项目做了一轮比较彻底的重构。这个项目的问题很典型核心业务文件很多都已经 1000 行以上页面层、服务层、运行时逻辑、模型定义混在一起改一个功能经常要在超长文件里来回滚本地重构和远程新代码并行推进合并风险很高这次重构我没有走“大重写”路线而是采用了一套更稳的方式先降熵再校正语义再硬化边界。这篇文章我想完整复盘一下这个过程包括大文件该怎么拆什么适合先用 part什么必须升级成独立类如何在远程代码持续变化时把本地重构安全回放到最新基线如何避免“重构做着做着把行为改坏了”一、问题不是“文件大”而是“职责失控”一开始最明显的问题是文件体量失控比如story_generation_orchestrator.dartsemantic_query_parser_service.dartalbum_page.dartstory_video_page.dartai_service.dartphoto_service.dartllm_service.dart这些文件的问题并不只是“长”而是多种职责堆在一起页面层常见问题一个页面文件里同时塞了页面状态业务查询弹层子组件图片加载调度导出逻辑动画/VFX 逻辑Service 层常见问题一个 service 文件里同时塞了对外 API配置常量生命周期调度逻辑单次任务处理持久化fallback模型定义这种结构的最大问题不是不好看而是维护成本、冲突概率和回归风险一起暴涨。二、第一阶段先做纯结构重组不碰行为第一阶段我的目标非常明确不先优化算法不先改功能不先追求“优雅架构”先把结构层次拉开。具体做法1. 先拆最肥的文件优先动那些已经天然分层、但还挤在一个文件里的模块。例如story_generation_orchestrator.dart拆成generationlocal runtimestory buildermodelssemantic_query_parser_service.dart拆成constantsshort routelocal fallbackllm parsermodelsalbum_page.dart先拆边缘大块tag browserdeferred image loading这里有个经验很重要不要一上来就拆页面主状态线先拆“边缘但独立”的大块。这样风险最低收益反而最快。三、为什么我没有一开始就强行独立类而是先用 part很多人看到这里会问既然都要重构为什么不直接抽成独立类答案是重构也要分阶段。part 适合什么场景part 特别适合第一阶段的“结构重组”改动小不需要立刻改可见性不需要一次性设计完整接口可以快速把阅读压力分散掉编译风险低比如这些页面层模块album_page_tag_browser.dartalbum_page_deferred_image.dartstory_video_page_view.dartstory_video_page_image.dart它们仍然强依赖宿主 State这时硬抽独立类往往只会造成构造参数爆炸状态传递更加绕代码变碎但不一定更清楚所以页面层我保留 part这是刻意的。四、第二阶段从“拆文件”升级到“收边界”当主文件已经瘦下来以后下一步就不能只盯着行数了。这时真正重要的问题变成谁拥有状态谁负责流程谁负责单次处理谁有最终写库权也就是不是继续拆文件而是开始硬化边界。五、AIService从“一个超大 service”拆到“状态机 runner processor”这是这轮重构里最关键的一步。原来的问题ai_service.dart 里混了太多东西lifecycle运行状态并发调度单图处理持久化profilercaption 异步队列这种文件最怕的不是长而是每一层都能顺手改全局状态。第一步先拆 phase先把它分成ai_service_lifecycle.dartai_service_pipeline.dartai_service_photo_processing.dartai_service_models.dartai_service_profiler.dart这一步只是把层次拉开。第二步抽出 AiPipelineRunner接着我把 analyzePhotosInBackground 的主流程抽成了一个内部执行体宿主 AIService 保留生命周期和总状态AiPipelineRunner 负责批处理流程它的意义不是“又少了几百行”而是宿主开始像状态机runner 开始像真正的批处理执行器。第三步抽出 AiPhotoProcessor再往下我把单图处理改造成输入_AiPhotoProcessingRequest输出_PhotoProcessResult并把原本在单图处理中“顺手做掉”的东西收回宿主持久化异步 caption 入队现在更接近下面这种关系AIService管生命周期、总状态、最终收口AiPipelineRunner管批处理调度AiPhotoProcessor管单图处理这是我觉得真正有价值的结构变化。六、PhotoService从胖 service 变成宿主壳层photo_service.dart 的处理方式也类似。我先拆成几个职责带modelsscanaccessai resetasset build但这还只是“拆文件”。真正有意义的是后续两步1. 抽出 PhotoScanCoordinator把扫描主流程从宿主里拿出来权限检查相册选择global fallback扫描计划准备但是我没有让它直接接管最终写库。PhotoService 仍然保留对外入口最终写入summary 收口这样 PhotoScanCoordinator 的定位就很清楚它负责“发现和协调”不是“全权接管所有后续动作”。2. 抽出 PhotoAssetBuilder再把资产到实体的构建逻辑抽出去PhotoScanCoordinator决定扫什么PhotoAssetBuilder决定怎么把资源变成 PhotoEntityPhotoService决定怎么落库、怎么收口这一步之后PhotoService 才真正像宿主壳层。七、LLMService先分职责再保留调用稳定性llm_service.dart 我没有直接抽成特别重的客户端架构而是先按职责拆成titlescompletionstory/music原因很简单这类模块的 prompt 和输入输出结构很容易继续变化。如果一开始就做太重的抽象后面接口一变重构成本反而更高。所以这里我采用的策略是先职责清晰再等接口稳定后决定是否继续硬化。八、一次非常关键的工程动作本地重构如何安全回放到远程最新代码这次重构还有一个现实问题本地我已经重构了一大批核心文件远程同一时间又推进了新的功能开发两边改到了同一批核心文件这种情况下最忌讳直接硬 merge。我最后采用的是这套流程1. 先完整备份本地工作先把当前本地成果存到一个独立分支和提交里。2. 把 master 更新到远程最新先拿到远程基线。3. 从最新 master 再开一个集成分支例如codex/replay-local-refactor-v24. 再把本地重构“受控回放”不是直接乱 merge而是先看重叠文件范围判断哪些是服务层可安全回放哪些是 UI 热点先延后处理在集成分支上做受控 cherry-pick / 回放最后的策略很重要我最终选择先回放 service 层重构先保留远程最新的 UI 页面版本等服务层集成成功后再单独处理 UI 热点这比“什么都一起 merge”稳太多了。九、我如何验证这次重构没有把项目搞崩这次我把验证分成了三层1. 全项目静态检查不再只 analyze 单个文件而是直接跑flutter analyze这是为了防止“局部通过、全局炸掉”。2. 代码生成远程新功能引入了新的 Isar 实体我补跑了build_runner因为有时候不是重构本身出错而是生成文件没跟上。3. 编译链验证最后再做一次真实构建flutter build apk --debug这一步特别重要因为analyze 通过不等于一定能完整编译Flutter 多平台项目很容易在真正构建时暴露问题最终这条集成分支能成功产出 APK说明至少 Android 编译链已经恢复健康。十、这次重构里我最认同的几个原则1. 先降熵再谈优雅先把结构理顺比一开始就追求“完美架构”重要得多。2. 页面层和 service 层不要用同一套重构节奏页面层先 partservice 层尽快走向 helper / runner / processor3. 一次只硬化一个边界不要同时把 lifecycle、pipeline、processor 全重写。一次只升一个职责块最稳。4. helper 不要偷偷改宿主核心状态如果一个 helper 看起来独立了但还能随手改宿主一堆状态那它并没有真正解耦。5. “重构”和“行为修正”一定要分清比如我在某次处理中让 _localSections 真正参与预览期人脸对齐这就是行为变化不该伪装成纯结构重组。6. 远程协作时先保住检查点能先形成一个“可编译、可保存、可回退”的检查点比继续无休止本地打磨更重要。十一、这轮重构之后项目真正变好了什么不是“文件变短了”这么简单。真正变好的是下面这几件事主文件开始像“入口”而不是“垃圾堆”业务层次开始能一眼看出来改一个模块时扫全文件的概率降低了远程协作下的冲突处理更可控后面继续演进时有明确的下一步方向一句话总结就是这个项目开始从“靠熟悉代码的人撑着维护”逐渐变成“靠结构维护”。十二、后续还会怎么继续这次我没有把所有页面热区都一起硬回放进来。比如 album_page、story_video_page 这种 UI 热点后续仍然值得单独处理。接下来的重点我会放在warning 收口UI 热点的单独重放继续收紧 processor / coordinator 的写权限边界只在真正稳定之后再把部分 part 升成更硬的独立类结语很多人做重构最后容易走向两个极端要么只改格式不改结构要么一上来就大重写把风险拉满我这次最大的体会是真正稳的重构不是“重写”而是持续把边界理清。先把混乱的大文件拆出层次再把职责从“共享私有作用域”慢慢收紧成“明确输入输出”最后再去谈更优雅的架构。这条路虽然慢一点但它更适合真实项目也更适合团队协作。