跳到主要内容

分页

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

查询参数​

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

分页参数

NameTypeRequiredDescription
pageintegeroptional从零开始的页码索引。第一页为 0（不是 1）。默认值：0。
sizeintegeroptional每页条目数。必须在 1 到 100 之间。默认值：20。
sortstringoptional排序表达式，格式为 字段,方向。例如：createdAt,desc。可通过重复此参数指定多个排序字段。

请求示例​

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

curl -X GET "https://api.lampay.app/api/v1/transfer/query/orders?page=1&size=10&sort=createdAt,desc" \
  -H "X-Api-Key: sk_live_abc123def456" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1709337600" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000"
信息 从零开始的索引

页码从零开始。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.contentarray当前页的条目列表。
data.page.sizeinteger请求的每页条目数。
data.page.numberinteger当前页码（从零开始）。
data.page.totalElementsinteger所有页面的总条目数。
data.page.totalPagesinteger总页数。计算方式为 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

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

注意 可排序字段

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

限制与默认值​

参数默认值最小值最大值
page00无上限（但超出 totalPages 的页面返回空 content）
size201100

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

遍历所有页面​

以下是一个获取分页端点所有页面的 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'
);
注意 性能考虑

循环获取所有页面适用于中小型数据集。对于非常大的数据集（数千条记录），请考虑是否真的需要一次获取所有记录。通常，您可以通过日期范围或状态过滤来缩小结果集，或者逐页处理条目而不将其全部累积到内存中。

空结果​

当页面没有条目时（集合为空或请求的页码超过最后一页），响应返回空的 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 且总数不会频繁变化，在第一次请求后缓存这些值，而不是在每次翻页时重新读取。