本文永久链接 – https://tonybai.com/2026/06/09/go-proposal-examples-to-support-arbitrary-function-signatures
大家好，我是Tony Bai。
在 Go 语言的开发日常中，编写 ExampleXxx 示例代码不仅是完善文档的必经之路，更是一门绝佳的“活文档”艺术。
通过在 “_test.go” 文件中编写以 Example 开头的函数，并在末尾加上 // Output: 注释，Go 官方的 go doc 和 pkgsite 就能在网页上直接渲染出可交互、可直接在浏览器中运行（Playable）的示例代码。
然而，在这个看似优雅的设计背后，却隐藏着一个让全球 Go 工程师如鲠在喉、折磨了大家近十年的“硬伤”：Go 官方对 Example 函数的签名有着极其死板的限制——它必须是无参、无返回值的空函数。
为了这个限制，我们在写文档示例时，不得不写出大量极度违背 Go 地道（Idiomatic）编程哲学的样板代码。
为了彻底拔掉这根刺，Go 编译器团队核心成员Damien Neil (neild)提交了一项被称为“大一统”的提案——Issue #79808：允许 Example 示例支持任意函数签名！
这项提案不仅终结了社区自 2017 年以来的长期争论（#21111 与 #64993），更用一种极其巧妙且务实的“解耦设计”，为 Go 语言的文档生态减负。
在真实的 Go 工程中，几乎所有的文件读写、网络调用都会返回 error。按照 Go 的地道写法，当我们调用一个可能失败的函数时，最自然的反应是直接将错误向上抛出：
// 我们真正希望在文档里向用户展示的地道写法
func ExampleReadFile() error {
data, err := os.ReadFile("config.json")
if err != nil {
return err // 优雅直接
}
fmt.Println(string(data))
return nil
}
但是，在目前的 Go 版本中，这行不通！ 因为 Example 函数不允许有任何返回值。
为了写出一个能通过 go test 验证的示例，你被迫在你的示例代码中写满各种“废话”：
// 迫于规则，我们不得不写出的妥协版本
func ExampleReadFile() {
data, err := os.ReadFile("config.json")
if err != nil {
log.Fatal(err) // 或者使用更难看的 panic(err)
}
fmt.Println(string(data))
// Output: { "port": 8080 }
}
这带来了一个极其糟糕的引导效应：新手在阅读官方文档时，会误以为在业务代码中遇到错误就应该直接 log.Fatal 或 panic。 示例代码不仅没能展示出 Go 语言优雅的错误处理哲学，反而成了不良编码习惯的传染源。
此外，当你在编写测试框架（Test Framework）或者使用 Go 新版引入的 synctest 虚拟时钟技术时，你必须拿到底层的 *testing.T 对象。但由于 Example 函数不能有入参，你根本无法写出一个可以传递 t *testing.T 对象的示例代码。
为了解决这两个痛点，Go 社区实际上进行了两场旷日持久的战役：
早在 2017 年，大牛 rogpeppe 就提出了这个想法。但当时官方为了等待 Go 2 的整体错误处理方案（Error Handling Draft）而将其无限期搁置。随着 Go 错误语法提案被无限期延迟，这个 hold 也终于在近年被拿掉。
随着多智能体测试和 synctest（需要虚拟时间同步）等现代测试技术的发展，开发者越来越需要展示涉及 testing.T / testing.B / testing.F 的完整用例。但因为不支持入参，大家不得不写出复杂的 Stub（伪造类）去强行拼凑。
面对这两个互相纠缠、细节极其复杂的提案，Go 核心团队的 neild 指出，之前的讨论之所以陷入死胡同，是因为大家把 “文档如何展示示例（Rendering）” 与 “测试框架如何运行示例（Execution）” 混为一谈了。
如果我们彻底将这两者解耦呢？
在 Issue #79808 中，他提出了一个近乎完美的极简方案：对 Example 函数的签名彻底放开限制。
只要你的函数命名符合 Example 或 ExampleXxx（且首字母大写），go doc 和 pkgsite 就会一律无条件地将其作为示例代码在网页上展示出来！
无论你的函数长成什么样：
package example_test
// 场景 A：优雅返回 error，不再需要 log.Fatal
func Example_returning_an_error() error {
f, err := os.Open("testfile")
if err != nil {
return err
}
defer f.Close()
return nil
}
// 场景 B：支持传入 testing.T，测试框架类的完美示范
func ExampleFunc_taking_a_t(t *testing.T) {
if err := examplepackage.Func(t); err != nil {
t.Fatal(err)
}
}
// 场景 C：甚至可以带上输入输出参数
func Example_in_and_out(a, b int) string {
return examplepackage.AddReturningString(a, b)
}
如果放开了签名限制，go test 怎么运行它们？
func TestExample_returning_an_error(t *testing.T) {
if err := Example_returning_an_error(); err != nil {
t.Fatal(err)
}
}
从这个跨越十年的提案博弈中，我们能清晰地感受到 Go 团队的实用主义工程哲学：
他们没有为了解决问题而去创造一套复杂的、充满各种边界特例的编译器黑魔法，而是通过“将文档展示与执行引擎完全剥离”这一解耦思路，在不增加运行时负担的前提下，完美解决了长期折磨开发者的体验难题。
让文档回归原本纯粹的模样，让代码不再为古板的规则而妥协。这也是 Go 语言吸引系统工程师的魅力所在。
资料链接：
还在为写 Agent 框架频频死循环、上下文爆炸而束手无策？我的新专栏 《从0 开始构建 Agent Harness》 将带你：
扫描下方二维码，开启从 0 开始构建Agent Harness 的实战之旅。
原「Gopher部落」已重装升级为「Go & AI 精进营」知识星球，快来加入星球，开启你的技术跃迁之旅吧！
我们致力于打造一个高品质的 Go 语言深度学习 与 AI 应用探索 平台。在这里，你将获得：
衷心希望「Go & AI 精进营」能成为你学习、进步、交流的港湾。让我们在此相聚，享受技术精进的快乐！欢迎你的加入！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
© 2026, bigwhite. 版权所有.
Related posts:
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。