pkg.go.dev API 发布后如何程序化获取模块信息

如果你在脚本里读取 pkg.go.dev 的网页 HTML，再用选择器猜模块信息，现在可以换成官方 JSON API。它面向已经发布的 Go 模块元数据，采用无状态、只读的 GET 请求；当前主要路径是 /v1beta，后续稳定后计划转向 v1。

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

先把网页查找换成结构化 API

这次变化的价值不只是“多了几个 URL”。过去工具、IDE 集成和自动化脚本常靠抓网页拿包信息，页面结构一改，解析器就要跟着修。pkg.go.dev API 把查询对象收敛成 JSON 服务，适合目录生成、依赖巡检、包推荐和 AI 工具补充上下文。

当前常用端点可以这样分工：

用 package 和 module 端点获取模块信息

实际使用时，建议先用明确的模块或包路径请求，再只提取业务需要的字段。下面的例子查看 go-cmp 的 cmp 包和模块，输出不会依赖网页排版：

# 用官方 JSON API 查询一个明确的 Go 包
curl -fsS 'https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp' \
  | jq '{path, name, modulePath, version, synopsis}'

# 查询模块级信息；-f 让 HTTP 错误进入脚本的错误分支
curl -fsS 'https://pkg.go.dev/v1beta/module/github.com/google/go-cmp' \
  | jq '{path, version, repository, hasGoMod, isRedistributable}'

这里的重点是“查询对象要明确”。模块端点适合做依赖目录，包端点适合做 API 搜索结果详情；不要拿包端点的字段去推断整个模块的全部版本。

两个最容易踩坑的边界：路径歧义与版本选择

网页端为了方便，遇到相同包路径可能会按最长匹配模块来展示；API 更强调精确性。如果一个包路径同时可能来自 example.com/a 和 example.com/a/b，服务会返回候选模块并要求客户端补充 module 参数。自动化脚本收到这类响应时，应记录候选并重新发起明确请求，而不是随机选一个。

需要固定结果时，再加 version。它可以是语义版本，例如 v1.2.3，也可以是默认开发分支 main 或 master；省略时通常解析最新标记版本。自定义分支名不在当前支持范围内。

把端点组合进一个可恢复的 Go 客户端

如果要定期生成模块目录，可以将 URL 前缀和查询路径分开，未来从 v1beta 切换到 v1 时只改一处。下面的最小客户端包含超时、状态码、JSON 解码和响应关闭：

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type PackageInfo struct {
    Path       string `json:"path"`
    ModulePath string `json:"modulePath"`
    Version    string `json:"version"`
    Synopsis   string `json:"synopsis"`
}

func main() {
    // 把 API 版本集中管理，便于未来切换稳定版本。
    endpoint := "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp"
    client := &http.Client{Timeout: 10 * time.Second}

    // 请求只读 JSON；超时可以避免定时任务被单个模块拖住。
    resp, err := client.Get(endpoint)
    if err != nil {
        panic(fmt.Errorf("请求 pkg.go.dev API 失败: %w", err))
    }
    defer resp.Body.Close() // 及时释放连接，便于客户端复用资源。
    if resp.StatusCode = 300 {
        panic(fmt.Errorf("API 返回 HTTP %s", resp.Status))
    }

    var info PackageInfo
    // 解码失败通常意味着响应形状或请求路径需要重新检查。
    if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
        panic(fmt.Errorf("解析模块信息失败: %w", err))
    }
    fmt.Printf("%s %s %s\n", info.Path, info.ModulePath, info.Version)
}

生产代码还应把歧义响应记录成可重试任务，并对搜索、版本列表和漏洞查询分别设置分页或缓存策略。pkgsite-cli 可以作为参考客户端，但官方资料也提示它的命令行接口仍可能变化；自己的集成应直接围绕 API 契约编写。

常见问题

pkg.go.dev API 能否替代网页抓取？

对模块和包元数据查询，可以优先使用 API。网页仍适合人工阅读文档，不能把 HTML 页面结构当成程序接口。

为什么同一个包路径还要指定 module？

因为一个路径可能落在不同模块中。API 选择精确性，会把候选模块交给客户端处理，避免隐式选择带来错误结果。

省略 version 会拿到哪个版本？

对支持版本参数的查询，省略时通常解析最新标记版本；需要可重复构建或审计时，应把明确的语义版本写入请求。

因此，这个 API 最适合放在“搜索或目录发现”与“后续文档消费”之间：先用明确路径拿到结构化元数据，再依据版本和模块边界决定下一步，而不是继续维护脆弱的页面解析器。