@umacloud/knowledge 1.0.1

package/architecture/04-antipatterns/architecture-antipatterns.md

@@ -0,0 +1,417 @@
+---
+id: architecture-antipatterns
+title: 架构反模式库
+domain: architecture
+category: 04-antipatterns
+difficulty: intermediate
+tags: [antipatterns, architecture, ball, distributed, golden, hammer, monolith, 候选方案]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 架构反模式库
+
+> 覆盖软件架构设计中最常见的 8 类反模式，每个反模式包含描述、症状、真实案例和重构方案。
+
+---
+
+## 反模式 1：大泥球 (Big Ball of Mud)
+
+### 描述
+
+系统缺乏清晰的模块边界和分层结构，代码随意耦合，任意组件可以调用任意其他组件。系统看似"能运行"，但随着规模增长，修改任何一处都可能引发不可预测的级联故障。
+
+### 症状
+
+- 无法画出清晰的架构图——一切都连接一切
+- 新人入职需要数月才能理解系统
+- 任何"小改动"都需要全量回归测试
+- 代码中充斥大量 `import` 指向不相关的模块
+- 部署必须整体发布，无法独立部署子系统
+- 循环依赖遍布代码库
+
+### 真实案例
+
+**某大型电商平台（2015-2018）**：初期为快速上线采用单体架构，3 年后代码量超过 200 万行，模块间超过 3000 个循环依赖。一次促销活动中修改购物车逻辑导致支付模块异常，全站故障 4 小时，直接损失超千万。事后复盘发现，购物车模块直接引用了支付模块的内部数据结构。
+
+### 重构方案
+
+1. **识别边界**：使用依赖分析工具（如 Structure101、Lattix）绘制实际依赖图
+2. **定义模块契约**：为每个逻辑模块定义公开 API 接口，禁止跨模块直接访问内部类
+3. **逐步解耦**：
+   - 引入反腐层（Anti-Corruption Layer）隔离遗留代码
+   - 按业务域拆分为独立模块，使用事件驱动通信
+   - 每次拆分一个边界，验证后再继续
+4. **架构守护**：在 CI 中集成 ArchUnit / deptry 等工具，自动检测违规依赖
+
+```java
+// ArchUnit 规则示例：禁止 payment 模块访问 cart 内部实现
+@ArchTest
+static final ArchRule paymentShouldNotAccessCartInternals =
+    noClasses().that().resideInAPackage("..payment..")
+        .should().accessClassesThat().resideInAPackage("..cart.internal..");
+```
+
+---
+
+## 反模式 2：分布式单体 (Distributed Monolith)
+
+### 描述
+
+名义上是微服务架构，但服务之间强耦合：同步调用链过长、共享数据库、必须同时部署多个服务才能完成一次变更。拥有微服务的所有运维复杂性，却没有获得独立部署和弹性的收益。
+
+### 症状
+
+- 修改一个服务需要同时修改和部署其他 3-5 个服务
+- 多个服务共享同一个数据库 schema
+- 服务间使用同步 RPC 调用链，一个服务宕机导致全链路雪崩
+- 没有独立的服务团队——一个团队同时维护多个服务
+- 部署顺序有严格依赖关系
+- 共享库包含业务逻辑而非纯工具函数
+
+### 真实案例
+
+**某金融科技公司（2019）**：将单体拆分为 40+ 微服务，但所有服务共享一个 PostgreSQL 实例的不同 schema，服务间通过 gRPC 同步调用。支付链路涉及 7 个服务的同步调用，平均延迟从 200ms 飙升到 1.2s。任一中间服务超时，整个支付链路失败。数据库成为瓶颈后无法独立扩容某个服务的数据层。
+
+### 重构方案
+
+1. **数据自治**：每个服务拥有独立数据库，通过事件同步数据
+2. **异步化**：将同步 RPC 链替换为事件驱动（Kafka/RabbitMQ）
+3. **Saga 模式**：长事务拆分为 Saga，每步有补偿操作
+
+```
+重构前（同步链）:
+  Order → Payment → Inventory → Shipping → Notification
+  任一环节失败 = 全链路失败
+
+重构后（编排 Saga）:
+  Order Service 发布 OrderCreated 事件
+  ├── Payment Service 订阅 → 发布 PaymentCompleted/PaymentFailed
+  ├── Inventory Service 订阅 → 发布 StockReserved/StockFailed
+  └── Shipping Service 订阅 → 发布 ShipmentScheduled
+  每个服务独立部署、独立扩容、独立数据库
+```
+
+4. **团队对齐**：一个团队拥有一个服务（或一组内聚服务），遵循 Conway 定律
+
+---
+
+## 反模式 3：金锤子 (Golden Hammer)
+
+### 描述
+
+团队对某项技术过度熟悉，将其应用于所有场景，不管是否适合。例如：所有数据存 MySQL、所有通信用 REST、所有前端用 React、所有部署用 Kubernetes。
+
+### 症状
+
+- 技术选型讨论时只有一个候选方案
+- "我们一直都是这么做的"成为决策依据
+- 简单问题用复杂方案解决（如 10 个页面的内部工具部署在 K8s 上）
+- 不适合的场景被强行适配（如图数据存在关系数据库中用 JOIN 模拟）
+- 团队拒绝学习新技术栈
+
+### 真实案例
+
+**某社交平台（2017）**：所有数据存储使用 MySQL，包括用户关系图谱（好友、关注）。当用户量突破 500 万后，6 层好友推荐查询需要多次 JOIN，单次查询耗时 12 秒。最终被迫迁移到 Neo4j，但迁移耗时 6 个月，期间该功能几乎不可用。如果初始技术选型时评估过图数据库，可以避免这次昂贵的迁移。
+
+### 重构方案
+
+1. **技术雷达**：建立团队技术雷达，定期评估新技术适用场景
+2. **适配性评估框架**：每次技术选型使用 ADR（Architecture Decision Record）
+
+```markdown
+# ADR-007: 用户关系存储技术选型
+
+## 背景
+用户关系图谱查询（好友推荐、N 度关系）需要高效图遍历。
+
+## 候选方案
+| 方案 | 图遍历性能 | 团队熟悉度 | 运维成本 | 生态成熟度 |
+|------|-----------|-----------|---------|-----------|
+| MySQL + 邻接表 | 差（多次 JOIN） | 高 | 低 | 高 |
+| Neo4j | 优（原生图引擎） | 低 | 中 | 中 |
+| Amazon Neptune | 优 | 低 | 中（托管） | 中 |
+
+## 决策
+选择 Neo4j。虽然团队熟悉度低，但图遍历是核心需求，关系数据库无法满足性能要求。
+
+## 后果
+- 需投入 2 周团队培训
+- 运维需增加 Neo4j 监控
+- 图遍历查询预计从 12s 降至 50ms
+```
+
+3. **Polyglot Persistence**：接受不同数据用不同存储的事实
+4. **PoC 验证**：关键技术选型前做 2-3 天的原型验证
+
+---
+
+## 反模式 4：过度工程 (Over-Engineering)
+
+### 描述
+
+在需求不确定或规模很小时就引入大量抽象层、设计模式、框架和基础设施。"未来可能需要"成为工程决策的主要驱动力，导致系统复杂度远超实际需求。
+
+### 症状
+
+- 一个 CRUD 功能有 7 层抽象（Controller → Service → Manager → Repository → DAO → Mapper → Entity）
+- 日活 100 的内部系统使用微服务 + K8s + Service Mesh
+- 代码中大量接口只有一个实现
+- 框架代码比业务代码多
+- 简单功能的开发周期反而更长
+- "这个抽象以后会有用的"——但从来没有用过
+
+### 真实案例
+
+**某创业公司 MVP（2020）**：3 人团队开发一个内部 CRM 工具，采用了微服务架构（12 个服务）、Kubernetes 部署、GraphQL + REST 双协议、CQRS + Event Sourcing、Redis + Elasticsearch + PostgreSQL。6 个月后只完成了用户登录和客户列表两个功能，且系统运维成本每月 3000 美元。竞争对手用 Rails 单体 3 周上线了完整 MVP。
+
+### 重构方案
+
+1. **YAGNI 原则**：You Aren't Gonna Need It——不到需要时不加抽象
+2. **复杂度预算**：
+
+```
+规模估算公式：
+  日活用户 < 1000     → 单体 + 单数据库
+  日活用户 1000-10万   → 模块化单体 + 读写分离
+  日活用户 10万-100万  → 服务化 + 缓存层
+  日活用户 > 100万     → 微服务 + 分布式存储
+```
+
+3. **渐进式架构**：从简单开始，在真实痛点出现时再演进
+4. **三次法则**：某个模式出现三次再抽象，而非预测性抽象
+5. **定期审计**：移除未使用的抽象层和"预留"接口
+
+---
+
+## 反模式 5：循环依赖 (Circular Dependencies)
+
+### 描述
+
+模块 A 依赖模块 B，模块 B 又依赖模块 A（直接或间接循环）。导致无法独立编译、测试、部署，修改任一模块都可能影响整个循环链。
+
+### 症状
+
+- 无法单独编译或测试某个模块
+- 导入顺序敏感，改变 import 顺序导致运行时错误
+- 两个模块必须同时发版
+- 依赖图中存在环路
+- 重构时"牵一发而动全身"
+
+### 真实案例
+
+**某企业 ERP 系统**：订单模块依赖库存模块（检查库存），库存模块依赖订单模块（获取待发货订单），财务模块依赖订单模块（获取订单金额），订单模块又依赖财务模块（检查信用额度）。形成 Order ↔ Inventory ↔ Finance 三角循环。任何一个模块的变更都触发其他两个模块的回归测试，发版需要三个模块同时部署。
+
+### 重构方案
+
+1. **依赖倒置**：引入抽象接口，高层模块依赖抽象而非具体实现
+
+```python
+# 重构前：循环依赖
+# order/service.py
+from inventory.service import InventoryService  # Order → Inventory
+
+# inventory/service.py
+from order.service import OrderService  # Inventory → Order（循环！）
+
+# 重构后：依赖倒置
+# shared/interfaces.py
+class OrderQueryPort(Protocol):
+    def get_pending_orders(self) -> list[Order]: ...
+
+class InventoryQueryPort(Protocol):
+    def check_stock(self, sku: str) -> int: ...
+
+# order/service.py
+class OrderService:
+    def __init__(self, inventory: InventoryQueryPort): ...
+
+# inventory/service.py
+class InventoryService:
+    def __init__(self, orders: OrderQueryPort): ...
+```
+
+2. **事件解耦**：用领域事件替代直接调用
+3. **提取公共模块**：将被双方依赖的逻辑提取为第三方模块
+4. **CI 守护**：使用 deptry / import-linter 在 CI 中阻止新的循环依赖
+
+---
+
+## 反模式 6：神对象 (God Object)
+
+### 描述
+
+一个类或模块承担了过多职责，成为系统的"上帝"——它知道一切、做一切。通常表现为几千行的巨型类，修改频率极高，合并冲突频繁。
+
+### 症状
+
+- 单个类/文件超过 2000 行
+- 该类被系统中 50% 以上的模块引用
+- 修改该类的 PR 经常产生合并冲突
+- 该类有 30+ 个公开方法，涵盖多个不同业务域
+- 单元测试该类需要 mock 大量依赖
+- 新人被告知"看这个类就能理解整个系统"
+
+### 真实案例
+
+**某 SaaS 平台的 UserManager 类**：一个 5000 行的 `UserManager` 类包含用户注册、登录认证、权限校验、个人资料管理、通知发送、活动日志、数据导出等功能。每周有 3-5 次合并冲突，新功能开发被迫在这个类中添加方法。重构前后对比：
+
+```
+重构前：
+  UserManager.java (5000 行, 47 个方法)
+    ├── 注册/登录 (8 个方法)
+    ├── 权限校验 (6 个方法)
+    ├── 个人资料 (5 个方法)
+    ├── 通知 (7 个方法)
+    ├── 日志 (6 个方法)
+    ├── 导出 (5 个方法)
+    └── 工具方法 (10 个方法)
+
+重构后（单一职责拆分）：
+  AuthenticationService.java (300 行)
+  AuthorizationService.java (250 行)
+  UserProfileService.java (200 行)
+  NotificationService.java (350 行)
+  AuditLogService.java (200 行)
+  UserDataExporter.java (180 行)
+```
+
+### 重构方案
+
+1. **职责识别**：列出该类所有公开方法，按业务域分组
+2. **逐步提取**：每次提取一个职责为独立类，保留旧方法作为委托（deprecate）
+3. **Strangler Pattern**：新功能写在新类中，旧方法逐步迁移
+4. **限制规则**：在 CI 中设置单文件行数上限警告（如 500 行）
+
+---
+
+## 反模式 7：上帝服务 (God Service)
+
+### 描述
+
+在微服务架构中，某个服务承担了过多业务逻辑，成为所有请求的必经节点。该服务成为系统的单点瓶颈和故障点，其可用性等同于整个系统的可用性。
+
+### 症状
+
+- 一个服务处理 60% 以上的 API 请求
+- 该服务的 CPU/内存使用率是其他服务的 5-10 倍
+- 该服务宕机等同于全站宕机
+- 该服务的代码仓库提交频率是其他服务的 3 倍以上
+- 扩容该服务时需要同步扩容其依赖的所有下游
+- 该服务被称为"核心服务"/"平台服务"/"网关服务"
+
+### 真实案例
+
+**某在线教育平台（2021）**：一个名为 `platform-service` 的服务负责用户管理、课程管理、订单处理、支付对接、视频转码调度和数据报表。双十一活动期间，课程秒杀流量冲垮了该服务，连带视频播放和报表功能全部不可用。服务 SLA 从 99.9% 降到 95%。
+
+### 重构方案
+
+1. **领域拆分**：按 DDD 限界上下文拆分为独立服务
+
+```
+重构路径：
+  Phase 1: 将报表功能拆出（读多写少，可独立扩容）
+  Phase 2: 将支付对接拆出（安全合规要求独立审计）
+  Phase 3: 将视频转码调度拆出（计算密集型，需独立资源池）
+  Phase 4: 将订单处理拆出（高并发场景独立扩容）
+  Phase 5: 剩余用户 + 课程管理作为核心域服务
+```
+
+2. **BFF 模式**：前端不直连上帝服务，通过 BFF 层路由到正确的领域服务
+3. **流量隔离**：高频/低频操作使用不同的服务实例和资源池
+4. **熔断降级**：即使在拆分完成前，也要为不同功能设置独立的熔断策略
+
+---
+
+## 反模式 8：数据库驱动设计 (Database-Driven Design)
+
+### 描述
+
+以数据库表结构作为系统设计的起点和核心，业务逻辑围绕表结构编写。导致领域模型贫血、业务逻辑散落在 SQL 和存储过程中、技术迁移成本极高。
+
+### 症状
+
+- 设计讨论从 ER 图开始而非业务流程
+- 业务规则写在存储过程和触发器中
+- 代码中充斥直接的 SQL 查询而非领域操作
+- 更换数据库需要重写大部分业务逻辑
+- 领域对象只有 getter/setter，没有行为（贫血模型）
+- 表之间的 JOIN 关系决定了代码的调用关系
+
+### 真实案例
+
+**某物流管理系统**：整个订单履约流程写在 15 个存储过程中（最大的一个超过 3000 行 PL/SQL），所有业务规则（运费计算、路线优化、异常处理）都在数据库层。当公司从 Oracle 迁移到 PostgreSQL 时，发现需要重写全部存储过程，且由于缺乏文档和测试，迁移耗时 18 个月，远超预期的 3 个月。
+
+### 重构方案
+
+1. **领域建模优先**：从业务流程和领域事件开始设计，而非表结构
+
+```
+数据库驱动（反模式）:
+  1. 设计 ER 图
+  2. 创建表
+  3. 围绕表写 CRUD
+  4. 在存储过程中加业务逻辑
+
+领域驱动（推荐）:
+  1. 识别限界上下文和聚合根
+  2. 定义领域事件和业务操作
+  3. 实现领域模型（包含行为）
+  4. 持久化层适配领域模型
+```
+
+2. **存储过程迁移**：逐步将业务逻辑从存储过程迁移到应用层
+3. **Repository 模式**：用 Repository 抽象隔离数据访问，领域模型不依赖数据库细节
+
+```python
+# 贫血模型（反模式）
+class Order:
+    id: int
+    status: str
+    total: float
+    # 只有数据，没有行为
+
+def cancel_order(order_id):
+    order = db.query("SELECT * FROM orders WHERE id = %s", order_id)
+    if order.status == "pending":
+        db.execute("UPDATE orders SET status = 'cancelled' WHERE id = %s", order_id)
+        db.execute("UPDATE inventory SET reserved = reserved - ... WHERE ...")
+        # 业务逻辑散落在服务层
+
+# 充血模型（推荐）
+class Order:
+    def cancel(self):
+        if self.status != OrderStatus.PENDING:
+            raise DomainError("只有待处理订单可以取消")
+        self.status = OrderStatus.CANCELLED
+        self.add_event(OrderCancelled(self.id))
+        # 业务逻辑内聚在领域对象中
+```
+
+4. **六边形架构**：领域核心不依赖任何基础设施，通过端口和适配器与外部交互
+
+---
+
+## 架构反模式检测与预防矩阵
+
+| 反模式 | 早期信号 | 检测工具 | 预防措施 |
+|--------|---------|---------|---------|
+| 大泥球 | 循环依赖数 > 10 | Structure101, deptry | ArchUnit 规则 |
+| 分布式单体 | 跨服务部署率 > 50% | 部署日志分析 | 服务独立性评审 |
+| 金锤子 | 技术选型无 ADR | 技术雷达评审 | ADR 流程 |
+| 过度工程 | 框架代码 > 业务代码 | 代码度量分析 | YAGNI 评审 |
+| 循环依赖 | 编译/启动顺序敏感 | import-linter, Madge | CI 依赖检查 |
+| 神对象 | 单文件 > 2000 行 | SonarQube, wc -l | 文件行数告警 |
+| 上帝服务 | 单服务流量 > 60% | APM 监控 | DDD 限界上下文 |
+| 数据库驱动 | 存储过程 > 50 个 | 代码搜索 | 领域建模优先 |
+
+---
+
+## Agent Checklist
+
+- [ ] 所有反模式均包含描述、症状、真实案例和重构方案四部分
+- [ ] 真实案例具有可信度和参考价值
+- [ ] 重构方案提供渐进式路径而非"推倒重来"
+- [ ] 包含代码示例和架构图辅助说明
+- [ ] 检测与预防矩阵覆盖所有反模式
+- [ ] 反模式覆盖从代码级（神对象）到系统级（分布式单体）
+- [ ] 文件行数 >= 300 行