API Compatibility 是一个面向接口变更场景的兼容性保障技能,适用于修改命令、schema、API、协议、配置格式、插件接口,或其他组件所消费的行为时。
用途
该技能的核心规则是:把每一个外部接口都视为与一个或多个消费方版本之间的契约。也就是说,接口不只是当前实现的一部分,而是需要被其他组件依赖和消费的稳定约定。
主要能力
- 契约枚举:要求列出可观察的输入、输出、错误码、默认值、副作用、顺序以及版本协商方式。
- 向后行为保留:除非破坏性变更是有意为之并且已经版本化,否则应保留既有行为。
- 兼容性测试矩阵:对于兼容性变更,至少测试当前生产者/当前消费者、新生产者/旧受支持消费者、旧受支持生产者/新消费者、不受支持的版本、未知字段以及缺失的可选字段。
- 变更策略:优先采用增量式变更和能力协商,而不是静默的语义变更。
- 失败明确化:让不兼容的组合清晰失败,而不是部分可用。
- 机器可读握手:当两个代码仓库必须“协同工作”时,把受支持范围编码为机器可读的握手,并测试被接受和被拒绝的相邻版本。
使用方式
在准备修改任何会被其他组件消费的接口时应用该技能。先枚举契约中的可观察要素,再判断变更是否属于破坏性变更;若需要兼容,则按上述测试矩阵验证新旧生产者与消费者之间的组合。对于需要协同工作的多个仓库,应建立机器可读的版本范围握手,并同时测试可接受与不可接受的相邻版本。
适用场景
- 修改命令、schema、API、协议、配置格式或插件接口。
- 修改会被其他组件消费的行为。
- 需要让新旧版本的生产者与消费者共存或协同工作。
- 需要明确版本协商与兼容边界。
限制
该技能强调文档本身不构成兼容性边界,因此不能仅靠文档声明兼容性。资料中未提供具体安装命令、代码示例、收费方式、价格、平台支持或效果数据,这些内容暂未提供。