tboss_oa_module/docs/dingtalk/server/数据分页.md

数据分页

更新于 2026-05-09DingTalk OpenAPI 支持两种分页方式，不同接口可能采用不同的分页机制。开发者应根据具体 API 的文档说明及业务场景选择合适的分页模式，以提升数据获取效率、降低服务端压力并保障系统稳定性。

适用对象与权限说明

本文档适用于以下类型的应用：

• 企业内部应用：由企业自主开发并仅供本企业使用的应用。

• 第三方企业应用：由ISV（独立软件开发商）开发，供多个企业安装使用的应用。

• 第三方个人应用：产品方案商开发者开发，提供给钉钉上个人用户使用的应用。

权限说明

调用任何 DingTalk OpenAPI 前，需确保应用已具备相应接口的调用权限。

请在钉钉开放平台控制台中完成以下操作：

1. 进入目标应用详情页。

2. 点击 基础信息 > 凭证与基础信息。

3. 在“权限管理”模块中添加所需 API 权限（如“读取通讯录”、“获取日程列表”等）。

参考文档：如何申请API权限

认证前置条件

所有接口调用前必须获取有效的 access_token，用于身份认证和权限校验。

• 使用 AppKey / AppSecret 或 Client ID / Client Secret 获取 access_token。

• access_token 有效期通常为 7200 秒，建议缓存并定期刷新。

• 错误的或过期的 access_token 将导致接口返回 40001 或 40014 错误码。

参考文档：如何调用API

方式一：nextToken方式

通过 nextToken 设置查询凭证实现连续数据读取。首次请求无需传入nextToken，后续请求需将上次接口响应中的nextToken值复制到本次请求中，即可继续获取后续数据。

请求流程说明

• 首次请求无需传入 nextToken，服务端将返回第一批数据及一个 nextToken 值。

• 后续请求需将上一次响应中的 nextToken 值填入查询参数中，用于获取下一页数据。

• 当响应中不再返回 nextToken 时，表示已读取全部数据。

例如：GET /v1.0/edu/grades/{identifier}/classes?nextToken=bGFzdD0xMTExMExMSZdGhlcnBhcmFtPXh4eCYuLi4u&maxResults=20

关键术语说明

• **nextToken**：服务端生成的不透明字符串凭证，标识当前查询的上下文位置，客户端仅需透传，不可解析或修改。

• **maxResults**：客户端建议的最大返回条目数，非精确值；实际返回数量可能小于该值，受服务端限制或剩余数据量影响。

说明

• maxResults 参数用于限制单次返回的最大记录数，建议不要超过500以避免响应延迟。

• 深度翻页可能导致性能下降，建议结合时间窗口过滤条件减少数据量。

推荐使用场景

• 数据同步任务（如通讯录同步、日志拉取）

• 大数据集导出

• 对数据完整性要求高的场景

方式二：pageSize方式

采用传统分页逻辑，适用于前端列表展示类接口（如用户列表、部门列表、审批单据等）。通过页码和每页大小控制数据分段加载。

请求流程说明

• 首次请求设置 pageNumber=1，pageSize 指定每页记录数。

• 每次请求递增 pageNumber，直至返回数据量小于 pageSize，通常表示已达末页。

说明

• 首次调用从pageNumber=1开始，逐页递增。

• 该方式不适合高频拉取大量数据的场景，可能影响服务端性能。

关键术语说明

• **pageNumber**：当前请求的页码，从 1 开始计数。

• **pageSize**：每页返回的数据条目数量，建议范围为 10～200。

推荐使用场景

• 前端分页控件集成（如表格分页）

• 小规模静态数据展示

• 用户主动触发的按页浏览操作

推荐选型与最佳实践

维度	nextToken 方式	pageSize 方式
数据一致性	高（基于游标）	中（基于偏移，易受写入影响）
适用数据量	大数据集（万级以上）	小到中等数据集（千级以内）
网络开销	较低（可设较大 maxResults）	中等（受限于推荐 pageSize 上限）
实现复杂度	中（需维护 token 状态）	低（简单递增页码）
典型场景	后台同步、数据迁移	前端展示、交互式查询

选型建议

• 增量同步类接口（如事件订阅拉取、变更日志获取）：优先使用 nextToken 方式，保证数据不重复、不遗漏。

• 列表展示类接口（如员工列表、审批单列表）：可使用 pageSize 方式，便于与前端分页组件对接。

最佳实践总结

• 增量同步类接口，推荐使用 方式一：nextToken 方式，保证数据不重复、不遗漏。

• 列表展示类接口可使用 方式二：pageSize方式，便于前端分页控件集成。

• 建议在客户端实现自动重试机制：若因nextToken失效导致失败，应回退至首次请求重新拉取。

• 避免过大的maxResults或pageSize，推荐值为10~200，兼顾网络传输效率与响应速度。