Go pkg.go.dev API 返回分页结果时怎么继续请求

第一次接入 pkg.go.dev API 时，最容易把分页写成 page=2、offset+=limit。这个接口真正返回的是游标：响应里的 nextPageToken 非空，就把它作为下一次请求的 token 参数继续请求；为空才表示没有下一页。原来的 limit、filter、q 等参数要保持不变。

官方地址：https://pkg.go.dev/v1/api

pkg.go.dev API 的分页契约不是 page=2

官方 API 文档把分页接口统一描述为：响应包含 items、total 和 nextPageToken。total 可能是 -1，表示服务端没有计算完整总数；客户端是否继续，只看 nextPageToken 是否为空。像 /v1/versions/{path}、/v1/packages/{path}、/v1/search 都使用这套约定。

因此，首个请求可以带上 limit=20 和 filter；拿到 token 后，不要重新计算偏移量，也不要替换筛选条件。文档还特别说明：即使当前页没有 items，只要 nextPageToken 非空，仍然存在下一页。

用 Go 把续页逻辑封装成可恢复循环

下面的示例读取模块版本列表。它把查询条件放入 url.Values，每页都复制一份参数，再设置 token；这样可以避免手工拼接导致的转义错误，也不会意外丢掉 limit 或 filter。

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
)

type Page struct {
    Items         []json.RawMessage `json:"items"`
    Total         int               `json:"total"`
    NextPageToken string            `json:"nextPageToken"`
}

func FetchAll(ctx context.Context, client *http.Client, endpoint string, limit int) ([]json.RawMessage, error) {
    values := url.Values{"limit": {fmt.Sprint(limit)}}
    var all []json.RawMessage
    var previousToken string

    for {
        query := values.Clone()
        if previousToken != "" {
            // 游标由服务端生成，只把它作为 token 传回，不计算 page 或 offset。
            query.Set("token", previousToken)
        }

        req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint+"?"+query.Encode(), nil)
        if err != nil {
            return nil, fmt.Errorf("创建请求: %w", err)
        }
        resp, err := client.Do(req)
        if err != nil {
            return nil, fmt.Errorf("请求分页数据: %w", err)
        }

        if resp.StatusCode/100 != 2 {
            // 错误响应也要关闭 body，避免长分页任务耗尽连接资源。
            body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
            resp.Body.Close()
            return nil, fmt.Errorf("HTTP %s: %s", resp.Status, string(body))
        }

        var page Page
        err = json.NewDecoder(resp.Body).Decode(&page)
        resp.Body.Close()
        if err != nil {
            return nil, fmt.Errorf("解析分页响应: %w", err)
        }
        all = append(all, page.Items...)

        if page.NextPageToken == "" {
            return all, nil
        }
        if page.NextPageToken == previousToken {
            // 服务端异常重复游标时主动退出，避免客户端无限请求。
            return nil, fmt.Errorf("服务端返回重复 nextPageToken")
        }
        previousToken = page.NextPageToken
    }
}

示例里没有把 total 当作停止条件，因为服务端可能返回未知总数。错误响应读取最多 4096 字节只是为了保留诊断信息；正式服务还可以加入重试策略，但重试应针对 429、5xx 等明确场景，并遵守接口限流。

三个容易漏掉的边界

生产代码还应给请求绑定超时的 context.Context，限制单轮最多读取多少页，并记录接口、limit、返回条数和 token 是否变化。token 本身不需要解析，也不要把它持久化成可以跨查询复用的业务游标；它只属于同一组原始请求条件。

常见问题

pkg.go.dev API 能不能用 offset 或 page 参数续页？

针对文档列出的这些分页响应，不应自行用 offset 或 page 推算下一页；应读取 nextPageToken，并用 token 请求下一页。

为什么要保留原来的 filter 和 limit？

token 是上一组查询条件生成的续取位置。改变筛选或分页大小会让游标失去原上下文，可能返回错误或得到不一致的数据。

分页循环要不要按 total 计算请求次数？

不要。total 可能未知，且最终停止信号是空的 nextPageToken；本地可以额外设置页数和总条数上限作为保护。

把判断集中到一个规则即可：先保留原查询，再读取 nextPageToken；非空就续取，空值才收尾。这样 Go 客户端既符合 pkg.go.dev API 的分页契约，也能在异常游标和网络错误出现时及时停下来。