Shopify API 版本升级后接口报错怎么排查

现象#

把 api_version 从旧版本改到新版本后，部分接口开始返回 400 或字段为空，回滚版本又恢复正常。

原因#

• 新版本移除了旧字段或改了必填参数
• 响应结构变化（分页、金额、枚举值大小写）未同步调整解析逻辑
• webhook 订阅仍绑定旧版本，payload 结构不一致
• SDK 版本落后，内部仍按旧 schema 序列化

处理步骤#

1. 先查官方 changelog，列出目标版本中 removed 与 changed 的字段
2. 在开发店铺用 GraphiQL 逐条验证查询，确认报错位置
3. 同步升级 SDK 与 webhook 订阅版本，保证请求与回调在同一版本
4. 灰度切换：先在一个店铺或一条业务线启用新版本，观察 24 小时

验收标准#

新版本下核心链路（读取商品、创建订单、回调处理）全部通过；无 400/字段缺失。