Go doc 为什么看不到未导出符号

如果你执行 go doc ./internal/cache，看不到以小写字母开头的类型、函数或字段，通常不是文档丢了，而是 go doc 默认遵守 Go 的导出规则：只展示公开文档。需要把未导出符号也纳入查询时，关键参数是 -u；-all 负责展开包中的文档范围，不能单独替代 -u。

官方资料：https://go.dev/doc/

可以先记住这一组判断：看包的完整文档用 -all，看未导出名称加 -u，想看声明或实现用 -src，命令包需要公开顶层符号时再考虑 -cmd。

默认输出为什么看不到未导出符号

Go 用标识符首字母大小写表达包级可见性。Cache、New 这类大写名称可以被其他包使用，cacheEntry、newShard 这类小写名称只在声明它们的包内部可见。go doc 面向的是 API 文档检索，因此默认输出优先呈现导出的包、类型、函数、方法和字段。

这也是为什么“源码里明明有这个类型，go doc 却没有”并不矛盾：命令找到的是同一个包，但展示层先应用了导出边界。未导出并不等于没有注释，也不等于编译器忽略它，只是没有进入默认的公开文档视图。

用 -u 查看未导出文档

-u 是解决标题问题的直接开关，它表示同时显示未导出和导出的符号、方法与字段。下面的示例把包路径写成相对当前模块的路径，适合排查内部包：

# 默认只看公开文档，先确认包路径能被当前模块解析
go doc ./internal/cache

# 加 -u 后，把未导出符号也纳入文档查询
go doc -u ./internal/cache

# 只定位一个未导出类型，避免整包输出过长
go doc -u ./internal/cache cacheEntry

上面的命令中，-u 改变的是“名称是否可见”，而不是把包变成可供外部导入的公开 API。即使 go doc -u 能展示 cacheEntry，其他包仍然不能直接引用这个小写类型。

如果只想确认某个未导出方法或字段，也可以继续使用符号定位语法。名称匹配失败时，优先检查包路径、大小写和符号所属类型，不要先把问题归因于文档生成失败。

-all、-u、-src 到底分别解决什么

这几个参数经常被一起记忆，但它们作用在不同维度：-all 影响包文档的展开范围，-u 影响是否包含未导出名称，-src 影响输出是否进入源码声明或实现。实际排查时可以按下面的命令组合选择：

# 查看包中更完整的文档范围，但仍按默认可见性筛选
go doc -all ./internal/cache

# 同时展开包文档并包含未导出符号
go doc -all -u ./internal/cache

# 查看指定未导出类型的声明与实现细节
go doc -u -src ./internal/cache cacheEntry

# 只看一个公开方法的文档，减少无关输出
go doc ./internal/cache.Cache.Get

可以用一个简单的决策顺序减少误用：

• “整包文档不够全”时先加 -all。
• “小写名称完全不出现”时加 -u。
• “文档只告诉我签名，我还要看实现”时加 -src。
• “输出太大”时不要盲目叠加参数，改成包路径加具体符号。

包文档、符号文档和源码查看不要混在一起

go doc 的参数位置决定了它在查什么。包参数用于进入一个包的文档空间；追加符号名后，命令会把范围收窄到类型、函数、方法或字段；-src 则把目标声明或实现源码带出来。下面这段小型包只用于说明名称边界：

package cache

// Cache 是对外公开的缓存类型，其他包可以通过包路径引用它。
type Cache struct {
	// shards 是未导出字段，只服务于当前包的内部实现。
	shards []map[string][]byte
}

// newShard 是未导出函数，负责创建一个内部分片。
func newShard() map[string][]byte {
	return make(map[string][]byte)
}

针对这个包，下面四种查询的目标不同：

表格中的命令是职责划分，不是四次必须连续执行的流程。查内部字段时，直接使用 -u 加符号定位通常比输出整个包更容易阅读。

包路径和命令包的边界也会造成“看不到”

如果 -u 仍然没有结果，下一层要检查的是查询对象，而不是继续叠加开关。

当前目录和模块路径是否正确

在模块根目录执行 go doc ./internal/cache 与在其他目录执行，包模式的解析结果可能不同。优先使用模块内的相对路径或完整导入路径，并确认目标目录确实包含同一个包名的 Go 文件。

# 从模块根目录查询内部包，避免把相对路径指向错误目录
cd /path/to/your/module
go doc -u ./internal/cache

# 直接使用完整导入路径，适合目录层级较深的模块
go doc -u example.com/project/internal/cache

命令包要不要显示顶层导出符号

当目标是 package main 时，命令包的顶层展示还有一个特殊边界：默认情况下，命令包的导出符号可能被省略；需要把命令当普通包看时使用 -cmd。这和 -u 是两个独立问题：前者解决命令包的展示方式，后者解决未导出符号是否参与文档检索。

# 把 package main 当作普通包展示其公开顶层符号
go doc -cmd ./cmd/worker

# 在命令包中同时查看未导出文档
go doc -cmd -u ./cmd/worker

一份可复用的排查清单

1. 先确认查询的是目标包，而不是相邻目录或另一个同名包。
2. 看到小写名称缺席时，直接尝试 go doc -u。
3. 需要更多包级条目时再加 -all，不要把它误认为“显示未导出”的开关。
4. 需要声明或实现时使用 -src，并尽量追加具体符号。
5. 目标是 package main 时单独判断是否需要 -cmd。
6. 如果名称仍匹配不到，检查大小写、类型方法的限定写法和当前模块目录。

一句话总结：go doc 默认站在公开 API 视角，-u 才是打开未导出符号的关键；-all、-src 和 -cmd 分别处理文档展开、源码查看和命令包展示。

相关问题

go doc -all 为什么还是看不到小写类型？

-all 扩大的是包文档展示范围，未导出名称仍需要 -u。通常直接使用 go doc -all -u 包路径。

go doc -u 会让未导出类型可以被其他包调用吗？

不会。它只改变文档检索结果，不改变 Go 编译器的包级可见性和导入规则。

什么时候应该使用 -src？

当签名和注释不足以解释行为，需要查看声明或实现时使用；为了控制输出，建议同时指定包和符号。