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() 之前，全局或按需设置封装键名：

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

// 示例：将所有集合响应包裹在 '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&#160;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 自有分页全貌。