集合接口的查询能力
集合接口通常要支持三类查询参数：过滤条件（哪些记录）、排序字段（按什么顺序）和字段选择（返回哪些字段）。这三类能力一旦开放给调用方，就等于把一部分查询能力暴露出去，因此每个参数都必须白名单化、限制复杂度，并明确默认值与上限。设计目标是让调用方能表达常见筛选需求，同时不给数据库和搜索引擎制造昂贵查询与注入面。
基本信息
| 过滤 | ?status=paid&created_after=2026-01-01，字段白名单 |
|---|---|
| 排序 | ?sort=-created_at，前缀减号表示倒序 |
| 字段裁剪 | ?fields=id,status 减少载荷与耦合 |
| 分页 | 游标分页比偏移分页更适合深分页与实时数据 |
典型使用场景
- 后台管理列表：按状态、时间区间、负责人筛选并排序
- 对账与导出：按条件拉取明细，字段裁剪降低传输量
- 移动端列表：只取渲染需要的字段，减少载荷与解析开销
- 第三方开放接口：对外提供受限的查询能力，避免暴露内部字段
- 数据同步：按更新时间增量拉取，配合游标推进
接口与实现要点
接口与实现要点
GET /v1/orders?status=paid&created_after=2026-01-01&sort=-created_at&fields=id,status,total&limit=50
实现侧：
- status 走枚举白名单校验，非法值直接 400
- created_after 走时间格式校验，不接受任意表达式
- sort 字段与方向都走白名单，禁止按未索引字段排序
- fields 只允许出现在公开字段清单里
# 每个过滤字段都应对应一个可用索引，否则列表页会成为慢查询来源参数风险与对策
| 参数 | 常见风险 | 对策 |
|---|---|---|
| 过滤条件 | 组合出昂贵查询或无索引扫描 | 字段白名单 + 索引核对 + 组合数量上限 |
| 排序 | 排序字段无索引导致临时表与全表排序 | 排序字段白名单，单独维护索引 |
| 字段选择 | 裁剪字段暴露内部字段名与敏感数据 | 公开字段清单，敏感字段永不进入清单 |
| 分页参数 | 偏移分页在深页时扫过大量行 | 改用游标分页，限制单页大小上限 |
使用要点
- 过滤与排序字段走白名单映射，绝不把调用方输入直接拼进查询语句
- 参数上限定为显式数值：单页大小、时间跨度、过滤条件个数都要有上限
- 默认返回字段要克制：默认只返回稳定且公开的字段，其余按需请求
- 对外接口的查询能力与内部接口分开：内部可以更宽，对外必须收敛
- 为每个新增的过滤与排序字段补索引与压测验证，再放行到接口
参数直接拼接进 SQL 或转发给搜索引擎会造成注入与资源耗尽；必须走白名单与绑定参数，并把限制写在接口契约里而不是只靠代码评审。
过滤能力的设计要与数据模型同步演进：新增状态字段时同步更新白名单与索引，否则调用方会用“全量拉取再本地过滤”的方式绕过限制。