Flashcat API
关于分页
title: "关于分页"
description: "Flashduty 开放 API 分页介绍。"
date: "2024-11-20T10:00:00+08:00"
url: "https://developer.flashcat.cloud/zh/flashduty/open-api/about-pagination"
一般情况下，当我们拉取或检索某种数据对象时，都会基于分页将数据分批次返回，而不是在一个请求中返回所有数据。
传统分页
我们把基于 OFFSET 和 LIMIT 查询的分页技术定义为传统分页。在大多数 Flashduty 列表查询 API 中，您可以看到以下参数定义：
{
"p": 1, // 分页页码，默认从1开始。offset=(p-1)*limit
"limit": 20 // 页内数目，最大值不超过100，默认为20
}
同时在响应中，我们会返回以下参数：
{
"total": 1000, // 当前条件下匹配到总条目数量
"hax_next_page": 20 // 当前条件下是否有下一页数据
}
基于传统分页技术进行查询虽然简单，但可能会遇到以下一些问题：
1. 性能问题：使用 OFFSET 和 LIMIT 进行分页查询时，数据库需要跳过指定数量的行（OFFSET），然后返回指定数量的行（LIMIT）。随着偏移量的增加，查询的性能可能会下降，特别是在处理大量数据时。每次查询都需要扫描和跳过前面的行，这会导致查询变得越来越慢。
2. 数据不稳定性：当使用 PAGE 和 LIMIT 进行分页查询时，如果在查询期间删除或插入了数据，可能会导致结果不稳定。例如，如果在查询过程中删除了前面的行，那么后续的偏移量可能会失效，导致结果不准确或缺失。
为了保护系统，确保大多数用户可以稳定访问，我们针对基于传统分页技术查询的 API 参数做了以下限制：
:::caution
要求 PAGE * LIMIT <= 10000，如果超过10000，系统将直接返回400错误信息。这种情况下，请您转为使用游标分页，或缩小查询条件。
:::
游标分页
我们把基于 SEARCH_AFTER_CTX 分页的技术定义为游标分页。游标分页技术可以更好地处理大数据集和高性能要求，并提供更稳定和高效的分页查询体验。
在以上API种您可以看到参数定义：
{
"search_after_ctx": "658bcbae6ab5a67b3b800230", // 游标索引，不设置时，从第一页开始
"limit": 20 // 页内数目，最大值不超过100，默认为20
}
同时在响应中，我们会返回以下参数：
{
"total": 1000, // 当前条件下匹配到总条目数量
"hax_next_page": 20,// 当前条件下是否有下一页数据
"search_after_ctx": "658ba7f9566077d6090e8d51" // 下一页游标地址，仅当存在下页时返回
}
关于 TOTAL
无论使用哪种分页技术，Flashduty 都会给您返回 TOTAL 和 HAS_NEXT_PAGE 参数。但是，请注意，TOTAL 值并不始终准确，为了保证系统可以快速响应，我们增加了以下限制：
:::caution
当匹配数据总量小于1000时，total 值为精确值；
当匹配数据总量大于等于1000时，total 值恒为1000。此时仅代表系统匹配到1000+数据。
:::
综上，请您通过 has_next_page 来判断是否存在下一页数据，而不是 total。