> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphafin.x-pai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

# 分页

对于可能返回大量数据的API端点，AlphaFinance采用分页机制来控制每次请求返回的数据量，提高API性能和用户体验。本文档将详细介绍如何使用分页功能有效地获取大型数据集。

## 分页参数

在请求中，您可以使用以下参数控制分页行为：

| 参数名      | 类型 | 默认值 | 最大值 | 描述                  |
| -------- | -- | --- | --- | ------------------- |
| `limit`  | 整数 | 20  | 100 | 每页返回的结果数量           |
| `page`   | 整数 | 1   | -   | 要检索的页码，从1开始         |
| `offset` | 整数 | 0   | -   | 结果集的起始位置（与`page`互斥） |

## 基本分页示例

以下是使用`page`和`limit`参数进行分页的基本示例：

```bash theme={null}
# 获取第一页数据，每页20条
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&page=1" \
  -H "X-API-KEY: your_api_key_here"

# 获取第二页数据，每页20条
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&page=2" \
  -H "X-API-KEY: your_api_key_here"
```

## 分页响应格式

启用分页的API响应包含`pagination`对象，提供关于当前分页状态和总数据量的信息：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": [
    // 返回的数据项...
  ],
  "pagination": {
    "current_page": 2,
    "total_pages": 5,
    "total_items": 98,
    "items_per_page": 20,
    "has_next_page": true,
    "has_prev_page": true
  }
}
```

`pagination`对象包含以下字段：

* `current_page`：当前页码
* `total_pages`：总页数
* `total_items`：总结果数量
* `items_per_page`：每页项目数
* `has_next_page`：是否有下一页
* `has_prev_page`：是否有上一页

## 使用偏移量进行分页

除了基于页码的分页外，您还可以使用`offset`参数直接指定起始位置：

```bash theme={null}
# 获取从第0个结果开始的20条数据
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&offset=0" \
  -H "X-API-KEY: your_api_key_here"

# 获取从第20个结果开始的20条数据
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=20&offset=20" \
  -H "X-API-KEY: your_api_key_here"
```

<Note>
  `page`和`offset`参数不应同时使用。如果同时提供，API将优先使用`offset`。
</Note>

## 游标分页

对于某些需要处理大量数据的API端点，我们还提供了基于游标的分页方式：

```bash theme={null}
# 获取第一页数据
curl -X GET "https://api.alphafin.x-pai.com/v1/market/trades?symbol=600519&limit=100" \
  -H "X-API-KEY: your_api_key_here"

# 使用返回的游标获取下一页
curl -X GET "https://api.alphafin.x-pai.com/v1/market/trades?symbol=600519&limit=100&cursor=eyJpZCI6MTAwMH0=" \
  -H "X-API-KEY: your_api_key_here"
```

使用游标分页时，API响应会包含`cursor`字段：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": [
    // 返回的数据项...
  ],
  "cursor": "eyJpZCI6MjAwMH0=",
  "has_more": true
}
```

* `cursor`：用于获取下一页结果的游标
* `has_more`：是否有更多结果可用

<Warning>
  游标值是一个不透明的字符串，其内容和格式可能会更改。请不要尝试解析或构造游标值。
</Warning>

## 分页最佳实践

1. **设置合理的`limit`值**：
   * 对于需要展示给用户的数据，选择适合您UI的`limit`值（如10-20）
   * 对于需要批量处理的数据，可以使用较大的`limit`值（如50-100）
   * 避免设置过小的`limit`值，这会导致过多的API调用

2. **使用正确的分页类型**：
   * 对于UI分页（用户可以跳转到特定页面），使用基于`page`的分页
   * 对于"加载更多"按钮或无限滚动，使用基于`offset`或游标的分页

3. **处理空结果**：
   * 当请求的页码超出可用范围时，API将返回空数据数组，而不是错误
   * 始终检查`pagination.total_items`或`has_more`字段来确定是否有更多数据

4. **并行请求注意事项**：
   * 避免同时发送大量并行分页请求，这可能触发速率限制
   * 考虑使用批处理端点（如果可用）而不是多个分页请求

## 示例代码

以下是在不同编程语言中实现分页请求的示例：

<CodeGroup>
  ```python Python theme={null}
  import requests

  def fetch_all_pages(api_key, endpoint, params):
      """获取所有页面的数据"""
      all_data = []
      page = 1
      has_more = True
      
      while has_more:
          # 复制基本参数并添加分页参数
          page_params = params.copy()
          page_params['page'] = page
          page_params['limit'] = 100
          
          # 发送请求
          headers = {"X-API-KEY": api_key}
          response = requests.get(endpoint, params=page_params, headers=headers)
          response_data = response.json()
          
          # 添加当前页数据
          all_data.extend(response_data['data'])
          
          # 检查是否有更多页
          pagination = response_data.get('pagination', {})
          current_page = pagination.get('current_page', 0)
          total_pages = pagination.get('total_pages', 0)
          
          has_more = current_page < total_pages
          page += 1
      
      return all_data

  # 示例用法
  api_key = "your_api_key_here"
  endpoint = "https://api.alphafin.x-pai.com/v1/stock/search"
  params = {"keyword": "银行"}

  all_banks = fetch_all_pages(api_key, endpoint, params)
  print(f"找到 {len(all_banks)} 家银行相关股票")
  ```

  ```javascript JavaScript theme={null}
  async function fetchAllPages(apiKey, endpoint, params) {
    let allData = [];
    let page = 1;
    let hasMore = true;
    
    while (hasMore) {
      // 复制基本参数并添加分页参数
      const pageParams = new URLSearchParams({
        ...params,
        page: page,
        limit: 100
      });
      
      // 发送请求
      const response = await fetch(`${endpoint}?${pageParams.toString()}`, {
        headers: { 'X-API-KEY': apiKey }
      });
      
      const responseData = await response.json();
      
      // 添加当前页数据
      allData = allData.concat(responseData.data);
      
      // 检查是否有更多页
      const pagination = responseData.pagination || {};
      const currentPage = pagination.current_page || 0;
      const totalPages = pagination.total_pages || 0;
      
      hasMore = currentPage < totalPages;
      page++;
    }
    
    return allData;
  }

  // 示例用法
  const apiKey = 'your_api_key_here';
  const endpoint = 'https://api.alphafin.x-pai.com/v1/stock/search';
  const params = { keyword: '银行' };

  fetchAllPages(apiKey, endpoint, params)
    .then(allBanks => {
      console.log(`找到 ${allBanks.length} 家银行相关股票`);
    });
  ```
</CodeGroup>

## 适用于分页的端点

以下是支持分页的主要API端点：

* 股票搜索：`/v1/stock/search`
* 股票列表：`/v1/stock/list`
* 行业成分：`/v1/industry/constituents`
* 指数成分：`/v1/indices/constituents`
* 公司公告：`/v1/events/announcements`
* 财务报表：`/v1/financials/income-statement`（等财务类端点）

## 相关资源

* [API错误码](/api-reference/errors)
* [速率限制](/api-reference/rate-limits)
* [批量请求](/core-concepts/batch-requests)