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:

user-page.mjs
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:新版本上线就可以删除旧版本吗?

先确认调用方已迁移,再按约定结束旧版本支持。


🧪 小练习

为头像列表写一份接口说明,给出第二页请求、成功响应、空结果以及非法排序时的结果。

// 请在这里记录接口约定