 

> 📝 一个"偷懒型"开发者的效率秘籍 | ⏱️ 阅读 4 分钟 | ✨ 文档即测试成就解锁

---

## 🎬 起因：我又被文档坑了

上周写了一个"字符串工具包"，想给同事用。打开 `pkg.go.dev` 一看文档...

结果：❌ 示例代码是半年前的；❌ 注释说"返回大写"，实际返回小写；❌ 同事照着抄，线上 `panic` 了。

> 🤦‍♂️ 那一刻我悟了：**文档不跑测试，等于没写**。

于是我翻出了 Go 的"隐藏技能"：**可执行示例（Executable Examples）**。用了一周，现在我的工具库文档，每个示例都能点"Run"直接跑，还能自动防过期。真香警告⚠️

 
---

## 🧱 第一步：3 分钟上手，把普通函数"变"成可运行示例

假设我写了个超简单的"字符串反转"函数：

```go
// reverse/reverse.go
package reverse

func String(s string) string {
    runes := []rune(s)
    for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
        runes[i], runes[j] = runes[j], runes[i]
    }
    return string(runes)
}
```

### ✅ 操作步骤：

**1️⃣ 在 `_test.go` 文件里写示例函数**
```go
// reverse/reverse_test.go
func ExampleString() {
    fmt.Println(String("hello"))
    // Output:
    // olleh
}
```

**2️⃣ 关键点：`// Output:` 注释不是装饰！**
- 这是测试期望值，`go test` 会拿实际输出跟它比对
- 输出不匹配？测试直接红，逼你更新文档或修代码

**3️⃣ 跑起来验证**
```bash
$ go test -v ./reverse
=== RUN   ExampleString
--- PASS: ExampleString (0.00s)
PASS
```

💡 **爽点**：这个示例会自动出现在 `pkg.go.dev` 的文档里，用户点"Run"就能在浏览器里试玩，不用装 Go 环境！

---

## 🎨 第二步：给常用工具函数加"活"文档

### 📌 示例 1：计算阶乘（带边界处理）

```go
// factorial/factorial.go
func Calc(n int) (int, error) {
    if n < 0 {
        return 0, fmt.Errorf("negative number: %d", n)
    }
    if n <= 1 {
        return 1, nil
    }
    result := 1
    for i := 2; i <= n; i++ {
        result *= i
    }
    return result, nil
}
```

```go
// factorial/factorial_test.go
func ExampleCalc_normal() {
    result, _ := Calc(5)
    fmt.Println(result)
    // Output:
    // 120
}

func ExampleCalc_error() {
    _, err := Calc(-3)
    fmt.Println(err)
    // Output:
    // negative number: -3
}
```

> ✨ **技巧**：一个函数可以写多个示例，用 `_` 后缀区分，文档里会并列展示，用户一眼看懂正常/异常场景。

### 📌 示例 2：处理"无序输出"的场景

切片去重后，如果用 `map` 做中间存储，遍历顺序不确定，怎么办？

```go
// unique/unique.go
func Ints(nums []int) []int {
    seen := make(map[int]bool)
    var result []int
    for _, n := range nums {
        if !seen[n] {
            seen[n] = true
            result = append(result, n)
        }
    }
    return result
}
```

```go
// unique/unique_test.go
func ExampleInts() {
    nums := []int{3, 1, 2, 1, 3}
    unique := Ints(nums)
    // 排序后再输出，保证顺序固定
    sort.Ints(unique)
    fmt.Println(unique)
    // Output:
    // [1 2 3]
}
```

✅ 如果实在不想排序，也可以加 `// Unordered output:`，测试只检查"这些值都有"，不关心顺序。

---

## 📦 第三步：进阶玩法，示例也能"组团"

### 🔹 给整个包写"入门示例"

```go
// 不带函数名，就是包级示例
// mathutil/mathutil_test.go
func Example() {
    // 演示工具包常用组合
    a := Add(2, 3)        // 5
    b := Multiply(a, 4)   // 20
    fmt.Println(IsEven(b))
    // Output:
    // true
}
```

### 🔹 给类型和方法写示例

```go
// counter/counter.go
type Counter struct {
    count int
}

func (c *Counter) Inc() {
    c.count++
}

func (c *Counter) Value() int {
    return c.count
}
```

```go
// counter/counter_test.go
func ExampleCounter_basic() {
    var c Counter
    c.Inc()
    c.Inc()
    fmt.Println(c.Value())
    // Output:
    // 2
}

func ExampleCounter_reset() {
    c := Counter{count: 10}
    c.count = 0  // 直接重置内部字段（演示用，生产环境建议加 Reset() 方法）
    fmt.Println(c.Value())
    // Output:
    // 0
}
```

> 🎯 命名口诀：`Example` + `类型名` + `_` + `方法名`，文档工具自动关联，不用手动配置。

---

## 💡 第四步：集成到我的开发流

### 🔄 本地开发：示例即测试
```bash
# 每次改代码，跑测试顺便验证文档
$ go test ./... -run Example
# ✅ 所有示例通过，文档放心发布
```

### 🚀 CI/CD：防"文档腐烂"
```yaml
# .github/workflows/test.yml
- name: Verify examples
  run: go test -run Example ./...
# 💥 示例挂了？合并请求直接拦下，逼你更新文档
```

### 🌐 线上文档：用户能"玩"的代码
- 用户访问 `pkg.go.dev/我的工具库`
- 看到示例 → 点"Run" → 浏览器里直接看效果
- 不用 `git clone`，不用 `go install`，零门槛体验函数行为

 
---

## 🎯 复盘：为什么我强烈安利这个功能？

| ✅ 真香点 | 💡 适用场景 |
|----------|------------|
| 📚 文档自动同步代码，永不"过期" | 写工具库/算法包，希望用户快速上手 |
| 🧪 示例即测试，改代码先过文档关 | 团队协作，减少"文档谁维护"的扯皮 |
| 🌍 用户浏览器里直接试玩，降低使用门槛 | 开源项目，需要大量代码演示 |
| ⚡ 写一次，两用（文档+测试），效率翻倍 | 个人项目，想偷懒但又要专业感 |

> 🤔 **我的血泪经验**：以前写文档像"写情书"，写完就忘；现在写示例像"写剧本"，每次跑测试都是"彩排"，上线自然稳。

---

## 🎬 尾声：让代码自己"说话"

上周有同事问："这个 `UniqueInts` 函数，输入空切片会返回 `nil` 还是空切片？"

以前我得：查代码→写回复→贴截图→等反馈。

这次我直接回："点这个示例链接，改输入为 `[]int{}` 点 Run，看输出👇"

30 秒后同事回复："👍 懂了，返回空切片，文档真方便！"

 
那一刻我觉得：**最好的文档，不是写得最漂亮的，而是用户能亲手"玩"起来的。**

--- 

📝 一个"偷懒型"开发者的效率秘籍 | ⏱️ 阅读 4 分钟 | ✨ 文档即测试成就解锁

用 Go 可执行示例，让文档自己跑测试！

编程语言

测试

开发工具

Go开发者必看！揭秘"文档即测试"黑科技，用ExecutableExamples让代码示例永不过期。3分钟学会为函数添加可运行示例，用户浏览器点Run即可测试，自动同步代码变更。解决文档与代码不一致痛点，提升协作效率，开源项目必备技能！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

用 Go 可执行示例，让文档自己跑测试！-腾讯云开发者社区-腾讯云

用 Go 可执行示例，让文档自己跑测试！

用 Go 可执行示例，让文档自己跑测试！

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐