Go pkg.go.dev API 怎样查询包的导出符号

如果工具要自动读取 Go 包的公开 API，不必抓取 pkg.go.dev 的网页。当前官方 API 提供 /v1/symbols/{path} 路由，返回包的结构化符号列表；把包路径、所属模块和版本明确传入，再配合 filter 与 nextPageToken，就能稳定查询导出符号。

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

最小可靠写法是：用完整包路径调用 /v1/symbols/...，模块有歧义时补 module，需要固定文档时补 version；分页时保留原请求，只增加上一页返回的 token。

先把包路径与模块边界写清楚

API 的路径部分是要查询的包导入路径。例如 golang.org/x/time/rate 是包路径，而 golang.org/x/time 是模块路径。相同的包路径可能由不同模块提供，网页界面可以按最长模块路径作选择，但 API 要求客户端把模块边界说清楚，否则会得到歧义错误和候选模块。

因此，自动化工具不要只拼接包路径。把模块当作查询身份的一部分保存，版本则作为可重复构建的时间边界。

# 用完整包路径查询；module 明确告诉 API 该包属于哪个模块
curl -G 'https://pkg.go.dev/v1/symbols/golang.org/x/time/rate' \
  --data-urlencode 'module=golang.org/x/time' \
  --data-urlencode 'version=latest' \
  --data-urlencode 'limit=20'

调用 symbols 路由查询导出符号

symbols 路由面向单个包，响应中包含模块路径、解析后的版本和分页的符号集合。需要只看类型时，可传入 Go 表达式形式的 filter，例如 kind == "Type"；这些过滤参数通常要经过 URL 编码，不能把空格和引号直接当作普通路径字符。

# 只保留类型符号；data-urlencode 负责正确编码空格和引号
curl -G 'https://pkg.go.dev/v1/symbols/golang.org/x/time/rate' \
  --data-urlencode 'module=golang.org/x/time' \
  --data-urlencode 'version=latest' \
  --data-urlencode 'filter=kind == "Type"' \
  --data-urlencode 'limit=50'

返回结果的核心不是网页排版，而是可供程序消费的 JSON。实际集成时，先读取外层的 modulePath 和 version，再处理 symbols.items；这样可以把服务器最终解析的版本写进索引或缓存，而不是只保存客户端传入的别名。

package main

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

type symbolPage struct {
	ModulePath string `json:"modulePath"`
	Version    string `json:"version"`
	Symbols    struct {
		Items []struct {
			Name string `json:"name"`
			Kind string `json:"kind"`
		} `json:"items"`
		NextPageToken string `json:"nextPageToken"`
	} `json:"symbols"`
}

func main() {
	// 用 Values 编码查询参数，避免 filter 中的空格和引号破坏 URL。
	q := url.Values{
		"module":  {"golang.org/x/time"},
		"version": {"latest"},
		"filter":  {`kind == "Type"`},
		"limit":   {"50"},
	}
	endpoint := "https://pkg.go.dev/v1/symbols/golang.org/x/time/rate?" + q.Encode()
	resp, err := http.Get(endpoint)
	if err != nil {
		panic(fmt.Errorf("请求 symbols API 失败: %w", err))
	}
	defer resp.Body.Close() // 读取完响应后及时释放连接资源。
	if resp.StatusCode/100 != 2 {
		body, _ := io.ReadAll(resp.Body)
		panic(fmt.Errorf("API 返回 %s: %s", resp.Status, body))
	}
	var page symbolPage
	if err := json.NewDecoder(resp.Body).Decode(&page); err != nil {
		panic(fmt.Errorf("解析 JSON 失败: %w", err))
	}
	fmt.Println(page.ModulePath, page.Version, len(page.Symbols.Items))
}

版本与构建上下文要固定

不传 version 时，API 会解析模块的最新版本；需要复现历史文档时，传入语义化版本。官方文档还允许使用默认开发分支名 main 或 master，服务端会解析成对应的伪版本，但不支持任意分支名。

同一个包在不同 GOOS/GOARCH 下可能拥有不同的导出符号，尤其是带平台文件的包。若工具生成平台相关索引，应同时传入 goos 和 goarch；若只是做通用文档检索，可以接受 API 的默认构建上下文。

按 nextPageToken 继续分页

符号较多时，响应里的 symbols 会分页。当前页的 items 为空并不一定代表结束，只要 nextPageToken 非空，就仍然存在下一页。续查时应原样保留第一次请求的参数，只额外增加 token；不要同时修改 limit、filter 或版本。

// fetchAllSymbols 按 API 返回的游标收集所有符号。
func fetchAllSymbols(client *http.Client, baseURL string, params url.Values) ([]string, error) {
	var all []string
	for {
		// token 是上一页的续查位置；其余参数在整个分页过程中保持不变。
		requestURL := baseURL + "?" + params.Encode()
		resp, err := client.Get(requestURL)
		if err != nil {
			return nil, fmt.Errorf("请求分页失败: %w", err)
		}
		var page symbolPage
		decodeErr := json.NewDecoder(resp.Body).Decode(&page)
		closeErr := resp.Body.Close() // 每一页都关闭响应体，避免长列表耗尽连接。
		if decodeErr != nil {
			return nil, fmt.Errorf("解析分页响应失败: %w", decodeErr)
		}
		if closeErr != nil {
			return nil, fmt.Errorf("关闭响应体失败: %w", closeErr)
		}
		for _, item := range page.Symbols.Items {
			all = append(all, item.Name)
		}
		if page.Symbols.NextPageToken == "" {
			return all, nil
		}
		// 只替换 token，保留包、模块、版本和过滤条件。
		params.Set("token", page.Symbols.NextPageToken)
	}
}

如果服务返回 HTTP 429，应把它当作速率限制处理，降低请求频率并使用有上限的重试策略；不要在同一个分页循环里无延迟地重复发起请求。遇到 JSON 错误时也要保留当前请求参数，方便定位是响应解析问题还是查询条件问题。

边界：API 查询与本地 go doc 不是一回事

pkg.go.dev API 面向已经发布到公共模块索引的数据，适合文档站、依赖分析器和离线索引任务。它不是任意本地目录的源码反射接口，也不应被当成网页抓取的替代包装。只想查看当前工作区的声明时，使用本地 go doc 更直接；要面向线上模块版本，则使用 API 并保存其解析后的版本。

• 包路径不完整或模块不明确：补全 module，不要盲目重试同一个请求。
• 需要稳定结果：传入版本，并记录响应中的最终版本。
• 符号数量较多：循环读取 nextPageToken，直到它为空。
• 平台差异明显：设置 goos 与 goarch，避免把一个平台的符号当成通用 API。

常见问题

为什么只传包路径会得到候选模块？

因为一个导入路径可能落在不同模块的边界内。API 需要客户端明确模块；拿到候选列表后，应选择实际依赖的模块再次请求。

filter 可以直接拼到 URL 字符串里吗？

不建议。过滤表达式包含空格、运算符和引号，应该使用 Go 的 url.Values.Encode 或 curl 的 --data-urlencode。

nextPageToken 不为空但 items 为空要不要停止？

不要停止。官方分页契约以 nextPageToken 是否为空作为是否还有下一页的判断，空的当前页也可能要求继续续查。