building-storefronts

Medusa 商城前端开发

使用 Medusa 构建商城前端的集成指南。涵盖 SDK 用法、React Query 模式，以及调用自定义 API 路由。

适用场景

以下任意商城前端开发任务都应加载此技能：

• 从商城前端调用自定义 Medusa API 路由
• 在前端应用中集成 Medusa SDK
• 使用 React Query 获取数据
• 实现带乐观更新的变更操作
• 错误处理和缓存失效

同时加载 building-with-medusa 的场景： 构建商城前端调用的后端 API 路由

重要：按需加载参考文件

以下快速参考不足以支持实现。 在编写商城前端集成代码之前，必须加载参考文件。

实现商城前端功能时加载此参考文件：

• 调用 API 路由？ → 必须先加载 references/frontend-integration.md
• 使用 SDK？ → 必须先加载 references/frontend-integration.md
• 实现 React Query？ → 必须先加载 references/frontend-integration.md

按优先级划分的规则类别

优先级	类别	影响	前缀
1	SDK 用法	严重	sdk-
2	React Query 模式	高	query-
3	数据展示	高（包含严重的价格规则）	display-
4	错误处理	中	error-

快速参考

1. SDK 用法（严重）

• sdk-always-use - 所有 API 请求都必须使用 Medusa JS SDK——绝不能使用常规的 fetch()
• sdk-existing-methods - 对于内置端点，使用现有 SDK 方法（sdk.store.product.list()、sdk.admin.order.retrieve()）
• sdk-client-fetch - 对于自定义 API 路由，使用 sdk.client.fetch()
• sdk-required-headers - SDK 会自动添加必需的标头（商城使用可发布 API 密钥，管理端使用身份验证）；常规 fetch() 缺少这些标头会导致错误
• sdk-no-json-stringify - 绝不能对 body 使用 JSON.stringify()——SDK 会自动处理序列化
• sdk-plain-objects - 向 body 传递纯 JavaScript 对象，而不是字符串
• sdk-locate-first - 使用 SDK 之前，务必先确定项目中 SDK 的实例化位置

2. React Query 模式（高）

• query-use-query - 对 GET 请求（数据获取）使用 useQuery
• query-use-mutation - 对 POST/DELETE 请求（变更操作）使用 useMutation
• query-invalidate - 在 onSuccess 中使查询失效，以便在变更操作后刷新数据
• query-keys-hierarchical - 采用分层结构组织查询键，以便有效管理缓存
• query-loading-states - 务必处理 isLoading、isPending、isError 状态

3. 数据展示（高）

• display-price-format - 严重： Medusa 中的价格按原值存储（$49.99 = 49.99，而不是以分为单位）。直接显示价格——绝不能除以 100

4. 错误处理（中）

• error-on-error - 在变更操作中实现 onError 回调，以处理失败
• error-display - 变更操作失败时向用户显示错误消息
• error-rollback - 使用乐观更新，并在出错时回滚，以改善用户体验

关键 SDK 模式

务必向 SDK 传递纯对象——绝不能使用 JSON.stringify()：

// ✅ CORRECT - Plain object
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: {
    product_id: "prod_123",
    rating: 5,
  }
})

// ❌ WRONG - JSON.stringify breaks the request
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: JSON.stringify({  // ❌ DON'T DO THIS!
    product_id: "prod_123",
    rating: 5,
  })
})

原因：

• SDK 会自动处理 JSON 序列化
• 使用 JSON.stringify() 会导致二次序列化，并破坏请求
• 服务端将无法解析 body

常见错误检查清单

开始实现前，请确认你没有犯以下错误：

SDK 使用：

• 使用常规 fetch()，而不是 Medusa JS SDK（会导致缺少标头错误）
• 没有对内置端点使用现有 SDK 方法（例如，使用 sdk.client.fetch("/store/products")，而不是 sdk.store.product.list()）
• 对 body 参数使用 JSON.stringify()
• 手动设置 Content-Type 标头（SDK 会自动添加）
• 硬编码 SDK 导入路径（先在项目中查找）
• 没有对自定义路由使用 sdk.client.fetch()

React Query：

• 修改数据后没有使查询失效
• 使用扁平查询键，而不是分层查询键
• 没有处理加载和错误状态
• 忘记在修改数据期间禁用按钮（isPending）

数据显示：

• **重要：**显示价格时除以 100（价格按原值存储：$49.99 = 49.99，而不是以美分为单位）

错误处理：

• 没有实现 onError 回调
• 没有向用户显示错误消息
• 没有妥善处理网络故障

如何使用

如需详细模式和示例，请加载参考文件：

references/frontend-integration.md - SDK usage, React Query patterns, API integration

参考文件包含：

• 逐步讲解 SDK 集成模式
• 完整的 React Query 示例
• 正确与错误的代码示例
• 查询键最佳实践
• 乐观更新模式
• 错误处理策略

何时使用 MedusaDocs MCP 服务

以下情况使用此技能（主要来源）：

• 如何从店面调用自定义 API 路由
• SDK 使用模式（sdk.client.fetch）
• React Query 集成模式
• 常见错误和反模式

以下情况使用 MedusaDocs MCP 服务（次要来源）：

• 内置 SDK 方法（sdk.admin.、sdk.store.）
• Medusa SDK 官方 API 参考
• 特定框架的配置选项

技能为何优先：

• 技能包含“不要使用 JSON.stringify”之类的关键模式，而 MCP 不会着重强调
• 技能展示正确与错误的模式；MCP 展示可实现的功能
• 规划需要理解模式，而不只是查阅 API 参考

与后端集成

⚠️ 重要：始终使用 Medusa JS SDK，绝不要使用常规 fetch()

构建涉及后端和前端的功能时：

1. **后端（building-with-medusa 技能）：**模块 → 工作流 → API 路由
2. **店面（此技能）：**SDK → React Query → UI 组件
3. 连接：
   • 内置端点：使用现有 SDK 方法（sdk.store.product.list()）
   • 自定义 API 路由：使用 sdk.client.fetch("/store/my-route")
   • 绝不要使用常规 fetch()——缺少可发布 API 密钥会导致错误

为何必须使用 SDK：

• Store 路由需要 x-publishable-api-key 标头
• Admin 路由需要 Authorization 和会话标头
• SDK 会自动处理所有必需的标头
• 使用不带标头的常规 fetch() → 身份验证／授权错误

后端 API 路由模式请参阅 building-with-medusa。