architecture-advisor

架构顾问

核心原则

1. 先询问，再推荐 — 在了解项目之前，绝不指定架构。先运行问卷，收集有关领域、团队、生命周期和约束的信息。
2. 选择合适规模的架构 — 最好的架构，是能够处理项目实际复杂度的最简单架构。CRUD 应用不需要 DDD。初创公司不需要 Clean Architecture。应根据实际需求而非理想目标匹配复杂度。
3. 架构并非一成不变 — 每种架构都有演进路径。从简单开始，在复杂度需要时再增加结构。记录决策，让团队知道何时需要演进。
4. 支持四种架构 — dotnet-claude-kit 提供一流的模式，支持 Vertical Slice Architecture（VSA）、Clean Architecture（CA）、DDD + Clean Architecture 和 Modular Monolith。每种架构都有各自的优势和权衡。

架构问卷

推荐架构之前，请从以下 6 个类别中提问。并非每个问题都适用于每个项目，可跳过不相关的问题。

类别 1：领域复杂度

#	问题	低信号	高信号
1	系统管理多少个不同的业务实体？	少于 10 个实体	20 个以上实体，且相互关联
2	业务规则是否涉及多个实体之间的交互？	规则仅针对单个实体的 CRUD	跨实体组的复杂不变量
3	是否存在包含多个步骤的业务工作流？	简单的请求 → 响应	Saga、审批链、状态机
4	领域专家是否使用专门的术语？	通用术语（创建、更新）	通用语言（承保、裁决）

类别 2：团队与组织

#	问题	低信号	高信号
5	开发团队有多大？	1-3 名开发人员	8 名以上开发人员，多个团队
6	不同团队是否负责系统的不同部分？	单个团队负责所有内容	团队按业务领域划分
7	团队对 .NET 的熟悉程度如何？	初级或水平不一	资深，熟悉各种模式

类别 3：系统生命周期与规模

#	问题	低信号	高信号
8	预计的系统生命周期是多久？	少于 2 年，MVP/原型	5 年以上，长期运行的产品
9	并发用户数或每秒请求数是多少？	少于 100 RPS	1000 RPS 以上，负载可变
10	系统是否需要按功能区域独立扩展？	负载均匀	热点需要独立扩展

类别 4：监管与合规

#	问题	低信号	高信号
11	是否有审计跟踪或合规要求？	基本日志记录即可	完整审计跟踪，SOX/HIPAA/PCI
12	系统的不同部分是否有不同的安全边界？	单一身份验证边界	多租户、数据隔离

类别 5：现有代码库

#	问题	低信号	高信号
13	这是全新项目还是棕地项目？	全新项目，从头开始	棕地项目，从旧系统迁移
14	团队是否遵循现有的架构模式？	没有既定模式	已有成熟规范

类别 6：集成复杂度

#	问题	低信号	高信号
15	系统需要集成多少个外部系统？	0-2 个简单 API	5 个以上系统，接口契约复杂
16	是否需要事件驱动或异步通信？	同步请求/响应	事件溯源、发布/订阅、最终一致性

决策矩阵

将问卷答案对应到架构建议：

特征	推荐架构	原因
领域复杂度低、团队规模小、生命周期短	垂直切片架构（VSA）	仪式最少、功能交付快、易于理解
领域复杂度低至中等、团队规模不限、以 API 为主	垂直切片架构（VSA）	功能内聚、每个操作对应一个文件、天然适配最小 API
领域复杂度中等、团队规模中等、生命周期长	整洁架构（CA）	通过项目引用强制实施边界、领域可测试、依赖方向清晰
领域复杂度高、术语专业、业务不变量复杂	DDD + 整洁架构	聚合保护不变量，值对象对领域概念建模，领域事件解耦副作用
存在多个限界上下文、每个领域配备独立团队、具备独立部署的可能性	模块化单体	模块隔离、独立数据存储、可逐步演进为微服务
棕地项目，已有分层架构	整洁架构	对从 N 层架构转型的团队而言较熟悉，既保留层级分离，又改善依赖方向

信号冲突时

如果不同信号指向不同架构：

1. 默认选择更简单的方案 — 拿不准时，先从 VSA 开始，再逐步演进
2. 领域复杂度优先 — 领域复杂度高时，优先级高于团队规模和生命周期信号
3. 团队熟悉度很重要 — 熟悉 CA 的团队使用 CA 会比学习 VSA 更高效，即使 VSA 在技术上更简单
4. 合规要求决定架构 — 监管要求往往会迫使架构设置更严格的边界（CA 或 DDD）

模式

垂直切片架构（VSA）

按功能而非按层组织。每个操作都是一个自成一体的切片。

src/MyApp.Api/
  Features/
    Orders/CreateOrder.cs    # Request + Handler + Response + Endpoint
    Orders/GetOrder.cs
  Common/
    Behaviors/ValidationBehavior.cs
    Persistence/AppDbContext.cs

适用场景： CRUD 密集型应用、API、MVP、小型至中型团队、中短期生命周期。 加载技能： vertical-slice

整洁架构（CA）

采用依赖倒置的同心分层结构。领域位于中心，基础设施位于边缘。

src/
  MyApp.Domain/              # Entities, interfaces, domain logic
  MyApp.Application/         # Use cases, DTOs, validation
  MyApp.Infrastructure/      # EF Core, external services
  MyApp.Api/                 # Endpoints, middleware

适用场景： 中等复杂度、生命周期长的系统、熟悉分层模式的团队。 加载技能： clean-architecture

DDD + 整洁架构

在整洁架构中使用战术 DDD 模式：聚合、值对象、领域事件。

src/
  MyApp.Domain/              # Aggregates, value objects, domain events, domain services
  MyApp.Application/         # Use cases orchestrating aggregates
  MyApp.Infrastructure/      # Persistence, external service adapters
  MyApp.Api/                 # Thin endpoints

适用场景： 领域复杂、术语专业、业务不变量严格、团队经验丰富。 加载技能： ddd + clean-architecture

模块化单体

在单个可部署单元中包含相互独立的模块，每个模块内部采用自己的架构。

src/
  MyApp.Host/                # Wires modules together
  Modules/
    Orders/                  # Own features, own DbContext, own architecture
    Catalog/                 # Can use VSA, CA, or DDD internally
  MyApp.Shared/              # Integration event contracts only

适用场景： 存在多个限界上下文、每个领域配备独立团队、未来可能拆分为微服务。 加载模板： modular-monolith

演进路径

架构不是一次性决定。系统会不断演进。以下是常见的迁移路径：

从	到	触发因素	方式
VSA	CA	领域逻辑不断增长，超出处理程序的职责范围	提取领域层和应用层，将功能保留为用例
VSA	模块化单体	出现多个限界上下文	将功能分组为模块，并添加模块边界
CA	DDD + CA	业务不变量变得复杂，出现原始类型偏执	引入聚合、值对象、领域事件
单体	模块化单体	团队相互掣肘、共享数据库造成耦合	拆分为各自拥有 DbContexts 和架构的模块
模块化单体	微服务	需要独立扩展、独立部署	将模块拆分为独立的可部署服务

反模式

为 CRUD 应用选择整洁架构

// BAD — 4 projects, 6+ files per feature for simple CRUD
src/MyApp.Domain/Entities/Product.cs
src/MyApp.Application/Products/CreateProduct/CreateProductCommand.cs
src/MyApp.Application/Products/CreateProduct/CreateProductHandler.cs
src/MyApp.Application/Products/CreateProduct/CreateProductValidator.cs
src/MyApp.Infrastructure/Persistence/ProductRepository.cs
src/MyApp.Api/Endpoints/ProductEndpoints.cs

// GOOD — VSA: 1 file for a simple CRUD feature
src/MyApp.Api/Features/Products/CreateProduct.cs

到处使用 DDD

// BAD — value objects and aggregates for a settings table
public class UserSettings : AggregateRoot  // overkill
{
    public ThemeName Theme { get; private set; }  // value object for "dark"/"light"?
    public void ChangeTheme(ThemeName theme) { /* domain event? really? */ }
}

// GOOD — simple entity for simple data
public class UserSettings
{
    public Guid UserId { get; init; }
    public string Theme { get; set; } = "light";
}

过早采用微服务

// BAD — splitting into 5 microservices on day one with 2 developers
OrderService (own repo, own DB, own CI/CD)
CatalogService (own repo, own DB, own CI/CD)
IdentityService (own repo, own DB, own CI/CD)
NotificationService (own repo, own DB, own CI/CD)
GatewayService (own repo, own CI/CD)

// GOOD — start as a modular monolith, extract when you have evidence
src/
  Modules/Orders/
  Modules/Catalog/
  Modules/Identity/
  Modules/Notifications/

跳过问卷

// BAD — "I always use Clean Architecture"
User: "Set up a new project for a todo app"
Agent: *immediately scaffolds 4-project CA solution*

// GOOD — ask first, then recommend
User: "Set up a new project for a todo app"
Agent: "Let me ask a few questions about your project to recommend the best architecture..."
Agent: *runs questionnaire, recommends VSA for low-complexity app*

决策指南

场景	建议
新项目，需求未知	执行问卷
简单的 CRUD API，1-3 名开发者	VSA
中等复杂度、生命周期长、团队经验丰富	Clean Architecture
领域复杂、使用专业术语	DDD + Clean Architecture
多个有界上下文、多个团队	Modular Monolith
现有 N 层代码库，需要现代化	Clean Architecture（迁移方式熟悉）
MVP / 初创公司，速度优先	VSA
监管 / 合规要求繁重	Clean Architecture 或 DDD（边界强制执行）
未来需要独立扩展	Modular Monolith（可随时拆分）