pkggo.devAPI读取包版本信息

如果发布脚本需要知道一个 Go 模块有哪些版本，不必抓取 pkg.go.dev 的网页 HTML。官方 API 提供了 /v1/versions/{path} 接口，直接返回 JSON 版本列表；通过 limit、filter、pseudo 和 token 就能控制数量、筛选规则、伪版本和分页。

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

最小做法是把模块路径放进 /v1/versions/ 后面，读取响应的 items；当 nextPageToken 非空时，沿用原查询参数并追加 token 继续请求。

版本接口返回什么，先看模块与版本边界

版本接口面向“模块”而不是单个包，典型地址是 https://pkg.go.dev/v1/versions/golang.org/x/time。返回结果中的每一项通常包含 modulePath、version、commitTime、isLatest、deprecated 和 retracted 等字段。版本按降序排列；默认只返回带标签的版本，是否包含伪版本由 pseudo 控制。

接口是 GET 请求，响应是 JSON。没有 version 这个“指定版本”参数，因为这个路由本身的任务就是列出版本；如果要读取某个版本对应的包或模块信息，应转到 package 或 module 路由。生产代码还要把模块路径、返回状态码和响应体大小分开记录，避免把“接口返回 200”误当成“已经拿到完整列表”。

先用一个小请求确认参数写法

首次接入时建议只取少量条目，先观察响应结构，再决定是否开启分页。下面的命令只展示请求写法，不把命令输出当作本文的运行证据：

# 只取三个标签版本，先确认模块路径和 JSON 字段
curl -G 'https://pkg.go.dev/v1/versions/golang.org/x/time' \
  --data-urlencode 'limit=3' \
  --data-urlencode 'pseudo=false'

如果要筛选主版本，可以给 filter 传 Go 表达式，例如 hasPrefix(version, "v2.")。过滤条件和其他查询参数都应该交给参数编码器处理，不要手工拼接引号、空格和括号。

用 Go 读取版本列表并处理分页

下面的示例只使用标准库。它把模块路径限制在 URL 的路径部分，用 url.Values 编码查询参数，遇到非 2xx 状态先读取有限错误体，并在响应成功后循环处理 nextPageToken。示例设置了页数上限，防止上游异常时无限读取。

package main

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

type moduleVersion struct {
	ModulePath string `json:"modulePath"`
	Version    string `json:"version"`
	CommitTime string `json:"commitTime"`
	IsLatest   bool   `json:"isLatest"`
	Deprecated bool   `json:"deprecated"`
	Retracted  bool   `json:"retracted"`
}

type versionsPage struct {
	Items         []moduleVersion `json:"items"`
	NextPageToken string          `json:"nextPageToken"`
}

func listVersions(ctx context.Context, client *http.Client, modulePath string) error {
	// 先拒绝会改变 URL 语义的输入，再把模块路径拼到官方版本路由。
	modulePath = strings.TrimSpace(modulePath)
	if modulePath == "" || strings.HasPrefix(modulePath, "/") || strings.ContainsAny(modulePath, "?#") {
		return errors.New("模块路径为空或包含非法 URL 字符")
	}

	endpoint, err := url.JoinPath("https://pkg.go.dev/v1/versions", modulePath)
	if err != nil {
		return fmt.Errorf("拼接模块地址失败: %w", err)
	}

	query := url.Values{}
	query.Set("limit", "50")
	query.Set("pseudo", "false")
	// 需要只看 v2 时再启用筛选，表达式会由 url.Values 负责编码。
	// query.Set("filter", ` hasPrefix(version, "v2.") `)

	for page := 1; page = http.StatusMultipleChoices {
			return fmt.Errorf("版本接口返回 HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
		}

		var result versionsPage
		if err := json.Unmarshal(body, &result); err != nil {
			return fmt.Errorf("解析版本 JSON 失败: %w", err)
		}
		for _, item := range result.Items {
			fmt.Printf("%s %s latest=%t retracted=%t\n", item.Version, item.CommitTime, item.IsLatest, item.Retracted)
		}
		if result.NextPageToken == "" {
			return nil
		}
		// 分页时保持原参数不变，只追加服务端返回的 token。
		query.Set("token", result.NextPageToken)
	}
	return errors.New("分页超过 100 页，停止读取并交给人工处理")
}

func main() {
	// 使用短超时和请求级 context，避免发布脚本被远端请求长期占住。
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	modulePath := "golang.org/x/time"
	if len(os.Args) == 2 {
		modulePath = os.Args[1]
	}
	client := &http.Client{Timeout: 15 * time.Second}
	if err := listVersions(ctx, client, modulePath); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

这里的 limit 只是单页上限，不是总数；nextPageToken 非空才表示还有下一页。继续请求时不要修改原来的筛选、伪版本和数量参数，否则可能得到不一致的分页结果。

生产接入时把四个边界写进清单

第一，限制请求频率。官方文档给出了按 IP 区块计算的 QPS 限制，批量扫描时要在本地做并发和退避控制，不要把 429 当成“没有版本”。

第二，区分标签版本和伪版本。发布清单通常只关心可复现的标签版本；需要追踪开发分支时再显式设置 pseudo=true，并把伪版本号和时间一起落日志。

第三，保留分页上下文。保存模块路径、原始查询参数和当前 token，失败重试时不要换筛选表达式。接口返回的 total 可能是未知值，不能用它判断已经遍历完毕。

第四，限制响应体。读取 JSON 前设置字节上限，并把非 2xx、JSON 解析失败、分页超限分别记为不同错误。这样后续排查能区分网络问题、服务端拒绝和输入结构变化。

常见问题

为什么不直接解析 pkg.go.dev 网页？

网页是给人阅读的展示层，字段和页面结构可能随界面调整；版本 API 直接返回机器可读 JSON，更适合发布检查、依赖报告和 IDE 辅助功能。

为什么请求成功却只拿到一页？

因为 limit 控制单页数量。检查 nextPageToken 是否非空；只要有值，就沿用原请求并追加 token，直到游标为空或达到你的安全上限。

把 pkg.go.dev API 接入工程时，先用小 limit 看清字段，再把模块路径校验、状态码、响应体上限、速率控制和分页游标固定下来。这样读取版本信息的代码才适合放进自动化发布链路。