Go fuzz 测试怎样限制输入并保留回归样例

Go 原生 fuzz 测试的关键不是无限制地制造随机输入，而是把“可接受的参数边界、少量种子、可重复的目标函数和失败样例”连成一个闭环。用 testing.F 写好一个 FuzzXxx 后，f.Add 负责提供稳定起点，f.Fuzz 负责定义被变异的参数；一旦发现失败输入，Go 会把它写入该 fuzz 测试的语料目录，后续普通测试也会重新执行它。

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

限制输入靠参数类型和测试前置条件，保留回归样例靠 testdata/fuzz/FuzzXxx。不要把随机性放进全局状态，也不要只依赖一次长时间 fuzz 运行的结果。

• 一个 fuzz 测试函数只接收一个 *testing.F，并且只注册一个 fuzz target。
• f.Add 的每个参数必须和 f.Fuzz 回调的 fuzz 参数类型、顺序完全一致。
• 普通 go test 会执行已有种子与失败样例；go test -fuzz 才会继续探索新输入。

先把 fuzz 输入边界固定下来

假设要测试一个把文本截断到指定长度的函数。这里把输入限定为 string 和 int，测试目标只关心长度非负且不超过字符串长度的场景。边界条件先写在目标函数里，避免把“参数不合法”与真正要发现的实现缺陷混在一起。

package textutil

import "testing"

// FuzzTruncate 只接收 Go fuzz 支持的基础参数，并注册一个目标函数。
func FuzzTruncate(f *testing.F) {
	// 种子覆盖空文本、短文本和长度边界，类型顺序必须与回调一致。
	f.Add("", 0)
	f.Add("gopher", 1)
	f.Add("gopher", 6)

	// 每次调用都根据当前输入计算，不把状态泄漏到下一次调用。
	f.Fuzz(func(t *testing.T, text string, n int) {
		if n  len(text) {
			return // 先排除不属于本例边界的输入。
		}

		got := Truncate(text, n)
		if len(got) > n {
			t.Fatalf("结果长度 %d 超过限制 %d", len(got), n)
		}
	})
}

这里的“限制输入”不是限制 fuzz 引擎只能生成三个值，而是先用类型签名规定可变异的字段，再用测试前置条件过滤不属于当前断言的组合。若把负数也纳入产品需求，就应该为它写出明确的预期，而不是直接忽略。

种子语料怎样覆盖真正重要的边界

f.Add 适合放少量、可读、长期稳定的起点。文本类输入至少应考虑空值、一个字符、刚好达到限制的值，以及包含多字节字符的值；整数则关注 0、1、最大业务边界和一个明显越界值。种子不是越多越好，重点是让普通 go test 能快速复现最重要的约束。

// 这些种子用于覆盖边界，而不是模拟完整线上样本。
f.Add("", 0)             // 空输入与零长度。
f.Add("Go", 1)           // 最小正长度。
f.Add("你好Go", 5)       // 多字节文本，提醒实现注意字节与字符语义。
f.Add("long-input", 99) // 明显越界，交给测试前置条件决定如何处理。

如果种子需要携带多个参数，顺序必须和回调一致，例如 f.Add([]byte("abc"), int64(3)) 对应 func(t *testing.T, data []byte, limit int64)。类型不一致时，问题发生在 fuzz 目标契约层，不应靠在回调内部强制转换来掩盖。

探索时间和并发要设成可控范围

日常回归建议用普通测试快速跑完种子；需要探索时，再指定一个明确的 -fuzztime，避免开发机或 CI 无边界运行。-parallel 可以控制同时运行的 fuzz 进程数，但目标函数必须足够快、确定，并且不能依赖全局可变状态。

# 只探索指定 fuzz 目标 30 秒，避免 CI 无限等待。
go test -fuzz=FuzzTruncate -fuzztime=30s ./...

# 日常回归只执行种子和已经保存的失败样例。
go test ./...

如果 fuzz 目标内部访问网络、时间或共享缓存，随机输入带来的结果可能不可重复。应把外部依赖替换成固定输入，或将这类集成行为移到独立测试中；fuzz 目标本身只保留可以快速判断的纯逻辑。

失败输入怎样变成长期回归样例

当 fuzz 引擎发现 panic、断言失败或执行超时，会尝试缩小输入，并将仍能触发问题的最小样例写入 testdata/fuzz/FuzzTruncate。修复代码后不要删除这份文件：普通 go test 会重新执行它，样例就从“偶然发现”变成了版本库里的回归约束。

# 目录结构示意：文件内容由 Go fuzz 语料格式保存。
example/
├── truncate.go
├── truncate_test.go
└── testdata/fuzz/FuzzTruncate/
    └── 7f3a...  # 失败输入的最小化语料文件

提交回归样例时，代码修复和语料文件要放在同一个变更中，并在评审说明里写清触发条件。不要手工把未知格式文件改成普通文本；语料文件的参数类型和顺序必须与 fuzz target 保持一致。

常见误区

• 把 f.Add 当成完整测试集：它只是种子，探索阶段仍会生成并保存新的有价值输入。
• 在 fuzz 回调里修改全局变量：并发和非确定执行顺序会让失败难以复现。
• 发现失败后只修代码不提交语料：下一次回归可能再次漏掉同一边界。
• 用不匹配的参数类型调用 f.Add：先对齐参数顺序和类型，再讨论业务断言。

常见问题

只想限制 fuzz 输入数量，应该怎么做？

用参数类型和测试前置条件定义边界，再用 -fuzztime 或迭代次数控制探索预算。不要为了限制数量而删除边界种子。

失败样例会不会只在 fuzz 模式下执行？

不会。保存到对应 testdata/fuzz/FuzzXxx 目录的语料属于该 fuzz 测试的种子集合，普通 go test 也会执行它们。

为什么 fuzz 回调必须避免全局状态？

fuzz 引擎可能并行、以非确定顺序调用目标函数；全局状态会让同一输入的结果受前一次调用影响，降低复现和定位质量。

实际落地时可以把流程压缩成一句话：用 f.Add 放稳定边界，用 f.Fuzz 写独立断言，用受控的 -fuzztime 做探索，再把失败文件和修复一起提交。这样 fuzz 测试才会持续产生可维护的回归价值。