# 数据分页

![AI 智能摘要](https://gw.alicdn.com/imgextra/i4/O1CN01Zx4PED22rkUkmRe1L_!!6000000007174-2-tps-226-40.png)![>](https://gw.alicdn.com/imgextra/i2/O1CN01UwOv1C27lrTuGFj2D_!!6000000007838-2-tps-17-30.png)

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

## 适用对象与权限说明

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

-   **企业内部应用**：由企业自主开发并仅供本企业使用的应用。
    
-   **第三方企业应用**：由ISV（独立软件开发商）开发，供多个企业安装使用的应用。
    
-   **第三方个人应用**：产品方案商开发者开发，提供给钉钉上个人用户使用的应用。
    

### 权限说明

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

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

1.  进入目标应用详情页。
    
2.  点击 **基础信息 > 凭证与基础信息**。
    
3.  在“权限管理”模块中添加所需 API 权限（如“读取通讯录”、“获取日程列表”等）。
    

参考文档：[如何申请API权限](https://open.dingtalk.com/document/development/add-api-permission)

### 认证前置条件

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

-   使用 **AppKey / AppSecret** 或 **Client ID / Client Secret** 获取 `access_token`。
    
-   `access_token` 有效期通常为 7200 秒，建议缓存并定期刷新。
    
-   错误的或过期的 `access_token` 将导致接口返回 `40001` 或 `40014` 错误码。
    

参考文档：[如何调用API](https://open.dingtalk.com/document/development/how-to-call-apis)

## **方式一：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，兼顾网络传输效率与响应速度。