简介

BitzOrcas.Modern 是一个固执己见的、以生产为首要目标的 .NET 10 模块化单体架构模板，用于构建多租户 SaaS 和企业级 API。围绕 AI 辅助开发 的核心理念设计——从清晰的模块边界到显式的四阶段注册，每一项架构决策都优先考虑代码的机器可读性、约束可执行性，以及对 LLM 协作者的安全性。

你获得完整的源代码——BuildingBlocks（基础框架）、Platform（平台级共享）、Hosts（应用宿主）和 Tooling（工具链）——通过 Minimal APIs、Mediator 和可插拔的 ORM 适配器层（SqlSugar 为主、EF Core 可选）进行组装。没有黑盒 NuGet 包：你拥有并可以修改一切。

核心特性

• 模块化单体，垂直切片。 每个模块都是一个限界上下文，拥有自己的 Contracts、Domain、Application、Infrastructure 和 Endpoints。跨模块通信仅通过 *.Contracts 项目进行——运行时项目永不互相引用。模块治理通过 IAppModule + ArchUnitNET 测试强制执行。
• AI 辅助开发设计。 代码库专为 LLM 理解而结构化：显式的四阶段 DI 注册、文档化的约束、保持不变量的模式。架构决策以 ADR 记录并通过自动化测试执行，而非仅靠约定。
• 第一天即多租户。 8 级 ITenantResolver 链，配合 TenantEntityBase 层次结构。SqlSugar 全局过滤器、跨租户查询模式和后台作业租户上下文传播开箱即用。
• 统一授权。 RBAC + ABAC + ReBAC + DataScope + Feature Flags + AppScope——单个 IAuthorizationDecisionService 根据请求分发到合适的策略评估器。
• 可插拔持久化。 SqlSugar（主 ORM，简洁干净）配合可选的 EF Core 和 Dapper（只读查询）适配器。不触碰应用代码即可切换 ORM——适配器模式让处理器保持纯净。
• 事件驱动架构。 聚合根上的领域事件 + 通过 CAP + RabbitMQ 的集成事件（Outbox 模式，同库事务）。自动重试、死信队列和每实例资源同步。
• 7 管道 Mediator 链。 验证 → 授权 → 幂等 → 事务 → 日志 → 活动审计 → 领域事件分发——每个行为都是可组合、可测试的管道步骤。
• 7 类审计 + 分表。 活动审计、实体变更审计、安全审计、异常审计、请求审计、授权审计和后台作业审计。按月分表存储，支持可配置的保留策略。
• 后台作业。 Quartz.NET 调度器配合 SystemJobTenantContext，支持租户感知的作业执行。
• 可观测性内置。 OpenTelemetry 链路追踪、指标和日志（OTLP）；Serilog 结构化日志；健康检查；租户操作的业务上下文标签。
• API 文档。 OpenAPI + Scalar UI。通过 Asp.Versioning.Http 实现版本化路由。
• 云就绪。 .NET Aspire AppHost 一条命令启动 SQL Server 和 RabbitMQ。生产部署支持 Docker Compose。
• 模板引擎。 基于 Scriban 的代码生成工具，从元数据脚手架新模块、特性和契约。
• Sandbox 示例模块。 内置 Notes（备忘录）、Greetings（问候）和 Ping（健康检查）示例，演示完整的垂直切片模式——新特性的理想起点。

架构总览

BitzOrcas.Modern/
├── src/
│   ├── BuildingBlocks/          共享框架库
│   │   ├── BitzOrcas.Domain         DDD 原语、`Result<T>`、EntityBase
│   │   ├── BitzOrcas.Application     Mediator 管道、授权、多租户、Sandbox
│   │   ├── BitzOrcas.Infrastructure  共享基础设施抽象
│   │   ├── BitzOrcas.Infrastructure.SqlSugar   SqlSugar 适配器（主 ORM）
│   │   ├── BitzOrcas.Infrastructure.EfCore     EF Core 适配器（可选）
│   │   ├── BitzOrcas.Infrastructure.Dapper      Dapper 只读查询适配器
│   │   ├── BitzOrcas.Infrastructure.Persistence.Models  共享持久化模型
│   │   ├── BitzOrcas.Modularity      IAppModule、AppModuleRegistry、边界校验
│   │   ├── BitzOrcas.CodeGeneration.*  Scriban 模板引擎
│   │   └── ...
│   │
│   ├── Platform/               平台级共享契约
│   │   ├── BitzOrcas.Platform.Application
│   │   ├── BitzOrcas.Platform.Contracts
│   │   └── BitzOrcas.SaaS.Contracts
│   │
│   ├── Hosts/                  应用宿主
│   │   ├── BitzOrcas.Api           API 组合根（Program.cs）
│   │   ├── BitzOrcas.AppHost       .NET Aspire 编排器
│   │   ├── BitzOrcas.JobHost       后台作业宿主（Quartz）
│   │   └── BitzOrcas.ServiceDefaults   Aspire 服务默认配置
│   │
│   └── Tooling/                开发与代码生成工具
│       ├── BitzOrcas.SeedData.Exporter   CSV 种子数据管理
│       └── BitzOrcas.Modern.Templates       dotnet new 模板
│
├── tests/                     架构测试 + 各模块测试
├── docs/                      ADR、上下文地图、路线图
└── scripts/                   构建与工具脚本

模块边界由 ArchUnitNET 规则（tests/ 目录中）强制执行。

垂直切片布局

每个特性都是一个垂直切片。Sandbox 模块演示了这个模式：

BuildingBlocks/BitzOrcas.Application/Sandbox/Notes/
  CreateNoteCommand.cs              ← 命令（IRequest<TResponse>）
  CreateNoteCommandHandler.cs       ← 处理器（IRequestHandler<TCommand, TResponse>）
  GetNoteByIdQuery.cs               ← 查询
  GetNoteByIdQueryHandler.cs        ← 查询处理器
  ISandboxDataPort.cs               ← 端口（持久化抽象）

处理器使用 public sealed，返回 ValueTask<Result<T>>，并使用 .ConfigureAwait(false)。端点定义在 API 宿主的 Endpoints/ 目录中，通过 MapBitzOrcasEndpoints() 映射。

组合根

src/Hosts/BitzOrcas.Api/Program.cs 通过四个显式阶段组装平台：

// 阶段 1：核心运行时（时钟、CurrentUser、审计默认、租户解析链、UoW）
builder.Services.AddBitzOrcasCoreRuntime(builder.Configuration);

// 阶段 2：持久化适配器（SqlSugar 主适配器；EF Core / Dapper 可选）
builder.Services.AddBitzOrcasPersistenceAdapters(builder.Configuration);

// 阶段 3：认证（JWT / HMAC / ApiKey — 启动时快速失败校验密钥）
builder.Services.AddBitzOrcasAuthentication(builder.Configuration, builder.Environment);

// 阶段 4：API 管道（Mediator + Mapster + JSON + OpenAPI + Scalar + RateLimiter）
builder.Services.AddBitzOrcasApiPipeline(builder.Configuration);

API 在启动时绝不修改数据。Schema 初始化和种子数据通过 --init-schema / --seed-demo CLI 参数处理——进程执行 schema 创建、审计分表创建和 CSV 种子数据填充，然后立即退出，不进入 web 管道。

技术栈

运行时

测试

分发

设计约束

BitzOrcas.Modern 围绕两个关键约束构建：

1. AI 辅助开发。 代码库的结构使 LLM 协作者能够理解边界、注册顺序和不变量而无需猜测。四阶段 DI 注册、显式模块契约和 ADR 强制执行的架构测试使系统自文档化。

2. Native AOT 就绪。 虽然当前并非所有依赖都支持 AOT（如 SqlSugar），但架构设计尽可能减少反射使用。Mediator 使用源代码生成，验证使用原生 IRequestRule，序列化使用 System.Text.Json。

下一步

• 环境准备 — 需要安装什么。
• 快速开始 — 60 秒运行项目。
• 架构 — 模块化单体、VSA、模块边界。
• 架构图 — 系统总览、模块依赖、管道流程的可视化图表。
• 模块 — Identity、Tenancy、Authorization、Auditing 等。
• 基础框架 — 共享框架库和适配器。