Pwoli.js 默认返回纯数据数组，不包含分页信息；通过配置 collectionEnvelope 可启用响应封装，使分页元数据（如当前页、总条数、总页数等）随数据一同返回。
pwoli.js 中如何在 api 响应中获取分页元数据？pwoli.js 默认返回纯数据数组，不包含分页信息；通过配置 `collectionenvelope` 可启用响应封装，使分页元数据（如当前页、总条数、总页数等）随数据一同返回。
在使用 Pwoli.js 构建 RESTful API 时，分页是高频需求。但默认情况下，Pwoli.respond() 直接返回一个扁平的 JSON 数组（如示例中的公司列表），不携带任何分页上下文——这意味着前端无法得知 currentPage、totalCount、totalPages 或 pageSize 等关键信息，难以实现稳健的分页控件（如页码跳转、加载更多、总数显示等）。
解决方案是启用 响应封装（Response Envelope）：通过设置 Pwoli.serializer.collectionEnvelope，将原始数据包裹进一个结构化对象，并自动注入分页元数据到 meta 字段中。
✅ 正确配置方式
在调用 Pwoli.respond() 之前，全局或按需设置封装键名：
// 示例：将所有集合响应包裹在 'companies' 键下 Pwoli.serializer.collectionEnvelope = 'companies'; // 然后正常响应数据 Pwoli.respond(companies); // ← 此处 companies 是 QuerySet 或数组
? 封装后的响应结构（示例）
启用后，API 返回不再是裸数组，而是如下标准格式：
{
"companies": [
{
"id": 1,
"title": "Company - 1",
"status": 1,
"description": "Company = 1 description",
"phone": null,
"email": "<a class=\"__cf_email__\" data-cfemail=\"cfaaa2aea6a38faca0a2bfaea1b6fee1aca0a2\" href=\"/cdn-cgi/l/email-protection\">[email protected]</a>",
"website": "",
"eventId": 3,
"createdAt": null,
"updatedAt": null,
"myGetter": "EVENT - 3"
}
// ... 其他项
],
"meta": {
"currentPage": 1,
"pageSize": 20,
"totalCount": 142,
"totalPages": 8,
"hasNext": true,
"hasPrev": false
}
}✅ meta 字段由 Pwoli 自动计算并注入，基于当前请求的 page、per-page 参数及数据源总记录数。
⚠️ 注意事项
- collectionEnvelope 必须在 Pwoli.respond() 调用前设置，否则无效；
- 若需为不同接口使用不同 envelope 键（如 /users → 'users'，/orders → 'orders'），建议在控制器中动态设置，避免全局污染；
- 确保数据源（如 Sequelize 模型查询）已正确应用分页逻辑（例如通过 .paginate() 或 .limit().offset()），否则 meta.totalCount 可能不准确；
- 前端解析时需适配新结构：数据路径变为 response.companies，分页信息位于 response.meta；
- 如需自定义 meta 字段名（如改为 pagination），可通过扩展 Pwoli.serializer 实现，但非默认行为。
? 总结
启用 collectionEnvelope 是 Pwoli.js 实现标准化分页响应的核心机制。它以极小的配置成本，将隐式分页信息显式暴露于响应体中，显著提升前后端协作效率与前端分页体验。记住关键口诀：先设 envelope，再调 respond，meta 自有分页全貌。
