技能介绍

解决什么问题

在开发 Headless Shopify 店铺时，前端通常需要直接与 https://{shop}.myshopify.com/api/2026-04/graphql.json 通信。然而，Storefront API 的字段繁多、版本更迭快（每季度发布一次），且涉及多种认证模式与金额格式差异，手写查询容易踩坑：比如把 MoneyV2 的「元」字符串误当「分」处理，或者在 Tokenless 模式下尝试读取 Metafields 导致报错。本技能提供了一套自包含的参考，帮助你快速编写、审查 Storefront GraphQL 请求。

核心能力与工作流

1. 认证与端点
支持两种模式：无需 Token 的公开模式（适合浏览商品和购物车，复杂度上限 1000）和携带 X-Shopify-Storefront-Access-Token 的模式（支持读取菜单、客户信息及自定义字段）。生产环境务必锁定版本号（如 2026-04）。

2. 关键操作场景

购物车管理：覆盖 cartCreate 到结算的完整生命周期。
本地化：通过 @inContext(country: CN, language: ZH) 指令获取人民币展示价和中文文案。
数据查询：提供 products、collections、search 等根字段的速查表与模板。

3. 编写规范
遵循六步工作法：选对根字段、精简字段以控制成本、Mutation 必须带 userErrors、强制分页、仅用 HTTPS、以及使用代码块包裹返回的 GraphQL。

适用边界与注意点

禁止用于 Admin 操作：商品改价、订单处理等后台任务应使用 Admin API。
客户账户限制：仅支持 Legacy 账户体系，新出的 Customer Account API v2 属于独立的 OAuth 流程，不在本技能覆盖范围内。
Token 安全：Private Token 仅限服务端使用，前端只能用 Public Token 或通过中转代理。

更多细节与可直接复制的模板，请参考技能包内的 references/ 目录。