Go pkg.go.dev API 返回多个版本时怎样选目标版本

调用 pkg.go.dev API 时，真正要解决的不是“列表里哪个版本排在第一”，而是先明确业务目标：要可复现的固定版本、某个主版本下的最新稳定标签，还是默认开发分支。把版本发现和文档查询拆成两步，再把最终选择写进 version 参数，就不会因为 latest 变化而得到不同结果。

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

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

先用 /v1/versions/{module} 取候选版本，再按兼容目标筛选；最终查询包、模块或符号时显式传入 version。需要提交历史时才打开 pseudo=true，遇到 nextPageToken 要原样翻页。

先列版本，再决定目标版本

版本列表接口针对模块路径，而不是单个包路径。返回结果按版本号降序排列，默认只列带标签的版本；伪版本需要显式开启。下面的命令只做“发现”，不要把第一条结果直接写进生产配置。

# 先取候选版本，limit 只限制当前页的返回数量
curl -sS "https://pkg.go.dev/v1/versions/golang.org/x/time?limit=5" \
  | jq '.items[] | {version, latestVersion, retracted}'

# 只看 v2 主版本；filter 是 API 支持的表达式，参数要进行 URL 编码
curl -G -sS "https://pkg.go.dev/v1/versions/example.com/trace" \
  --data-urlencode 'filter=hasPrefix(version, "v2.")' \
  | jq '.items[] | .version'

筛选时要把三个字段分开理解：version 是当前条目的版本，latestVersion 是模块当前识别到的最新版本，retracted 表示该条目是否被撤回。某个模块的最新版本并不等于你的应用应该使用的版本。

版本字符串应该怎样选

如果构建需要可复现，直接使用完整语义版本，例如 v0.16.0。如果工具只服务于某个主版本，可以在版本列表中保留 v1. 或 v2. 前缀，再从稳定标签中选择。不要把“主版本前缀”误写成文档查询接口的模糊匹配规则，最后的请求仍然应该落到一个确定的版本。

如果目的是观察默认开发分支，API 文档支持把 version 设为 master 或 main，服务会解析到对应的伪版本。其他任意分支名不能当作通用版本选择器。需要提交历史或未打标签的开发状态时，才在版本列表请求中使用 pseudo=true。

# 固定版本：适合构建记录、缓存键和回归报告
curl -sS "https://pkg.go.dev/v1/package/golang.org/x/time/rate?version=v0.16.0"

# 查询默认开发分支：结果会解析到对应的伪版本
curl -sS "https://pkg.go.dev/v1/package/golang.org/x/time/rate?version=main" \
  | jq '{path, version, isLatest}'

还有一个容易忽略的边界：同一个包路径可能由多个模块提供。API 发现歧义时会返回候选模块，而不是替你猜最长路径；此时先确定模块，再把 module 参数补进后续请求。

一个可落地的选择顺序

可以把选择规则固定成下面四步：第一，记录调用方需要的主版本；第二，读取版本页并保留分页结果；第三，排除撤回版本，优先挑带标签的稳定版本；第四，用选中的完整版本查询目标包。这样 API 的排序只是输入，而不是业务决策。

分页时不要重新拼接路径或修改原请求参数。响应只要有非空的 nextPageToken，就保留原请求并额外加入 token；否则可能漏掉后续版本。列表接口的总数也可能暂时未知，因此不要用 total 是否为零来判断“没有更多数据”。

package main

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

type page struct {
	Items         []struct{ Version string `json:"version"` } `json:"items"`
	NextPageToken string `json:"nextPageToken"`
}

func readVersions(module, token string) (page, error) {
	// 使用同一组查询参数翻页，只额外追加 token，避免漏项。
	u := "https://pkg.go.dev/v1/versions/" + url.PathEscape(module)
	q := url.Values{"limit": {"50"}}
	if token != "" {
		q.Set("token", token)
	}
	resp, err := http.Get(u + "?" + q.Encode())
	if err != nil {
		return page{}, err
	}
	defer resp.Body.Close() // 读取响应结束后及时释放连接资源。
	if resp.StatusCode/100 != 2 {
		return page{}, fmt.Errorf("pkg.go.dev 返回状态码 %s", resp.Status)
	}
	var p page
	if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
		return page{}, err
	}
	return p, nil
}

常见误区与简短结论

• 把缺少 version 理解成“永远返回某个固定版本”：实际是按服务当前规则解析最新版本，生产记录应保存完整版本号。
• 把 pseudo=true 当成“更稳定”：它只是允许列表包含伪版本，不能替代稳定标签。
• 只读取第一页：版本较多的模块必须持续处理 nextPageToken。
• 忽略模块歧义：包路径确定后仍要确认它属于哪个模块，必要时显式传 module。

一句话总结：版本列表负责提供候选，语义版本负责表达目标，version 参数负责让最终文档请求可复现。

相关问题

问：只想看 v1 下最新的稳定版本，应该怎么做？
答：请求版本列表时按 v1. 前缀筛选，跳过 retracted=true 和伪版本，再把选中的完整标签传给包查询。

问：为什么网页能打开，API 却提示模块不明确？
答：网页可以按自身规则选择展示模块，API 更强调精确性。根据候选列表确定真实模块路径，并在后续请求中显式传入 module。