API 版本写在 URL 还是请求头才生效

现象#

在请求头加了 X-Shopify-API-Version: 2026-10，响应头返回的仍是 2026-07，新版本字段继续报 Field doesn't exist；把版本写进 URL 后才恢复正常。

原因#

• 版本由 URL 路径决定，形如 /admin/api/2026-10/graphql.json，请求头不是选版入口
• 完全不写版本时会回落到最旧的受支持稳定版，而不是最新稳定版
• 目标版本已退役时会被 forward 到最旧可用版本，响应头里的值才是实际版本
• SDK 或网关重写了 base URL，把版本段吃掉，代码里配置的版本没有生效

处理步骤#

1. 检查最终请求地址是否包含 /admin/api/{version}/graphql.json 完整路径
2. 每次响应读取 X-Shopify-API-Version，与期望值不一致就告警
3. SDK 初始化时显式设置 apiVersion，不要依赖默认值或环境变量残留
4. 网关与 mock 不要改写 /admin/api/{version} 路径段，重写按前缀匹配
5. 升级前在开发店只替换 URL 里的版本号做对比，确认差异确实来自版本

验收标准#

响应头 X-Shopify-API-Version 与 URL 中的版本完全一致，新字段可查，旧字段的 deprecated 警告按预期出现。