API 版本：准备兼容迁移

发布 04/05/2026 · 更新 23/10/2026 · API与系统集成 · 5 分钟阅读 · 作者 Cyber Intelligence Embassy

内容摘要

改变编号本身不能保护调用方。兼容性既包括消息，也包括真实客户端依赖的行为。

本文目录

从客户端角度评估

表格是审查框架，并非普遍保证。新增字段可能影响严格解析器；新增枚举值可能破坏穷举分支。应盘点客户端、库与假设。

变更	需检查的风险	所需证据
删除或重命名字段	无法读取原字段	明确迁移与客户端测试。
增加可选字段	严格读取或命名冲突	测试现有调用方。
响应增加枚举值	分支处理不完整	定义未知值的处理。
改变默认值	业务结果变化	比较未显式传值的场景。

安排新旧共存

说明新旧结构、默认值、错误、分页和授权规则，用代表性的调用场景执行契约测试。
明确版本选择方式，区分服务版本与 OpenAPI 文档版本，并检查缓存和网关。
发布时间表、迁移指引及联系渠道。用适度遥测了解实际使用，并准备与数据兼容的回退。

区分弃用和停止服务

Deprecation 标示资源被弃用；Sunset 可以告知预计何时不可用。这些响应头不会替客户端完成迁移。停止版本前，应检查剩余调用方、义务及恢复流程。

一手资料

版本对消费者的影响

在 URL 中添加数字本身并不能保留现有客户端。即使路径保持不变，类型、预期值、行为或错误响应的更改也可能导致不兼容。

清点活跃客户端及其使用情况。
针对新合约测试旧客户端版本。
公布共存期并在停用前检查使用情况。

一手资料：IETF RFC 9457 — Problem Details for HTTP APIs. 相关方法：阅读实用指南.

异步API任务

接受请求不能证明工作已完成。

账号、操作和可复用标识符
状态、时间、间隔和过期
产出、错误、取消和剩余影响
一个获授权任务及中断后核实的结果

可复现的验收案例

虚构示例：数据不代表客户或实际观察结果。

查看案例输入

{
    "job_id": "J-42",
    "timeline": [
        {
            "elapsed_seconds": 0,
            "http": 202,
            "state": "pending"
        },
        {
            "elapsed_seconds": 5,
            "http": 200,
            "state": "running"
        },
        {
            "elapsed_seconds": 6,
            "http": 200,
            "state": "cancel_requested"
        },
        {
            "elapsed_seconds": 7,
            "http": 200,
            "state": "succeeded"
        }
    ]
}

预期判断

读取状态时返回 200 并不表示处理已完成。请求取消后，也只能根据已确认的最终结果作出判断。

取消请求来得太晚

虚构场景：跟踪同一任务 J-42，时间为提交后的秒数。状态名称由本示例的契约定义，并非 HTTP 规定。

时间	响应与状态	可以得出的结论
+0 s	HTTP 202 · pending	已接受处理，但尚未确认最终结果。
+5 s	HTTP 200 · running	状态读取成功，任务仍在运行。
+6 s	HTTP 200 · cancel_requested	已记录停止请求，但尚未确认取消。
+7 s	HTTP 200 · succeeded	处理先完成。显示已确认的成功并检查实际影响，不要显示为已取消。

Microsoft — Asynchronous request-reply

202能证明任务最终完成吗？

不能。它表示接受处理，而非最终结果。应查询操作状态。

一手资料：MDN — 202 Accepted. 相关方法：阅读实用指南.

软件更新：核查签名者身份变化

判断签名制品是否仍对应批准的生产者、构建流程和版本。

检查新包前记录允许的生产者、密钥或证书身份、颁发者和构建流程。将预期绑定到软件和已经可信的确认渠道。待核查制品不能独自定义自己的接受策略。
将收到文件的摘要与证明的对象核对。根据预定信任根验证签名，再核查身份、构建者和参数。另一个身份的密码学有效签名并不满足服务策略。
测试已公告轮换、非预期颁发者、缺失签名和不同文件。新身份未确认时保持制品待处理。记录批准和回退方式；签名不能证明没有漏洞。

可复现的验收案例

虚构示例：数据不代表客户或实际观察结果。

查看案例输入

{
    "signature_valid": true,
    "digest_matches": true,
    "expected_signer": "approved-publisher",
    "observed_signer": "different-publisher",
    "expected": "hold_for_independent_confirmation"
}