php分页需符合rest原则：用limit/offset等语义化query参数，响应体含分页元信息（total、next、prev等完整url），推荐补充x-total-count和link头；避免深度offset，优先游标分页。
PHP 分页本身和 RESTful API 没有绑定关系，关键在于「如何让 API 的分页行为符合 REST 原则」——即用标准 HTTP 方法、状态码、响应头和可预测的 URL 结构，而不是把 page=2 当作业务逻辑硬塞进接口里。
URL 设计：用 query 参数，但要语义清晰
RESTful 不禁止 query 参数，反对的是把分页逻辑藏在 path 里（比如 /users/page/2）。正确做法是统一用 limit 和 offset 或 page + per_page，且保持参数名稳定：
-
limit表示单页最多返回几条（推荐，比per_page更通用） -
offset表示跳过前 N 条（适合数据库LIMIT offset, limit） - 避免混用：
page=2&per_page=10要自己算offset = (page - 1) * per_page，容易出错 - 必须做参数校验：
limit不能为负、不能超过 100；offset不能为负
响应体里必须带分页元信息
客户端不能靠猜来翻页。PHP 接口返回的 JSON 必须包含分页上下文，例如：
{
"data": [...],
"meta": {
"total": 127,
"limit": 20,
"offset": 40,
"next": "/api/users?limit=20&offset=60",
"prev": "/api/users?limit=20&offset=20",
"first": "/api/users?limit=20&offset=0",
"last": "/api/users?limit=20&offset=120"
}
}注意：next/prev 是完整 URL，不是相对路径；last 的 offset 要基于 total 算准（floor((total - 1) / limit) * limit），否则可能越界。
立即学习“PHP免费学习笔记（深入）”；
用 HTTP 头补充分页线索（可选但推荐）
除了响应体，还可以用标准 HTTP 头辅助客户端理解分页状态：
-
X-Total-Count: 127—— 总数，方便前端做分页控件 -
Link: /users?limit=20&offset=0>; rel="first", /users?limit=20&offset=60>; rel="next"—— RFC 5988 标准格式，curl 和某些 HTTP 客户端能自动识别 - 不要在 header 里传
data，只传控制信息；body 才放实际数据
性能陷阱：offset 深度分页会变慢
MySQL 中 LIMIT 100000, 20 实际要扫描前 100020 行，越往后越慢。真实项目中应避免纯 offset 方案：
- 用游标分页（cursor-based）：基于上一页最后一条记录的
id或created_at做条件，如WHERE id > 12345 ORDER BY id LIMIT 20 - 游标方式无法跳转任意页，但适合“下一页/上一页”场景，性能稳定
- 如果必须支持跳页（比如输入页码），考虑缓存总数和页码映射，或限制最大可访问页码（如
offset ）
分页真正难的不是写 limit 和 offset，而是让每个环节都对齐客户端预期：URL 可预测、响应可解析、性能不崩、错误可感知。漏掉 Link 头或返回空 next 却不设 null，都可能让前端反复请求无效地址。
