分页

SDK 提供了通用的分页器工具，可用于任何返回分页结果的端点。各方法返回原始响应；你可以将其包装为分页器。

​

基础分页

quick-start.ts

Typescript

import { Client, UserPaginator, PaginatedResponse, Schemas } from '@xdevplatform/xdk';

const client: Client = new Client({ bearerToken: 'your-bearer-token' });

// 使用合适的类型为任意列表型端点提供封装
const followers: UserPaginator = new UserPaginator(
  async (token?: string): Promise<PaginatedResponse<Schemas.User>> => {
    const res = await client.users.getFollowers('<userId>', {
      maxResults: 100,
      paginationToken: token,
      userfields: ['id','name','username'],
    });
    return { 
      data: res.data ?? [], 
      meta: res.meta, 
      includes: res.includes, 
      errors: res.errors 
    };
  }
);

​

手动分页

manual.ts

import { UserPaginator, Schemas } from '@xdevplatform/xdk';

await followers.fetchNext();          // 第一页
while (!followers.done) {
  await followers.fetchNext();        // 后续页
}

const userCount: number = followers.users.length;  // 已获取的全部用户
const firstUser: Schemas.User | undefined = followers.users[0];
const nextToken: string | undefined = followers.meta?.next_token;

​

异步迭代

async.ts

import { Schemas } from '@xdevplatform/xdk';

for await (const user of followers) {
  const typedUser: Schemas.User = user;
  console.log(typedUser.username);  // 完整类型安全的访问
}

​

将下一页作为新实例

next.ts

import { UserPaginator } from '@xdevplatform/xdk';

await followers.fetchNext();
if (!followers.done) {
  const page2: UserPaginator = await followers.next(); // 独立的分页器，从下一页起步
  await page2.fetchNext();
  console.log(page2.users.length);  // 第二页的项目
}

​

错误处理与速率限制

errors.ts

import { UserPaginator, Schemas } from '@xdevplatform/xdk';

try {
  for await (const item of followers) {
    const user: Schemas.User = item;
    // 处理用户...
  }
} catch (err: unknown) {
  if (followers.rateLimited) {
    console.error('触发频率限制，需要退避');
    // 退避 / 稍后重试
  } else {
    console.error('分页错误：', err);
    throw err;
  }
}