pkg.go.dev API 刚开放，Go 项目如何避开模块路径歧义？

5 月下旬，Go 官方给 pkg.go.dev 新增了开发者盼了很久的接口能力：不用爬网页，工具可以直接走 API 查询模块、版本、包、符号和漏洞信息。但有个很容易踩的坑也跟着冒出来了——网页端会自动帮你选「最长模块路径」，API 却要求调用方明确传准确的模块信息，不然就会返回歧义结果。

把 pkg.go.dev API 接入内部工具时，先把包路径和模块路径分开建模；默认查询最新版本，只有在发布检查或者问题复现场景下才显式传入指定版本。

一个看似正常的包查询，为什么在 API 里卡住了

假设团队要做一个依赖巡检页面，输入的是 example.com/a/b/c。在网页端打开完全正常，写代码的时候顺着思路拼出下面这个请求地址也很自然：

curl -s https://pkg.go.dev/v1beta/package/example.com/a/b/c | jq .

问题在于，同一个包路径可能同时落在 example.com/a 和 example.com/a/b 两个模块里。网页端会按照最长模块路径的规则自动做选择，API 为了保证自动化执行的结果可以复核，会要求模块边界定义清晰。返回歧义不是服务出故障，而是调用参数缺少了对应的业务判断依据。

这也是这次官方 API 发布最值得留意的设计取舍：接口优先保证结果精确，而不是把网页上所有的猜测逻辑直接复制给自动化脚本。

先看清 v1beta 能查什么，再划定客户端的能力边界

官方目前提供的接口是无状态、只读的 GET 服务，主要端点集中在 /v1beta。它们适合用来做依赖目录、版本校验、符号索引和漏洞提示场景，不适合直接拿来替代本地的模块下载器。

• /v1beta/package/{path}：获取包元数据、包名和描述摘要。
• /v1beta/module/{path}：获取模块基础信息。
• /v1beta/versions/{path}：获取模块对应的所有版本列表。
• /v1beta/packages/{path}：获取模块下包含的所有包。
• /v1beta/symbols/{path}：获取包声明的公开符号信息。
• /v1beta/vulns/{path}：查询模块或者包对应的漏洞信息。

这里要给内部工具划一条明确的边界：API 返回的是结构化元数据，实际构建流程仍然需要项目自身的 go.mod、代理和测试链路来负责。新接口开放可用不等于可以跳过本地验证环节。

用 Go 写一个能区分歧义、404 和正常结果的查询器

下面这个客户端实现逻辑非常纯粹：只做指定包的查询动作，完整保留 HTTP 状态码和响应体。路径参数先用 url.PathEscape 编码，版本信息作为查询参数传入；后续要切换到模块、符号或者漏洞端点时，边界逻辑依然能保持清晰。

package main

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

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

func queryPackage(ctx context.Context, pkg, version string) (PackageInfo, error) {
    endpoint := "https://pkg.go.dev/v1beta/package/" + url.PathEscape(pkg)
    if version != "" {
        endpoint += "?version=" + url.QueryEscape(version)
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        return PackageInfo{}, err
    }
    req.Header.Set("Accept", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return PackageInfo{}, err
    }
    defer resp.Body.Close()
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return PackageInfo{}, err
    }
    if resp.StatusCode == http.StatusNotFound {
        return PackageInfo{}, fmt.Errorf("package not found: %s", pkg)
    }
    if resp.StatusCode = 300 {
        return PackageInfo{}, fmt.Errorf("pkgsite status=%d body=%s", resp.StatusCode, body)
    }
    var info PackageInfo
    if err := json.Unmarshal(body, &info); err != nil {
        return PackageInfo{}, fmt.Errorf("decode pkgsite response: %w", err)
    }
    if info.ModulePath == "" || info.Path == "" {
        return PackageInfo{}, errors.New("pkgsite response misses modulePath or path")
    }
    return info, nil
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    info, err := queryPackage(ctx, "github.com/google/go-cmp/cmp", "")
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Printf("%s %s %s\\n", info.Path, info.ModulePath, info.Version)
}

代码里有两个判断逻辑千万不要删掉：404 说明对应路径没有可用文档，歧义或者其他 4xx 响应要把返回体交给上层逻辑记录下来。不然巡检页面最后只会显示一个模糊的「查询失败」提示，后续排查问题的时候还得重新发请求拉数据。

版本参数决定你拿到的是正式发布结果还是开发分支结果

不传 version 参数时，接口会自动解析到模块的最新标记版本。做依赖目录展示场景下这么用最省事；做发布回归校验的时候则应该把对应版本固定下来：

curl -s "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp?version=v0.7.0" \
  | jq '{path, modulePath, version, isLatest}'

curl -s "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp?version=main" \
  | jq '{path, version}'

当前接口支持传入语义版本，也允许填写 main 或者 master，分支名会被解析成对应的伪版本；自定义的任意分支名不在支持范围内。一个很实用的判断规则是：页面展示通用最新内容的时候可以省略版本参数，构建报告和安全问题复现场景下不要省略版本参数。

把新能力落地成工具时，三类结果要分开处理

建议你在数据模型里单独保留 requested_path、requested_version、resolved_module 和 resolved_version 四个字段。这样一次查询到底请求了什么内容、服务端最终解析出了什么结果，不会混在一个可变的展示字符串里。

• 查询成功：保存模块路径、解析后的版本、包摘要和查询时间，供目录或者报告场景调用。
• 模块歧义：展示所有候选模块，让使用方补全模块参数；不要自动默认选择第一个结果。
• 路径不存在或者响应结构变化：分别记录 404 状态和解码错误，保留原始状态码，方便后续回溯排查。

当前 API 还处于 v1beta 阶段，官方同时提供了 OpenAPI 规范，建议把响应解码逻辑放在单独的小包里维护。命令行参考实现 pkgsite-cli 可以用来快速熟悉接口能力，但官方已经提示它的命令行界面还没稳定，不要直接把它的输出文本当成长期依赖的协议格式。

常见问题：pkg.go.dev API 接入前后要确认什么

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

针对模块、包、版本、符号和漏洞这类结构化查询场景，可以优先使用官方 API；网页抓取不再是这类场景下的必选主路径。

为什么网页能正常打开，API 却提示模块不明确？

网页端会采用最长模块路径规则自动做选择，API 要求调用方明确指定模块，保证自动化执行的结果可以复现对齐。

生产环境应该固定使用 v1beta 还是等待 v1 版本发布？

可以先使用 v1beta 版本，但要把响应模型做隔离、记录原始请求状态，同时留意官方 API 规范和版本变化。不要把内部代码直接绑定在命令行工具的文本输出格式上。

查询最新包内容时要不要一直传 version=main？

不建议这么做。目录展示和发布版本查询通常拿最新标记版本即可；只有确实需要查看开发分支内容的时候，才显式传入 main 或者 master。

复查清单

这次 API 发布的价值不只是多了一组可用 URL，而是把 Go 生态元数据从页面呈现逻辑里拆成了可直接调用的标准契约。接入前确认四件事：路径是否明确、版本是否需要固定、错误是否能区分、响应模型是否可替换。四项都确认没问题之后，再把查询结果接入依赖目录、IDE 插件或者内部审计流程，后续维护成本会低很多。