modular-monolith-architecture

模块化单体架构 — 项目脚手架

生成可用于生产环境的模块化单体项目，遵循行业最佳实践，具备恰当的模块边界、内部 API、共享内核和基础设施。

概述

模块化单体是一个可独立部署的应用，由松耦合、高内聚的模块组成，每个模块代表一个限界上下文。它结合了单体架构的简洁性（单次部署、ACID 事务、进程内调用）与微服务风格的模块化（边界清晰、团队自主、独立开发）。

此技能可搭建完整项目，包含：

• 模块隔离：每个模块负责自己的领域、数据访问和 API 接口
• 模块间通信：通过公共契约/接口进行，绝不暴露内部细节
• 共享内核：将横切关注点（身份验证、日志记录、事件）放在共享层
• 按模块划分数据库架构：在单个 RDBMS 中实现逻辑隔离
• 支持后续迁移的边界：模块日后可拆分为微服务

工作流

步骤 1：收集需求

如果用户尚未指定，请询问：

1. 语言/框架（例如 C#/ASP.NET Core、Java/Spring Boot、TypeScript/NestJS、Python/Django、Go）
2. 项目名称
3. 业务模块（例如 Product、Order、Payment、Shipping、Notification）
4. 数据库偏好（PostgreSQL、MySQL、SQL Server、用于开发的 SQLite）
5. 其他功能：事件总线、API 网关、Docker、CI/CD

如果用户提供了 $ARGUMENTS，请解析：$ARGUMENTS[0] = 语言/框架，$ARGUMENTS[1] = 项目名称，其余参数 = 模块名称。

步骤 2：生成项目结构

阅读所选框架的架构参考资料：

• 详细的结构模式请参见 references/project-structures.md
• 模块设计模式请参见 references/module-design.md
• 对比和决策指南请参见 references/architecture-guide.md
• 事件驱动模式和事件总线设计请参见 references/event-driven-patterns.md
• 模块间通信和契约版本管理请参见 references/api-versioning-communication.md
• 具体的脚手架示例请参见 examples/dotnet-scaffold.md 和 examples/nestjs-scaffold.md

生成项目时，请遵循以下关键规则：

模块规则

1. 每个模块都有自己的目录和内部层（Domain/Application/Infrastructure/API）
2. 模块只能通过公共契约（接口/DTO）通信，绝不引用其他模块的内部类型
3. 每个模块都有自己的数据库架构或迁移文件夹
4. 每个模块自行注册其服务/依赖项
5. 模块之间不得存在循环依赖

共享内核规则

1. 仅包含横切关注点：基类实体、通用值对象、事件总线接口、身份验证抽象
2. 必须保持精简——如果内容变得庞大，说明其中某些内容应归属于某个模块
3. 绝不包含特定于任何模块的业务逻辑

基础设施规则

1. 单一入口点（Program.cs / main.ts / main.py / main.go）
2. 由组合根将所有模块连接起来
3. 共享数据库上下文/会话，但各架构相互隔离
4. 通过事件总线实现模块间的异步通信（进程内实现，可升级为消息代理）

步骤 3：生成代码

为每个模块生成：

• 领域层：实体、值对象、领域事件、仓储接口
• 应用层：用例／命令／查询、DTO、验证
• 基础设施层：仓储实现、数据库配置、迁移
• API 层：控制器／处理程序、请求／响应模型、模块注册

还要生成：

• 共享内核：基类、事件总线、通用抽象
• 宿主／入口点：组合根、中间件、配置
• 测试：模块单元测试、集成测试、契约测试和架构边界测试——参见 references/testing-strategies.md
• 可观测性：模块范围内的日志记录、运行状况检查和跟踪设置——参见 references/observability.md
• Docker（如果有要求）：Dockerfile + 包含数据库的 docker-compose
• README.md：架构概览、运行方法、添加模块的方法（使用 examples/README-template.md）

步骤 4：验证

生成后：

1. 验证没有模块直接引用其他模块的内部类型
2. 确认每个模块都有自己的架构／迁移文件夹
3. 检查共享内核不包含业务逻辑
4. 确保项目可以成功构建／编译
5. 运行生成的所有测试

脚本 可用于集成到 CI：

• scripts/validate-boundaries.sh <modules-dir> — 检测跨模块边界违规
• scripts/validate-shared-kernel.sh <shared-dir> <modules-dir> — 确保共享内核不引用模块
• scripts/check-circular-deps.sh <modules-dir> — 检测模块间的循环依赖

步骤 5：迁移指南

如果用户询问如何将模块提取为微服务，请参见 references/migration-to-microservices.md，其中提供了详细的分步指南，涵盖：

• 何时提取（基于证据的信号）
• 提取前检查清单
• 创建服务、替换实现、添加弹性机制
• 回滚策略

应遵循的核心原则

原则	含义	执行方式
高内聚	模块包含其领域所需的一切	每个模块包含领域层 + 应用层 + 基础设施层 + API 层
低耦合	模块不依赖彼此的内部实现	仅通过共享契约／接口进行通信
单一职责	每个模块都有一个有界上下文	每个模块目录对应一个业务领域
数据封装	模块拥有自己的数据	每个模块使用独立的数据库架构，不进行跨模块查询
依赖显式化	所有模块依赖都清晰可见	模块注册文件列出所需契约
领域驱动设计	模块与业务领域保持一致	按业务能力命名，而不是按技术层命名

调用示例

/modular-monolith dotnet ECommerceApp Product Order Payment Shipping
/modular-monolith spring-boot MyShop catalog basket checkout
/modular-monolith nestjs SaasApp tenant billing notification
/modular-monolith go FinanceApp accounts transactions reporting

不适用场景

如果用户描述以下情况，建议改用微服务：

• 团队需要完全独立的部署节奏
• 需要多语言技术栈（Python 机器学习 + Go API + Java 企业应用）
• 对每个服务有极端的独立扩展需求
• 已有 Kubernetes 基础设施和成熟的 DevOps 能力

如果符合以下情况，建议采用简单的单体架构：

• 独立开发者或非常小的团队（1-3 名开发者）
• 领域边界不明确的原型／MVP
• 业务领域少于 3 个的应用