Visual LabINTERACTIVE LEARNING
知识库 概念
04 · BUSINESS BACKENDP012 MIN

API 分页、过滤与排序契约

把数据库查询能力包装成安全、稳定、可演进的公共接口。

MENTAL MODELQUERY API CONTRACT
01Parse Query
02Validate Whitelist
03Inject Data Scope
04Run Indexed Query
05Encode Cursor
API 查询参数是公开语言，不能等同 ORM 的任意 where；服务端必须控制复杂度、字段和租户范围。
01 · CONCEPTS & BOUNDARIES

先把概念与边界说清楚

定义告诉你它是什么，边界告诉你它不负责什么；企业系统最常见的误解通常发生在两者混用时。

01

Pagination Contract

统一 pageSize、cursor、hasNext、nextCursor 和总数是否可用。

02

Filter Whitelist

公开有限字段和操作符，并映射到内部查询。

03

Stable Sorting

指定默认排序并加入唯一 tie-breaker，让多页结果形成全序。

02 · BLIND BOTS CASE

高级搜索拖垮数据库

问题现场

客户端可传任意 contains 过滤和五列排序，一个租户发出全表模糊查询。

  1. 01

    公开业务需要的 filter DSL。

  2. 02

    限制组合、页大小和查询时间。

  3. 03

    为高成本报表改为异步导出。

得到什么

普通列表有确定性能边界，重查询进入可观测的后台任务。

03 · PRACTICE

马上动手

  1. 设计 GET /orders 查询参数。
  2. 决定何时返回 exact total、estimated total 或不返回。
04 · PITFALLS

常见坑

  • 把 ORM where 暴露给客户端
  • 排序字段无白名单
  • 过滤前忘记注入 tenant scope
05 · KNOWLEDGE CHECK为什么 Data Scope 应在解析用户过滤后由服务端注入？查看答案⌄
答案

用户过滤是可选查询条件，租户/数据范围是不可取消的安全边界；必须由服务端独立合并，不能允许客户端覆盖。