modular-monolith-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modular Monolithic Architecture — Project Scaffolder

Modular Monolithic Architecture — 项目脚手架生成器

Generate production-ready Modular Monolith projects with proper module boundaries, internal APIs, shared kernel, and infrastructure following industry best practices.

遵循行业最佳实践，生成具备合理模块边界、内部API、共享核心层及基础设施的生产级Modular Monolith项目。

Overview

概述

A Modular Monolith is a single deployable application organized into loosely coupled, highly cohesive modules — each representing a bounded context. It combines monolithic simplicity (single deployment, ACID transactions, in-process calls) with microservices-style modularity (clear boundaries, team autonomy, independent development).

This skill scaffolds complete projects with:

Module isolation: Each module owns its domain, data access, and API surface
Inter-module communication: Via public contracts/interfaces, never internal details
Shared kernel: Cross-cutting concerns (auth, logging, events) in a shared layer
Database-per-module schema: Logical isolation within a single RDBMS
Migration-ready boundaries: Modules can be extracted to microservices later

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

本工具可搭建包含以下特性的完整项目：

模块隔离：每个模块独立管理自身领域、数据访问及API接口
模块间通信：仅通过公共契约/接口实现，绝不暴露内部细节
共享核心层：横切关注点（认证、日志、事件）统一置于共享层
单库多模块 schema：在单个关系型数据库内实现逻辑隔离
可迁移边界：后续可将模块提取为微服务

Workflow

工作流程

Step 1: Gather Requirements

步骤1：收集需求

If the user hasn't specified, ask for:

Language/Framework (e.g., C#/ASP.NET Core, Java/Spring Boot, TypeScript/NestJS, Python/Django, Go)
Project name
Business modules (e.g., Product, Order, Payment, Shipping, Notification)
Database preference (PostgreSQL, MySQL, SQL Server, SQLite for dev)
Additional features: Event bus, API gateway, Docker, CI/CD

If the user provides

$ARGUMENTS

, parse them:

$ARGUMENTS[0]

= language/framework,

$ARGUMENTS[1]

= project name, remaining = module names.

若用户未明确指定，需询问以下信息：

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

若用户提供

$ARGUMENTS

，按如下解析：

$ARGUMENTS[0]

= 语言/框架，

$ARGUMENTS[1]

= 项目名称，剩余参数为模块名称。

Step 2: Generate Project Structure

步骤2：生成项目结构

Read the architecture references for the chosen framework:

For detailed structure patterns, see references/project-structures.md
For module design patterns, see references/module-design.md
For comparison and decision guide, see references/architecture-guide.md
For event-driven patterns and event bus design, see references/event-driven-patterns.md
For inter-module communication and contract versioning, see references/api-versioning-communication.md
For concrete scaffold examples, see examples/dotnet-scaffold.md and examples/nestjs-scaffold.md

Generate the project following these critical rules:

参考所选框架的架构文档：

详细结构模式请见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

生成项目时需遵循以下核心规则：

Module Rules

模块规则

Each module gets its own directory with internal layers (Domain/Application/Infrastructure/API)
Modules communicate ONLY through public contracts (interfaces/DTOs) — never reference another module's internal types
Each module has its own database schema or migration folder
Each module registers its own services/dependencies
No circular dependencies between modules

每个模块拥有独立目录，包含内部层级（Domain/Application/Infrastructure/API）
模块间仅通过公共契约（接口/DTO）通信——绝不引用其他模块的内部类型
每个模块拥有独立的数据库schema或迁移文件夹
每个模块独立注册自身服务/依赖
模块间无循环依赖

Shared Kernel Rules

共享核心层规则

Contains ONLY cross-cutting concerns: base entities, common value objects, event bus interfaces, auth abstractions
Must be thin — if it grows large, something belongs in a module
Never contains business logic specific to any module

仅包含横切关注点：基础实体、通用值对象、事件总线接口、认证抽象
必须保持精简——若体积过大，说明部分内容应归属到模块中
绝不包含特定模块的业务逻辑

Infrastructure Rules

基础设施规则

Single entry point (Program.cs / main.ts / main.py / main.go)
Composition root wires all modules together
Database context/session is shared but schemas are isolated
Event bus for async inter-module communication (in-process, upgradeable to message broker)

单一入口点（Program.cs / main.ts / main.py / main.go）
组合根负责整合所有模块
数据库上下文/会话共享，但schema相互隔离
事件总线用于模块间异步通信（进程内实现，可升级为消息中间件）

Step 3: Generate Code

步骤3：生成代码

For each module, generate:

Domain layer: Entities, value objects, domain events, repository interfaces
Application layer: Use cases/commands/queries, DTOs, validation
Infrastructure layer: Repository implementations, database configuration, migrations
API layer: Controllers/handlers, request/response models, module registration

Also generate:

Shared kernel: Base classes, event bus, common abstractions
Host/entry point: Composition root, middleware, configuration
Tests: Module unit tests, integration tests, contract tests, and architecture boundary tests — see references/testing-strategies.md
Observability: Module-scoped logging, health checks, and tracing setup — see references/observability.md
Docker (if requested): Dockerfile + docker-compose with database
README.md: Architecture overview, how to run, how to add modules (use examples/README-template.md)

为每个模块生成以下内容：

Domain层：实体、值对象、领域事件、仓库接口
Application层：用例/命令/查询、DTO、验证逻辑
Infrastructure层：仓库实现、数据库配置、迁移脚本
API层：控制器/处理器、请求/响应模型、模块注册代码

同时生成：

共享核心层：基类、事件总线、通用抽象
宿主/入口点：组合根、中间件、配置
测试代码：模块单元测试、集成测试、契约测试及架构边界测试——请见references/testing-strategies.md
可观测性：模块级日志、健康检查及链路追踪配置——请见references/observability.md
Docker（若需）：Dockerfile + 包含数据库的docker-compose配置
README.md：架构概述、运行指南、模块添加方法（使用examples/README-template.md模板）

Step 4: Validate

步骤4：验证

After generation:

Verify no module directly references another module's internal types
Confirm each module has its own schema/migration folder
Check that the shared kernel contains no business logic
Ensure the project builds/compiles successfully
Run any generated tests

Validation scripts are available in scripts/ for CI integration:

scripts/validate-boundaries.sh <modules-dir>

— detects cross-module boundary violations

scripts/validate-shared-kernel.sh <shared-dir> <modules-dir>

— ensures shared kernel doesn't reference modules

```
scripts/check-circular-deps.sh <modules-dir>
```
— detects circular dependencies between modules

生成完成后：

验证无模块直接引用其他模块的内部类型
确认每个模块拥有独立的schema/迁移文件夹
检查共享核心层是否包含业务逻辑
确保项目可成功构建/编译
运行生成的测试用例

CI集成可使用scripts/目录下的验证脚本：

scripts/validate-boundaries.sh <modules-dir>

—— 检测跨模块边界违规

scripts/validate-shared-kernel.sh <shared-dir> <modules-dir>

—— 确保共享核心层未引用模块内容

scripts/check-circular-deps.sh <modules-dir>

—— 检测模块间循环依赖

Step 5: Migration Guidance

步骤5：迁移指导

If the user asks about extracting modules to microservices, see references/migration-to-microservices.md for a detailed step-by-step guide covering:

When to extract (evidence-based signals)
Pre-extraction checklist
Creating the service, swapping the implementation, adding resilience
Rollback strategy

若用户询问将模块提取为微服务的方法，请参考references/migration-to-microservices.md中的详细步骤指南，涵盖：

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

Key Principles to Enforce

需遵循的核心原则

Principle	What It Means	How to Enforce
High Cohesion	Module contains everything for its domain	Domain + Application + Infrastructure + API per module
Low Coupling	Modules don't depend on each other's internals	Communication only via shared contracts/interfaces
Single Responsibility	Each module has one bounded context	One business domain per module directory
Encapsulated Data	Module owns its data	Separate DB schema per module, no cross-module queries
Explicit Dependencies	All module dependencies are visible	Module registration file listing required contracts
Domain-Driven Design	Modules align with business domains	Named after business capabilities, not technical layers

原则	含义	实施方式
高内聚	模块包含其领域的所有相关内容	每个模块包含Domain + Application + Infrastructure + API层
低耦合	模块不依赖其他模块的内部实现	仅通过共享契约/接口通信
单一职责	每个模块对应一个限界上下文	每个模块目录对应一个业务领域
数据封装	模块拥有自身数据的控制权	每个模块使用独立的DB schema，禁止跨模块查询
依赖显式化	所有模块依赖均可见	模块注册文件列出所需契约
领域驱动设计	模块与业务领域对齐	以业务能力命名，而非技术层级

Example Invocations

调用示例

/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

/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

When NOT to Use This

不适用于以下场景

Suggest microservices instead if the user describes:

Teams needing completely independent deployment cadences
Requirements for polyglot tech stacks (Python ML + Go APIs + Java enterprise)
Extreme per-service scaling requirements
Already having Kubernetes infrastructure and DevOps maturity

Suggest a simple monolith if:

Solo developer or very small team (1-3 devs)
Prototype/MVP with unclear domain boundaries
Application with fewer than 3 distinct business domains

若用户描述以下情况，建议使用微服务：

团队需要完全独立的发布节奏
多技术栈需求（如Python机器学习 + Go API + Java企业级服务）
极端的单服务扩容需求
已具备Kubernetes基础设施及DevOps成熟度

若用户属于以下场景，建议使用简单单体应用：

独立开发者或极小团队（1-3人）
原型/MVP，领域边界不清晰
应用包含少于3个独立业务领域