企业架构十大反模式与避坑宝典

企业架构十大反模式与避坑宝典 (Architecture Anti-Patterns & Pitfalls)

一套优秀的架构底座不仅要定义“推荐怎么做”，更要严厉指出“绝对禁止怎么做”。在实际工程演进中，经验不足的开发者往往会因惯性思维引入隐蔽的坏味道（Smells），轻则导致系统在突发流量下雪崩，重则引发跨租户数据越权与巨额经济损失。

本文由资深架构师团队梳理，深度剖析在 BitzOrcas.Modern 体系中必须严防死守的 10 大架构反模式 及对应的正向防御法则。

1. 异步伪阻塞导致线程池饥饿 (Sync-over-Async Starvation)

致命反模式：在 Mediator Pipeline Behavior 或 CommandHandler 中调用 .Result 或 .Wait() 同步等待异步任务：

// 严禁这样写：在高并发下极易引发 ASP.NET Core ThreadPool 线程枯竭与请求排队死锁
var user = _userRepository.GetByIdAsync(userId).Result;

正向防御法则：必须全链路使用 async/await 并向下透传 CancellationToken，保持异步状态机贯穿至数据驱动最底层。

2. 跨模块层级穿透 (Cross-Module Layer Penetration)

致命反模式：诉讼模块 Litigation.Application 直接在 csproj 中添加对 Identity.Infrastructure 或 Identity.Domain 的物理引用。
正向防御法则：模块间在编译期仅允许依赖对方的 *.Contracts。如果需要触发跨模块联动，首选 CAP 事务发件箱集成事件；如果需要直接查询，通过对方暴露在 Contracts 中的只读 Store 端口或 Mediator 跨模块 Query。该规则受 ArchitectureTests 门禁自动化断言守护。

3. 多租户缓存与原生 SQL 隔离穿透 (Tenant Isolation Leakage)

致命反模式：使用 Dapper 编写高性能 SQL 时遗漏 TenantId 过滤条件，或在 Redis 中写入全局共享 Key：
```
// 严禁这样写：租户 A 会读到租户 B 的缓存数据
await _cache.SetAsync("active_case_summary", summary);
```
正向防御法则：所有缓存 Key 必须显式携带 {tenantId} 命名空间前缀（如 $"tenant:{tenantId}:cases:{caseId}"）；所有原生 SQL 语句必须在 WHERE 条件中硬性包含 TenantId = @TenantId。

4. 本地时钟导致的物理分表时间漂移 (Local Time Partition Drift)

致命反模式：分表计算逻辑中调用 DateTime.Now 本地时钟，当应用部署在未统一配置时区的 Docker 容器中时，导致写入的分表与预期相差数小时甚至跨天。
正向防御法则：框架全线采用 UTC 时间戳（DateTimeOffset.UtcNow），日期转换在应用展示层完成，分表键计算必须严格基于 UTC 日期。

5. 简单 CRUD 场景过度包装 DTO (Separate DTO Explosion)

开发效率反模式：为了一个仅仅包含 3 个字段的简单字典表，机械化创建 15 个一次性 DTO 与繁琐的手写 AutoMapper 映射代码。
正向防御法则：遵循框架的聚合根同构原则。内部垂直切片内部可直接复用具有编译期 Fluent 约束的领域聚合根，唯有真正跨越网络/进程边界的 API 契约才定义外部 DTO。

6. 在长事务内部进行非幂等外部调用 (Non-Idempotent Call in Long Transaction)

分布式反模式：在数据库事务块内部直接调用第三方微信支付或外部法院 HTTP 接口，导致数据库行级锁长达数秒不释放。
正向防御法则：严格遵循 “事务快速提交，状态异步驱动”。业务在本地事务中将待调用意图写入 CAP 事务发件箱（Outbox），由独立后台线程负责对外网络请求与重试补偿。

7. 领域逻辑抛出临时异常代替 Result (Throwing Raw Exceptions)

错误处理反模式：遇到业务逻辑不满足时随手 throw new Exception("余额不足")。
正向防御法则：业务失败不是不可预期的系统崩溃，必须返回强类型的 Result.Failure(ModuleErrors.Code)。仅当发生数据库断连、硬件不可达等物理灾难时才抛出异常由全局 ExceptionHandler 接管并返回 RFC 9457 ProblemDetails。

8. 裸写魔术字符串与隐式状态 (Magic String Pollution)

可维护性反模式：在业务逻辑中到处充斥 "PENDING"、"01"、"ERR_FAIL" 等无语义魔术字符串。
正向防御法则：所有系统状态必须显式声明为枚举或强类型智能枚举；所有错误码必须在模块契约的 *Errors 静态只读属性中显式挂载，确保全局可搜索、可溯源。

9. 生产发版锁表式卸载索引 (Dropping Indexes During DDL)

运维发版反模式：在自动化迁移脚本中对包含数百万行的大表执行 DROP INDEX 然后重建，导致发版期间全表锁死。
正向防御法则：BitzOrcas 的 SQL Server 目录探测路径严格禁止卸载已有索引，只对新表建声明索引，已有表按 ALTER TABLE ADD NULL 且附加 LOCK_TIMEOUT 5000 锁安全退出。

10. 智能体高危操作失控放行 (Unsupervised Autonomous Mutation)

AI 治理反模式：将具备退款、删除用户、撤销合同能力的 MCP 工具直接开放给模型全自主调用。
正向防御法则：高危业务必须实施 人机协同复核（Human-in-the-Loop），采用两阶段预备与确认模式（Prepare & Confirm），必须经操作人 MFA 步进认证签名方可提交最终写操作。