当前位置：首页 > news >正文

AIP-158 分页

news 来源：原创 2025/5/3 16:01:11

编号	158
原文链接	AIP-158: Pagination
状态	批准
创建日期	2019-02-18
更新日期	2019-02-18

API通常需要提供数据集，最常见的是 List 标准方法。但集合大小往往是不受控制的，会随着时间增长，提高了查找时间和通过网络传输的应答大小。因此对集合进行分页是非常重要的。

指南

返回数据集的接口必须一开始就提供分页功能，因为向现存方法添加分页功能是无法向后兼容的变更。

// The request structure for listing books.
message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The maximum number of books to return. The service may return fewer than
  // this value.
  // If unspecified, at most 50 books will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListBooks` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListBooks` must match
  // the call that provided the page token.
  string page_token = 3;
}

// The response structure from listing books.
message ListBooksResponse {
  // The books from the specified publisher.
  repeated Book books = 1;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

返回集合的请求消息应当定义 int32 page_size 域，允许用户设定返回的最大结果数量。
- page_size 域不得是必需域。
- 如果用户未设定 page_size （或设定为 0 ），API选择合适的默认值。API 应当在文档中记录默认值。API 不得返回错误。
- 如果用户设定的 page_size 大于 API 允许的最大值，API 应当将其强制设置为允许的最大页大小。
- 如果用户为 page_size 设定了负值，API 必须返回 INVALID_ARGUMENT 错误。
- API 可以返回少于请求数量（包括零）的结果，即使未到达集合末尾。
集合的请求消息应当定义 string page_token 域，允许用户前进到集合的下一页。
- page_token 域不得是必需域。
- 如果用户在后续分页请求中修改了 page_size ，服务必须遵守新的页大小。
- 用户要保持接口的所有其他参数不变；如果任何参数不同，API 应当返回 INVALID_ARGUMENT 错误。
应答不得是流式应答。
返回集合的应答消息应当定义 string next_page_token 域，为用户提供用于检索下一页的页令牌。
- 包含分页结果的域应当是消息的第一个域，编号为 1 。它应当是重复域，包含一组资源，构成一个结果页。
- 如果已到达集合末尾， next_page_token 域必须为空。这是告诉用户“集合结束”的唯一方法。
- 如果未到达集合末尾（或API无法及时确认），API 必须提供 next_page_token 。
返回集合的应答消息可以提供 int32 total_size 域，为用户提供列表总项目数。
- 总数可以是估计值（此时API 应当在文档中明确记录）。