接口能力迁移是把来源平台上的接口调用关系、认证方式、触发规则和扩展逻辑，按业务用途在目标平台重新实现，并保证调用方在切换后行为一致。它涉及调用入口、认证授权、触发回调、字段映射、错误码与重试、扩展脚本六类对象，与数据搬运、平台日常配置分属不同任务。下面按盘点、分类、重建、验证、切换五步展开，每步说明输入、动作、产出和完成标志。
要点总览（TL;DR）
- 接口能力迁移的对象是调用方看到的行为：调用入口、认证授权、触发回调、字段映射、错误码与重试、扩展逻辑六类，数据搬运和平台日常配置不在其中。
- 先盘点接口台账，记录调用方、频率、认证方式和依赖字段，重点排查定时任务、硬编码地址等无文档的隐式调用。
- 按业务关键度、调用方数量、对外暴露情况和等价能力，把每个接口归入原样重建、改用内置能力、合并简化或下线四类策略，并组织评审。
- 重建阶段按认证、触发、字段映射、错误码的顺序推进，用影子调用和回归用例比对新旧返回，差异逐条登记复测。
- 切换从低风险接口和调用方开始，每批填写切换单、预设回退条件，观察成功率和延迟，收尾时核对台账终态、旧接口停用和文档监控更新。
先回答：接口能力迁移要迁哪些东西
接口能力迁移的对象是“调用方看到的行为”，而不仅是接口本身。判断一个接口是否迁移完成，看两件事：原有调用方按原方式调用后，返回结构和业务结果一致；出现异常时，调用方能收到可识别的错误信息，迁移团队能从日志或监控中定位问题。
把迁移对象拆成六类，便于逐项对照：
| 对象类别 | 具体内容 | 迁移时的关注点 |
|---|---|---|
| 调用入口 | 接口地址、请求方法、协议、版本路径 | 地址变化是否要求调用方改配置，能否做兼容转发 |
| 认证与授权 | 密钥、令牌、签名算法、权限范围 | 凭证如何换发，旧凭证的失效时间 |
| 触发与回调 | 主动调用、事件推送、定时触发、回调地址 | 回调地址由谁提供，重试与超时策略是否一致 |
| 字段与参数映射 | 请求参数、返回字段、必填项、类型、默认值 | 字段名和结构变化需要映射表兜底 |
| 错误码与重试 | 错误码含义、异常返回结构、重试规则 | 调用方是否按错误码做分支处理 |
| 扩展脚本或插件 | 接口前后的校验、转换、通知逻辑 | 目标平台有无等价扩展点，逻辑放哪里执行 |
边界上要分清三件事：数据迁移关注历史记录和字段值的搬运，接口迁移关注调用关系能否继续工作；目标平台的日常配置是在迁移完成后持续进行的运营动作，不属于本次迁移范围；平台自身的版本升级、证书更新也不在迁移清单内。把这三类工作混在一起，容易导致台账失焦、责任不清。
第一步：盘点接口清单与调用方
盘点的目标是把“谁在调什么接口”查清楚，形成一份可支撑后续决策的接口台账。输入有三类：来源平台的接口文档、网关或访问日志、调用方代码与配置。文档给出设计意图，日志反映真实流量，代码和配置暴露实际调用参数，三者互相印证。
台账建议包含以下字段：接口名称与路径、业务用途、调用方（系统或团队）、调用频率、认证方式、依赖字段、是否对外暴露、当前状态。调用频率可从日志统计近30天日均调用量，用于后续排切换顺序。
无文档的隐式调用是盘点中最容易漏的部分，重点排查三类线索：定时任务配置中的外部地址、调用方代码里硬编码的域名或路径、网关日志中出现但文档未登记的路径。对每个可疑路径，回溯到具体调用方确认用途，确认后补入台账。
盘点完成的标志是：台账中每个接口都能对应到至少一个调用方，每个调用方调用的接口都在台账中有记录，不存在无主的孤立接口。发现无人调用的接口不要直接删除，先标记“待确认”，留到分类阶段处理。
第二步：按用途分类并确定迁移策略
分类的目的是把台账转成逐接口的策略决策。建议从四个维度判断：业务关键度（中断是否影响核心流程）、调用方数量、是否对外暴露、目标平台是否有等价能力。四个维度组合后，归入四类策略：
| 策略 | 适用情形 | 处理方式 |
|---|---|---|
| 原样重建 | 业务关键、调用方多、无等价能力 | 在目标平台按原契约重建，优先保证行为一致 |
| 改用内置能力 | 目标平台已有等价功能 | 调用方切换到内置能力，旧接口安排下线 |
| 合并简化 | 多个接口用途重叠、调用方少 | 合并为一个接口或减少字段，需调用方确认 |
| 下线 | 无调用方或业务已废弃 | 通知相关方后停用，保留一段时间只读记录 |
对目标平台没有等价能力的接口，处理方式有两种：在目标平台上用扩展脚本或自定义逻辑重建，或调整业务流程绕开该能力。前者工作量大但行为可控，后者需要业务方确认流程变化可接受。两种方式都要在策略表中写明理由和风险，例如“重建后回调延迟可能增加，需观察”。
策略确认需要接口负责人、主要调用方开发和业务确认人共同评审。评审重点不是逐条表决，而是确认三类高风险项：对外暴露接口的契约变更、关键业务接口的替代方案、下线接口的调用方是否已知情。评审结论记入策略表，作为后续重建和验证的依据。
第三步：在新平台重建认证、触发与字段映射
重建阶段按“认证—触发—映射—错误码”的顺序推进，每一步都有明确产出。
认证与授权先对齐。列出旧接口使用的凭证类型（密钥、令牌、签名），在目标平台申请对应凭证，确认签名算法和有效期一致。回调类接口还要确认签名校验方式，避免切换后因验签失败被调用方拒收。凭证换发要提前通知调用方，约定新旧凭证并行的时间。
触发方式与回调地址随后重建。主动调用类接口确认目标平台的地址和请求方法；事件推送类接口配置回调地址、重试次数和超时时间，重试策略尽量与旧接口一致，差异要记录在映射表中。定时触发类接口确认调度周期和时区设置。
字段与参数映射表是这一阶段的核心产出。逐接口列出旧字段名、新字段名、类型、是否必填、默认值、转换规则。常见转换包括枚举值对照、日期格式、金额单位、嵌套结构展平。映射表写完后由调用方开发确认，避免上线后才发现字段对不上。
错误码与异常返回统一约定：旧错误码在新平台对应哪个码，无法对应的归入哪类通用错误，返回体结构是否保持。调用方如果按错误码做重试或告警分支，这一项必须逐条核对。
重建完成的标志是：单个接口在测试环境中能被真实调用方成功调用一次，返回结构与映射表一致，异常场景能返回约定错误码。每完成一个接口，在联调记录中登记调用时间、调用方和结果。
第四步：用影子调用与回归用例验证
验证的目标是在切换前发现新旧接口的行为差异。主要手段是影子调用：同一请求同时发往新旧接口，比对两边返回，调用方仍以旧接口结果为准，新接口只记录不生效。影子调用适合读类接口和幂等写接口；非幂等写接口改用录制回放，用历史请求样本在新接口上重放并比对。
回归用例按三类选取：正常路径覆盖主要业务场景；边界值覆盖空值、超长字段、特殊字符、最大分页；异常与重试覆盖认证失败、参数错误、下游超时、重复回调。每类至少准备若干条，关键接口逐条执行。
比对内容包括返回结构（字段是否齐全、层级是否一致）、字段值（枚举、日期、金额换算是否正确）、错误码（同一异常是否返回同一码）、响应时间量级（是否在同一数量级，明显变慢要记录）。比对结果记入验证报告，差异逐条登记。
差异处理流程：先判断差异属于映射错误、平台行为差异还是用例本身有问题；映射错误修正映射表后复测；平台行为差异评估对调用方的影响，必要时调整调用方适配；每条差异修正后必须复测并更新记录。验证通过的判定标准是：关键接口的正常路径和异常路径全部比对一致，非关键接口的差异已登记且有明确处理结论，没有未解释的返回结构差异。
迁移任务、验证记录和差异处理需要在工作项中跟踪时，可以把每个接口的验证状态、差异清单和复测结果挂在对应工作项下，让接口负责人和调用方开发看到同一份进度，避免靠聊天记录对账。ONES 的工作项与文档能力可用于承载这类记录，具体配置按团队现有流程设置。
第五步：分批切换与回退安排
切换顺序从风险低的接口开始：先切调用量小、非对外、无关键业务依赖的接口，验证切换流程本身顺畅后，再切关键接口和对外接口。同一接口涉及多个调用方时，按调用方分批切换，每批只改一部分调用方的配置。
每批切换前填写切换单，要素包括：接口名称、涉及调用方、切换时间窗、执行人、验证人、回退开关的操作方式。回退开关要事先确认可用，例如调用方配置可快速改回旧地址、旧接口在切换后保留只读运行一段时间。
观察窗口内盯三个指标：调用成功率、错误码分布、延迟。成功率低于切换前基线、出现新的错误码集中出现、延迟明显上升，都视为异常信号。观察窗口长度按接口调用频率设定，低频接口适当延长。
回退触发条件在切换单中预先写定，例如“成功率连续低于阈值”或“关键调用方报告业务异常”。触发回退后，先恢复调用方配置，再定位原因，修复后重新走验证流程，不直接二次切换。切换完成的确认包括：该批调用方全部切换、观察窗口内指标正常、旧接口调用量降至零或仅剩待下线调用方。
角色分工与各阶段交付物
迁移涉及五类角色，职责按阶段划分：
| 角色 | 主要动作 | 负责的交付物 |
|---|---|---|
| 接口负责人 | 组织盘点、制定策略、把关映射与验证结论 | 接口台账、策略表、切换单 |
| 调用方开发 | 提供调用信息、确认映射表、执行切换与回退 | 调用方清单、映射确认记录 |
| 平台管理员 | 配置认证、触发、回调与扩展逻辑 | 配置记录、联调记录 |
| 测试 | 设计回归用例、执行影子比对、登记差异 | 验证比对报告、差异处理记录 |
| 业务确认人 | 确认关键接口策略、验收切换结果 | 策略评审意见、切换验收结论 |
交付物在阶段结束时评审并归档：台账和策略表在分类阶段评审，映射表和联调记录在重建阶段评审，验证报告在切换前评审，切换单在每批切换后归档。跨团队接口由接口负责人发起确认，调用方开发书面回复确认结果，确认记录与台账关联，避免口头约定无人留痕。
示例：一条订单状态回调接口的迁移过程
以下为演示情景。来源平台在订单状态变化时向外部仓储系统推送回调，迁移到目标平台。
台账记录：接口为订单状态回调，调用方是仓储系统，日均调用约两千次，认证方式为签名校验，依赖字段包括订单号、状态码、变更时间，属于对外暴露接口。策略评审定为原样重建，理由是仓储系统按固定字段解析，且该回调影响发货流程，不能简化。
重建时，认证沿用签名校验，签名算法与旧接口一致，密钥提前换发并通知仓储系统并行使用。回调地址改为目标平台地址，重试三次、超时十秒，与旧接口一致。映射表中状态码做枚举对照，旧系统的“已支付”对应新系统的“支付完成”，变更时间格式由时间戳改为 ISO 格式并在映射表中注明。
影子调用阶段，同一订单事件同时推送到新旧地址，比对发现两处差异：新接口在订单取消场景返回的状态码与旧接口不同，仓储系统会误判为异常；变更时间格式变化导致仓储系统解析失败。前者修正映射规则，后者在映射表中增加格式转换。修正后复测通过。
切换时先切一个仓库的调用方，观察两天，成功率和延迟正常后切换其余调用方。旧回调地址保留两周只读运行，确认无调用后停用。
完成检查：迁移收尾要核对什么
迁移结束前逐项核对以下清单：
- 接口台账中每个接口都有终态：已迁移、已替代或已下线，没有“进行中”遗留项。
- 旧接口的停用已执行，停用通知已发给全部调用方，通知时间和对象有记录。
- 接口文档已更新为目标平台的地址、参数和错误码，监控告警已指向新接口，责任人已更新。
- 遗留差异全部登记，每条有处理结论或跟踪计划，明确跟进人和时间。
- 迁移复盘记录了实际工作量与计划的偏差、影子调用发现的主要差异类型、切换中出现的问题及处理方式，供后续同类迁移参考。
清单全部核对通过，迁移才算真正结束；仍有未闭环项的，按遗留差异跟踪，不并入日常运营。
常见问题
接口能力迁移和数据迁移可以并行做吗？
可以并行，但两条线要分开管理。数据迁移关注历史记录和字段值的搬运，接口迁移关注调用关系在切换后能否继续工作。并行时注意一个衔接点：新接口依赖的字段如果来自历史数据，需要先确认数据侧已就位，否则影子调用比对会出现大量字段缺失的假差异。建议在验证阶段前完成接口所需基础数据的迁移，并在验证报告中注明数据版本。
影子调用对写接口不适用怎么办？
影子调用要求同一请求可以安全地发往两处，非幂等写接口直接并行会产生重复数据。这类接口改用录制回放：从日志中抽取历史请求样本，在新接口的测试环境中重放，比对返回结构和业务结果，不写入生产。回放样本要覆盖正常、边界和异常三类，重放前确认测试环境的下游依赖可用，避免因环境问题误判为接口差异。
目标平台没有等价能力，接口一定要重建吗？
不一定，有两种处理方式：在目标平台上用扩展脚本或自定义逻辑重建，或调整业务流程绕开该能力。前者行为可控但工作量大，后者需要业务方确认流程变化可接受。选择时评估三点：该接口中断对核心流程的影响、调用方改造的成本、绕开后的流程是否引入新的手工环节。无论选哪种，都要在策略表中写明理由和风险，并纳入评审。
切换后观察多久可以停用旧接口？
观察窗口按接口调用频率设定，高频接口可以短一些，低频接口适当延长，确保覆盖至少一个完整业务周期。停用旧接口前确认三件事：该接口全部调用方已切换、观察窗口内成功率和延迟正常、旧接口调用量降至零或仅剩已确认下线的调用方。停用前发出通知并保留一段时间只读运行，给遗漏的调用方留出发现问题的机会。
迁移过程中发现台账漏了接口，怎么处理？
补入台账后按正常流程走分类和策略评审，不要因为进度压力跳过。漏记通常来自无文档的隐式调用，补录时同步排查同类线索：定时任务配置、调用方代码中的硬编码地址、网关日志中未登记的路径。如果漏记接口已接近切换时间，优先评估能否延后该批切换，把补录和验证纳入同一批处理，避免带着未知调用方上线。
