pkg.go.dev API 怎么服务 Go 依赖目录：模块元数据读取与文档页面边界

团队给 Go 依赖做目录时，最先遇到的通常不是“页面打不开”，而是同一个包路径要展示哪个模块、哪个版本，以及它在不同构建上下文下是否有不同符号。直接抓取网页很快会被页面结构绑住。pkg.go.dev API 更适合做只读目录：返回 JSON，便于保存模块元数据；但它不替你完成本地编译、测试和兼容性判断。

一、先把 pkg.go.dev API 当成只读依赖目录

官方 API 的入口是 https://pkg.go.dev/v1/，请求都是 GET，第一段路径决定查询类型。它适合做依赖搜索、文档索引和版本目录，不适合充当构建系统。目录程序可以把响应保存下来，再由本地 go list、测试和构建去确认当前工程是否真的能使用该版本。

先在数据模型里分开三类记录：包记录保存包路径和文档摘要，模块记录保存模块版本与仓库信息，版本记录保存每个标签的状态。这样后面遇到 v2 模块、撤回版本或不同 GOOS/GOARCH 时，不会把一个页面字段误当成最终兼容结论。

二、用 /v1/package 读取包级元数据

包级请求可以从最小形式开始：

curl -L "https://pkg.go.dev/v1/package/golang.org/x/time/rate?doc=markdown&examples=true&licenses=true"

返回的 Package 响应通常包含 modulePath、version、isLatest、path、name、synopsis 等字段。若目录需要指定版本，加入 version；若要核对某个平台的文档，使用 goos 和 goarch。文档内容、示例和许可证是可选字段，按目录用途开启，避免无意义地扩大响应。

这里的判断点不是“页面上有没有这个包”，而是响应能否稳定映射到你的目录字段。比如 isStandardLibrary 可以帮助分类，isRedistributable 可作为展示提醒，但都不能代替团队对依赖许可证和发布策略的复核。

三、用 /v1/module 和 /v1/versions 组织模块目录

模块级请求回答“这个模块是谁”，版本路由回答“它有哪些版本”。模块响应可以记录 path、version、commitTime、hasGoMod、repoUrl 等字段；版本列表则包含 modulePath、version、latestVersion、deprecated、retracted 等版本状态。目录表至少要保留模块路径和版本号的联合键。

curl -L "https://pkg.go.dev/v1/module/golang.org/x/time"
curl -L "https://pkg.go.dev/v1/versions/golang.org/x/time?limit=20&filter=hasPrefix(version,%20%22v0.%22)"

不要把 latestVersion 当成“项目一定适合当前工程”的承诺。它只是站点目录中的版本关系。真正升级前，还应检查 Go 版本、模块图、代码变更和回归测试。

四、处理歧义路径、构建上下文和分页

包路径可能对应不同模块。例如 a/b/c 既可能是模块 a/b 下的包，也可能是模块 a 下的包。如果 API 返回错误和 candidates，程序不要猜最长路径，而应选定一个候选模块后重新请求：

{
  "message": "ambiguous package path",
  "candidates": ["a/b", "a"]
}

构建上下文也要单独存储。goos 和 goarch 缺省时通常采用站点默认上下文；某些包在 linux/amd64 与 js/wasm 的文档或导出符号并不相同。

涉及版本和包列表时，响应可能带非空 nextPageToken。下一次请求要完整复用原 URL，只追加 token 参数；如果同时修改 limit、filter 或版本条件，续页结果就不再可靠。请求层还要把 HTTP 429 记录为限流状态，采用退避和队列，而不是立即重复轰击接口。

常见问题：API 返回的信息能替代本地构建吗？

pkg.go.dev API 能确认依赖一定能编译吗？

不能。它提供目录和文档元数据；编译、测试、平台兼容与实际模块图仍要由本地工具链确认。

包路径出现多个模块时应该怎么选？

读取错误响应里的 candidates，结合工程声明的模块路径显式传入 module，不要凭字符串长度猜测。

版本列表为什么要保存 nextPageToken？

因为版本结果可能分多页返回。保存令牌才能在下一轮沿用原请求继续读取，避免目录只保留第一页。

把 pkg.go.dev API 放在“发现与索引”这一层，目录会更稳定：包、模块、版本、构建上下文各有自己的字段，歧义与限流都有明确分支；到了发布或升级环节，再把本地构建结果作为第二份证据写回目录。