终结十年纠结：Go 新提案允许 Example 支持任意函数签名

本文永久链接 – 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 对象的示例代码。

十年博弈：从 #21111 到 #64993 的宿命碰撞

为了解决这两个痛点，Go 社区实际上进行了两场旷日持久的战役：

战役 1：允许 Example 返回 error（#21111 – 始于 2017 年）

早在 2017 年，大牛 rogpeppe 就提出了这个想法。但当时官方为了等待 Go 2 的整体错误处理方案（Error Handling Draft）而将其无限期搁置。随着 Go 错误语法提案被无限期延迟，这个 hold 也终于在近年被拿掉。

战役 2：允许入参带上 *testing.T（#64993 – 始于 2024 年）

随着多智能体测试和 synctest（需要虚拟时间同步）等现代测试技术的发展，开发者越来越需要展示涉及 testing.T / testing.B / testing.F 的完整用例。但因为不支持入参，大家不得不写出复杂的 Stub（伪造类）去强行拼凑。

大一统方案 #79808：允许任意函数签名的 Example！

面对这两个互相纠缠、细节极其复杂的提案，Go 核心团队的 neild 指出，之前的讨论之所以陷入死胡同，是因为大家把 “文档如何展示示例（Rendering）” 与 “测试框架如何运行示例（Execution）” 混为一谈了。

如果我们彻底将这两者解耦呢？

在 Issue #79808 中，他提出了一个近乎完美的极简方案：对 Example 函数的签名彻底放开限制。

1. 规则大解放

只要你的函数命名符合 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)
}

2. 完美的运行防线

如果放开了签名限制，go test 怎么运行它们？

对于有参数或返回值的 Example：testing 包一律不自动运行它们。这极大地简化了测试运行器的复杂度，避免了处理带有复杂入参的函数执行。
防止混淆：如果一个 Example 带有入参或返回值，但你却在末尾写了 // Output: 注释，go test 会直接抛出编译期错误，防止开发者产生误解。
如何跑测试？：如果你依然希望在测试中运行这些复杂的示例，非常简单，写一个伴随的 Test… 函数手动调用它即可：

func TestExample_returning_an_error(t *testing.T) {
  if err := Example_returning_an_error(); err != nil {
    t.Fatal(err)
  }
}

小结：让代码回归纯粹

从这个跨越十年的提案博弈中，我们能清晰地感受到 Go 团队的实用主义工程哲学：

他们没有为了解决问题而去创造一套复杂的、充满各种边界特例的编译器黑魔法，而是通过“将文档展示与执行引擎完全剥离”这一解耦思路，在不增加运行时负担的前提下，完美解决了长期折磨开发者的体验难题。

让文档回归原本纯粹的模样，让代码不再为古板的规则而妥协。这也是 Go 语言吸引系统工程师的魅力所在。

资料链接：

https://github.com/golang/go/issues/21111
https://github.com/golang/go/issues/64993
https://github.com/golang/go/issues/79808

还在为写 Agent 框架频频死循环、上下文爆炸而束手无策？我的新专栏 《从0 开始构建 Agent Harness》 将带你：

抛弃臃肿框架，回归“驾驭工程 (Harness Engineering)”的第一性原理
用 Go 语言手写 ReAct 循环、并发拦截与上下文压缩引擎等，复刻极简OpenClaw
构建坚不可摧的 Safety Middleware 与飞书人工审批防线
在底层实现 Token 成本审计、链路追踪与自动化跑分评估
从“调包侠”进化为掌控大模型边界的“AI 操作系统架构师”

扫描下方二维码，开启从 0 开始构建Agent Harness 的实战之旅。

原「Gopher部落」已重装升级为「Go & AI 精进营」知识星球，快来加入星球，开启你的技术跃迁之旅吧！

我们致力于打造一个高品质的 Go 语言深度学习 与 AI 应用探索 平台。在这里，你将获得：

体系化 Go 核心进阶内容: 深入「Go原理课」、「Go进阶课」、「Go避坑课」等独家深度专栏，夯实你的 Go 内功。
前沿 Go+AI 实战赋能: 紧跟时代步伐，学习「Go+AI应用实战」、「Agent开发实战课」、「Agentic软件工程课」、「Claude Code开发工作流实战课」、「OpenClaw实战分享」等，掌握 AI 时代新技能。
星主 Tony Bai 亲自答疑: 遇到难题？星主第一时间为你深度解析，扫清学习障碍。
高活跃 Gopher 交流圈: 与众多优秀 Gopher 分享心得、讨论技术，碰撞思想火花。
独家资源与内容首发: 技术文章、课程更新、精选资源，第一时间触达。

衷心希望「Go & AI 精进营」能成为你学习、进步、交流的港湾。让我们在此相聚，享受技术精进的快乐！欢迎你的加入！

img{512x368}