build-backend-service-patterns

name: build-backend-service-patterns description: 服务架构模式——分层、通信、韧性。当需要设计后端服务架构、跨服务通信或处理分布式问题，或提到"微服务""重试""熔断"

Service Patterns — 服务架构模式

入口/出口

• 入口: 涉及多个服务/模块的边界设计、通信模式选择、韧性策略
• 出口: 模式选择记录 + 接口定义 + 韧性配置
• 指向: 架构确定后进入 build-backend-api-design（定义具体接口）
• 输出路径: verify-workflow-review（下游验证技能）
• 前置加载: CANON.md

何时不使用

• 只是在单服务内部实现一个清晰函数或端点
• 服务边界、通信方式和容错策略已经由 spec/ADR 明确
• 问题集中在具体 API 合约或数据库 schema，而不是服务架构

服务分层

Presentation  →  API Handler / Controller（HTTP、验证、序列化）
     │
Business      →  Service（领域逻辑、规则、工作流）
     │
Data          →  Repository / Adapter（数据访问、外部 API 封装）
     │
Infrastructure →  DB、Cache、Queue、外部服务

依赖方向: 上层依赖下层，依层不跨层。Business 不直接 import HTTP 框架类型。

通信模式

选择原则:

需要立即响应 + 强一致？→ 同步
可延迟 + 需要韧性？  → 异步
多消费者 + 解耦？   → Event-Driven
跨服务长事务？      → Saga

韧性模式

重试与退避

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = Math.pow(2, attempt) * 100;  // 100ms → 200ms → 400ms
      await sleep(delay);
    }
  }
  throw new Error('unreachable');
}

断路器

状态机:
  CLOSED → (连续失败 N 次) → OPEN（立即失败，不调用）
  OPEN → (等待 timeout) → HALF_OPEN（尝试一次）
  HALF_OPEN → 成功 → CLOSED | 失败 → OPEN

断路器保护下游服务不被雪崩淹没。 当调用已经反复失败时，快速失败 > 继续重试拖死上游。

幂等性

// 每个写操作需要幂等键
interface CreateOrderRequest {
  idempotencyKey: string;  // 客户端生成 UUID
  items: OrderItem[];
}

// 服务端: 相同幂等键 → 返回相同结果（不重复创建）
async function createOrder(req: CreateOrderRequest): Promise<Order> {
  const existing = await db.orders.findBy({ idempotencyKey: req.idempotencyKey });
  if (existing) return existing;
  return db.orders.create(req);
}

任何涉及支付的端点必须有幂等键。 网络重试 + 重复扣款 = 灾难。

模式选择

原则: 从最简单的模式开始。当代码变复杂因为模式不够时才升级，不因为"如此"。

错误处理

// 区分可恢复错误 vs 不可恢复错误
class RetryableError extends Error { /* 网络超时、503 */ }
class FatalError extends Error { /* 验证失败、404 */ }

async function handleServiceCall(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (err) {
    if (err instanceof RetryableError) {
      return withRetry(fn);
    }
    throw err;  // Fatal — 上层处理
  }
}

常见说辞

验证失败处理

好坏示例

✅ Good: 最简模式 + 韧性完整

订单创建流程:
- API Handler → 调用 OrderService.createOrder()
- OrderService → 写入 DB + 发事件到 Queue（异步解耦）
- 邮件服务消费 Queue 事件（异步，不阻塞订单创建）

韧性配置:
- OrderService → DB: withRetry(3, exponentialBackoff)
- OrderService → Queue: 断路器（5 次连续失败打开）
- createOrder API: idempotencyKey 必填
- Queue 消费者: 死信队列（失败 3 次进入 DLQ）

模式选择: Repository + Service（最简，匹配 CRUD 围绕单一实体需求）

❌ Bad: 过早工程化 + 缺韧性

订单创建流程:
- API → OrderService → InventoryService → PaymentService → NotificationService
  （同步链 4 层，任何一层超时整条链失败）

韧性配置: (未配置重试、断路器、幂等键)

模式选择: CQRS + Saga + Event Sourcing
  （当前只需 CRUD，过早引入 3 个高复杂度模式）

红旗 — STOP

• 单体拆成微服务但没有定义故障模式（网络分区、超时、下游宕机）
• 没有重试/断路器的跨服务 HTTP 调用
• 支付相关端点缺少幂等键
• 队列消费者没有死信队列（DLQ）—— 坏消息反复消费
• 同步调用链 > 3 层（请求串行穿透多个服务）
• 从表现层直接调用数据层（跳过 Business/Service）

输出模板

服务架构设计完成后，应在 ADR 或 03-plan.md 中记录以下结构：

## Service Architecture — [功能名称]

### 服务边界
| 服务 | 业务领域 | 负责范围 |
|------|---------|---------|
| [服务 A] | [领域] | [职责描述] |
| [服务 B] | [领域] | [职责描述] |

### 通信模式
| 调用路径 | 模式 | 理由 |
|---------|------|------|
| [A → B] | 同步 / 异步 / Event / Saga | [需要立即结果 / 可延迟 / 多消费者 / 跨服务长事务] |

### 韧性配置
| 调用路径 | 重试策略 | 断路器 | 幂等性 | 超时 |
|---------|---------|--------|-------|------|
| [A → B] | [次数 + 退避] | [阈值] | [是否需要] | [毫秒值] |

| 队列 | 消费者 | 死信队列 | 重试次数 |
|------|--------|---------|---------|
| [Queue A] | [消费者] | [DLQ 配置] | [次数] |

### 模式选择
| 需求 | 选定模式 | 复杂度代价 | 选择理由 |
|------|---------|-----------|---------|
| [需求描述] | [模式名] | [低/中/高] | [当前需求最简方案] |

### 故障模式
| 单点 | 降级方案 | 影响范围 |
|------|---------|---------|
| [单点描述] | [降级策略] | [受影响服务/用户] |

验证清单

• 服务边界清晰（按业务领域，不按技术层）
• 跨服务调用有重试和超时配置
• 支付/扣款相关有幂等键
• 异步消费者有死信队列
• 故障模式已识别（单点在哪？降级方案？）
• 选择的是当前需要的最简模式