1. 理解 Laravel API 的分页机制
在 API 场景下，分页是一项基本机制，用于控制单次响应的数据量，减少带宽消耗并提升前端渲染效率。通过在请求中携带page与per_page等参数，服务端据此筛选数据并返回与分页相关的元信息。LengthAwarePaginator和Pagination相关对象在 Laravel 内部负责构建这样的结构，便于前端逐页获取数据。
常见的分页模式有两种：页码分页和简单分页。页码分页通常包含total、links 等信息，便于用户跳转到任意页；简单分页则以下一页链接为主，开销更低，适用于数据量极大的场景。理解这两种模式，有助于在 API 设计中做出合适的取舍。
1-1 需求场景分析
对于需要向客户端提供可筛选、可翻页的数据接口时，可配置的页容量是关键点。通过将per_page设为可自定义的查询参数，前端可以控制每页显示的记录数量，而服务器端通过paginate或cursorPaginate来按需加载。
此外，推荐在返回的 JSON 结构中包含data、links与meta字段，便于前端直接读取当前页数据、下一页/上一页链接以及分页统计信息。
2. 实操：路由与控制器实现分页
2-1 路由与控制器的基本写法
在 Laravel 的 API 项目中，先定义路由，再在控制器中实现分页逻辑。通过读取请求中的per_page，实现对分页容量的动态控制，同时使用paginate生成分页对象并返回资源集合。路由与控制器是实现分页的基础链路。
// 路由（routes/api.php）
Route::get('/api/users', [App\\Http\\Controllers\\UserController::class, 'index']);// 控制器（app/Http/Controllers/UserController.php）
namespace App\\Http\\Controllers;use Illuminate\\Http\\Request;
use App\\Models\\User;
use App\\Http\\Resources\\UserResource;class UserController extends Controller
{public function index(Request $request){// 读取前端传来的 per_page，默认 15，最大限制 100$perPage = (int) $request->query('per_page', 15);$perPage = max(1, min($perPage, 100));// 获取分页数据，并返回资源集合（包含分页信息）$users = User::query()->paginate($perPage);return UserResource::collection($users);}
}
2-2 使用 API Resource 输出分页数据
在 Laravel 中，结合 API Resource（资源）输出分页数据，可以让前端更加方便地读取分页结构。Resource会将数据统一封装，同时保留分页的 links 与 meta 字段，便于前端处理下一页、上一页等链接。
// 使用资源集合返回分页数据
use App\\Http\\Resources\\UserResource;$users = User::paginate($perPage);
return UserResource::collection($users);
注意：如果需要对分页集合进行定制，可以新建一个自定义的 ResourceCollection，并在其中控制输出结构，同时保持分页链接的完整性。
3. 自定义分页参数与链接保留策略
3-1 per_page、page 的正确使用与边界处理
为了实现灵活的分页控制，需要在控制器中对per_page进行校验并设定合理的默认值。通常的做法是读取 per_page，再通过 paginate 指定页容量。同时建议对边界进行限制，避免极端值影响性能。
示例要点：对请求参数进行强类型转换、限制最大值、保留必要的查询参数。这样的处理能确保 API 的稳定性与可预测性。
$perPage = (int) $request->query('per_page', 15);
$perPage = max(1, min($perPage, 100)); // 限制在 1-100 之间
$users = User::paginate($perPage);
3-2 保留前端筛选条件以形成稳定的分页链接
常见场景是前端在筛选条件改变时，仍希望分页链接保留当前筛选条件。为此，可以在分页对象上调用 appends 或使用 withPath 保留路径，确保链接中的参数完整。
$users = User::query()->when($request->has('role'), function($q) use ($request) {$q->where('role', $request->input('role'));})->paginate($perPage)->appends($request->except('page')); // 保留其他查询参数
// 或者直接： ->withPath('/api/users')
4. API 资源结构与分页数据
4-1 常见的 JSON 结构与含义
当使用 Laravel 的分页对象输出 API Resource 时，响应体通常包含 data、links 与 meta 三个键。data 存放当前页的数据集，links 提供下一页、上一页等跳转链接，meta 包含总条数、当前页、每页条数等统计信息。这些字段对于前端实现自定义分页组件非常有帮助。
在一些场景中，你还可以自定义 ResourceCollection 的 toArray 输出，以更精准地控制分页结构，同时仍保留原生分页链接。
4-2 前端如何读取分页链接与数据
前端在收到分页 JSON 后，可以直接解析 data、links 与 meta，从而实现遍历当前页数据、渲染跳转按钮、以及展示总数与页码信息。以下为前端样例取值逻辑，帮助快速对接：
fetch('/api/users?per_page=10').then(res => res.json()).then(json => {const items = json.data; // 当前页数据const next = json.links.next; // 下一页链接const prev = json.links.prev; // 上一页链接const total = json.meta.total; // 总条数});
5. 前端对接分页链接的最佳实践
5-1 请求参数设计与一致性
前端应统一使用 per_page 与 page 作为分页控制参数，且在发起请求时保持参数名的一致性，以确保后端分页逻辑的正确解析。对筛选参数也要统一放在查询字符串中，以确保分页链接的可重复使用性。
同时，使用 cursor pagination（游标分页）也是一个可选方案，尤其在数据量很大、且排序字段稳定时，可以通过 cursorPaginate 实现高效分页，避免了对整表进行 offset 计数的开销。
5-2 兼容性与前端组件的对接
若前端框架或组件库需要固定结构，可以在 API 层通过 ResourceCollection 自定义输出版式，例如为前端提供固定字段名的分页对象，以减少耦合与解析成本。
// 前端读取的字段结构示例（若自定义）
return response()->json(['data' => $users->items(),'links' => ['self' => $request->fullUrl(),'next' => $users->nextPageUrl(),],'meta' => ['current_page' => $users->currentPage(),'from' => $users->firstItem(),'to' => $users->lastItem(),'total' => $users->total(),],
]);
6. 常见问题解答
问题 1：如何自定义分页链接的路径
在 Laravel 中，可以通过调用 withPath 设置分页基础路径，或使用 appends 保留查询参数，从而确保分页链接的稳定性和可重复性。实现要点：使用 ->withPath('/api/users') 或在分页对象上调用 ->appends(request()->except('page'))。
$users = User::paginate($perPage);
$users->withPath('/api/users');
$users->appends(request()->except('page'));
问题 2：如何处理前端对分页参数的兼容性
建议将前端分页参数通过查询字符串传递，并在后端对其进行校验与规范化，例如：
$perPage = (int) $request->query('per_page', 15);
$perPage = max(1, min($perPage, 100));
$users = User::paginate($perPage)->appends($request->query());
问题 3：使用 simplePaginate 时该如何返回分页结构
若对性能要求极高且不需要总数信息，可以使用 simplePaginate；它仅提供下一页链接，减少查询成本，示例：
$perPage = 20;
$users = User::orderBy('id')->simplePaginate($perPage);
return UserResource::collection($users);
问题 4：如何在大型数据集保持分页性能
对超大数据集，考虑使用游标分页（cursor pagination）以避免对整表进行偏移计算带来的开销。示例使用 cursorPaginate：
$perPage = 50;
$users = User::orderBy('id')->cursorPaginate($perPage);
return UserResource::collection($users);
要点：游标分页需要有稳定的排序字段，且对前端实现有一些额外的参数处理工作，但在百万级数据量的场景下，可以显著提升查询性能与响应速度。
