跳到主要内容

Store API 设计原则

在扩展、创建或更新 Store API 的接口时，应考虑以下原则。

接口必须包含一个 明确定义的 JSON 结构化数据​

每个接口/端点都需要特定的输入数据结构，并且应使用定义的、可预测的结构返回数据。 这在 JSON 结构化数据中定义，其中包含 API 可以返回的所有属性的完整列表，以及它可以接受的输入参数。

明确定义的结构化数据还提供了一层安全性，因为它使我们能够验证和清理发送到 API 的请求。

在定义结构化数据时，请参考 WordPress REST API 手册，其中记录了可用的属性和类型，以及 JSON 结构化数据标准。 此外：

  • 属性应使用 snake_case 🐍 格式。
  • 应避免使用含糊的术语，并且属性名称应尽量使用易于理解的语言，而不是 "WooCommerce" 术语或设置名称。
  • 属性应使用美式英语定义，但字段的描述应进行本地化。
  • 允许使用多种类型，例如，如果某个值不适用，可以使用 null 类型。
  • 在可能的情况下，建议使用 sanitize_callback 和 validate_callback，以确保在处理请求之前，数据以正确的格式接收。

如果您在定义一致的结构化数据时遇到困难，则您的方法可能存在问题。 一个常见的实际例子是表示 文章标签。 可能会有人想在响应中使用别名 (Slug) 作为属性字段名：

tags: [
  "my-tag": {
    // ...标签数据
  },
  "my-other-tag": {
    // ...标签数据
  }
]

但是，这在结构化数据中难以表示，并且对客户端来说不可预测。 更好的方法是使用一个数据数组，其中一个属性是别名：

tags: [
  {
    "slug": "my-tag",
    // ...标签数据
  },
  {
    "slug": "my-other-tag",
    // ...标签数据
  }
]

接口应围绕具有单个类型结构化数据的资源进行设计​

接口应围绕资源（名词）而不是操作（动词）进行设计。 接口还应仅返回由其结构化数据定义的单一类型的数据。 例如：

接口资源类型预期数据
wc/store/v1/cart购物车一个购物车对象
wc/store/v1/cart/items购物车商品购物车商品对象的列表
wc/store/v1/products产品产品对象的列表
wc/store/v1/products/1产品一个产品对象

在 Store API 中，有两个值得注意的例外情况，即 错误 和 购物车操作。

错误处理​

错误，包括验证错误，应该返回一个错误响应码（4xx 或 5xx）和一个 WP_Error 对象。AbstractRoute 类将负责将 WP_Error 对象转换为有效的 JSON 响应。

错误消息应该进行本地化，但不需要使用面向客户的语言（客户端应该使用给定的错误码来创建必要的面向客户的提示）。

错误码应该以 woocommerce_rest_ 为前缀。

购物车操作​

某些端点设计用于避免客户端需要进行多次 API 调用。这纯粹是为了方便。

例如，wc/store/v1/cart/add-item 端点接受一个数量和一个产品 ID，但返回完整的购物车对象，而不是仅仅更新的项目列表。

暴露的数据必须属于当前用户或为非敏感数据​

资源，包括客户和订单数据，应该仅反映当前会话。不要返回其他客户的数据，因为这会违反隐私和安全。

允许在响应中包含商店数据，例如商店货币的 设置，但应避免 私有或敏感数据。为了允许更广泛地访问数据，您必须使用经过身份验证的 WC REST API。

从 API 返回的数据不应该进行 转义（这由客户端负责进行渲染），但应该进行清理。例如，HTML 应该通过 wp_kses_post 进行处理。

客户端有责任正确地转义来自 API 的数据，但我们应该尽量避免返回可能不安全的数据。

资源集合应该进行分页​

大量的数据应该进行分页，以避免对 服务器 造成过载。例如，返回产品集合。

  • 使用响应头 X-WP-Total、X-WP-TotalPages 和 Link 来指示 可用 的资源。
  • 使用参数 page 和 per_page 来检索特定的页面。
  • per_page 的最大允许值为 100。

API 回复应使用标准的 HTTP 状态码​

在返回内容时，应使用有效的 HTTP 回复码，例如：

  • 200 OK 用于成功的回复（这是默认的回复码）。
  • 201 Created 用于创建资源，例如，添加新的购物车商品或应用新的优惠券。
  • 204 No Content 用于成功的删除操作。
  • 400 Bad Request 当缺少必需的参数时。
  • 403 Forbidden 当请求不允许时，例如，如果提供的安全随机数无效。
  • 404 Not Found 如果资源不存在。
  • 409 Conflict 如果资源无法更新，例如，如果购物车中的某个内容无效并被删除。

关于 DELETE 请求的说明：在 WordPress REST API 中，一种常见的模式是返回已删除的对象。在 Store API 的情况下，我们选择返回一个空回复，并使用状态码 204 No Content，这更有效。

完整的 HTTP 状态码列表可以在这里找到。

应该尽可能避免破坏性变更​

Store API 通过使用结构化数据与 API 消费者建立契约。除非绝对必要，否则不应破坏此契约。如果必须进行破坏性变更，则需要发布 Store API 的新版本。

破坏性变更是指任何更改现有结构化数据格式、删除结构化数据属性、删除现有路由或对任何已公开且可能已被消费者使用的内容进行向后不兼容的更改。可以通过弃用现有属性而不是删除它们，或者弃用路由并将它们替换为不同的路由来避免破坏性变更，如果需要进行重大更改。

非破坏性变更始终允许，而无需增加 API 版本。以下是一些示例：

  • 向结构化数据添加新的属性。
  • 添加新的路由、端点、方法。
  • 添加可选的请求参数。
  • 重新排序回复字段。

只有当错误修复导致向后不兼容的更改时，版本才会增加。除非存在需要回溯修复的安全问题，否则不会将修复回滚到过去的 API 版本。