woocommerce-store-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

The Store API is the public REST surface used by Woo blocks (Cart, Checkout, Mini-Cart) and external integrations. It lives under

/wc/store/v1/*

and has its own conventions distinct from the older

/wc/v3/*

admin REST API.

Store API是Woo区块（购物车、结账、迷你购物车）及外部集成所使用的公开REST接口。它位于

/wc/store/v1/*

路径下，拥有与旧版

/wc/v3/*

后台REST API不同的专属规范。

This skill complements

woocommerce-backend-dev

(general PHP conventions) and

woocommerce-performance

(cache priming patterns). Read those first for general conventions; this skill covers Store-API-specific decisions.

此技能是

woocommerce-backend-dev

（通用PHP规范）和

woocommerce-performance

（缓存预加载模式）的补充。请先阅读这两项内容了解通用规范；本技能涵盖Store API特有的决策要点。

authentication.md —
```
permission_callback
```
styles, nonce enforcement via
```
AbstractCartRoute
```
, when to extend which abstract.
rest-conventions.md — Path/body/query separation, collection vs item vs action routes, status codes, idempotency.
schema-design.md — Schema as public contract, field discipline, response-shape alignment.
variation-handling.md — Server-authoritative variation reconciliation.
performance.md — Where to apply cache priming in Store API responses. Cross-links to
```
woocommerce-performance
```
for the underlying patterns.

authentication.md —
```
permission_callback
```
的样式、通过
```
AbstractCartRoute
```
执行nonce验证、何时扩展对应的抽象类。
rest-conventions.md — 路径/请求体/查询参数的区分、集合型/单项型/操作型路由、状态码、幂等性。
schema-design.md — 架构作为公开契约、字段规范、响应结构一致性。
variation-handling.md — 服务器主导的变体协调。
performance.md — 在Store API响应中何处应用缓存预加载。交叉链接到
```
woocommerce-performance
```
以了解底层模式。

Schemas are the public contract. What the schema declares must be what the route returns. Don't bolt fields onto a response after the schema produced it.
Pick the right abstract. Routes that mutate per-user state via cookies must extend
```
AbstractCartRoute
```
(which enforces nonces) or implement equivalent CSRF protection.
```
AbstractRoute
```
alone is for read-only or own-auth routes.
GET is safe. No side effects, no body. Auto-create-on-read is allowed only as in-memory materialisation; persist on the first explicit write.
Server is authoritative on identity. Don't trust client-supplied attribute payloads for variations; derive them from the variation product.
Don't ship dead fields. Schema properties that have only one possible value forever, or that mirror data already exposed elsewhere, are public-API surface that's easier to add later than to retract.

架构即公开契约：架构声明的内容必须与路由返回的内容一致。不要在架构生成后再向响应中添加字段。
选择合适的抽象类：通过Cookie改变用户状态的路由必须继承
```
AbstractCartRoute
```
（它会执行nonce验证）或实现等效的CSRF防护。仅
```
AbstractRoute
```
适用于只读或自有认证的路由。
GET请求是安全的：无副作用，无请求体。仅允许在内存中实现“读取时自动创建”；需在首次显式写入时持久化数据。
服务器拥有身份权威：不要信任客户端提供的变体属性负载；应从变体产品中派生这些属性。
不要保留无用字段：永远只有一个可能值，或镜像已在其他地方暴露的数据的架构属性，属于公开API层面的内容，添加容易但撤回困难。

Authentication.php — global Store API auth filter; deliberately bypasses WP's cookie-nonce check.
AbstractCartRoute.php — nonce enforcement, cart-session loading,
```
Nonce
```
/
```
Cart-Token
```
response headers.
AbstractRoute.php — base class for routes that don't need cart-session/nonce machinery.
AbstractSchema.php —
```
prepare_html_response()
```
,
```
prepare_money_response()
```
, response-formatting helpers.
CartItems.php — canonical example of collection-style POST/DELETE routes.
CartController.php — variation reconciliation reference (
```
parse_variation_data()
```
).