woocommerce-store-api

WooCommerce Store API

Store API 是 Woo 区块（购物车、结账、迷你购物车）和外部集成使用的公共 REST 接口。它位于 /wc/store/v1/* 下，使用独立于旧版 /wc/v3/* 管理 REST API 的约定。

何时使用此技能

• 在 /wc/store/v1/ 下添加新路由。
• 修改现有路由的响应结构、状态码或参数架构。
• 为前端将使用的新资源设计架构。
• 将区块（或 iAPI store）连接到 Store API 端点。

此技能补充 woocommerce-backend-dev（通用 PHP 约定）和 woocommerce-performance（缓存预加载模式）。请先阅读这些内容，了解通用约定；此技能涵盖 Store API 特有的设计决策。

主题

• authentication.md — permission_callback 样式、通过 AbstractCartRoute 强制执行 nonce，以及何时扩展不同的抽象类。
• rest-conventions.md — 路径、请求体和查询参数的区分，集合、单项和操作路由，状态码，幂等性。
• schema-design.md — 架构作为公共契约、字段规范、响应结构对齐。
• variation-handling.md — 由服务器负责的变体协调。
• performance.md — 在 Store API 响应中应用缓存预加载的位置。包含指向 woocommerce-performance 中相关底层模式的链接。

核心原则

• 架构是公共契约。 架构声明的内容必须与路由返回的内容一致。不要在架构生成响应后再向其中添加字段。
• 选择合适的抽象类。 通过 cookie 修改每用户状态的路由必须扩展 AbstractCartRoute（它会强制执行 nonce），或实现等效的 CSRF 保护。AbstractRoute 仅适用于只读路由或使用自身身份验证的路由。
• GET 是安全的。 不产生副作用，不使用请求体。只有在内存中实例化时才允许按需创建；应在首次明确写入时持久化。
• 身份以服务器为准。 不要信任客户端提供的变体属性载荷；应从变体产品中推导这些属性。
• 不要发布无用字段。 永远只有一个可能值的架构属性，或与其他地方已公开的数据重复的属性，都会成为公共 API 的一部分；日后添加比撤回容易得多。

参考文件

• Authentication.php — 全局 Store API 身份验证筛选器；有意绕过 WP 的 cookie nonce 检查。
• AbstractCartRoute.php — nonce 强制执行、购物车会话加载、Nonce/Cart-Token 响应标头。
• AbstractRoute.php — 无需购物车会话或 nonce 机制的路由基类。
• AbstractSchema.php — prepare_html_response()、prepare_money_response()、响应格式化辅助方法。
• CartItems.php — 集合样式 POST/DELETE 路由的典型示例。
• CartController.php — 变体协调参考（parse_variation_data()）。