API 版本管理、分页、筛选、排序与接口文档
🎯 引言
学完这篇文章,你能为列表接口约定分页、筛选和排序参数,并写出前端可以直接使用的接口说明。
🏷 什么时候需要新版本
假设前端一直读取 name,你把它直接改成 displayName,旧页面就会显示不出名字。这种修改会影响已有调用者,可以保留 /api/v1/users,在 /api/v2/users 返回新字段。
只增加一个不影响旧页面的字段,通常不必建立新版本。版本号用于区分不兼容的行为,修改前先看旧客户端是否还能正常使用。
📄 分页让客户端分次读取列表
假设数据库按 ID 排列了 5 个用户。请求第二页,每页两条:
GET /users?page=2&pageSize=2 HTTP/1.1
服务端应跳过前两条,返回用户 3 和 4。跳过的数量叫 offset,计算方式是:
const offset = (2 - 1) * 2;
得到 2。第一项是页码,第二项是每页条数。接收参数时应检查它们是正整数,并为 pageSize 设上限,例如不超过 100;具体字段校验沿用参数校验篇。
在数据库查询中使用分页
下面的函数接收 mysql2 连接,以及已经校验的数字 page、pageSize:
export async function readUserPage(connection, page, pageSize) {
const offset = (page - 1) * pageSize;
const [rows] = await connection.query(
'SELECT id, username FROM user ORDER BY id LIMIT ? OFFSET ?',
[pageSize, offset]
);
return rows;
}
LIMIT 控制返回数量,OFFSET 控制跳过数量,ORDER BY id 保持排序明确。传入 2、2 时读取第二组两条记录。不要先查出全部用户,再在 Node.js 内存中截取一页。
🔎 筛选只返回符合条件的记录
请求名字包含“明”的用户:
GET /users?name=明&page=1&pageSize=10 HTTP/1.1
接口文档要明确 name 是“完全相同”还是“包含”。这里约定包含,服务端先筛选符合条件的记录,再排序和分页;否则先取十条再筛选,可能漏掉其他页中的匹配用户。
客户端的名字值通过数据库参数传入,不能直接拼成 SQL。沿用 MySQL 接入课程 的参数查询方式。
↕️ 排序只开放明确支持的选项
例如约定两个选项:
| 参数 | 服务端执行的排序 |
|---|---|
| sort=-createdAt | 创建时间从新到旧,同一时间再按 ID 倒序 |
| sort=name | 名字升序,同名时再按 ID 升序 |
前面的负号是这个接口约定的“倒序”标记。客户端发送其他值时返回 400,不把任意 sort 文本直接写进 SQL。
追加 ID 用于处理相同名字或时间,避免这些记录每次请求时顺序不确定。创建时间排序要求数据表具有对应的创建时间字段。
📤 返回数据和分页信息
查询前面 5 个用户中的第二页,可以约定返回:
{
"data": [{ "id": 3, "name": "小林" }, { "id": 4, "name": "小雨" }],
"meta": { "page": 2, "pageSize": 2, "total": 5 }
}
data 是当前页的数据;meta 描述页码、每页条数和符合筛选条件的总条数。前端用 total 和 pageSize 计算页数,此时共三页。total 需要对同样的筛选条件另行计数,不是当前数组长度。
没有匹配记录时,仍返回 200,data 为 []、total 为 0。列表为空是正常结果。
📝 把接口约定写到同一份文档
文档至少列出调用方实际需要的信息:
| 项目 | 本例约定 |
|---|---|
| 方法与路径 | GET /users |
| 身份要求 | 需要有效登录凭据 |
| page | 默认 1,正整数 |
| pageSize | 默认 10,范围 1 到 100 |
| name | 可选,按名字包含关系筛选 |
| sort | 默认 -createdAt,也允许 name |
| 成功 | 200,正文含 data 和 meta |
| 参数错误 | 400,提示哪个参数不符合要求 |
| 身份或权限错误 | 401 或 403 |
文档中的默认值、字段和示例要与代码一起更新。不要只贴成功 JSON,让前端猜测必填项和失败行为。
❓ 知识问答
Q1:每个列表都必须返回 total 吗?
不必须。如果只需要“加载更多”,可以约定返回是否还有下一页,双方明确使用方式即可。
Q2:翻页期间有人新增或删除数据会怎样?
记录的位置可能变化,按页码翻页时可能重复或漏看个别记录。持续变化的信息流需要另行设计稳定的翻页规则。
Q3:新版本上线就可以删除旧版本吗?
先确认调用方已迁移,再按约定结束旧版本支持。
🧪 小练习
为头像列表写一份接口说明,给出第二页请求、成功响应、空结果以及非法排序时的结果。
// 请在这里记录接口约定
