SuperAPI AI 工具集

pagination-filtering

编程与开发

查看项目

更新于 10-16 09:31

技能介绍

用途:为列表接口设计统一的分页、筛选、排序、搜索与字段选择规范,适用于所有列表 API、大数据量查询、复杂筛选和全文搜索场景。

主要能力: 分页提供三种方式。Offset 分页用 page/page_size 或 offset/limit,响应含 page、page_size、total、total_pages,适合数据量小(<10 万)、需跳页、需 total 的场景,不适合大数据量或高并发更新。Cursor 分页用 cursor+limit,响应含 next_cursor、has_more,适合大数据量、无穷滚动、实时数据流、性能要求高、数据频繁更新,不适合跳页或精确 total;实现上 cursor 通常是排序字段值,如 WHERE id > cursor ORDER BY id LIMIT 20。Time-based 分页用 since/until,适合日志、事件流、时间相关数据。选择决策:后台管理/小数据用 offset,公开 API/大数据/信息流用 cursor,日志/事件用 time-based。

筛选支持基础单值、多值(逗号或重复参数)、范围(price_min/price_max、created_after/created_before)以及操作符(eq、ne、gt、gte、lt、lte、in、nin、like)。全文搜索用 q/keyword/search,搜索范围通常服务端定义。排序用 sort=created_at 升序、sort=-created_at 降序、sort=-priority,name 多字段,或用 sort_by+order。字段选择用 fields 指定返回字段、include 返回嵌套关联。

使用方式:按工作流程评估数据量与查询场景,选择分页方式,列出可筛选字段、支持的操作符、可排序字段与默认排序,决定是否支持搜索与字段选择,写入 OpenAPI 参数定义并输出列表接口规范。配套模板为 templates/pagination-filter-sort-template.md。

限制与注意:全 API 应统一分页方式,page_size 需设上限(如 max 100),排序字段需限制以防暴露敏感字段,筛选参数需校验防注入,搜索 q 需最小长度,列表响应需有 total 或 has_more,大数据集用 cursor 而非 offset,默认排序需明确。常见坑包括不同端点分页风格不一致、深分页 OFFSET 慢、响应格式不统一等。具体实现细节与代码示例以资料为准,未提供的部分暂未说明。