架构评审清单：先看风险，再看方案优雅

// ❌ 坏做法：直接查库，无防护
async function getArticle(id: string) {
  let data = await redis.get(`article:${id}`)
  if (!data) {
    // 缓存未命中，直接查库
    // 大量并发请求同时穿透到数据库
    data = await db.query('SELECT * FROM articles WHERE id = ?', id)
    await redis.set(`article:${id}`, data, 'EX', 3600)
  }
  return data
}

// ✅ 好做法：空值缓存 + 互斥锁 + 降级
async function getArticle(id: string) {
  let data = await redis.get(`article:${id}`)
 
  // 空值缓存：防止缓存穿透
  if (data === '__NULL__') {
    return null
  }
 
  if (!data) {
    // 互斥锁：同一时刻只有一个请求去查库
    const locked = await redis.set(
      `lock:article:${id}`, '1', 'EX', 10, 'NX'
    )
    if (locked) {
      try {
        data = await db.query(
          'SELECT * FROM articles WHERE id = ?', id
        )
        if (data) {
          await redis.set(`article:${id}`, data, 'EX', 3600)
        } else {
          // 内容不存在，缓存空值，防止反复穿透
          await redis.set(`article:${id}`, '__NULL__', 'EX', 60)
        }
      } finally {
        await redis.del(`lock:article:${id}`)
      }
    } else {
      // 没拿到锁的请求，短暂等待后重试或降级
      await sleep(50)
      return getArticle(id)
    }
  }
 
  return data
}

// ❌ 坏做法：同步调用链，无补偿
async function placeOrder(order: Order) {
  // 1. 创建订单
  await orderDb.insert(order)
  // 2. 扣库存（远程调用）
  await inventoryService.deduct(order.items)
  // 3. 发起支付（远程调用）
  await paymentService.charge(order.amount)
  // 4. 更新订单状态
  await orderDb.update(order.id, { status: 'paid' })
  // 如果第 3 步成功但回调超时，第 4 步不执行
  // 订单永远卡在「待支付」
}

// ✅ 好做法：本地消息表 + 状态机 + 补偿
async function placeOrder(order: Order) {
  // 用事务保证订单写入和消息写入的原子性
  await db.transaction(async (tx) => {
    await tx.insert('orders', {
      ...order,
      status: 'pending_payment' // 明确初始状态
    })
    await tx.insert('outbox_messages', {
      aggregate_id: order.id,
      event_type: 'order.created',
      payload: order,
      status: 'pending' // 待发送
    })
  })
 
  // 后台任务轮询 outbox，投递到消息队列
  // 库存服务和支付服务消费消息，各自处理
  // 如果支付回调超时，由定时任务触发状态补偿
}
 
// 补偿任务：处理超时未支付的订单
async function compensateStaleOrders() {
  const staleOrders = await orderDb.query(
    `SELECT * FROM orders
     WHERE status = 'pending_payment'
     AND created_at < NOW() - INTERVAL 30 MINUTE`
  )
  for (const order of staleOrders) {
    // 先查支付服务的真实状态，再决定补偿动作
    const payResult = await paymentService.query(order.id)
    if (payResult?.status === 'success') {
      await orderDb.update(order.id, { status: 'paid' })
    } else {
      await orderDb.update(order.id, { status: 'cancelled' })
    }
  }
}

// ❌ 坏做法：硬切数据格式，无法回滚
function generateBill(usage: Usage) {
  return {
    userId: usage.userId,
    amount: usage.seconds * ratePerSecond, // 新格式：按秒
    // 旧代码期望的是 minutes 字段，回滚后无法解析
  }
}

// ✅ 好做法：数据格式向前兼容 + 灰度标记
function generateBill(usage: Usage, mode: 'legacy' | 'per_second') {
  const base = {
    userId: usage.userId,
    // 同时保留两种粒度的数据，确保新旧代码都能读取
    amount_minutes: usage.minutes * ratePerMinute,
    amount_seconds: usage.seconds * ratePerSecond,
    billing_mode: mode,
    version: 2 // 显式版本号
  }
  return base
}
 
// 灰度切流：按用户百分比逐步切换
function getBillingMode(userId: string): 'legacy' | 'per_second' {
  const hash = hashCode(userId) % 100
  if (hash < GRAY_PERCENTAGE) { // 初期 5%，逐步调大
    return 'per_second'
  }
  return 'legacy'
}

<!-- ❌ 坏做法：目标模糊，无法验证 -->
本系统需要高性能、高可用、易扩展。
采用微服务架构，保证系统的灵活性和可维护性。

<!-- ✅ 好做法：目标可量化，非目标明确 -->
目标：
- 订单查询接口 P99 < 200ms，QPS 支撑 5000
- 核心链路可用性 > 99.95%（月度不可用 < 22 分钟）
- 支持未来 6 个月内接入新的支付渠道
 
非目标：
- 本次不重构用户认证模块
- 不支持跨区域多活（后续规划）

# ❌ 坏做法：一步到位，无回滚考虑
deploy:
  strategy: rolling
  batch_size: 100%   # 全量发布
  rollback: manual    # 手动回滚，无自动化
  data_migration: v2_schema  # 新 schema 不兼容旧代码

# ✅ 好做法：灰度 + 自动回滚 + 数据兼容
deploy:
  strategy: canary
  canary_percentage: 5    # 先切 5% 流量
  observation_window: 30m # 观察 30 分钟
  auto_rollback:
    trigger:
      error_rate: "> 1%"
      p99_latency: "> 500ms"
  data_migration:
    phase: forward_compatible  # 新代码兼容新旧数据格式
    # 第二阶段再清理旧字段

<!-- ❌ 坏做法：决策散落在聊天中，无法追溯 -->
群里讨论了一下，决定用 Kafka 而不是 RabbitMQ。
原因是 Kafka 性能好。

<!-- ✅ 好做法：ADR 格式，背景、选项、取舍完整 -->
# ADR-023: 消息队列选型
 
## 状态
已接受 (2026-06-20)
 
## 背景
订单事件需要异步通知下游 3 个服务，日均消息量 200 万。
要求消息顺序性（同一订单的事件必须有序）。
 
## 选项
| 维度 | Kafka | RabbitMQ |
|------|-------|----------|
| 吞吐量 | 百万级/秒 | 万级/秒 |
| 顺序保证 | partition 内有序 | 单队列有序 |
| 运维成本 | 较高，需 ZooKeeper/KRaft | 较低 |
| 团队经验 | 2 人熟悉 | 全组熟悉 |
 
## 决策
选择 Kafka。订单量级下 RabbitMQ 吞吐量足够，
但 partition 级别的顺序保证更简单可靠。
运维成本由平台团队统一承担。
 
## 后果
- 正：顺序性保证简单，扩展性强
- 负：团队需要学习 Kafka 运维，预计 2 周上手期