YouTube API返回百万预估结果场景下如何正确实现分页

接口返回的1,000,000是API侧的预估阈值，当匹配结果量级达到百万级时就会固定返回该值，完全不代表真实结果总数，不能基于这个数值计算总页数、生成分页页码，正确的分页实现完全基于游标机制，具体逻辑如下：

核心分页规则 #

• 采用游标分页模式，不要使用传统的offset偏移量分页逻辑，YouTube API所有列表类接口均通过pageToken参数实现分页跳转。
• 首次请求接口时无需传递pageToken参数，接口返回体中会携带分页标识：存在nextPageToken时代表还有下一页数据，存在prevPageToken时代表存在上一页数据（第一页返回结果不会携带该字段）。
• 不要预先生成全量页码导航，由于无法获取真实总页数，分页控件仅需保留「上一页」「下一页」按钮即可，不要提供跳转到最后一页、跳转到指定数字页码的功能，API本身也不支持跨多页的直接跳转。

分页终止判断 #

不要依赖pageInfo.totalResults判断是否到最后一页，按以下规则判断终止即可：

• 某次接口返回的结果中不存在nextPageToken字段，即为最后一页，直接终止分页、禁用下一页按钮。
• 注意搜索类接口存在硬限制：无论匹配到多少结果，最多仅支持返回前1000条匹配内容，当拉取条数累计到1000条时，即使返回nextPageToken也可能触发权限报错，此时直接终止分页即可，属于接口正常限制。

注意事项 #

• 分页请求过程中，除pageToken外的所有查询参数（包括搜索关键词、排序规则、筛选条件、时间范围、maxResults单页条数等）必须保持完全一致，否则之前获取的pageToken会直接失效，返回参数错误。
• 不要通过totalResults / maxResults的方式计算总页数，该计算结果无实际参考价值，会出现计算得出数万页、实际仅能拉取十几页的情况。
• 如果需要做分页缓存，需要将pageToken和对应查询参数绑定存储，单独存储token会导致参数变化后分页失效。

逻辑参考示例 #

let currentPageToken = null
let hasNext = true
// 固定除pageToken外的所有基础请求参数
const baseParams = {
  part: "snippet",
  q: "目标搜索关键词",
  maxResults: 50, // 单页最大支持传50
  type: "video"
}

async function loadPageData() {
  const res = await youtube.search.list({
    ...baseParams,
    pageToken: currentPageToken
  })
  // 渲染当前页列表内容
  renderTable(res.data.items)
  // 更新分页状态
  hasNext = Boolean(res.data.nextPageToken)
  currentPageToken = res.data.nextPageToken || null
  updateButtonStatus(hasNext)
}

// 下一页点击事件
function onNextPageClick() {
  if (!hasNext) return
  loadPageData()
}

// 上一页逻辑同理，提前缓存每页对应的prevPageToken即可实现

内容的提问来源于stack exchange，提问作者Tavishi chaturvedi