architecture-paradigm-modular-monolith

模块化单体范式

适用场景

• 将大型代码库组织成边界清晰的模块
• 团队希望具备微服务的边界划分，但不引入分布式系统的复杂性

不适用场景

• 已经采用微服务分布式架构
• 模块边界会带来不必要复杂性的小型应用

何时采用此范式

• 希望获得类似微服务的团队自主性，同时避免分布式系统的运维开销。
• 内部模块间错综复杂的依赖关系拖慢了发布速度。
• 单体架构目前更易于运维，但未来显然需要演进为基于服务的模型。

采用步骤

1. 识别模块：定义与不同业务能力或领域驱动设计中的限界上下文相对应的模块边界。
2. 封装内部实现：使用语言级可见性修饰符（例如 public/private）、独立的包或命名空间来隐藏各模块的实现细节。
3. 公开契约：每个模块都应通过定义明确的外观、API 或事件公开其功能。禁止模块间直接访问数据库表或直接调用实现。
4. 落实架构适应性检查：实施自动化测试，一旦模块间出现禁止的依赖或包引用，就让构建失败。
5. 规划演进：持续跟踪变更耦合度和部署范围等指标，以便就是否以及何时将模块拆分为独立服务做出明智决策。

主要交付物

• 一份架构决策记录（ADR），用于映射模块边界并定义共享代码的规则。
• 每个模块交互点的正式契约文档（例如 OpenAPI 规范、事件架构）。
• 自动化依赖检查，以及各模块专用的 CI/CD 作业，以落实边界约束。

风险与缓解措施

• 退化为“泥球”：
  • 缓解措施：如果不严格落实，模块边界必然会逐渐瓦解。将任何边界违规视为导致构建失败的错误，并在代码审查中保持严谨。
• 共享数据库热点：
  • 缓解措施：共享数据库上的高争用可能成为瓶颈。明确架构所有权，使用基于视图的访问限制数据可见性，或实施数据复制策略以降低耦合。

故障排除

常见问题

技能未加载 检查 YAML frontmatter 语法和必填字段

超出令牌限制 采用渐进式披露——将详细内容移至模块中

未找到模块 确认 SKILL.md 中的模块路径正确

具体组件

此范式的实现通常包含的工具和抽象概念的词汇表。它们不是依赖项，也不是 tools: frontmatter。

• dependency-analyzer：用于发现禁止依赖边的模块依赖关系图构建器
• module-boundary-enforcer：当模块跨边界导入时使构建失败
• refactoring-planner：根据模块为未来拆分做好准备的程度对其排序

退出标准

• ADR 将模块边界映射到业务能力，定义共享代码规则，并说明将模块拆分为独立服务的条件。
• 每个模块仅通过有文档说明的外观、API 或事件公开功能；模块间不存在直接数据库表访问（通过架构所有权审查验证）。
• 自动化依赖检查会在任何禁止的跨模块导入出现时使 CI 构建失败，并且至少记录一个此类违规测试用例。
• 跟踪变更耦合度指标（总是一起变更的模块），并将耦合度超过 50% 的模块对标记为边界审查候选项。