场景案例二：新增列表分页

第 11 章 · 场景案例二：新增列表分页

本章目标：跟练 在已有列表接口上加分页——Ask 定契约 → 后端 SRX → 审阅 →（可选）前端 SRX → 审阅 → 验收 commit；控制 前后端分卡；处理 多路径建议 / 影响面清单。

学时建议：3.5～4 小时（含 2 小时实操）

前置：srx-v7 ch10（500 修复流程）；ch07 契约优先；ch11 绝学：后端与前端分两张任务卡。

11.1 场景背景

项目	内容
需求	`GET /api/orders/` 支持 `?page=1&page_size=20`
现状	一次返回全部数据，大数据量慢
涉及	后端 handler/views + 可能 serializer；前端列表页（若有）
约束	不传 page 时行为与现网兼容（默认第 1 页）
团队习惯	契约优先（ch07）

与 ch10 区别：ch10 是 修 bug；本章是 新功能，要先 Ask 对齐 JSON 契约 再改代码。

11.2 学完你能

能力	验收
采样	记录当前 JSON 结构
Ask	定 page/total 字段与兼容策略
后端 SRX	四要素 + 默认值 + 上限
分卡	后端与前端分任务
审阅	查参数校验、误改 settings
验收	5 项 checklist 全过

11.3 开工准备（10 分钟）

git checkout main && git pull    # 若用 GitHub（git-collab ch08）
git checkout -b feature/order-pagination

项目 → 打开项目 确认仓库根
浏览器或 Postman 请求当前 GET /api/orders/，复制一段真实 JSON

你应该看到：当前无 page/total 或结构较 flat——记下来写进 Ask。

11.4 第一轮：Ask 对齐方案（不改盘）

Ask 输入：

需要在订单列表 GET /api/orders/ 增加分页 page、page_size。
当前返回 JSON 样例：
（粘贴真实响应，脱敏即可）

请说明：
1. 建议改哪些文件
2. 响应是否增加 total、page、page_size 等字段，命名建议
3. 不传 page 时如何保持与现网兼容
4. page_size 上限建议

只讨论方案，不改代码。

您要确认：

字段名与团队/OpenAPI 一致
默认 page=1、page_size=20、上限 100（可调整）
再进入 SRX

你应该看到：文件清单 + JSON 结构建议；无审阅条。

11.5 第二轮：SRX 改后端（任务卡 B1）

新任务 + SRX-V7引擎

【目标】订单列表接口支持 page、page_size 分页
【范围】
  - @handlers/order.go（或 apps/order/views.py，按项目改）
  - @handlers/order_test.go（若有，同步改测试）
  - 不改 migrations、不改 URL 路径、不改 settings
【约束】
  - page 默认 1，page_size 默认 20，上限 100
  - 响应增加 total、page、page_size（与 Ask 方案一致）
  - 不新增第三方依赖
  - 若出现【多路径建议】，按「契约优先」：先定响应 JSON 再改查询
【验收】
  - ?page=1&page_size=10 只返回 10 条且 total 正确
  - 不传参数时等价 page=1
  - go test / pytest 相关用例通过

执行中：

影响面清单 提到前端 → 记下，本节不改（ch05）
改 settings → Ctrl+Enter 纠正

审阅三看（ch09 绝学 12）：

文件	看什么
handler/views	offset/limit 或 slice 是否正确
test	是否覆盖默认参数与上限
其它	一律 ✗