pkg.go.dev 开放 API 后能自动化哪些依赖查询

pkg.go.dev 开放 API 后，团队最值得自动化的不是抓取网页，而是把 Go 包和模块元数据按结构化接口接入依赖台账、研发门户和 CI。官方 API 当前以无状态、只读的 /v1beta 路径提供包、模块、版本、包列表、搜索、符号、反向依赖和漏洞信息；它能减少 HTML 抓取，但不会替你完成私有模块授权、可达性分析或升级决策。

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

落地时先把“查询事实”和“治理结论”分开：API 负责提供可重复读取的公开元数据，内部系统负责缓存、归档、权限、漏洞确认和升级闭环。

pkg.go.dev API 先解决的是结构化查询

官方介绍把当前接口定位为查询已发布 Go 模块元数据的服务。最适合自动化的第一类任务是建立依赖台账：输入模块路径后读取版本列表，再读取模块包含的包；输入包路径后获取包名、所属模块、版本、简介和平台信息。保存这些字段时，同时记录请求路径、查询版本、抓取时间和接口版本，后续才能解释一次变更来自哪里。

第二类任务是研发检索。搜索接口适合做内部门户的候选发现，符号接口适合快速定位包导出的类型和函数，imported-by 则能帮助评估一个公共包的使用面。漏洞接口可以作为依赖巡检的输入，但最终是否受影响仍要结合主模块、实际构建图和组织的修复策略。

把模块清单映射成可重复的查询任务

不要把一次请求结果直接当成最终报告。可以为每个模块建立三层记录：模块层保存路径和版本候选；包层保存包路径、名称和简介；治理层保存查询时间、漏洞线索、人工确认状态与内部工单号。这样即使最新版本发生变化，也能比较“本次看到了什么”和“上次看到了什么”。

# 查询模块版本；生产脚本应把响应保存到带时间戳的原始记录
curl -fsS "https://pkg.go.dev/v1beta/versions/github.com/google/go-cmp" \
  -o module-versions.json

# 查询包元数据；失败时保留 HTTP 状态和请求路径，便于重试与审计
curl -fsS "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp" \
  -o package.json

脚本中应区分 4xx、5xx 和解析失败：4xx 通常需要修正路径或参数，5xx 与网络错误适合有限次数退避；JSON 字段缺失时不要静默写成空版本。缓存键至少包含端点、路径和 version，否则同一个包的最新结果可能覆盖指定版本记录。

遇到路径歧义时要显式指定 module

网页界面可以按最长模块路径帮用户选择，但 API 更强调精确性。当一个包路径可能由多个模块提供时，调用方应保存候选列表并明确传入模块信息，而不是把第一个结果当成确定答案。版本参数也要写入任务：省略时通常查询最新标记版本，指定语义化版本或 main 时则应在台账中保留原始请求和解析后的版本。

自动化脚本最容易漏掉的三个边界

第一是公开数据与私有依赖的边界。pkg.go.dev API 面向公开发布的模块元数据，企业内部模块、代理鉴权和组织权限仍由自己的仓库或代理系统处理。第二是缓存与新鲜度的边界：定时同步可以缓存稳定版本，但发布前检查要明确重新拉取条件，不能把旧快照伪装成实时事实。

第三是漏洞线索与修复结论的边界。接口给出的是可供进一步处理的信息，组织仍要判断漏洞是否进入实际构建图、是否被代码路径使用、是否已有替代版本，并把结论回写到工单或依赖清单。自动化的价值是减少查询成本，不是跳过审查。

常见问题

可以用 API 直接生成完整 SBOM 吗？

不能只靠它完成。API 可以提供公开模块和包元数据，但 SBOM 还需要从实际构建图、许可证、私有依赖和制品信息中补齐证据。

为什么查询包时要记录 version？

省略版本通常面向最新版本，而历史报告需要可重放。把请求版本和返回版本一起保存，才能解释升级前后的差异。

API 返回漏洞信息后就能自动阻断发布吗？

不应直接等同。先结合项目实际依赖、可达性、修复版本和组织策略确认，再决定告警、阻断或接受风险。

因此，pkg.go.dev API 最适合成为 Go 依赖自动化的公开数据入口：模块和包查询进入台账，搜索与符号查询服务研发门户，反向依赖和漏洞结果进入影响面与治理流程。把请求参数、版本、缓存和人工结论分别保存，系统才会稳定、可解释，也不会把接口能力夸大成完整的供应链平台。