pkg.go.dev API 分页结果如何持续同步到本地索引

我第一次画这个同步器的设计草图时，最自然的想法是：把 pkg.go.dev 返回的 nextPageToken 存下来，下次任务从这里继续。重新对照官方 API 文档后，我放弃了这个方案。文档只保证 token 用来取得同一请求的下一页，并要求除新增 token 外保持原请求不变；它没有把 token 定义成可以长期保存的变更日志位置。

更稳妥的做法是：每次同步都固定 endpoint、limit、filter 等参数，完整消费本轮的 nextPageToken 链，把结果写入暂存集合；只有全部页面成功后，才原子替换本地索引。中途失败时继续保留上一次成功快照，下次重新开始这一轮。

官方 API 文档：https://pkg.go.dev/v1/api

先确定本地索引要解决什么

pkg.go.dev v1 API 提供包、模块、版本、搜索、符号和 imported-by 等查询。并不是所有路由都分页，但 /v1/versions/{path}、/v1/search 等列表接口会返回分页对象。本文以“持续同步一个已知公开模块的版本列表”为例，本地索引用于离线搜索、依赖报表和版本状态对比。

这个目标有三个约束：

• 不能因为某次任务只成功了前几页，就把完整旧索引替换成半份新数据。
• 同一个模块版本重复出现在重试或合并结果中时，必须按稳定主键去重。
• 分页条件发生变化时，应视为一个新的查询，而不是沿用旧 token。

我会把“页内游标”和“长期同步状态”分成两类数据。页内游标只活在一次任务内；长期状态保存查询指纹、上次成功时间和最终条目。

分页接口真正承诺了什么

官方文档给出的分页规则很明确：响应中的 nextPageToken 非空就表示还有下一页；下一次请求应逐字保持原请求，只增加 token 参数。除 token 外修改请求，可能得到错误。

还有一个很容易漏掉的边界：当前页 items 为空，不代表分页已经结束。只要 nextPageToken 仍非空，就必须继续请求。对过滤后的结果尤其如此，一页可能没有匹配项，但服务端仍然给出后续游标。

这也是为什么我不使用“已读取条数等于 total”作为结束判断。官方版本列表示例中，total=-1 表示总数未知；真正可靠的分页结束条件是 nextPageToken 为空。

把一次同步设计成完整快照

持续同步不一定等于服务端提供增量流。当前 API 文档描述了分页查询，但没有把搜索或版本路由定义为全站变更日志。因此，对一个有界目标集合，我更倾向于周期性生成完整快照：

• 为 endpoint、模块路径、limit、filter、pseudo 计算查询指纹。
• 本轮所有页面先进入暂存集合，并按稳定主键去重。
• 拿到空的 nextPageToken 后，才生成新的正式索引文件。
• 写临时文件、刷盘并重命名；任何错误都不碰旧快照。
• 成功后记录 last_success_at，下一次重新遍历。

对于版本列表，稳定主键可以使用 modulePath + version。对于搜索结果，则更适合用 packagePath + modulePath + version。主键必须来自响应里的业务标识，不能用页码或数组下标。

Go 实现：完整消费分页并原子写入

下面的示例只使用标准库，把一个公开模块的 tagged versions 同步到 JSON 文件。它故意不跨任务保存 token；每次启动都用同一组基础参数从第一页开始，完整成功后替换索引。

package main

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"path/filepath"
	"sort"
	"strings"
	"time"
)

const maxResponse = 8  maxResponse {
			return zero, fmt.Errorf("单页响应超过 %d 字节", maxResponse)
		}

		if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500 {
			if attempt == 3 {
				return zero, fmt.Errorf("临时错误重试耗尽: HTTP %d", resp.StatusCode)
			}
			// 有限退避，避免 429 后立即重放同一请求
			select {
			case 

示例中的 pseudo=false 是一个明确的产品选择：本地索引只收 tagged versions。如果业务需要伪版本，应改成固定的 pseudo=true，并让查询指纹随之变化。不要在分页中途修改它。

atomicWriteJSON 适合单进程、同文件系统的轻量索引。多进程写入、Windows 覆盖语义、海量条目或需要在线查询时，我会改用 SQLite/PostgreSQL 事务：本轮写入带 sync_run_id 的暂存表，完整成功后在事务中切换 active run。

错误处理不能和业务空结果混在一起

官方文档给出的限流是每个 IP block 45 QPS，超过后返回 HTTP 429。示例是串行请求，正常情况下远低于这个上限，但共享出口、多个同步任务或其他调用方仍可能把总速率推高。

这里有个我很在意的调用方体验：失败日志要写“保留旧索引”，而不是含糊地写“同步完成 0 条”。传输错误、限流和真正的空集合是三种不同状态，监控指标也应该分开。

为什么不把 search 当成全站增量源

/v1/search 的接口目标是按 q 与可选 symbol 搜索结果，并按匹配程度排序。当前文档没有提供“从某个更新时间以后列出所有变化”的参数，也没有把搜索 token 描述为永久 changelog cursor。

因此，更合适的同步边界是：

• 维护一组明确的 module/package 查询目标。
• 对每个目标周期性生成完整快照。
• 以响应业务主键和内容哈希判断新增、变化与消失。
• 把 pkg.go.dev API 当查询源，不把它推断成未声明的事件流。

如果本地索引真的需要覆盖整个 Go 公共模块生态，应该重新评估数据源与规模，而不是不断扩大 search 关键词。pkg.go.dev 的 About 页面说明站点数据来自 Go Module Mirror，并监控 Go Module Index；这和搜索 API 的使用目标并不相同。

兼容策略：查询条件变化就建新快照

同步器上线后，最容易被忽略的是配置升级。比如 limit 从 100 调成 200，filter 增加主版本限制，或 pseudo 从 false 改成 true。虽然结果可能看起来相近，但它们已经是不同查询。

查询指纹可以把这种变化显式化。启动任务时，用 endpoint 和固定 query 参数计算 SHA-256；本地索引保存同一指纹。若指纹不同，就生成新快照，不能加载旧 token 续跑。代码的 schemaVersion 则用于管理本地文件结构变化，两者职责不同。

删除判断也要谨慎。某条记录在新快照中消失，可能是过滤条件改变、模块状态变化或暂时查询异常。只有本轮所有页面成功并且查询指纹相同，才有资格把“未出现”解释为当前快照已不存在。

适合谁，以及我会怎样落地

对几十到几千个明确模块做版本报表，这个“完整分页 + 暂存 + 原子替换”方案很实用：实现简单，恢复逻辑清楚，也不会被持久化 token 绑住。对于百万级全生态索引、高并发在线搜索或严格变更审计，它就不是终点，需要数据库事务、任务分片、限流协调和更合适的数据源。

我最终保留的四条设计原则是：

1. token 是本轮页面游标，不是跨天的永久检查点。
2. 固定查询参数并计算指纹，分页期间只增加 token。
3. 以业务主键去重，完整成功前不触碰旧索引。
4. 用 nextPageToken 判断结束，不用页内条数或 total 猜测。

常见问题

当前页 items 为空，还要请求下一页吗？

要。官方文档明确说明，只要 nextPageToken 非空就还有下一页，即使当前页没有 items。

nextPageToken 能写进数据库，明天继续吗？

不建议把它当永久断点。当前文档只说明它用于重复原请求并取得下一页，没有承诺跨较长时间或查询变化后的稳定性。更稳妥的是让一次同步完整消费分页链。

limit 改了，旧 token 还能用吗？

不应继续使用。下一页请求除 token 外要保持原请求不变；limit、filter、pseudo 等任何固定参数变化，都应开始新查询。

怎样同步伪版本？

/v1/versions/{path} 默认只返回 tagged versions；需要伪版本时设置 pseudo=true。这个参数应进入查询指纹，并在整轮分页中保持不变。

本地索引用 JSON 文件还是数据库？

单进程、小规模、离线读取可以用原子 JSON 文件；多写入者、大规模数据、在线查询或需要按批次切换时，使用支持事务的数据库更合适。核心契约不变：先完成暂存快照，再切换正式版本。