code-modularization-evaluator

代码模块化评估器

使用 Vlad Khononov 在《Balancing Coupling in Software Design》中提出的平衡耦合模型评估代码模块化。此技能有助于识别有问题的耦合模式，并提供可操作的重构建议。

核心原则

耦合本身并非坏事，设计不当的耦合才是坏事。 目标是实现平衡的耦合，而不是消除所有耦合。

基本公式：

MODULARITY = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

满足以下条件时，系统即可实现模块化：

• 集成强度高的组件彼此靠近（位于同一模块／服务中）
• 集成强度低的组件可以相距较远（位于不同服务中）
• 易变性低的组件可以容忍耦合不匹配

耦合的三个维度

始终从以下三个维度评估耦合：

1. 集成强度（共享了哪些知识？）

从最强（最差）到最弱（最好）：

级别	类型	描述	示例
1	侵入式	使用非公开接口	直接访问另一服务的数据库、通过反射访问私有字段
2	功能式	共享业务逻辑／规则	两处重复相同的验证逻辑、操作依赖执行顺序
3	模型式	共享领域模型	两个服务使用完全相同的实体定义
4	契约式	仅共享显式接口	设计良好的 API、DTO、协议

2. 距离（知识传播的范围有多远？）

从最近到最远：

1. 同一类中的方法
2. 同一文件中的类
3. 同一命名空间／包中的类
4. 不同命名空间中的模块
5. 独立服务／微服务
6. 由不同团队负责的服务
7. 不同的系统／组织

3. 易变性（变化频率有多高？）

使用领域驱动设计的子域分类：

• 核心子域：易变性高（提供竞争优势、频繁变化）
• 支撑子域：易变性低（必不可少，但无法形成差异化）
• 通用子域：易变性低（问题已解决、较为稳定）

决策框架

评估代码时，使用以下矩阵：

集成强度	距离	结果
高	远	❌ 复杂度（分布式单体）
低	近	❌ 复杂度（不必要的抽象）
高	近	✅ 模块化（将相关内容放在一起）
低	远	✅ 模块化（将独立组件分开）

例外情况：如果易变性低，耦合不匹配可以接受。

共变性分析

使用共变性识别具体的耦合类型。详细示例请参阅 references/connascence-types.md。

静态共变性（编译时，更容易修复）

按强度从弱到强排列：

1. 名称（CoN）：组件对名称达成一致
2. 类型（CoT）：组件对类型达成一致
3. 含义（CoM）：组件对值的含义达成一致（魔法数字）
4. 位置（CoP）：组件对值的顺序达成一致
5. 算法（CoA）：组件共享算法逻辑

动态共变性（运行时，更难检测）

按强度从弱到强排列： 6. 执行（CoE）：方法调用的顺序很重要 7. 时序（CoTm）：执行时机很重要 8. 值（CoV）：多个值必须一同变化 9. 标识（CoI）：必须引用同一个实例

共变性规则

1. 尽量减少整体共变性
2. 尽量减少跨越模块边界的共变性
3. 尽量增加模块边界内的共变性
4. 将较强的共变性转换为较弱的形式
5. 随着距离增加，共变性应减弱

评估清单

分析代码时，请检查以下内容：

危险信号（需要立即采取行动）

• 直接访问其他服务的数据（侵入性耦合）
• 使用反射访问私有字段
• 在多个服务中重复业务逻辑
• 微服务需要同步部署
• 类的 CBO（对象间耦合度）> 14
• 频繁变更模块的稳定性指数为 0.3-0.7
• 模块之间存在循环依赖

警告信号（需要进一步调查）

• 多个组件共享魔法数字/值（CoM）
• API 中依赖位置的参数（CoP）
• 在多个位置重复算法逻辑（CoA）
• 方法必须按特定顺序调用（CoE）
• 方法链过长：a.b().c().d()（违反迪米特法则）
• 名为“Manager”“Helper”“Utility”的类承担过多职责

健康模式

• 服务之间基于契约进行集成
• DTO 能真正抽象内部模型
• 模块内具有高内聚性
• 每个类只承担单一职责
• 对外部依赖进行依赖注入

重构策略

按集成强度问题分类

侵入性耦合 → 契约耦合：

1. 找出所有对实现细节的直接依赖
2. 定义明确的接口/契约
3. 创建适配器层
4. 通过适配器处理所有访问

功能耦合 → 模型耦合：

1. 将共享业务逻辑提取到专用模块
2. 明确所有权
3. 通过显式依赖使用该模块

模型耦合 → 契约耦合：

1. 创建针对集成场景的 DTO
2. 在边界处映射内部模型与 DTO
3. 独立于模型对契约进行版本管理

按共现类型分类

从	到	技术
CoM（含义）	CoN（名称）	用具名常量/枚举替代魔法值
CoP（位置）	CoN（名称）	使用具名参数、构建器模式或参数对象
CoA（算法）	CoN（名称）	将算法提取到单一位置，并通过名称引用
CoT（类型）	CoN（名称）	使用鸭子类型或接口
CoE（执行）	显式	使用状态机、构建器模式或构造函数注入
CoI（身份）	显式	使用显式连线的依赖注入

按距离问题分类

高强度 + 高距离（分布式单体）：

• 方案 A：缩短距离——合并服务/模块
• 方案 B：降低强度——引入契约、异步消息传递

低强度 + 低距离（过度抽象）：

• 移除不必要的抽象层
• 内联过度通用的代码
• 合并紧密相关的类

分析工作流

收到评估代码模块化的请求时：

1. 梳理组件结构

   • 识别模块、服务、类
   • 绘制依赖关系图

2. 评估集成强度

   • 对每项依赖分类：侵入性/功能/模型/契约
   • 标记跨边界的高强度依赖

3. 衡量距离

   • 记录组件位置（同一文件 → 不同系统）
   • 识别团队/所有权边界

4. 评估易变性

   • 对每个组件的子域类型进行分类
   • 记录历史上频繁变更的区域

5. 应用公式

   • 检查：强度与距离是否恰当匹配？
   • 易变性是否能解释任何不匹配？

6. 识别共现

   • 扫描特定的共现类型
   • 按以下情况确定优先级：高强度 + 低局部性 + 高度数

7. 提出建议

   • 按影响和工作量确定优先级
   • 提供具体的重构技术

输出格式

按以下结构组织评估：

## Modularization Assessment

### Summary
[Brief overview of coupling health]

### Component Map
[Describe module/service structure]

### Coupling Analysis
| Component Pair | Strength | Distance | Volatility | Balance |
|---------------|----------|----------|------------|---------|
| A → B         | Model    | High     | High       | ❌      |

### Connascence Issues
1. [Specific connascence type]: [Location] - [Impact]

### Recommendations
1. **Priority 1**: [Action] - [Rationale]
2. **Priority 2**: [Action] - [Rationale]

### Refactoring Plan
[Step-by-step approach for highest-priority item]

参考资料

• 详细的共现示例：参见 references/connascence-types.md
• 耦合度量：参见 references/coupling-metrics.md
• 重构模式：参见 references/refactoring-patterns.md

局限性

• 没有执行上下文，无法评估运行时行为
• 评估波动性需要领域知识
• 评估团队／组织间的距离需要项目上下文
• 仅靠静态分析无法获取历史变更频率