1 前言

代码写到后面，真正让人头疼的，往往不是功能本身，而是结构。

项目刚开始时，代码量不大，开发者对上下文也足够熟悉。哪怕一个文件里同时放了流程控制、状态管理、工具函数和数据处理，短时间内似乎也不会出太大问题。可一旦项目进入持续迭代阶段，需求变多、参与的人变多、历史代码变多，结构问题就会迅速放大。

这时候，很多团队会出现一种很典型的状态：代码还能跑，但越来越难改；功能还能加，但越来越难稳；问题还能修，但修完又容易带出新问题。表面看是“代码太多了”，本质上却常常是“代码没有被合理组织起来”。

高内聚、低耦合，就是解决这类问题时最核心的两条设计原则。它们不是只存在于架构图里的口号，也不是只有大项目才需要考虑的高级概念，而是几乎所有工程代码都会遇到、也迟早都要面对的基本问题。

1.1 痛点

很多代码库之所以越来越难维护，并不是因为业务复杂到无法控制，而是因为结构在不断失衡。

一个功能不断往同一个文件里堆，最后一个文件几千行，阅读和修改都非常费劲。
一个模块里既有业务逻辑，又有公共方法、对象状态、数据转换和日志处理，职责越来越混乱。
模块之间互相依赖，改动一个接口，常常需要联动修改一串代码。
看起来做了复用，实际上却是复制粘贴，类似逻辑分散在多个地方，后期维护成本很高。
新人接手代码时，很难快速判断“这个功能到底该改哪一层、放哪个模块、依赖谁”。

这些问题单独看都不算致命，但一旦叠加起来，代码库就会逐渐进入一种“谁都能改一点，但谁都不敢大改”的状态

1.2 根因

这些问题背后的根因，通常不是某一段代码写错了，而是整体组织方式出了问题。

很多项目在开发早期更关注“先把功能做出来”，这本身没有问题，但如果一直沿用这种思路，后面就容易把临时方案写成长期结构。久而久之，原本只是为了赶进度做的一次合并、一次偷懒、一次顺手复用，就会变成整个系统里的结构性负担。

更具体一点看，常见根因往往有三个。

没有边界意识，不清楚哪些代码属于公共能力，哪些代码属于具体业务。
没有层级意识，不清楚对象、模块、工具、流程各自该放在哪一层。
没有拆分意识，明明一个功能已经明显过大了，还是继续往原文件和原类里追加代码。

代码一旦缺少边界、层级和拆分这三件事，后续维护就很容易从“写代码”变成“猜代码”。这些问题背后的根因，通常不是某一段代码写错了，而是整体组织方式出了问题。

更具体一点看，常见根因往往有三个。

没有边界意识，不清楚哪些代码属于公共能力，哪些代码属于具体业务。
没有层级意识，不清楚对象、模块、工具、流程各自该放在哪一层。
没有拆分意识，明明一个功能已经明显过大了，还是继续往原文件和原类里追加代码。

代码一旦缺少边界、层级和拆分这三件事，后续维护就很容易从“写代码”变成“猜代码”。

1.3 目标

写代码时谈结构，并不是为了把项目做得“看起来高级”，而是为了让系统在后续迭代中依然可控。

一套好的代码结构，至少应该实现几个目标。

让每个模块的职责清晰，看到名字就大致知道它负责什么。
让模块之间的依赖关系简单，内部变化尽量不要扩散到外部。
让一个功能在变复杂之后，能够自然地继续拆分，而不是被迫塞进一个越来越大的文件。
让团队协作更顺畅，不同成员可以围绕清晰边界并行开发。
让后续重构有落脚点，知道哪些代码该沉淀，哪些代码该隔离，哪些代码该拆出去。

所以，本文接下来要讨论的，不只是“代码怎么写更优雅”，而是“代码怎样组织，才能在工程上更稳定、更好维护”。

2 高内聚

高内聚是软件设计里非常基础、也非常容易被说空的一条原则。很多人知道这个词，但真正落到代码上时，常常还是会把各种不相关的逻辑写进同一个类、同一个模块、同一个文件里。

从工程实践上讲，高内聚最核心的价值，不在于概念本身，而在于它能帮助我们回答一个非常现实的问题：这一段代码，到底应不应该继续放在这里。

2.1 定义

所谓高内聚，本质上就是一句话：让一个模块内部的代码尽量围绕同一类职责组织。

这里的“模块”可以是很多层级上的概念。它可以是一个类、一个文件、一个目录，也可以是一个完整功能单元。无论是哪一种，高内聚都意味着它内部的组成部分应该服务于一个明确目标，而不是把各种顺手写到的逻辑混杂在一起。

比如，一个“订单支付模块”就应该主要处理支付相关的事，包括参数校验、支付状态流转、支付结果处理和失败补偿。它可以很复杂，但这种复杂应该是围绕“支付”展开的。
如果这个模块里又塞进了积分计算、消息推送、优惠券发放和报表统计，那么它虽然看起来还是一个模块，实际上内部已经失去了统一中心。

所以，高内聚不是要求模块一定要小，而是要求模块聚焦。
一个模块可以不小，但不能散。

2.2 特征

判断一个模块是否具备高内聚，通常可以看下面几个特征。

职责是否单一。模块内部解决的是不是同一类问题，而不是把完全不同类型的逻辑塞在一起。
边界是否明确。能不能清楚说出这个模块负责什么、不负责什么。
命名是否贴切。模块、类、文件的名字，是否能准确反映内部主要职责。
修改是否集中。某个功能变化时，相关改动是否主要集中在这个模块内，而不是散落在多个无关位置。
阅读是否顺畅。开发者读这个模块时，是否能围绕一个清晰主题理解代码，而不是在不同职责之间来回切换。

高内聚的代码通常有一个很明显的感受：读起来像是在读一件完整的事。
低内聚的代码则像是在一个房间里同时堆了工具、衣服、文件和食物，什么都有，但什么都不清楚。

2.3 价值

高内聚最大的价值，不是“结构更漂亮”，而是直接降低维护成本。

2.3.1 易读

当一个模块内部只围绕一类职责展开时，阅读成本会明显下降。开发者不需要一边看流程，一边猜哪些代码是工具函数，哪些是状态处理，哪些只是临时补丁。模块主题越单一，理解速度通常越快。

2.3.2 易改

需求变更时，最怕的不是改动本身，而是不知道改动会影响哪里。高内聚的模块因为职责集中，所以改动范围通常更可控。很多时候，需求变化只需要进入对应模块修改，而不需要在整个项目里到处搜索。

2.3.3 易测

高内聚模块更容易做测试，因为它处理的问题更集中，输入输出边界也更清楚。
如果一个类既管流程、又管数据、还管外部调用，那测试时往往很难隔离问题；如果职责单一，测试就会自然很多。

2.3.4 易协作

团队开发中，清晰的职责划分会直接提升协作效率。每个人都更容易判断自己该改哪部分代码，也更容易避免多人同时修改同一块混杂逻辑。

2.3.5 易演进

系统不是一次写完就结束的，很多代码都要经历多轮需求变化。高内聚会让后续拆分、替换和重构更有抓手，因为你知道一个模块内部大致在处理哪一类职责，它的演进方向也更容易判断。

2.4 误区

高内聚很重要，但在实际落地时也很容易被误解。

高内聚不等于代码越碎越好。把一件完整的事硬拆成很多极小文件，并不会自动带来更好的结构，反而可能让调用关系更绕。
高内聚不等于一个类只能有一个函数。真正要控制的是职责，而不是机械地控制代码行数和函数个数。
高内聚不等于完全不共享。合理的公共能力沉淀是必要的，关键在于公共部分是不是足够稳定、足够通用。
高内聚不等于只看局部。一个模块内部再清晰，如果它对外暴露混乱、依赖关系复杂，整体设计仍然可能是失败的。

说到底，高内聚不是形式规则，而是一种组织方式。它要求我们始终追问一件事：这些代码，是不是在共同完成同一个目标。

如果答案越来越模糊，那通常就意味着，这个模块该重新整理了。

3 低耦合

如果说高内聚关注的是“模块内部要不要聚焦”，那么低耦合关注的就是“模块之间要不要纠缠”。

在真实项目里，很多代码之所以越改越难，不是因为单个模块写得太差，而是因为模块之间绑得太紧。一个类改了成员字段，外面一串代码要跟着改；一个模块调整了内部流程，其他几个模块也会被连带影响。表面上看是依赖，实际上已经变成了牵制。

低耦合的意义，就是尽量让这种牵制变少，让模块之间保持必要联系，但不要互相缠死。

3.1 定义

低耦合，指的是模块之间的依赖关系尽量简单、清晰、稳定。

这里的“依赖”本身并不是问题。只要系统存在分工，模块之间就一定会有调用、有数据交换、有上下游关系。真正的问题在于，依赖是不是过深、过多、过于脆弱。

一个低耦合的系统，通常具备这样的特征：模块之间通过明确接口进行交互，外部只需要知道“这个模块提供什么能力”，而不需要知道“它内部是怎么实现的”。这样一来，模块内部即使重构、替换、优化，只要对外接口不变，其他模块通常就不需要跟着大改。

所以，低耦合不是追求“完全没有依赖”，而是追求一种更健康的依赖关系：依赖边界明确，影响范围可控，内部变化不轻易外溢。

3.2 表现

低耦合不是一个抽象口号，它会直接体现在代码组织和开发体验上。

一个模块如果只通过少量清晰接口对外提供能力，外部代码不会直接读写它的内部状态，也不会依赖它的私有实现细节，这通常就是低耦合的表现。相反，如果外部模块不仅调用它的方法，还知道它的内部字段、内部流程、内部缓存策略，甚至依赖它某个“暂时这样写”的细节，那耦合就已经很深了。

在工程实践中，耦合过高通常会表现为几种很典型的现象。

一个模块改动后，多个无关模块都需要同步修改。
外部代码直接操作另一个模块的内部对象或状态，而不是通过稳定接口访问。
模块之间相互引用，调用链越来越长，最后很难分清主次关系。
某些公共模块表面上是“公共能力”，实际上却偷偷依赖具体业务逻辑。
替换一个实现时，不只是替换本身困难，连调用方也要一起调整。

这些现象背后，其实都说明一件事：模块之间没有真正建立边界，彼此知道得太多，绑定得太深。

3.3 影响

高耦合最直接的后果，就是系统会逐渐失去可维护性。

首先，改动成本会越来越高。原本只是想修一个局部问题，结果因为依赖链太长，不得不同时检查上游、下游和多个旁支模块。开发者花掉的大量时间，不是在实现需求，而是在确认“这样改会不会连带出别的问题”。

其次，测试成本也会变高。模块之间耦合越深，越难单独验证其中一部分逻辑。很多问题明明出在一个模块里，但因为依赖关系复杂，最后只能在系统集成阶段才能暴露出来，这会显著增加定位和回归成本。

再者，团队协作会变差。低耦合的系统允许不同成员围绕接口并行开发，而高耦合系统里，很多人会因为共享同一片模糊区域而频繁冲突。大家表面上在开发不同功能，实际上可能都在改同一组底层实现细节。

从更长远的角度看，高耦合还会阻碍架构演进。系统一旦形成“牵一发而动全身”的格局，很多本来应该做的重构、替换和优化，最后都会因为风险太大而被推迟。久而久之，代码库就会越来越沉，越来越硬，进入一种只能继续叠加、很难真正整理的状态。

所以，低耦合的价值并不只是“让结构更优雅”，而是让系统在长期迭代中还能持续被修改、被扩展、被替换。

3.4 误区

低耦合很重要，但在实际理解上也常常会走偏。

一个常见误区，是把低耦合理解成“模块之间最好完全没有关系”。这其实不现实。任何稍微成体系的软件，都不可能做到完全孤立。真正合理的目标，是让依赖关系变得必要、明确、稳定，而不是一味切断所有联系。

另一个误区，是只要加了接口层、抽象层，就默认自己实现了低耦合。事实上，如果抽象本身并不稳定，或者接口只是把混乱逻辑包了一层壳，耦合并不会真正下降，只会从“显性耦合”变成“被包装过的耦合”。

还有一种误区，是把低耦合做成了过度设计。为了降低耦合，硬拆出太多中间层、适配层、包装层，结果调用链反而更长，理解成本更高。这样写出来的代码，虽然看起来层数很多、边界很多，但真正维护时未必更轻松。

所以，低耦合的关键不在于“层数多不多”，而在于模块之间是不是通过合适的边界在交互。边界清楚、依赖稳定，就是低耦合；边界模糊、互相窥探，就算写了再多抽象，也还是高耦合。

4 二者关系

高内聚和低耦合经常被放在一起说，不是因为它们刚好是一对概念，而是因为它们本来就在共同描述同一件事：代码应该如何被组织。

一个好的系统，不只是要求“每个模块内部要清楚”，也要求“模块和模块之间要清楚”。前者是高内聚，后者是低耦合。少了任何一边，结构都会失衡。

4.1 为什么要一起看

只谈高内聚，不谈低耦合，容易出现一种情况：模块内部确实做到了职责集中，但模块之间仍然互相缠绕。也就是说，每个模块看起来都像在认真做自己的事，可一旦放到一起，彼此依赖关系依然很重，改动时还是会连锁扩散。

反过来，只谈低耦合，不谈高内聚，也会出问题。因为模块之间虽然表面上切开了，但模块内部可能仍然混乱不堪。这样即使边界看起来存在，内部实现依然难读、难改、难维护。

所以，高内聚和低耦合其实是在分别解决两个方向的问题。

高内聚解决的是模块内部的组织问题。
低耦合解决的是模块外部的连接问题。

只有当一个模块内部足够聚焦，外部边界才更容易定义；只有当模块边界明确，模块之间的依赖才更容易收敛。两者结合起来，才能真正形成稳定、清晰、可演进的结构。

从这个角度看，高内聚和低耦合不是并列关系，更像是一体两面。一个强调“向内收”，一个强调“向外控”，共同作用的结果，才是良好的模块化设计。

4.2 对工程开发的意义

在工程开发里，高内聚和低耦合的意义非常现实，并不只是设计层面的“理论正确”。

首先，它能显著降低维护成本。功能修改时，开发者更容易判断应该改哪个模块，也更容易评估这次改动会影响多大范围。代码的可预期性会明显提升。

其次，它能提升团队协作效率。职责明确的模块更适合拆分任务，依赖清晰的模块更适合并行开发。这样一来，不同成员之间的相互等待、相互干扰都会减少。

再者，它能让系统更容易演进。真实项目几乎都会经历需求变更、功能扩展、性能优化和架构调整。如果代码从一开始就具备较好的内聚与解耦，那么后续的重构就会更像“局部整理”，而不是“全局手术”。

最后，它还能帮助团队建立统一的代码判断标准。很多时候，代码评审里最难的不是发现语法问题，而是判断结构是否合理。高内聚和低耦合，恰恰就是这种结构判断的核心尺度。看到一段代码时，团队可以自然去问：它是不是放错了地方？它是不是知道了太多不该知道的东西？它是不是承担了太多不该承担的职责？

这些问题一旦形成共识，代码质量就不再只是依赖某个人的经验，而会逐渐变成团队共同维护的工程习惯。

5 层级设计

高内聚和低耦合要真正落地，不能只停留在原则层面，还必须落实到代码的层级设计上。

所谓层级设计，本质上是在回答一个很现实的问题：不同类型的代码，到底应该放在哪里。
如果这个问题没有想清楚，项目就很容易出现一种常见状态：公共代码和业务代码混在一起，对象和流程写在同一个文件里，模块名看起来很多，实际边界却很模糊。最后不是代码不能运行，而是代码虽然能运行，却越来越难维护。

5.1 为什么要分层

代码分层，不是为了把目录做得好看，也不是为了显得“架构完整”，而是为了让不同职责的代码各归其位。

如果没有分层，最直接的问题就是“什么都能写在一起”。控制流程可以写在对象里，工具函数可以写进业务模块，公共能力也可能偷偷依赖具体业务。短期内看，这样写很快；但时间一长，所有层次都会互相污染，最终没有人能准确说清一段代码到底属于哪里。

分层真正带来的价值，主要有几个。

让职责更清楚。开发者能更容易判断这段代码是业务逻辑、公共能力，还是对象封装。
让依赖更稳定。下层提供基础能力，上层组织业务流程，关系更容易保持清晰。
让协作更顺畅。不同人可以围绕不同层次分工，而不是反复改同一片混杂代码。
让后续重构更容易。代码已经按层次组织时，拆分和迁移都会更有抓手。

所以，分层不是形式问题，而是长期维护能力的问题。

5.2 common 模块

common 模块在很多项目里都存在，但也是最容易被误用的地方。
它看起来像公共层，实际上往往最容易变成“先放这里，后面再整理”的收纳箱。

5.2.1 放什么

真正适合放进 common 的内容，通常要满足两个前提：通用，并且稳定。

也就是说，这类代码不属于某个具体业务，而是多个模块都可能复用；同时，它不会因为某个功能调整就频繁改动。

常见适合放进 common 的内容有这些。

基础工具能力，比如字符串处理、时间处理、文件处理、通用校验。
底层公共封装，比如日志、配置读取、异常封装、统一返回结构。
无明显业务语义的基础数据结构或公共基类。
多个业务模块都会依赖、且语义长期稳定的底层能力。

这类代码的特点是，即使将来某个具体业务被删掉了，它们依然可以独立存在。

5.2.2 不放什么

很多代码表面上“也被多个地方调用”，但其实并不适合放进 common。
尤其是那些带有明显业务色彩、随着业务变化而频繁变化的代码，更不应该为了图省事塞进去。

通常不适合放进 common 的有这些。

某个具体功能专用的流程逻辑。
只被少数场景临时复用的业务辅助函数。
带有明显领域语义的数据转换逻辑。
因为暂时不知道该放哪，所以先扔进去的代码。

判断一段代码该不该进 common，可以问自己一句话：
如果去掉当前业务，它还应不应该存在？
如果答案是否定的，那它大概率就不属于 common。

5.2.3 常见问题

common 最典型的问题，不是没有价值，而是边界失控。

很多团队一开始也知道 common 应该放公共能力，但随着项目推进，只要哪里放不下、来不及整理、又想顺手复用，就往 common 里塞。最后它会逐渐变成整个项目里最重、最乱、最难动的模块。

这类问题通常会表现为：

common 里开始出现明显业务名词。
common 反向依赖业务模块。
common 修改一次，会影响大批无关功能。
大量“看起来通用，实际上没人敢复用”的代码长期堆积。

所以，common 不是越大越好。真正好的 common，往往反而是克制的。

5.3 对象模块

面向对象的价值，不在于“代码里有多少个类”，而在于对象是否有清晰职责。
如果类只是把一堆函数包起来，而没有边界、没有语义、没有责任划分，那它并不会让结构更好，只会让代码换一种方式变乱。

5.3.1 职责边界

一个对象模块最核心的要求，就是职责边界明确。

对象应该围绕某个明确实体、角色或能力来设计，而不是什么都管。比如一个订单对象，核心职责应该是维护订单状态和订单行为；一个车辆对象，核心职责应该是描述车辆属性与相关操作；一个配置对象，就应该专注配置读取、校验和转换。

对象边界一旦模糊，就很容易出现下面这种情况：

对象既负责状态管理，又负责编排业务流程。
对象既处理自身逻辑，又承担数据访问。
对象既是领域实体，又顺手充当工具类。

这种设计表面上“功能集中”，实际上会让对象越来越臃肿，最后变成一个什么都知道、什么都参与的大类。

5.3.2 面向对象的模块化

对象模块化，不是把功能机械地拆成很多 class，而是让每个对象对应一个清晰职责单元。

比如一个复杂功能，不应该永远只有一个大而全的 Manager 或 Processor。更合理的做法通常是围绕职责继续拆开，让不同对象分别承担不同角色。

以一个较复杂的业务功能为例，常见可以拆成：

负责核心领域数据表达的对象。
负责状态流转的对象。
负责规则判断的对象。
负责外部交互的对象。
负责流程编排的服务对象。

这样做的好处，不是“类更多了”，而是结构更清晰了。每个对象都只承担自己该承担的部分，阅读和维护时也更容易判断问题落点。

5.3.3 接口设计

对象模块要想真正做到低耦合，关键还在于接口。

外部模块使用对象时，应该更多依赖它暴露出来的能力，而不是依赖它的内部细节。换句话说，对象应该通过方法表达行为，通过接口隔离实现，而不是让外部随意读写内部状态。

一个好的对象接口，通常具备几个特征。

语义明确，能反映对象真正提供的能力。
封装内部细节，不把临时实现暴露给外部。
输入输出边界清楚，便于理解和测试。
尽量稳定，不因为内部重构就频繁变化。

接口设计得越清楚，对象模块越容易独立演进；接口越混乱，外部越容易和内部实现绑死。

5.4 功能模块

除了 common 和对象模块，更直接的一层组织方式，就是按功能来划分模块。
在真实项目里，这通常也是最容易让团队形成共识的一种方式。

5.4.1 一个功能一个模块

一个独立功能，通常就应该对应一个独立模块或目录。

这样做最大的好处，是边界清晰。开发者看到目录结构时，就能快速知道一个功能的主要代码在哪、相关依赖在哪、扩展点在哪。相比于把多个功能揉在一个大模块里，按功能拆分更利于阅读、协作和后续维护。

当然，“一个功能一个模块”并不意味着机械地按页面、接口或按钮去拆，而是按相对完整的业务能力来拆。一个模块要能表达一件相对独立的事，而不是只承载零散代码片段。

5.4.2 模块之间的边界

功能模块一旦独立出来，就必须明确边界。

一个模块应该关心自己的业务能力，不应该随意进入别的功能模块内部拿数据、改状态、拼流程。模块之间如果确实需要协作，也应该通过接口、服务调用或清晰的数据契约来完成，而不是互相窥探实现细节。

模块边界一旦守不住，就很容易出现“表面分模块，实际全耦合”的局面。目录虽然分开了，但内部却彼此穿透，最后只是把混乱从一个文件搬到了多个文件夹里。

5.4.3 模块之间的依赖

功能模块之间存在依赖很正常，关键在于依赖方向和依赖方式要可控。

通常更合理的做法是：

公共层被业务层依赖，而不是反过来。
基础模块被上层模块依赖，而不是横向乱引用。
模块之间依赖接口能力，而不是依赖内部实现。
尽量避免循环依赖和多跳依赖。

一个健康的功能模块体系，不一定完全简单，但至少应该让人看得懂：谁依赖谁，为什么依赖，边界在哪里。

6 大文件拆分

层级设计解决的是“代码应该放在哪一层”，而大文件拆分解决的是“当一层里面已经塞得太满时，该怎么办”。

在很多项目里，最常见的一种结构问题就是：功能本身没有完全错，目录可能也不是没有分，但某个核心文件已经膨胀到几千行，什么都写在里面。
这时候再谈高内聚和低耦合，就不能只讲原则了，必须回到一个现实动作：继续拆。层级设计解决的是“代码应该放在哪一层”，而大文件拆分解决的是“当一层里面已经塞得太满时，该怎么办”。

在很多项目里，最常见的一种结构问题就是：功能本身没有完全错，目录可能也不是没有分，但某个核心文件已经膨胀到几千行，什么都写在里面。
这时候再谈高内聚和低耦合，就不能只讲原则了，必须回到一个现实动作：继续拆。

6.1 为什么要拆

一个文件变大，本身不一定有问题。真正的问题在于，大文件往往意味着职责开始堆叠，结构开始失焦。

当一个文件里同时出现参数处理、流程控制、对象定义、状态管理、规则判断、外部调用和错误处理时，它虽然还叫“一个功能文件”，但实际上已经不再是一个清晰单元，而是多个职责被强行塞在一起。

继续拆分的意义主要在于：

降低阅读成本，让开发者更快定位自己关心的部分。
降低修改风险，把局部变化尽量控制在局部文件中。
提高复用可能，把真正独立的职责沉淀为可复用能力。
提高协作效率，避免多人长期挤在同一个大文件上改动。
为后续测试和重构创造条件。

所以，大文件拆分不是为了追求“文件越小越专业”，而是为了让一个已经失控的功能重新恢复结构。

6.2 什么情况下该拆

是否该拆，不能只看代码行数，但代码行数往往是一个很明显的信号。

6.2.1 文件过大

如果一个文件已经大到阅读时需要反复搜索、反复折叠、反复上下跳转，那通常就该警惕了。几千行代码不是绝对不能存在，但它至少说明：这个文件里已经承载了相当多的信息密度。

这时候比“到底几百行算大”更重要的是：你还能不能一眼说清它内部有哪些主要职责。如果说不清，往往就意味着该拆。

6.2.2 职责过多

一个文件里如果同时包含多个明显不同的职责，也是典型的拆分信号。

一部分代码在处理数据定义。
一部分代码在做核心流程控制。
一部分代码在封装外部接口调用。
一部分代码在做本功能专用工具处理。
一部分代码又在处理状态机或规则判断。

这些内容如果长期混在一个文件里，问题不是“代码有点多”，而是“职责已经不止一个”。

6.2.3 维护困难

如果每次改动这个文件，都要花很长时间确认影响范围，或者一改就容易牵出旧逻辑，那它也已经是拆分对象了。

维护困难往往说明文件内部边界不清。代码虽然都在一个地方，但改一处时，开发者并不能自然确认哪些部分和它有关，哪些部分无关。

6.2.4 协作困难

多人协作时，如果大家总在同一个大文件里改不同内容，冲突会越来越频繁。
这种冲突不只是 Git 冲突，更是认知冲突：每个人都只能在局部理解代码，却要共享同一片混杂区域。

这类文件通常不是“太忙”，而是“太杂”。

6.3 怎么拆

拆分不是简单切文件，更不是把一份大文件随机拆成几段。真正有效的拆分，应该围绕职责、流程和边界来做。

6.3.1 按职责拆

这是最常见、也通常最稳的一种方式。
把不同职责的代码分别放到不同文件中，让每个文件承担一个相对单纯的角色。

比如一个复杂功能里，可以把以下内容拆开：

数据结构定义。
规则判断逻辑。
核心流程编排。
外部依赖封装。
本功能内部专用工具。

这样拆的关键，不是“均匀分配行数”，而是让文件职责更单一。

6.3.2 按流程拆

有些功能天然就是流程驱动的，比如初始化、执行、回调、收尾、异常处理等阶段非常清晰。
这种情况下，可以按流程阶段拆分文件，让每一部分负责一个相对独立的流程段。

这种拆法适合流程较长、但阶段边界明确的功能。它能显著降低“整个流程全写在一个方法里”的复杂度。

6.3.3 按对象拆

如果一个大文件内部已经隐含了多个对象角色，那么按对象拆分通常是更自然的选择。

比如原来一个文件里同时在管理任务、规则、上下文、执行器和结果对象，那就说明它已经不是一个单纯文件，而是多个对象强行共居一室。此时按对象拆分，可以让结构重新变得清楚。

6.3.4 按层次拆

如果一个大文件同时混杂了接口层、服务层、数据层和工具层代码，那么最应该做的不是继续优化函数，而是先按层次拆开。

也就是说，让不同层次的代码分别回到自己该在的位置。
这类拆分做完后，很多“代码太长”的问题其实会自然缓解，因为原本拥挤的原因不是算法复杂，而是层次混放。如果一个大文件同时混杂了接口层、服务层、数据层和工具层代码，那么最应该做的不是继续优化函数，而是先按层次拆开。

也就是说，让不同层次的代码分别回到自己该在的位置。
这类拆分做完后，很多“代码太长”的问题其实会自然缓解，因为原本拥挤的原因不是算法复杂，而是层次混放。

6.4 目录组织

大文件拆分之后，通常不能只是从一个大文件变成多个平铺文件，更合理的做法是同步建立功能目录结构。
否则代码虽然分成了多个文件，但整体仍然缺乏组织。

6.4.1 单模块目录

当一个功能已经明显复杂到需要拆分时，通常就应该给它一个独立目录，而不是仍然和其他功能文件混在同一级。

这个目录的意义在于：把一个功能的相关代码真正聚拢起来，让它形成一个清晰单元。

6.4.2 子文件划分

在一个功能目录下，常见可以按职责继续划分几个子文件或子目录，例如：

model：放数据结构、对象定义。
service：放核心业务逻辑。
repository 或 gateway：放外部数据访问或依赖封装。
rule：放规则判断。
utils：放仅该功能内部使用的小工具。
controller 或 handler：放入口处理与参数对接。

具体命名可以根据语言和团队风格调整，但核心思想不变：同一功能下，不同职责继续分开。

6.4.3 命名建议

目录和文件命名越清楚，结构的价值就越能体现出来。

命名时有几个原则比较重要。

名字要能表达职责，而不是只表达技术动作。
优先用稳定语义命名，不要用临时开发背景命名。
避免出现 misc、temp、other 这类没有信息量的名字。
同一层级保持风格统一，不要一部分按对象命名，一部分按流程命名，一部分又按人名或历史习惯命名。

好的命名，本质上也是结构设计的一部分。因为很多时候，读者最先接触到的不是代码，而是目录和文件名。