Go fuzzing 种子语料库的目录组织方式

Go fuzzing 的种子语料库不要按“文件越多越好”来堆。更稳妥的组织方式是先按 Go package 划边界，再按 FuzzTestName 拆目录，最后按样本用途管理文件。这样，某个输入属于哪个 Fuzz 目标、是否会在普通 go test 中回归、能不能安全提交到仓库，都能在目录层面看出来。

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

把 f.Add 中的少量最小种子和 testdata/fuzz/FuzzTestName 中的文件型种子视为同一个目标的输入资产；目录只服务一个 Fuzz 目标，样本进入仓库前经过脱敏、最小化和代码评审。

先明确 seed corpus 的目录边界

Go 官方文档把 seed corpus 定义为用户提供给某个 fuzz test 的初始输入，来源包括 fuzz 测试里的 f.Add，以及 package 下的 testdata/fuzz/{FuzzTestName} 文件。这里的关键不是目录名称本身，而是最后一级目录必须对应一个明确的 Fuzz 目标。

推荐把项目结构收敛为下面这样：

parser/
├── parser.go
├── parser_test.go
└── testdata/
    └── fuzz/
        ├── FuzzParse/
        │   ├── protocol-header
        │   ├── empty-payload
        │   └── regression-2026-01
        └── FuzzRoundTrip/
            ├── unicode-boundary
            └── escaped-delimiter

# 每个末级目录只对应一个 Fuzz 目标，避免样本被错误的函数消费
# 文件名描述输入边界或回归来源，不把账号、令牌等敏感信息写进样本

FuzzParse 和 FuzzRoundTrip 即使都处理字节切片，也不建议共用一个目录。目录隔离能减少误用：维护者看到一个失败样本时，可以直接判断它应该回归哪个目标，而不必猜测参数顺序和解析协议。

用最小代码种子表达稳定基线

目录文件适合保存较长的协议样本或需要单独评审的回归输入，但最小、稳定、每次都应该跑的基线可以直接写在 f.Add 中。下面的示例把一个合法输入和一个空输入作为起点，真正的解析逻辑仍由被测函数负责。

func FuzzParse(f *testing.F) {
	// 把最小且稳定的边界样本直接登记为种子，便于每次 go test 回归。
	f.Add([]byte("name=go"))
	f.Add([]byte{})

	f.Fuzz(func(t *testing.T, input []byte) {
		// 模糊输入不能改变测试进程的全局状态，异常只归因于当前样本。
		_, err := Parse(input)
		if err != nil {
			// 解析失败是允许结果；这里仅约束不能 panic 或泄漏资源。
			return
		}
	})
}

种子参数的类型和顺序必须与 fuzz 函数参数一致。若目标接收 []byte 和 int64，目录里的 corpus 文件也要编码为相同顺序的值，不能因为文件名写了“整数样本”就改变实际参数格式。

文件型种子按用途分组，不按随机结果命名

进入 testdata/fuzz/FuzzParse 的文件最好能回答“为什么保留它”。可以用三类用途管理，而不必把随机生成的哈希直接当成业务名称：

文件名可以使用 protocol-header、empty-payload、regression-2026-01 这类短名称。真正的事件背景写在相邻的变更说明或提交信息里，避免把内部工单号、用户标识和原始请求体直接暴露在仓库路径中。

把种子样本当作需要审计的输入资产

模糊测试输入不是普通测试数据。它可能包含真实请求片段、个人数据、访问令牌或触发高资源消耗的超大文件。发布到仓库之前，至少要把样本看成一项需要保护的输入资产：脱敏后再提交，尽量缩小，说明来源，限制只能被对应的 Fuzz 目标消费。

# 先列出目标目录中的文件，确认新增样本只落在预期的 Fuzz 目标下
find testdata/fuzz/FuzzParse -maxdepth 1 -type f -print

# 查看版本差异，重点检查凭据、真实用户数据和无关的大文件
git diff -- testdata/fuzz/FuzzParse

# 普通测试会重新消费已提交的 seed corpus，作为回归入口
go test ./...

这些命令不能证明样本“绝对安全”，但能把目录范围、版本差异和回归入口固定下来。需要更强的隔离时，把来源不明或资源消耗异常的输入留在受控工作区，不要为了追求覆盖率直接提交。

运行时怎样区分回归与持续 fuzzing

普通 go test 会运行 seed corpus，因此目录中的失败样本修复后仍然会成为回归测试。持续 fuzzing 则需要显式指定目标和时间，例如：

# 先跑固定种子，确认目录中的已知输入没有破坏基础回归
go test ./parser

# 在受控环境中继续探索 FuzzParse，时间参数按团队资源设置
go test -fuzz=FuzzParse -fuzztime=30s ./parser

持续 fuzzing 产生的输入与仓库种子不是同一层资产。Go 的 fuzzing 引擎会维护生成语料；团队应先复现、最小化、脱敏，再把真正有长期回归价值的输入复制到对应的 testdata/fuzz/FuzzParse，而不是把缓存目录整体提交。

常见目录误区

把所有 Fuzz 目标的文件放进一个 corpus 目录

这会模糊参数契约和归属。一个目录只服务一个 Fuzz 目标，跨目标复用时复制并重新审查，比共享目录更容易追踪。

把失败样本原样提交

失败样本可能含有真实输入和敏感字段。先缩小到能复现问题的最小样本，再脱敏，并在提交说明中写清它对应的修复。

用文件名代替 corpus 编码

文件名只是维护线索，Go 仍按 corpus 文件格式和 fuzz 参数类型解析内容。类型、顺序和版本头必须符合官方格式。

把 GOCACHE 中的生成语料复制进仓库

生成语料服务于持续 fuzzing 的探索，只有经过复现与筛选后才适合成为稳定 seed。缓存本身不应作为仓库目录结构。

一份可执行的目录检查清单

• 每个 package 的种子是否位于自己的 testdata/fuzz 下。
• 最后一级目录名是否与 Fuzz 目标名称一致。
• 每个文件能否说明用途，并且没有凭据、个人数据或无关超大内容。
• 新增回归样本是否已最小化、脱敏，并附带修复背景。
• go test 是否能把固定 seed corpus 当作普通回归入口。
• 持续 fuzzing 的缓存是否与仓库中的稳定种子分开。

目录设计的目标不是让 fuzzing 看起来整齐，而是让输入边界可发现、样本来源可追溯、回归行为可重复。按 Fuzz 目标隔离目录，再用用途和审计规则约束文件，后续扩充语料库时就不会把覆盖率、复现和安全责任混在一起。