API 版本管理
公共 API 采用日期版本，与 Shopify 使用同一套方案，因此你所依赖的版本不会在脚下悄然变化。日期版本是不兼容变更的粗粒度边界；在同一个版本内，schema 仍会以只增不减的方式演进。
版本名称
版本名为 YYYY-MM，其中月份为季度起始月：2026-01、2026-04、2026-07、2026-10。只有出现不兼容变更时才会切出新的日期版本——没有不兼容变更的季度会被跳过，因此版本相对少见。
此外还有一个 unstable 版本，跟随最新的开发进度，可在稳定发布前预览变更。请勿在其上构建生产环境集成。
选择版本
有两种方式，按优先级排列：
- URL 路径（推荐）： 把版本写进端点——
…/backend/<subdomain>/api/2026-07/graphql。它明确、利于缓存，也便于直接复制。 - 请求头： 向不带版本的
…/backend/<subdomain>/graphql端点发送X-Api-Version: 2026-07。
如果省略版本——或指定了未知的、已过下线日期的版本——请求将由仍受支持的最旧版本处理，而不是最新版本。你绝不会被悄悄升级到某个不兼容变更上。对于打算长期维护的集成，请显式固定版本。
每个响应都会通过 X-Api-Version 响应头告知处理它的版本，因此你随时知道是哪个契约作出的应答；若你此前依赖默认行为，也能据此发现偏差。
支持周期
每个稳定版本至少受支持 12 个月，且与下一个版本至少重叠 9 个月。实际上任意时刻都有两到三个版本在线，为迁移留出了从容的窗口。版本的下线日期在其发布当天即公布。
什么算不兼容变更
在同一版本内，我们可能做出只增不减的变更，你的客户端必须能够容忍：
- 新增类型、查询或变更（mutation）；
- 为现有字段新增可选参数；
- 为对象类型新增字段；
- 为枚举新增取值（因此切勿假定枚举是封闭的）。
新的日期版本只保留给真正的不兼容变更：删除或重命名字段或类型、收紧可空性，或改变某个参数或默认值的含义。这些变更绝不会发生在既有版本内部——你所固定的版本会保持其行为直到下线日期。
弃用
弃用会通过两种方式告知，让你在任何东西失效之前就有所了解：
- 在 schema 中。 将被淘汰的字段会标记
@deprecated，并附上指明替代方案的原因说明。内省与 GraphQL Playground 会自动把这些信息呈现给每个客户端。 - 在响应中。 当某个请求确实解析了已弃用字段时，响应会带上
X-Api-Deprecated-Reason响应头（以及对应的extensions.deprecations条目），指明它触及的具体弃用项——这样，弃用在你遇到它的那一刻就会出现在日志里，无需专门去查。
已弃用字段会保留一个已公布的最短期限，之后才会在后续的日期版本中被移除。