Pwoli.js 分页配置详解与实现方法

Pwoli.js 默认返回扁平化数据数组，缺乏分页元信息，难以支撑前端复杂的分页交互；本文详解如何通过简洁配置启用“集合信封”（collection envelope）机制——只需一行代码设置 `Pwoli.serializer.collectionEnvelope = 'companies'`，即可自动将数据封装进指定键，并在统一的 `pagination` 对象中注入 `current_page`、`total_count`、`total_pages` 等标准化分页字段，无需改动业务逻辑或手动计算，真正实现开箱即用、结构清晰、前后端协同高效的分页体验。

在 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，确保响应结构一致性。

通过这一配置，你即可在不修改业务逻辑的前提下，快速获得生产就绪的分页能力——数据与元信息解耦清晰、结构可预测、前端消费零成本。

本篇关于《Pwoli.js 分页配置详解与实现方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！