PHP分页JSON输出教程

本文深入讲解了如何在PHP中构建规范、安全且健壮的分页JSON API，强调分页的核心不在于前端交互逻辑，而在于后端是否完整、准确地将总记录数、当前页码、每页数量、总页数、前后页状态等关键元信息通过结构化JSON（含data和meta字段）可靠传递给前端；同时系统梳理了参数校验（如page/limit的类型转换、范围限制与过滤）、SQL查询优化（COUNT(*)与LIMIT+OFFSET双查、预处理防注入）、边界情况处理（totalCount为0、越界页码、空响应）及响应细节（Content-Type设置、中文编码、HTTP状态码提示），帮助开发者避开线上常见陷阱，打造真正可信赖的分页接口。

PHP分页本身不关心输出格式，关键是你在组装响应数据时是否把分页元信息（总条数、当前页、每页数、页码列表等）一并塞进 JSON，而不是只返回 $data 数组。

分页参数怎么从 URL 安全读取

别直接用 $_GET['page'] 或 $_GET['limit']，必须过滤和校验：

• page 应转为整型，且不能小于 1；max($page, 1) 是底线，但建议再加范围限制（如最大 1000 页）
• limit 同样要转整型，并硬性限制可选值（如只允许 10/20/50/100），避免用户传 ?limit=999999 拖垮数据库
• 用 filter_input(INPUT_GET, 'page', FILTER_SANITIZE_NUMBER_INT) 更稳妥，但注意它会把空字符串转成 0，得额外判空

SQL 查询要带 LIMIT + OFFSET，别漏 COUNT(*)

JSON API 的分页不是靠前端“加载更多”，而是后端真实分段查库。必须做两件事：

• 先执行一次 COUNT(*) 获取总记录数（注意 WHERE 条件要完全一致）
• 再用 LIMIT :limit OFFSET :offset 查当前页数据（OFFSET = ($page - 1) * $limit）
• 如果用 PDO，务必用预处理防止 SQL 注入；若用 MySQLi，也得用 bind_param

示例片段：

$total = $pdo->prepare("SELECT COUNT(*) FROM users WHERE status = ?");
$total->execute([$status]);
$totalCount = (int)$total->fetchColumn();
<p>$offset = ($page - 1) * $limit;
$stmt = $pdo->prepare("SELECT id, name, email FROM users WHERE status = ? ORDER BY id DESC LIMIT ? OFFSET ?");
$stmt->execute([$status, $limit, $offset]);
$data = $stmt->fetchAll(PDO::FETCH_ASSOC);
</p>

JSON 响应结构要包含分页元数据

只返回 ["a","b","c"] 是不合格的 API。标准做法是包裹一层对象，含 data 和 meta：

• meta.total：总记录数（来自 COUNT）
• meta.page：当前页（即输入的 page）
• meta.limit：每页条数（即输入的 limit，或服务端默认值）
• meta.last_page：总页数（ceil($totalCount / $limit)）
• meta.has_next / has_prev 可选，布尔值，方便前端控制按钮显隐

最终输出：

header('Content-Type: application/json; charset=utf-8');
echo json_encode([
  'data' => $data,
  'meta' => [
    'total' => $totalCount,
    'page' => $page,
    'limit' => $limit,
    'last_page' => (int)ceil($totalCount / $limit),
    'has_next' => $page  $page > 1,
  ]
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

容易被忽略的边界情况

线上出问题往往不在主流程，而在这些地方：

• 当 $totalCount === 0 时，last_page 会是 0，ceil(0 / $limit) 是 0，但页码应从 1 开始，需单独处理为 1 或空数组
• OFFSET 超过实际总数时，MySQL 不报错但返回空数组，此时 page 参数已越界，建议返回 404 或在 meta 中标出 is_out_of_range => true
• 没设 Content-Type: application/json，某些前端框架（如 Axios）可能解析失败
• 中文字段用 json_encode 默认会转 Unicode（\u4f60\u597d），加 JSON_UNESCAPED_UNICODE 才能保持可读

分页 JSON API 的核心不是“怎么分”，而是“怎么让前端能可靠地翻页”——这取决于你有没有把总数、边界、当前状态都诚实告诉对方。

今天关于《PHP分页JSON输出教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！