在 Pwoli.js 中，API 默认返回纯数据数组，不包含分页元信息；通过启用集合信封（collection envelope）机制，可将数据包裹在指定键下，并自动注入 current_page、total_count、total_pages 等分页元数据到响应体中。
在 pwoli.js 中，api 默认返回纯数据数组，不包含分页元信息；通过启用集合信封（collection envelope）机制，可将数据包裹在指定键下，并自动注入 `current_page`、`total_count`、`total_pages` 等分页元数据到响应体中。
Pwoli.js 默认采用“扁平化” JSON 响应设计——即直接返回资源数组（如 [{ "id": 1, "title": "Company - 1" }, ...]），虽简洁但缺失分页上下文。若需在前端实现带页码跳转、总条数显示或禁用/启用「下一页」按钮等交互，必须让 API 同时返回数据 + 分页元信息（metadata）。
解决方案是启用 collection envelope（集合信封）功能。该机制会将原始数据数组封装进一个具名对象，并在同一层级注入标准化分页字段。配置方式极其简洁，只需在调用 Pwoli.respond(...) 前设置序列化器的 collectionEnvelope 属性：
// 在控制器逻辑中（例如 index action 内） Pwoli.serializer.collectionEnvelope = 'companies'; // 此后调用 respond 即生效 Pwoli.respond(companies); // ← companies 是查询得到的 Model 实例数组
配置生效后，API 响应结构将从：
[
{ "id": 1, "title": "Company - 1", "myGetter": "EVENT - 3" },
{ "id": 2, "title": "Company - 2", "myGetter": "EVENT - 5" }
]变为标准的带元数据封装格式：
{
"companies": [
{ "id": 1, "title": "Company - 1", "myGetter": "EVENT - 3" },
{ "id": 2, "title": "Company - 2", "myGetter": "EVENT - 5" }
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total_count": 47,
"total_pages": 3
}
}✅ 关键说明：
- collectionEnvelope = 'companies' 中的字符串 'companies' 即为数据主键名，建议与资源复数形式一致；
- 分页元信息统一挂载在顶层 pagination 对象下，字段命名语义清晰、符合 RESTful 惯例；
- 所有分页参数（如 page、per-page）由 Pwoli 自动从请求 Query 解析并应用，无需手动计算；
- 若需自定义 pagination 键名（如改为 meta），可通过继承并重写 Pwoli.serializer.getPaginationData() 方法实现。
? 最佳实践建议：
- 在 BaseController 中统一设置 Pwoli.serializer.collectionEnvelope，避免各 action 重复声明；
- 前端 Axios/Fetch 接收响应后，应优先校验 response.data.pagination 是否存在，再进行 UI 渲染；
- 若某接口无需分页（如获取单条详情），请在该 action 中临时清空信封：Pwoli.serializer.collectionEnvelope = null，确保响应结构一致性。
通过这一配置，你即可在不修改业务逻辑的前提下，快速获得生产就绪的分页能力——数据与元信息解耦清晰、结构可预测、前端消费零成本。
