本指南介绍了 Merchant API 如何处理版本控制、版本发布和不同版本的生命周期。
版本控制方案
Merchant API 在子 API 级别采用版本控制策略。这意味着 Merchant API 中的各个组件或服务将具有自己的版本生命周期。
版本控制格式和呈现方式
稳定的子 API 版本：如果子 API 采用的是稳定版本，则其所有方法也采用的是稳定版本。稳定的子 API 版本表示为 vX（例如 v1、v2）。这些是可用于生产环境的主要版本。
Alpha 版子 API：如果子 API 为 Alpha 版，则其所有方法均为 Alpha 版。Alpha 子 API 版本表示为 vXalpha（例如 v1alpha、v2alpha）。这些是抢先体验版，属于实验性版本，旨在用于测试和快速迭代。Alpha 版没有稳定性保证，也没有保证的生命周期。Alpha 版可在 30 天通知期过后更改或停用。
版本更改
主要版本递增（例如，从 v1 到 v2）：这些版本表示向后不兼容和破坏性更改，需要开发者采取行动。只有稳定子 API 的破坏性更改才会有新版本号。例如，从 v1 升级到 v2。
次要更改：向后兼容的添加或修复会显示为对现有主要版本的更改。此类更改将在相应主要版本的版本说明中详细说明。对子 API 进行的非破坏性添加将发布到最新稳定版本的 Alpha 渠道，或直接发布到最新稳定版本。
日落
我们会定期弃用旧版 Merchant 子 API 版本。我们承诺，从正式弃用公告发布之日起，稳定版主要版本 (vX) 的弃用期限为 12 个月。
例如，如果我们在 2026 年 1 月 15 日弃用 Products 子 API 的 v1 版，则该版本最早将于 2027 年 1 月 15 日弃用。在此日期之后，该子 API 的早期版本将无法再使用。
子 API 版本和生命周期状态
下表列出了 Merchant API 的每个子 API 的最新版本：
| 子 API | Alpha 版 | Beta 版 | 状态 |
|---|---|---|---|
| 账号 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 产品 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 商品输入 | 不可用 | v1 Beta 版 | v1 Beta 版处于有效状态 |
| 本地商品目录 | 不可用 | v1 Beta 版 | v1 Beta 版处于有效状态 |
| 区域商品目录 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 数据源 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 促销活动 | 不可用 | v1 Beta 版 | v1 测试版已发布 |
| 报告 | 不可用 | v1 Beta 版 | v1 Beta 版处于有效状态 |
| 转化次数 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 通知 | 不可用 | v1 Beta 版 | v1 Beta 版处于有效状态 |
| 评价 | 不可用 | v1 Beta 版 | v1 测试版已生效 |
| 配送设置 | 不可用 | v1 Beta 版 | v1 Beta 版处于有效状态 |
| Product Studio | v1 alpha | 不可用 | v1 Alpha 版处于有效状态 |
最佳做法
- 定期查看版本说明和最新动态，了解新版本、重大更新、改进以及有关子 API 发布和弃用的公告。
- 如果子 API 有 2 个或更多稳定版本，我们建议您始终使用最新版本。
- 设计应用以妥善处理各种子 API 错误，包括网络问题、速率限制，以及可能随较新子 API 版本引入的新错误代码或消息。
- 不要等到子 API 版本即将弃用时才开始规划升级。新版本发布后，立即开始评估和测试。
- 如果您有功能请求或对子 API 路线图有疑问，请与我们联系并提出问题或反馈。如需了解如何与 Merchant API 团队联系以获取技术支持，请参阅获取 Merchant API 方面的帮助。