API 兼容性与零停机数据库迁移（Expand_Contract、双写与验证）

---

title: API 兼容性与零停机数据库迁移（Expand_Contract、双写与验证）

date: 2025-11-26

keywords:

• 零停机迁移
• Expand_Contract
• 双写
• 回填
• 兼容性

description: 采用Expand_Contract与双写策略实现零停机数据库迁移，分阶段发布与回填数据，提供参数选择与一致性验证，确保兼容与安全回滚。

categories:

• 文章资讯
• 技术教程

---

概述

零停机迁移通过先扩展后收缩的发布流程, 配合双写与回填实现读写路径的平滑切换。通过版本兼容与灰度验证, 确保在迁移期间业务连续且可回滚。

关键实践与参数

• 分阶段: Expand(增加Schema/接口) → Backfill(回填) → Read Switch(读新) → Contract(移除旧)
• 双写窗口: 写操作同时落旧表与新表, 设置窗口长度与指标阈值
• 版本兼容: 新旧API与Schema同时兼容, 使用Feature Flag切换
• 回填速率: 控制批大小与速率, 避免对线上造成压力
• 验证指标: 读写成功率、延迟、差异计数与告警

示例/配置/实现

-- Expand: 添加新列或新表
ALTER TABLE orders ADD COLUMN status_code INT NULL;

-- 回填示例
UPDATE orders SET status_code = CASE status
  WHEN 'PAID' THEN 2 WHEN 'PENDING' THEN 1 ELSE 0 END
WHERE status_code IS NULL
LIMIT 1000; -- 批量执行控制速率

// 双写示意
async function updateOrder(id, payload) {
  await db.tx(async t => {
    await t.none('UPDATE orders SET status=$1 WHERE id=$2', [payload.status, id])
    await t.none('UPDATE orders SET status_code=$1 WHERE id=$2', [mapStatus(payload.status), id])
  })
}

-- Read Switch: 读新列并保留回退能力
SELECT id, COALESCE(status_code, CASE status WHEN 'PAID' THEN 2 WHEN 'PENDING' THEN 1 ELSE 0 END) AS status_code
FROM orders WHERE id = $1;

验证

• 一致性检查: 比较旧字段与新字段映射后的差异计数应为0
• 灰度验证: 按流量分组逐步切换读新路径, 观察错误与延迟
• 回填安全: 批次执行在可控速率, 无显著资源抖动
• 回滚演练: 切换失败时回退到旧读路径与关闭双写

注意事项

• 双写窗口内需防止写入放大导致锁争用
• 兼容版本需覆盖所有客户端, 避免旧版本崩溃
• 回填需幂等, 失败重试不会造成坏数据
• 每阶段均需具备明确的回退点与审计记录