分页

返回资源集合的端点使用无游标的、基于偏移量的分页。本页介绍查询参数、响应格式以及高效分页遍历结果集的最佳实践。

查询参数

所有分页端点接受以下查询参数：

Name	Type	Required	Description

请求示例

获取第二页的转账记录，每页 10 条，按创建日期降序排列：

从零开始的索引

页码从零开始计数。page=0 返回第一页，page=1 返回第二页，依此类推。

响应格式

分页响应将结果列表包装在一个 data 对象中，其中包含总数、页面元数据和导航信息。

分页响应200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [
      {
        "transferId": "txn_001",
        "amount": "250.00",
        "currency": "USD",
        "status": "COMPLETED",
        "createdAt": "2026-03-01T10:30:00Z"
      },
      {
        "transferId": "txn_002",
        "amount": "75.50",
        "currency": "USD",
        "status": "COMPLETED",
        "createdAt": "2026-03-01T09:15:00Z"
      }
    ],
    "page": {
      "size": 10,
      "number": 1,
      "totalElements": 47,
      "totalPages": 5
    }
  }
}

响应字段

字段	类型	说明
`data.content`	array	当前页的条目列表。
`data.page.size`	integer	请求的页面大小。
`data.page.number`	integer	当前页码（从零开始）。
`data.page.totalElements`	integer	所有页的条目总数。
`data.page.totalPages`	integer	总页数。计算方式为 `ceil(totalElements / size)`。

排序表达式

sort 参数接受字段名和排序方向，以逗号分隔：

sort=field,direction

方向	含义
`asc`	升序（A-Z，最早优先，最小优先）
`desc`	降序（Z-A，最新优先，最大优先）

示例

表达式	行为
`sort=createdAt,desc`	最新的条目优先
`sort=amount,asc`	最小金额优先
`sort=status,asc`	按状态字母顺序

多字段排序

要按多个字段排序，重复使用 sort 参数。第一个字段为主排序；后续字段用于打破平局：

?sort=status,asc&sort=createdAt,desc

这将按状态字母顺序排序，然后在每个状态组内按创建日期（最新优先）排序。

:::caution 可排序字段并非所有字段都可排序。尝试按不可排序的字段排序将返回 S012（INVALID_PARAMETER）。常见的可排序字段包括 createdAt、updatedAt、amount 和 status。请参阅具体端点文档了解支持的排序字段列表。 :::

限制和默认值

参数	默认值	最小值	最大值
`page`	0	0	无上限（但超出 `totalPages` 的页面返回空 `content`）
`size`	20	1	100

如果您请求的 size 大于 100，服务器会将其限制为 100 而不返回错误。如果您请求负的 page 或 size，服务器将返回 S012（INVALID_PARAMETER）。

遍历所有页面

以下是一个 JavaScript 示例，用于获取分页端点的所有页面：

javascript

async function fetchAllPages(path, apiKey, apiSecret) {
  const allItems = [];
  let page = 0;
  let totalPages = 1; // 第一次请求后会更新

  while (page < totalPages) {
    const response = await apiRequest(
      'GET',
      `${path}?page=${page}&size=100&sort=createdAt,desc`,
      null,
      apiKey,
      apiSecret
    );

    if (!response.success) {
      throw new Error(`API error: ${response.code} - ${response.message}`);
    }

    allItems.push(...response.data.content);
    totalPages = response.data.page.totalPages;
    page++;
  }

  return allItems;
}

// 使用方式
const allTransfers = await fetchAllPages(
  '/api/v1/transfer/query/orders',
  'sk_live_abc123def456',
  'your-api-secret-here'
);

:::caution 性能注意事项循环获取所有页面适用于中小型数据集。对于非常大的数据集（数千条记录），请考虑是否真的需要一次获取所有记录。通常，您可以通过日期范围或状态进行过滤来减少结果集，或逐页处理数据而不将所有数据积累在内存中。 :::

空结果

当页面没有条目时（无论是因为集合为空还是您请求了超出最后一页的页面），响应返回一个空的 content 数组和准确的元数据：

空页面200

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [],
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 0,
      "totalPages": 0
    }
  }
}

高效分页技巧

使用过滤器减少结果集

大多数列表端点除了分页外，还支持查询过滤器（按状态、日期范围、ID 前缀等）。在分页之前先应用过滤器缩小结果范围，而不是获取所有数据后在客户端进行过滤。

选择合适的页面大小

默认大小 20 适用于 UI 驱动的分页。对于批处理或数据导出，使用 size=100 以减少 HTTP 往返次数。对于移动客户端或低带宽场景，考虑使用较小的值如 10。

处理并发修改

在高活跃度的系统中，页面请求之间可能会有条目被创建或删除。这可能导致条目在页面之间移位（重复出现或被跳过）。如果精确处理至关重要，请使用带固定时间戳边界的日期范围过滤器，而不是仅依赖页码。

缓存总数

totalElements 和 totalPages 值在每次请求时都会计算。如果您正在构建带有页码的 UI 且总数不经常变化，可以在第一次请求后缓存这些值，而不是每次翻页时都重新读取。

分页 ​

查询参数 ​

请求示例 ​

响应格式 ​

响应字段 ​

排序表达式 ​

示例 ​

多字段排序 ​

限制和默认值 ​

遍历所有页面 ​

空结果 ​

高效分页技巧 ​

分页