pkg.go.dev API 分页游标失效后如何恢复同步

用 pkg.go.dev API 做模块版本、包列表或搜索结果同步时，最容易踩到的坑不是“怎么拼 token”，而是把上一次响应里的 token 当成永久书签。分页 token 只对原请求上下文有意义；如果 limit、filter、version 或查询词发生变化，继续带着旧 token 请求，服务端可能拒绝，客户端也可能得到一段无法接续的结果。

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

先把分页请求当成不可变快照

pkg.go.dev API 的分页响应通常包含 items、total 和 nextPageToken。官方规则是复用原请求，并在下一次请求中加入 token；不要同时修改 limit、filter、version 或 q。这也是恢复同步的第一条边界：先保存“第一页请求”，再保存游标。

正常续页与失效恢复放在同一个循环里

下面的示例以 /v1/versions/{path} 为例。它没有假设服务端公开了固定的 token 过期时间，而是把“token 不可用”当成一种可恢复的游标错误：清空游标、回到第一页，并依赖稳定键去重。

package main

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

type page struct {
    Items         []struct { ModulePath, Version string } `json:"items"`
    NextPageToken string `json:"nextPageToken"`
}

func syncVersions(ctx context.Context, module string) error {
    base := "https://pkg.go.dev/v1/versions/" + url.PathEscape(module)
    values := url.Values{"limit": {"50"}}
    token := ""
    restarted := false
    seen := map[string]bool{}

    for {
        // 续页只追加 token；其他参数保持不变，避免游标上下文被改写。
        query := values.Encode()
        if token != "" { query += "&token=" + url.QueryEscape(token) }
        req, err := http.NewRequestWithContext(ctx, http.MethodGet, base+"?"+query, nil)
        if err != nil { return err }
        resp, err := http.DefaultClient.Do(req)
        if err != nil { return err }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close() // 每页都关闭响应体，避免恢复时耗尽连接池。
        if readErr != nil { return readErr }

        // 令牌错误不重复撞同一页：只允许回到第一页恢复一次。
        if resp.StatusCode >= 400 && token != "" {
            if restarted { return fmt.Errorf("分页游标连续失效: %s", resp.Status) }
            token, restarted = "", true
            continue
        }
        if resp.StatusCode >= 400 { return fmt.Errorf("pkg.go.dev API: %s", resp.Status) }

        var current page
        if err := json.Unmarshal(body, ¤t); err != nil { return err }
        for _, item := range current.Items {
            key := item.ModulePath + "@" + item.Version
            if !seen[key] { seen[key] = true /* 业务落库也应使用这个稳定键。 */ }
        }
        if current.NextPageToken == "" { return nil }
        token = current.NextPageToken
    }
}

示例中的 restarted 只是防止同一轮同步无限回到第一页。生产实现还应把第一页参数、最后成功 token、已处理数量和请求时间写入任务日志；不要把 token 单独存成跨查询复用的全局状态。

哪些情况应该重新开始，哪些情况不该重试

如果只是网络短暂断开，可以在相同请求上做有限次退避重试；如果服务返回 429，则按响应头或服务约定等待，并保留当前上下文。遇到 token 相关的 4xx，先记录原请求指纹，再清空 token 回到第一页。若 limit 或 filter 确实需要调整，也要把它视为一次全新同步，不能沿用旧 token。

• token 相关 4xx：丢弃 token，回到第一页，限制恢复次数。
• 429：按限流策略等待，仍使用原请求上下文。
• 5xx 或网络错误：有限退避重试，超过次数再交给任务队列。
• 响应 JSON 不符合预期：保存原始响应片段，停止写入，避免把错误页当数据。

幂等合并比“精确续上那一页”更可靠

游标恢复通常会重新看到第一页或前几页，因此同步表应该把 modulePath + version、packagePath + version 等稳定组合键设为唯一键。写入时使用 upsert 或“存在则更新、不存在则插入”，这样恢复不会产生重复记录。若业务要求严格的增量边界，还需要在本地保存完整快照版本，不能只依赖 API token。

最后检查三件事：请求指纹是否一致、token 是否只来自上一页、落库键是否稳定。做到这三点，游标失效只会让一次同步回到起点，不会演变成漏数据、重复数据和无限重试。

相关问题

pkg.go.dev API 的 token 能否长期保存？

不建议。它应被视为原请求上下文中的短期续页位置，长期任务应保存请求参数和同步快照，而不是只保存 token。

修改 limit 后还能使用原 nextPageToken 吗？

不能把它当作可靠行为。官方要求下一页复用原请求，修改 limit 后应从第一页重新开始。

重新开始会不会造成重复数据？

会看到重复项，但不应重复落库。使用模块路径、版本或包路径加版本的稳定键做幂等合并即可。