在现代企业级单体与微服务架构中，底层构建块的设计质量决定了整个系统的稳定上限。
building-blocks/ 目录汇总了 BitzOrcas.Modern 经过生产实战锤炼的核心原语与基础设施武器库。每个构建块均遵循 “强类型契约、零多余反射、严格租户隔离、默认安全” 的设计哲学。
核心构建块知识地图
构建块导航清单
1. 核心领域原语与统一时钟
Entity、AggregateRoot、TenantAggregateRoot继承阶梯；- 强类型
Result与Error抛弃低效业务异常； IAppClock统一时间源彻底杜绝时区与环境漂移。
2. 统一聚合根与持久化内核
- 告别繁琐的 1:1
*Entity与Mapper胶水代码； - Roslyn 增量生成器在编译期自动生成 EF Core 与 SqlSugar 双 ORM Fluent 配置；
- 值对象扁平化（Flattening）与拦截器自动审计。
3. 标准列表查询内核与 QueryShape
IDeclareQueryShape声明式定义查询形状，编译期锁定执行计划；- 双 ORM 投影直接下推到 SQL
SELECT列级别，零实体回表； - 防崩溃分页规范化（1~1000 边界单点守门）。
4. 事件总线与 CAP Outbox
- 进程内领域事件 vs 跨模块集成事件；
- 事务性发件箱（Transactional Outbox）确保业务数据与事件同生共死；
- 幂等消费防重与重试机制。
5. 多级缓存与防击穿（FusionCache）
- 内存 L1 + Redis L2 双层多级缓存；
- 负缓存（Negative Caching）与 Single-Flight 单飞防击穿；
- 事务提交后按 Tag 广播失效。
6. 分布式锁与租约防死锁
IDistributedLock强类型锁句柄与await using安全释放；- Redis 原子获取与所有者校验释放；
- 租约过期机制与 FallbackMode 降级策略。
7. 数据库驱动后台作业（Quartz）
- 调度器无关的
IJobExecutor<T>业务执行器； - Quartz 持久化集群保证多实例单点触发；
- Operations 探针与优雅停机。
8. S3 对象存储与预签名安全
IFileStorage统一存储抽象（Local / MinIO / AWS S3）；- 客户端直传预签名 URL（Presigned URL），API 零带宽消耗；
- 租户私有桶防盗链与 IDOR 越权拦截。
9. 租户配额与限流计量
- 令牌桶（Token Bucket）算法与突发流量缓冲；
- Host 层 RedisTokenBucket 限流与 PlatformBilling
QuotaService配额检查； - 429 Too Many Requests 优雅拦截。
10. OpenAPI 3.1 与 Scalar 现代文档
[GenerateEndpoint]编译期元数据提取；- Native AOT 模式下完全零反射；
- Scalar 现代交互式 API 调试控制台。
本章核心导航
- 01/16
核心构建块
Entity、AggregateRoot、TenantAggregateRoot、Result、Error、领域事件、查询值对象、平台硬边界与时钟的当前契约。
- 02/16
统一聚合根与持久化内核
深度剖析 BitzOrcas.Modern 为什么抛弃传统的 Entity + Mapper + Aggregate 三件套，以及编译期 ORM Fluent Configuration Generator 如何实现零反射双 ORM 适配。
- 03/16
列表查询与导出范围契约
说明 W0 列表查询契约、组合分页、范围筛选值对象、QueryShape 标量展开、远程选项、关联快照和导出范围校验。
- 04/16
标准列表查询内核与 QueryShape
深度剖析 BitzOrcas.Modern 标准列表查询内核，揭秘 QueryShape 编译期执行计划生成、多表联查别名自动解耦、手写条件扩展与双 ORM 投影下推。
- 05/16
持久化构建块
统一聚合根、编译期 ORM 配置、Command/ReadModel/Query 端口、SqlSugar 与 EF Core 生产并行契约。
- 06/16
共享基础构建块
Result、错误、时间、调用者、租户、种子框架与共享抽象归属规则的源码核验参考。
- 07/16
多级缓存与防击穿：FusionCache L1/L2 实战
深度剖析 BitzOrcas.Modern 多级缓存体系，揭秘 FusionCache 内存 L1 + Redis L2 双层架构、CacheScope 租户隔离、负缓存防御与提交后精准标签失效。
- 08/16
分布式锁与租约防死锁：IDistributedLock 深度实操
深入解析 BitzOrcas.Modern 分布式锁内核，揭秘 Redis 原子加锁与所有者校验释放、租约自动续期机制以及 Deny/Allow 降级防御策略。
- 09/16
事件构建块
CAP、RabbitMQ、SQL Server Outbox、主题契约、消费者幂等和失败运维的参考说明。
- 10/16
事件抽象层
区分领域事件、集成事件与通知端口，并说明事件收集、主题解析和 Null 适配器的运行边界。
- 11/16
数据库驱动后台作业与调度安全：Quartz 实操指南
告别难以运维的外部 Cron！深入解析 BitzOrcas.Modern 数据库驱动后台作业体系，揭秘类型化 IJobExecutor 调度器无关设计、Quartz 持久化集群防并发堆积与 Operations 探针。
- 12/16
对象存储与 S3 兼容集成：IFileStorage 安全实操
深度剖析 BitzOrcas.Modern 对象存储构建块，揭秘 IFileStorage 抽象、MinIO/AWS S3 生产适配器、客户端直传预签名 URL 与租户防越权隔离。
- 13/16
配额与限流：Host 令牌桶与计费配额
区分 Host 层 Redis 令牌桶限流与 PlatformBilling 计费配额两套机制：429 与超额的归属、QuotaService 检查、用量提交命令与幂等事实。
- 14/16
现代 API 文档与零反射生成：OpenAPI 3.1 + Scalar
告别沉重低效的 Swashbuckle 运行时反射！深入解析 BitzOrcas.Modern 编译期 OpenAPI 3.1 元数据提取与 Scalar 交互式现代 API 文档客户端。
- 15/16
多渠道消息投递构建块：从通知事实到外部扇出
掌握 BitzOrcas.Modern 企业级消息投递架构，深入通知事实落盘与异步扇出解耦、邮件/短信/企微连接器与发送状态防丢失。
- 16/16
Web 与 API 基础设施构建块：Minimal API 与管线装配
深入解析 BitzOrcas.Modern 的 Web 与 HTTP API 基础设施底座，掌握 [GenerateEndpoint] 编译期 Minimal API 绑定、ASP.NET Core 中间件拓扑与 RFC 9457 Problem Details 规范。