vertical-slice-architecture

垂直切片架构

快速参考：5 条规则

1. 一个功能 = 一个目录，其中包含处理器、请求/响应类型、验证逻辑和测试
2. 每个功能有一个入口点——一个接收路由器和依赖项的设置/注册函数。名称因约定而异（Setup、RegisterRoute、Map）；关键在于其作用，而非名称。
3. 尽量减少切片之间的耦合，尽量增强切片内部的耦合
4. 不要过早抽象——只有在多个切片中出现真正的重复后，才建立共享仓储/服务层
5. 主要通过入口点测试每个功能，验证结果（数据库状态、API 调用、响应）。也鼓励进行平台/适配器测试。

项目结构

{project}/
  features/              # or internal/features/ (Go), Features/ (.NET)
    {domain}/            # orders/, users/, kvs/
      {operation}/       # create/, list/, delete/
        handler          # Single entry point + orchestration
        request/response # DTOs
        validator        # Input validation (optional)
        test             # Co-located integration test
        internal/        # Feature-private helpers (optional)
  platform/              # or Infrastructure/ — shared cross-cutting concerns
    middleware/           # Auth, error handling, idempotency
    database/            # Connection pooling, circuit breakers
    observability/       # Metrics, tracing, structured logging
    opqueue/             # Operation queues, outbox patterns (if needed)
  main                   # Composition root wires features + infrastructure

工作流：添加新功能

1. 创建目录：features/{domain}/{operation}/
2. 定义处理器，并提供一个导出的设置函数
3. 定义请求/响应类型（简单情况可内联定义）
4. 添加验证逻辑
5. 在组合根（main）中注册
6. 编写集成测试：调用设置函数、发送请求并验证结果

工作流：添加横切关注点

放在 platform/ 中（不要放在功能内部）。例如：

• 身份验证中间件、错误处理、请求日志记录
• 数据库连接池、断路器
• 幂等中间件、操作队列、事件通知
• 可观测性（指标、追踪、结构化日志）

工作流：提取共享逻辑

只有在多个切片中出现真正的重复时才提取（自行判断——“3 个以上切片”只是经验参考，并非硬性规则）：

• 重复的业务规则：提取为领域实体/值对象
• 重复的数据访问模式：提取为共享仓储（仅针对该特定模式）
• 重复的 HTTP 辅助逻辑：提取到 platform/httpx/

按语言划分的关键决策

识别项目所用的语言/框架，并查阅相应参考资料：

• 各语言的模式：Go、.NET、Java、TypeScript、Python 的相关内容见 references/patterns-by-language.md
• 各语言的测试：testcontainers、模拟验证、集成测试模式的相关内容见 references/testing.md
• 核心原则：详细规则、反模式和共享领域模型指南见 references/principles.md

单一入口点契约

每个功能都公开一个主要的设置/注册函数。内部类型保持私有。入口点名称遵循惯例——关键在于：每个功能有一个将该切片接入框架的公共函数。

• Go——惯例名称为 Setup 或 RegisterRoute；签名为 func Setup(r gin.IRoutes, repo Repository)；通过显式参数进行 DI。
• .NET——惯例名称为 Map（静态）；签名为 static void Map(IEndpointRouteBuilder app)；依赖项由处理器中的 DI 容器解析。
• Java/Kotlin——通过组件扫描发现的 @RestController 类；使用 Spring DI（构造函数注入）。
• TypeScript——惯例名称为 setup；签名为 function setup(router: Router, db: Database): void；通过显式参数进行 DI。
• Python——惯例名称为 setup；签名为 def setup(router: APIRouter, db: Database) -> None；通过显式参数或 Depends() 进行 DI。

例外情况：版本化 API 可以提供 SetupV1/SetupV2 封装函数，共用内部处理器接线逻辑。采用自动发现机制的框架（Spring、NestJS）则使用控制器/模块类本身作为入口点。

测试

各语言的完整测试策略见 references/testing.md，包括功能集成测试、平台/适配器测试、模拟验证模式和测试命名惯例。