模块化粒度设计原则
模块化粒度决定了插件化架构的基础质量。粒度太粗，模块内部耦合堆积，难以独立演进；粒度太细，接口数量爆炸，编排成本和信任审查成本剧增。本章围绕五个核心原则展开，每个原则都直接影响模块边界、系统分层、组件职责、数据流/控制流、信任链路、选型权衡与风险，最后给出统一的落地步骤与验收标准。
1. 高内聚低耦合
模块内部的元素应紧密关联（高内聚），模块之间的依赖应尽量弱化（低耦合）。这一原则直接定义模块边界：一个模块应当包含完整的一组业务或技术能力，对外只暴露最小接口。
- 模块边界：同一个变化原因、同一种抽象层次的代码归入一个模块。
- 系统分层：每层模块只依赖下层抽象，不跨层调用。
- 组件职责：模块内部可按职责细分子模块，但对外表现一致。
- 数据流/控制流：内部数据传递无外部中间件，流向通过公共 API 暴露；控制流在模块内闭环，外部仅通过事件或回调触发。
- 信任链路：高内聚模块可被独立验证和信任，低耦合保证替换时不影响其他模块。
风险点：过度追求低耦合可能导致接口黑洞（如 event bus 无所不包），或内聚不足导致模块频繁拆分。落地时需使用依赖图工具（如 jdepend / clang-ast）监控耦合度，内聚度可参考 LCOM（缺乏内聚度）指标。
2. 单一职责原则
每个模块只承担一个业务或技术维度的职责。这决定了模块边界的精细度：一个模块应当只有一个变化原因。
| 维度 | 说明 | 验收标准 |
|---|---|---|
| 模块边界 | 按业务域（订单、支付）或技术域（日志、缓存）划分，不混合 | 模块功能描述不超过一句话 |
| 系统分层 | 同一层模块不交叉依赖，高层模块可调用低层模块 | 无循环依赖，可用依赖分析工具验证 |
| 组件职责 | 每个模块内所有类/函数服务于同一目标 | 模块内类数量 < 20（经验值） |
| 信任链路 | 单一职责模块更容易被形式化验证和审计 | 模块的公共 API 数量 ≤ 5 |
选型权衡：细粒度模块利于复用，但引入插件化时接口数量可能激增；粗粒度模块减少了通信开销，但增加替换风险。建议按“业务域 + 变化频率”折衷，变化快的部分适当细拆。
3. 接口隔离原则
模块间通信接口应当小而专，避免客户端依赖不需要的方法。这一原则直接影响模块间通信规范的制定。
- 模块边界：每个接口对应一个明确的使用场景，不设计“万能”接口。
- 数据流/控制流：接口只定义必要输入/输出，调用方不关心实现细节。控制流由接口侧的调度器或事件总线管理。
- 风险点：接口膨胀导致调用方频繁适配，破坏开闭原则。需定期评审接口变更频率，超过 30% 方法被弃用的接口应重构。
落地步骤：先定义最小接口契约（包含方法签名、错误码、版本号），再通过代码生成工具自动生成接口桩代码，避免手写不一致。
4. 依赖反转原则
抽象不应依赖细节，细节依赖抽象。在模块化架构中，高层模块定义抽象接口，低层模块负责实现，实现可通过插件机制动态注入。
- 系统分层：依赖方向与调用方向相反——高层模块拥有接口定义，低层模块实现接口。
- 组件职责：接口定义模块（如 PluginAPI）属于核心层，实现模块（具体插件）属于扩展层。
- 信任链路：核心层不信任任何实现模块，需通过接口签名校验和数字签名验证插件的完整性。
落地步骤示例：
// 仅示意模块间依赖关系，非真实代码
PluginAPI (抽象) ←--- 依赖 核心主程序
↑ |
| 实现 | 调用
PluginA / PluginB (具体) 事件/数据总线5. 模块间通信规范
通信规范是模块间协作的契约，包括传输协议、数据序列化、错误处理、版本兼容等。它决定了数据流和信任链路的具体实现。
| 选型 | 适用场景 | 风险点 | 信任链路要求 |
|---|---|---|---|
| 事件总线（异步、广播） | 多模块解耦，业务通知 | 事件丢失、顺序错乱 | 事件源签名、幂等消费 |
| RPC（同步、点对点） | 高性能组件间调用 | 超时、级联失败 | 服务鉴权、熔断保护 |
| 共享内存 + 信号 | 实时、低延迟场景 | 竞态、内存泄漏 | 内存隔离、权限校验 |
验收标准：通信模块必须提供版本化接口，支持向前/向后兼容至少两个大版本；单元测试覆盖率达到 90% 以上，混沌测试验证异常场景。
综合落地步骤与验收标准
将上述五项原则整合为可执行的架构落地流程：
- 边界分析：使用上下文映射（Context Mapping）划分模块，对齐业务域。
- 接口设计：按单一职责、接口隔离定义每个模块的公共 API，并确保依赖方向由抽象指向具体。
- 通信契约：选定通信方式，定义消息格式、版本号、错误码、超时与重试策略。
- 内聚测试：通过代码分析工具计算 LCOM 和依赖度，调整模块边界。
- 集成验证：利用契约测试确保模块间接口不泄露内部细节，控制流和信任链路通过签名与审计验证。
验收标准速查表
| 检查项 | 合格线 | 工具/方法 |
|---|---|---|
| 模块内聚度（LCOM） | LCOM < 0.7 | jdepend / NDepend |
| 模块间耦合度 | 依赖数 < 10 个（每个模块） | 依赖图 / 扇入扇出分析 |
| 接口隔离 | 每个接口方法数 ≤ 5 | 静态代码检查 |
| 依赖反转 | 无循环依赖，核心模块不依赖扩展模块 | 依赖图检测 + 架构测试 |
| 通信规范 | 支持2个版本兼容，混沌测试通过率 > 99% | 契约测试 / 混沌工程 |
以上五项原则并非孤立的：高内聚与单一职责界定模块边界，接口隔离与依赖反转规范接口形态，通信规范约束运行时数据流与信任链路。只有同时满足，才能构建出可管控、可扩展的插件化架构。