在大型前端项目中，TypeScript 以类型系统带来保障，但业务迭代不可避免积累技术债务。若只关注功能是否实现，忽视了代码的耦合与内聚，最终会让维护成本失控。本文从源码解析视角，探讨如何识别并治理TypeScript项目中的技术债务。
一、为什么源码解析是发现技术债务的可靠手段
技术债务不像语法错误那样直观。它隐藏在模块依赖、类型设计、函数职责中。人工审查速度慢且易遗漏。基于 TypeScript Compiler API 或 AST 工具，能自动扫描源码结构，生成依赖图、统计扇入扇出、计算内聚度指标，让隐性问题可视化。借助 dependency-cruiser、Madge、jscpd 等工具，团队可以在不运行业务代码的情况下完成架构体检。
二、耦合：TypeScript 中的典型表现
1. 跨模块依赖泛滥
当模块A为了一个工具函数引入模块B，模块B又反向引用模块A，形成循环依赖。TypeScript 编译或许不报错，但运行时的初始化顺序和打包体积都会受影响。源码解析可以构建模块依赖图，快速定位循环依赖、高扇出模块。
2. 类型层面过度耦合
例如一个接口包含二十个属性，多个不相关组件共享该接口。修改一个字段导致整个调用链编译失败。这说明类型定义缺少按需拆分。通过AST统计接口被引用次数、字段访问次数，能识别“胖接口”。这种接口看似提高了复用，实际上让所有使用方都被迫依赖大量无关字段，是典型的耦合问题。
3. 全局状态与单例滥用
大量模块直接读写同一个全局对象或单例，形成隐式耦合。TypeScript 类型系统无法阻止这种设计，但通过解析变量引用关系，可以标记对全局状态读写最多的模块。尤其是 Redux、Pinia 之外的临时全局变量，往往成为跨模块通信的暗线，让数据流难以追踪。
三、内聚：被忽视的质量维度
1. 上帝类与上帝函数
一个类或函数承担过多职责，导致内部方法和属性之间关联度低。源码解析可以计算 LCOM（类中方法内聚度），LCOM值越高表示内聚越差。例如一个 UserService 既处理登录鉴权，又负责发送营销邮件、生成统计报表，其方法之间几乎没有共享字段，就是典型的低内聚。
2. 混合职责模块
有些模块同时处理网络请求、日期格式化、状态管理，命名却很宽泛如 utils.ts、common.ts。分析模块内部符号的依赖关系，能发现这种“万能模块”。它们看似提升了开发便利，实际上是内聚不足的集中体现，任何需求变化都可能引发意外修改。
3. 重复逻辑与发散式变化
相似逻辑散落多处，修改一个业务规则需要同时改动多个文件。通过AST代码相似度分析，可以定位重复片段，这是内聚不足的重要信号。重复代码不仅增加维护成本，还会在不同副本之间产生行为漂移，进一步加深技术债务。
四、用指标量化技术债务
想要治理技术债务，必须先度量。以下指标在TypeScript源码解析中非常实用：
- 扇入/扇出：扇入高表示模块被大量依赖，修改风险高；扇出高表示模块依赖过多，职责可能过宽。
- 循环依赖数：反映架构层面的耦合程度，数量越多，构建与测试越脆弱。
- LCOM（方法缺乏内聚度）：衡量类内部方法共享属性的程度，值越高技术债务越重。
- 重复代码率：AST 节点相似度检测，重复片段往往是内聚不足的产物。
- 类型安全漏洞密度：统计 any、@ts-ignore、类型断言的使用频率，过高说明类型系统正在失效。
这些指标可以组合成技术债务评分卡，帮助团队识别优先级最高的重构对象。例如某个模块循环依赖多、扇出高、LCOM 值也高，就应优先治理。
五、治理方向：降低耦合、提升内聚
1. 用依赖倒置解开模块耦合
高内聚模块通过接口依赖抽象，而不是直接依赖具体模块。TypeScript 的接口和类型别名可以很好支撑这一模式。重构时，先让源码解析结果指出耦合热点，再逐步引入抽象层。这样既能减少直接依赖，又能保留类型检查能力。
2. 拆分胖接口与上帝类
按照单一职责原则，将大接口拆成多个小接口，让每个模块只依赖它真正需要的类型。工具类拆分为按领域命名的模块，减少 common.ts 的膨胀。例如将用户相关的格式化函数、权限判断、存储操作分别归入 user-format.ts、user-permission.ts、user-storage.ts。
3. 建立架构看门狗
把耦合与内聚指标纳入CI流水线。当循环依赖、LCOM、any密度等指标超过阈值时阻止合并，将技术债务控制在早期。这样团队不会在项目后期被动偿还高额利息，而是让架构质量持续维持在可接受水平。
结语
TypeScript 给了类型层面的约束，但真正的代码健康需要从结构层面持续观察。通过源码解析量化耦合与内聚，不仅能看清技术债务的真实分布，也能让重构有据可依。与其在项目后期偿还高额利息，不如从现在开始，用工具度量每一个模块的“健康度”。