1. 异步迁移基础：异步任务概念、数据库迁移生命周期、异步 vs 同步迁移对比
1.1 异步任务概念
在数据库迁移场景中，异步任务是指将迁移操作的执行与调用方的等待逻辑解耦。调用方提交迁移请求后，立即获得一个任务标识符（Task ID），无需阻塞等待迁移完成；后台工作线程或独立进程接管实际的数据搬迁、结构变更、索引重建等耗时操作。
核心特征：非阻塞提交 + 状态轮询/回调通知 + 可重试/可取消。
| 特征 | 说明 | 开发阶段常见问题 |
|---|---|---|
| 非阻塞提交 | API 调用立即返回，不等待迁移完成 | 未正确处理返回状态，误以为迁移已结束 |
| 状态轮询 | 客户端定期查询任务进度 | 轮询间隔不合理导致延迟感知或服务压力 |
| 回调通知 | 迁移完成/失败时触发 webhook 或消息 | 回调超时、签名校验失败、重复通知 |
| 可重试/可取消 | 支持失败重试或手动终止 | 重试幂等性缺失、取消后残留锁或临时表 |
1.2 数据库迁移生命周期
一个完整的数据库迁移任务，无论同步还是异步，都遵循以下阶段。异步迁移在每个阶段都可能引入额外的故障点。
- 评估与规划：分析源库对象、数据量、依赖关系，生成迁移计划。
- 结构迁移：在目标库创建表结构、索引、约束、存储过程等。
- 全量数据迁移：将源库存量数据分批搬迁至目标库。
- 增量同步：持续捕获源库变更（CDC），实时或准实时同步到目标库。
- 数据校验：对比源和目标的数据一致性，发现差异并修复。
- 切换与割接：将业务流量从源库切换到目标库，完成迁移。
开发阶段常见陷阱：异步任务在“全量数据迁移”阶段容易因大事务、锁等待、网络抖动导致任务挂起；在“增量同步”阶段常因 binlog 位点丢失或重复消费引发数据不一致。
1.3 异步 vs 同步迁移对比
选择同步还是异步迁移，直接影响开发阶段的测试策略、故障排查手段和代码复杂度。下表从多个关键维度进行对比。
| 对比维度 | 同步迁移 | 异步迁移 |
|---|---|---|
| 调用方式 | 阻塞等待，直到迁移完成或失败 | 立即返回 Task ID，后台执行 |
| 超时处理 | 客户端连接超时即失败 | 任务可长时间运行，需单独设置超时策略 |
| 状态追踪 | 通过返回值直接获取结果 | 需轮询或回调获取状态 |
| 资源占用 | 占用一个连接/线程直到完成 | 释放调用方资源，后台线程池管理 |
| 故障排查难度 | 低，错误直接返回 | 高，需查看任务日志、状态表、回调记录 |
| 适用场景 | 小数据量、低延迟要求、测试环境 | 大数据量、跨网络、生产环境割接 |
| 开发阶段风险 | 连接池耗尽、阻塞主流程 | 任务丢失、状态不一致、回调失败 |
开发建议：在 Development 阶段，优先使用同步迁移进行功能验证和单元测试；异步迁移用于集成测试和压力测试，并提前搭建任务监控面板（如 Task 状态表、延迟指标、失败重试队列）。
1.4 异步迁移的典型故障模式
基于上述生命周期和对比，开发阶段最常见的异步迁移故障模式包括：
- 任务丢失：提交后因队列溢出、进程重启导致任务未被调度。
- 状态不一致：任务实际已完成，但状态表未更新，导致客户端误判。
- 回调超时/失败：迁移完成后回调地址不可达或签名错误。
- 重复执行：缺乏幂等性设计，重试导致数据重复或冲突。
- 资源泄漏：异步任务异常退出后，临时表、锁、会话未清理。
排查起点：遇到异步迁移故障时，首先检查任务状态表（task_status）、工作线程日志（worker.log）、回调记录（callback_history），定位任务当前处于生命周期的哪个阶段。