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

# 关于分页

> Flashduty Open API 分页机制说明

一般情况下，当我们拉取或检索某种数据对象时，都会基于分页将数据分批次返回，而不是在一个请求中返回所有数据。

## 传统分页

***

我们把基于 OFFSET 和 LIMIT 查询的分页技术定义为传统分页。在大多数 Flashduty 列表查询 API 中，您可以看到以下参数定义：

### 请求参数

| 参数      | 类型     | 描述                                      |
| ------- | ------ | --------------------------------------- |
| `p`     | number | 分页页码，默认从 1 开始。offset = (p - 1) \* limit |
| `limit` | number | 页内数目，最大值不超过 100，默认为 20                  |

### 响应参数

| 参数              | 类型      | 描述            |
| --------------- | ------- | ------------- |
| `total`         | number  | 当前条件下匹配到总条目数量 |
| `has_next_page` | boolean | 当前条件下是否有下一页数据 |

### 示例

<Tabs>
  <Tab title="请求示例">
    ```json theme={null}
    {
      "p": 1,
      "limit": 20
    }
    ```
  </Tab>

  <Tab title="响应示例">
    ```json theme={null}
    {
      "total": 1000,
      "has_next_page": true
    }
    ```
  </Tab>
</Tabs>

### 潜在问题

基于传统分页技术进行查询虽然简单，但可能会遇到以下一些问题：

<AccordionGroup>
  <Accordion title="性能问题">
    使用 OFFSET 和 LIMIT 进行分页查询时，数据库需要跳过指定数量的行（OFFSET），然后返回指定数量的行（LIMIT）。随着偏移量的增加，查询的性能可能会下降，特别是在处理大量数据时。每次查询都需要扫描和跳过前面的行，这会导致查询变得越来越慢。
  </Accordion>

  <Accordion title="数据不稳定性">
    当使用 PAGE 和 LIMIT 进行分页查询时，如果在查询期间删除或插入了数据，可能会导致结果不稳定。例如，如果在查询过程中删除了前面的行，那么后续的偏移量可能会失效，导致结果不准确或缺失。
  </Accordion>
</AccordionGroup>

### 查询限制

为了保护系统，确保大多数用户可以稳定访问，我们针对基于传统分页技术查询的 API 参数做了以下限制：

<Warning>
  要求 PAGE × LIMIT ≤ 10000，如果超过 10000，系统将直接返回 400 错误信息。这种情况下，请您转为使用游标分页，或缩小查询条件。
</Warning>

***

## 游标分页

***

我们把基于 SEARCH\_AFTER\_CTX 分页的技术定义为游标分页。游标分页技术可以更好地处理大数据集和高性能要求，并提供更稳定和高效的分页查询体验。

### 支持的 API

我们在以下 API 中提供了游标分页支持：

* [故障列表](/zh/api-reference/on-call/incidents/incident-list)
* [告警列表](/zh/api-reference/on-call/alerts/alert-read-list)

### 请求参数

| 参数                 | 类型     | 描述                     |
| ------------------ | ------ | ---------------------- |
| `search_after_ctx` | string | 游标索引，不设置时从第一页开始        |
| `limit`            | number | 页内数目，最大值不超过 100，默认为 20 |

### 响应参数

| 参数                 | 类型      | 描述                |
| ------------------ | ------- | ----------------- |
| `total`            | number  | 当前条件下匹配到总条目数量     |
| `has_next_page`    | boolean | 当前条件下是否有下一页数据     |
| `search_after_ctx` | string  | 下一页游标地址，仅当存在下页时返回 |

### 示例

<Tabs>
  <Tab title="请求示例">
    ```json theme={null}
    {
      "search_after_ctx": "658bcbae6ab5a67b3b800230",
      "limit": 20
    }
    ```
  </Tab>

  <Tab title="响应示例">
    ```json theme={null}
    {
      "total": 1000,
      "has_next_page": true,
      "search_after_ctx": "658ba7f9566077d6090e8d51"
    }
    ```
  </Tab>
</Tabs>

***

## 关于 TOTAL

***

无论使用哪种分页技术，Flashduty 都会给您返回 `total` 和 `has_next_page` 参数。但是，请注意，`total` 值并不始终准确，为了保证系统可以快速响应，我们增加了以下限制：

<Warning>
  * 当匹配数据总量小于 1000 时，`total` 值为精确值
  * 当匹配数据总量大于等于 1000 时，`total` 值恒为 1000，此时仅代表系统匹配到 1000+ 数据
</Warning>

<Tip>
  请您通过 `has_next_page` 来判断是否存在下一页数据，而不是 `total`。
</Tip>