Learn Go with Tests 章节模板解读:把 TDD 循环固化为每个章节的标准骨架
Learn Go with Tests 章节模板解读:把 TDD 循环固化为每个章节的标准骨架
导读
template.md 是开源书籍《Learn Go with Tests》的章节模板(Chapter template):全书每一章都以测试驱动开发(TDD)的红绿重构循环为骨架展开,从"先写测试"到"重构",再到"为下一个新需求重复"。本文以该模板为核心,逐节拆解它定义的七个标准步骤,并结合仓库中各章节的实际代码演进(如 hello-world、integers、mocking 等目录下的 v1 → vN 版本)说明每一步的落地方式。读完本文,你将掌握一套可复用的 TDD 章节写作/学习结构,并能对照真实 Go 源码看懂"测试先行—最小实现—重构"的完整节奏。
模板是什么:全书统一的 TDD 教学骨架
template.md 全文仅列出章节的标准章节标题:
# Chapter template
Some intro
## Write the test first
## Try to run the test
## Write the minimal amount of code for the test to run and check the failing test output
## Write enough code to make it pass
## Refactor
## Repeat for new requirements
## Wrapping up
它不做具体教学,而是规定每一章的叙事顺序:先给一段引入("Some intro"),然后严格按 TDD 五步循环推进,遇到新需求就重复循环,最后以"Wrapping up"收尾。
这份模板并非孤立文件,而是全书实际执行的写作规范。contributing.md 的 Style guide 明确要求:"Always be reinforcing the TDD cycle. Take a look at the Chapter Template."(始终强化 TDD 循环,参考章节模板)。仓库维护说明 CLAUDE.md 进一步确认:TDD 仪式性标题在各章节中"near-verbatim"(近乎逐字)复现,且步骤太琐碎时可以合并,但不得改名。
从仓库统计看,正文中直接以 ## Write the test first 开头的章节文档多达 27 个(integers.md、iteration.md、arrays-and-slices.md、maps.md、mocking.md、concurrency.md、select.md、reflection.md、sync.md、context.md、http-server.md、json.md、io.md、time.md、websockets.md 等),覆盖 Go 基础语法、标准库特性到完整 Web 应用构建。可以说,这份模板就是整本书"用测试学 Go"方法论的形式化表达。
第一步:Write the test first(先写测试)
模板要求每个新功能先写测试,再写实现。这一步的意义在 hello-world.md 中讲得很清楚:回顾式补测试有"测试在代码不正确时仍然通过"的风险,而测试先行能确保测试真正在验证需求。
以 integers.md 为例,要写一个 Add 函数,先创建 adder_test.go:
package integers
import "testing"
func TestAdder(t *testing.T) {
sum := Add(2, 2)
expected := 4
if sum != expected {
t.Errorf("expected '%d' but got '%d'", expected, sum)
}
}
注意两个细节:
- 使用
%d而不是字符串的%q,因为断言的是整数; - 包名不再是
main,而是按功能分组的integers——Go 中每个目录只能有一个包,目录结构即包结构。
仓库中对应的实际代码位于 integers/v1/adder_test.go,其目录布局与文档描述一致:adder_test.go 与 adder.go 同包共存。
测试文件的基本规则
hello-world.md 总结了 Go 测试文件的三条硬规则:
- 文件名必须以
_test.go结尾(如hello_test.go); - 测试函数名必须以
Test开头; - 测试函数只接受一个参数
t *testing.T,并通过import "testing"引入。
t 是测试框架的"钩子":调用 t.Errorf 会输出格式化消息并让测试失败。模板后续每一步的验证都依赖这条基础设施。
第二步:Try to run the test(运行测试,观察失败)
写完测试后运行 go test。由于实现尚不存在,这一步必然失败,但失败的原因必须是清晰的。
integers.md 中首次运行得到编译错误:
./adder_test.go:6:9: undefined: Add
mocking.md 中则依次出现两个编译错误:先是 undefined: Countdown,随后是 too many arguments in call to Countdown(have (*bytes.Buffer) want ())。
关键认知在 hello-world.md 中反复强调:要"倾听编译器"(listen to the compiler)。Go 是静态类型语言,编译器清楚代码应该如何拼装,编译错误往往直接告诉你下一步该改什么。模板要求先跑测试,正是为了让失败信息成为后续步骤的导航。
注意 Go 模块(Go 1.16+)
hello-world.md 特别提醒:在 Go 1.16 及更高版本中,新目录里直接 go test 会报:
go: cannot find main module; see 'go help modules'
解法是在每个新章节目录先执行 go mod init SOMENAME(如 go mod init example.com/hello),生成 go.mod。模块名与 package main 无关,只是项目标识。仓库根目录的 go.mod 即全书作为单一 Go 模块的体现。
第三步:Write the minimal amount of code(写最小代码让测试可运行)
模板的第三步是:写刚好能让测试运行的最小代码,然后再次观察失败输出。目的不是让测试通过,而是确认"测试为正确的原因失败"。
integers.md 中的最小实现:
package integers
func Add(x, y int) int {
return 0
}
(多个同类型参数可缩写为 (x, y int)。)此时测试运行输出:
adder_test.go:10: expected '4' but got '0'
失败信息准确反映了缺陷——Add 还没真正相加。这就是"为正确的原因失败"。
mocking.md 中,最小实现先写成空函数 func Countdown() {},测试因参数不匹配编译失败,编译器"告诉"你函数签名应该接收一个 *bytes.Buffer,修改后失败信息变为 got '' want '3',同样干净利落。
对应仓库源码:integers/v1/adder.go 中 Add 返回 0,mocking/v1/main.go 中是空实现——每个 v1 目录都定格了"最小实现"这一瞬间。
第四步:Write enough code to make it pass(写足够代码让测试通过)
测试确认失败原因无误后,才进入让测试通过的实现阶段。模板刻意区分"minimal"与"enough":第三步满足编译器即可,第四步才真正实现行为。
integers.md 用一个例子说明 TDD 的边界:严格意义上"最小通过代码"可以是 return 4——但这显然是作弊,需要换一组数字的新测试才能逼出真实实现。作者借此预告了后续章节会介绍**属性测试(Property Based Testing)**来根治这类问题(见 roman-numerals.md)。最终正确的实现:
// Add takes two integers and returns the sum of them.
func Add(x, y int) int {
return x + y
}
hello-world.md 的经典演进路径则是:Hello() → Hello(name string) → Hello(name, language string),每步都在测试驱动下增量展开:
func Hello(name string, language string) string {
if name == "" {
name = "World"
}
prefix := englishHelloPrefix
switch language {
case spanish:
prefix = spanishHelloPrefix
case french:
prefix = frenchHelloPrefix
}
return prefix + name
}
仓库中的 hello-world/v1 到 hello-world/v8 完整保存了这条演进链:v1 只有 hello.go(无测试),v2 引入测试与函数,v3 起逐步加入参数、常量、if、switch、子测试与断言辅助函数。每个版本目录就是模板循环一次迭代的"快照"。
第五步:Refactor(重构)
测试变绿后,模板进入重构环节。重构的定义在仓库文档中有明确表述:refactoring-checklist.md 开篇即给出——重构只是改进既有代码且不改变行为,因此测试不应变动;如果"重构"时不得不改测试,那你做的是别的(设计变更)。
该清单归纳了可安全进行的重构操作:
- 引入私有方法、字段、新类型与接口;
- 修改公共方法内部实现;
- 不能改变行为或方法签名(因为测试与这两者耦合)。
常用重构手法(附 IDE 快捷键)
| 手法 | 说明 | GoLand/IntelliJ 快捷键 |
|---|---|---|
| Inline variables | 变量仅被传递一次时内联 | command+option+n |
| Extract variables | 相同值重复出现时提取命名变量(DRY) | command+option+v |
| Extract constant | 魔法值(magic value)提取为具名常量 | command+option+c |
| Extract method | 把冗长公共方法中的步骤封装为私有方法 | command+option+m |
| Rename(例外) | 重命名公共符号属自动安全变更 | shift+F6 |
hello-world.md 展示了重构的完整范例:通过引入常量 englishHelloPrefix 消除魔法字符串,把 if 链重构为 switch 并抽出私有函数 greetingPrefix,同时把测试中的重复断言提取为辅助函数 assertCorrectMessage(接受 testing.TB 接口并调用 t.Helper(),使失败时报告调用行号而非辅助函数内部)。重构不仅针对生产代码,测试代码同样需要重构。
refactoring-checklist.md 还强调重构的方法论意义:经常性的小重构是良好设计的必要条件——代码若长期不重构,复杂度会指数级累积,届时连讨论整体设计都无从谈起。
新需求循环:Repeat for new requirements
模板在五个步骤之后安排"Repeat for new requirements":一个需求完成后,新的需求重新从"Write the test first"开始。这正是 TDD 迭代式开发的落点。
mocking.md 是绝佳示范:倒计时程序被切成三个可独立迭代的需求——"打印 3"→"打印 3、2、1 和 Go!"→"每行之间等待一秒"。作者明确说明这样切分的重要性:"能尽可能小地切分需求,从而拥有可工作的软件"是重要技能。仓库 mocking 下的 v1 至 v6 六个版本目录,逐一对应这些需求的测试驱动实现(v5 引入 Sleeper 接口与注入,v6 完成倒计时并接入 main)。
hello-world.md 同样如此:从"Hello, world"→"Hello, YOU"→"默认 World"→"支持西班牙语/法语",每个新需求都是"写测试→看失败→最小实现→重构"的完整循环。作者在章末总结道:"我们以小而易于理解的步骤,从 Hello() 走到了 Hello("name", "French")"——这就是"Repeat for new requirements"的成果。
收尾:Wrapping up
每个章节以"Wrapping up"结束,通常以要点列表回顾本章涵盖的内容,有时拆分为带命名的小节(如语法知识点、TDD 过程要点),末尾还可能附加"Additional material/Further reading"链接。
hello-world.md 的收尾极具代表性,它把收获分为两类:
Go 语法:编写测试、带参数与返回值的函数声明、if/const/switch、变量与常量声明。
TDD 过程与每步的意义:
- 先写失败测试并看它失败——确保测试与需求相关,且失败信息易读;
- 写最小代码让它通过——确保拥有可工作的软件;
- 在测试保护下重构——确保代码精良、易于维护。
这段收尾精确回扣了模板的五个步骤,把机械的循环提炼成方法论:TDD 是需要练习才能习得的技能,把问题拆成可测试的小组件,写软件会轻松得多。
模板背后的方法论:为什么每章都要这样写
从 gb-readme.md(本书前言)可以还原模板的设计动机。作者在向团队引入 Go 时试验过多种方式:精读大部头教材、做 kata(代码练习)效果都不理想——前者需要过高投入,后者范围有限且容易让学习变得零散。真正有效的方式是"缓慢引入语言基础,并用测试固化概念":测试既验证了代码正确性,也记录了学到的特性。
contributing.md 则给出了对贡献者的补充约束,它们共同构成模板之外的配套规范:
- 尽量缩小读者所需的知识面(例如学
struct不必先懂指针),简洁至上; - 每个章节末尾应有可运行的应用程序(
package main加main函数),让读者能实际运行体验; - 所有测试必须通过;
- 提交 PR 前运行
./build.sh。
这解释了为什么模板结构如此克制:固定的章节骨架 + 每章独立可运行的代码,让读者可以在任何章节随时停下来动手验证,也保证全书风格一致、贡献者可依模板扩展。
总结
template.md 以极简的七个标题,定义了《Learn Go with Tests》每一章的标准叙事:先写测试 → 运行并观察失败 → 写最小代码确认失败原因 → 写足够代码让测试通过 → 重构 → 新需求循环 → 收尾。模板的价值不在篇幅,而在纪律——它把"测试先行、小步前进、随时重构"的 TDD 精神固化成可复制的写作与学习流程。对照仓库中 hello-world、integers、mocking 等目录的 v1 → vN 版本演进,可以看到每一步在真实 Go 代码中的落地形态;而 refactoring-checklist.md、contributing.md、CLAUDE.md 则从不同侧面补充了模板的配套规范。无论你是想按此结构自学 Go,还是仿照它组织自己的技术教程,这份模板都是一套经过 27 个章节验证的可靠骨架。