WooCommerce REST API 分页功能正确使用指南-php教程-PHP中文网

WooCommerce REST API 分页功能正确使用指南

本文详解如何在 WooCommerce REST API 中正确使用分页参数（如 per_page 和 page），解决因 URL 路径拼接错误导致分页失效、数据量受限或认证失败的问题。

本文详解如何在 woocommerce rest api 中正确使用分页参数（如 `per_page` 和 `page`），解决因 url 路径拼接错误导致分页失效、数据量受限或认证失败的问题。

在使用 WooCommerce REST API 官方 PHP SDK 时，一个常见误区是将分页参数（如 per_page=30）直接拼接到资源路径中（例如 'orders?per_page=30'）。这种写法看似直观，实则违反 SDK 的设计规范——SDK 的 get() 方法明确要求将查询参数以关联数组形式传入第二个参数，而非硬编码进 URI 字符串中。否则，SDK 可能忽略该参数、触发签名验证失败，或与基础 URL 构造逻辑冲突，最终导致仅返回默认的 10 条记录（WooCommerce 默认 per_page 值为 10）。

正确的调用方式如下：

Wordpress REST API

OpenClaw技能，提供WordPress REST API命令行工具，支持通过原生HTTP处理文章、页面、分类、标签、用户及自定义请求。

下载

// ✅ 正确：通过第二个参数传递分页配置
$parameters = [
    'per_page' => 30,
    'page'     => 1, // 获取第 1 页（可选，默认为 1）
    'status'   => 'completed' // 其他合法参数也可一并加入
];

try {
    $orders = $woocommerce->get('orders', $parameters);
    echo "共获取 " . count($orders) . " 条订单。\n";
} catch (HttpClientException $e) {
    echo "API 请求失败: " . $e->getMessage();
}

⚠️ 注意事项：

禁止在 endpoint 字符串中拼接查询参数（如 'orders?per_page=30'），这会导致 SDK 无法正确生成带签名的请求 URL，尤其在启用 query_string_auth 时极易引发 401 认证错误；

per_page 最大值受 WooCommerce 后台设置限制（默认通常为 100），超出将被截断，可通过 wp-admin → WooCommerce → Settings → Advanced → REST API 调整；

若需遍历全部数据，请结合 page 参数循环请求，并检查响应头中的 X-WP-Total 与 X-WP-TotalPages 字段判断总页数；

确保 query_string_auth => true 仅用于 HTTPS 环境，HTTP 下存在安全风险，推荐优先使用 Basic Auth Header 方式。

掌握这一参数传递规范，不仅能稳定启用分页，也为后续集成筛选、排序、嵌套资源等高级功能奠定基础。