Shopify Admin API

userErrors 和顶层 errors 到底先看哪个

现象#

调用 productCreate 返回 200,代码读 data.productCreate.product.id 时抛空指针;换一条查询又只拿到 errors 数组,data 直接是 null。

原因#

  • 顶层 errors 表示请求本身不合法,例如字段名拼错、成本超限,此时 data 为 null
  • userErrors 属于业务校验失败,请求执行了但没落库,HTTP 状态仍是 200
  • 选择集里某个非空字段报错会让整个 data 变成 null,其他字段的结果一起被掩盖
  • SDK 把 errors 抛异常、把 userErrors 当普通数据返回,业务层容易只处理其中一种

处理步骤#

  1. 统一封装:先判 errors 非空则按请求错误抛出,附带 extensions.code
  2. 再判 payload.userErrors 非空,逐条记录 field 与 message
  3. 两者都为空才认为写入成功,并回读 id 确认对象真实存在
  4. 对 MAX_COST_EXCEEDED 与 THROTTLED 单独走退避重试,不要计入业务失败
  5. 日志同时记 X-Request-Id,方便与 Shopify 侧记录对齐

验收标准#

构造缺必填字段的请求,日志出现 userErrors 的 field 与 message;构造错字段名的请求,出现顶层 errors 与 code,两条路径互不吞没。

专项深读 · 可复现排查指南

GraphQL:把请求错误和业务校验分开处理

HTTP 200 只表示 HTTP 传输成功,不表示 mutation 已完成。调用方需要同时检查顶层 errors 与 mutation 返回的 userErrors,不能直接读取 product.id。

建议按以下顺序复现和定位

  1. 记录响应状态、顶层 errors、data 和 mutation 字段,不记录原始访问令牌。
  2. 如果有顶层 errors,检查请求字段、权限、查询成本以及是否得到部分 data。
  3. 如果 productCreate.userErrors 非空,按 field/message 展示业务校验失败,不把它当网络错误无限重试。
  4. 当 errors 与 userErrors 都为空时,再确认创建对象返回的 id。
  5. 对可重试的限流/短暂故障执行有边界的退避;对无效输入不要重试。

可参考的示例(非真实客户环境)

// 结构示例:适配你实际选择的 mutation 名称
const body = await response.json();
if (body.errors?.length) {
  throw new Error(JSON.stringify(body.errors));
}
const payload = body.data?.productCreate;
if (payload?.userErrors?.length) {
  return { ok: false, issues: payload.userErrors };
}
if (!payload?.product?.id) {
  throw new Error('缺少 product.id,需要检查响应');
}
return { ok: true, id: payload.product.id };
注意:不同 mutation 的结果字段不同;示例仅演示响应分支,不能不经修改直接复制到所有 Shopify API。GraphQL 也可能返回部分 data。

交付与验证记录应该包含什么

分别构造无效字段、业务验证失败和正常创建三种响应,确保日志能清晰区别故障层次,且不会重复创建商品。

原始技术资料:Shopify / Google 官方文档。本节为根据公开文档整理的排查方法与模拟示例,未宣称来自客户项目或已在您的店铺实测。

本文由 风格技术 技术团队整理,适用于 Shopify 标准版与 Plus 店铺。Shopify 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。