构建 RFC 8288 分页 Link 响应头

功能说明

分页 API 常用 Link 响应头告知客户端前后页地址。该函数根据当前页、每页数量和总数生成 RFC 8288 格式的 self、first、prev、next、last 链接，并保留基础地址中的原有查询参数。它适合 REST 接口、开放数据平台和需要无额外响应体的分页场景。

关键代码

先校验 page、perPage、total 的整数与范围，计算 lastPage 并拒绝超出末页的请求。使用 URL 复制基础地址，为每个关系设置 page 与 limit 参数。仅在存在上一页或下一页时添加对应链接，最后用逗号连接所有关系。

const targetUrl = new URL(url);
targetUrl.searchParams.set("page", String(target));
targetUrl.searchParams.set("limit", String(perPage));
return "<" + targetUrl.toString() + '>; rel="' + rel + '"';

使用注意

该函数假设分页参数名为 page 与 limit，其他命名需修改实现。total 为 0 时 lastPage 取 1，仍会生成链接。基础地址已有的 page 与 limit 会被覆盖，其他查询参数保留。链接字符串包含尖括号与引号，写入响应头前应由框架处理编码。

验证方式

断言第 2 页共 5 页时包含 self、first、prev、next、last 五个关系。第 1 页不含 prev，末页不含 next。page 超出末页抛 RangeError，非整数参数抛 RangeError。基础地址中的筛选参数应保留，total 为 0 时仍能生成有效头部。