分页与轮询

本文介绍如何处理 API 的分页查询和数据轮询。

分页查询

分页参数

所有列表类接口支持分页：

请求示例

GET /v1/logs?page=1&pageSize=20

响应格式

{
  "code": 200,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

遍历所有数据

async function fetchAllData() {
  let page = 1;
  let allItems = [];
  
  while (true) {
    const response = await fetch(`/v1/logs?page=${page}&pageSize=100`);
    const data = await response.json();
    
    allItems = allItems.concat(data.data.items);
    
    if (page >= data.data.pagination.totalPages) break;
    page++;
  }
  
  return allItems;
}

数据轮询

异步任务查询

某些耗时操作会返回任务 ID，需要轮询获取结果：

async function pollResult(taskId) {
  const maxAttempts = 30;
  const interval = 2000; // 2秒
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`/v1/tasks/${taskId}`);
    const data = await response.json();
    
    if (data.data.status === 'completed') {
      return data.data.result;
    }
    
    if (data.data.status === 'failed') {
      throw new Error(data.data.error);
    }
    
    await new Promise(r => setTimeout(r, interval));
  }
  
  throw new Error('Timeout');
}

最佳实践

• 合理设置 pageSize，建议不超过 100
• 轮询时设置合理的间隔和超时
• 使用指数退避策略处理失败重试