36、API 分页与过滤模式详解

API 分页与过滤模式详解

1. 分页模式

分页模式允许将大型结果集或单个大资源拆分成一系列小的块进行处理，避免一次性返回大量数据。它主要使用三个特殊字段： maxPageSize 、 pageToken 和 nextPageToken 。

1.1 最终 API 定义

以下是分页模式的最终 API 定义示例：

abstract class ChatRoomApi {
  @get("/chatRooms")
  ListChatRooms(req: ListChatRoomsRequest): ListChatRoomsResponse;
  @get("/{id=chatRooms/*/messages/*/attachments/*}:read")
  ReadAttachment(req: ReadAttachmentRequest): ReadAttachmentResponse;
}

interface ListChatRoomsRequest {
  pageToken: string;
  maxPageSize: number;
}

interface ListChatRoomsResponse {
  results: ChatRoom[];
  nextPageToken: string;
}

interface ReadAttachmentRequest {
  id: string;
  pageToken: string;
  maxBytes: number;
}