Go testing.F 为什么需要 Fuzz 入口函数

Go 的原生模糊测试不是把一个普通的 TestXxx(*testing.T) 换个名字就结束了。testing.F 是模糊测试的入口对象：它负责接收种子、注册唯一的 Fuzz 回调，并让 go test 知道哪些函数可以被持续变异输入。真正处理每一组输入时，回调拿到的仍然是 *testing.T。

因此，FuzzXxx(*testing.F) 是“测试入口”，f.Fuzz(func(t *testing.T, ...)) 是“单组输入检查器”。没有前者，工具无法发现并调度 fuzz 测试；把 *testing.T 直接当入口，也就没有地方注册种子和 fuzz 目标。

testing.F 是入口，*testing.T 才是每次输入的执行器

Go 的 fuzz 测试有一层很明确的职责分工。测试框架先扫描符合命名和签名规则的 FuzzXxx，调用它完成种子登记，再由 f.Fuzz 注册一个只负责检查单次输入的函数。模糊引擎后续会重复调用这个回调，因此回调应该尽量快速、确定，并且不要依赖会跨调用残留的全局状态。

下面的例子检查一个名称规范化函数是否满足幂等性：规范化一次和规范化两次的结果应该相同。这里的业务函数和测试都是一个可独立替换的小实验。

package normalize

import (
    "strings"
    "testing"
)

// normalizeName 只做边缘空白清理和小写转换，便于观察属性是否稳定。
func normalizeName(s string) string {
    return strings.ToLower(strings.TrimSpace(s))
}

// FuzzNormalizeName 是工具识别的 fuzz 入口，参数必须是 *testing.F。
func FuzzNormalizeName(f *testing.F) {
    // 种子覆盖空白、普通文本和非 ASCII 文本三种起点。
    f.Add("  Go-Test  ")
    f.Add("服务名称")
    f.Add("")

    // 每次变异输入由 *testing.T 负责报告失败，不在这里调用 F 的日志方法。
    f.Fuzz(func(t *testing.T, s string) {
        once := normalizeName(s)
        twice := normalizeName(once)
        if once != twice {
            t.Fatalf("规范化不是幂等的：once=%q twice=%q", once, twice)
        }
    })
}

注意两处容易写错的地方：入口函数名要以 Fuzz 开头，且一个 fuzz 测试只能注册一个 f.Fuzz 目标；回调的第一个参数是 *testing.T，后面才是待变异的基本类型。t.Fatalf、t.Errorf 这类调用属于单次输入的失败报告。

f.Add 为什么必须和 Fuzz 回调逐项匹配

f.Add 的作用是把人工挑选的边界样本放入种子语料。它不是给入口函数传参，也不是替代随机生成器。引擎会从这些样本开始寻找新的覆盖路径，所以种子最好包含空值、边缘空白、编码边界或业务上常见的输入。

匹配关系可以用一张小清单记住：

例如回调改成 func(t *testing.T, b []byte) 后，原来的字符串种子就不再匹配；参数数量、顺序或类型任意一项不一致，都会在测试启动阶段暴露问题。不要为了让编译通过把种子强行转换成另一种语义类型，应该先决定 fuzz 目标真正接收的是字符串还是字节。

失败输入如何变成可复现语料

当 fuzz 回调因为断言失败或 panic 找到问题时，Go 会把导致失败的输入保存为该 fuzz 测试的语料条目，通常位于项目的 testdata/fuzz/FuzzNormalizeName 目录。这个目录中的条目与 f.Add 种子一样，会在普通的 go test 阶段被重新执行。

这里要区分“失败语料”和“业务日志”：失败语料包含的是能重现问题的输入，日志只是当次运行的文字输出。修复代码后，先让这条语料在普通测试中通过，再考虑是否保留它作为长期回归样本。不要在回调里修改共享变量来记录状态，否则并行调用和非确定顺序会让问题变得难以判断。

用 go test 区分种子检查和持续 fuzz

第一次接入时，先运行默认测试，让种子和已有语料过一遍：

# 先执行种子语料，快速确认入口和回调可以工作
go test ./...

# 只运行指定 fuzz 测试的种子或已保存语料
go test -run=FuzzNormalizeName ./...

# 在限定时间内持续变异输入，避免本地实验无限运行
go test -fuzz=FuzzNormalizeName -fuzztime=20s ./...

go test 默认不会长时间进行随机变异；-fuzz 指定一个匹配单个 fuzz 测试的正则，-fuzztime 控制这次实验的时长。若只想复现某个失败条目，可以使用该条目报告中的测试名和语料标识，通过 -run 定向执行。

常见问题

能不能把入口写成 func FuzzXxx(t *testing.T)

不能。工具通过 *testing.F 判断这是 fuzz 入口；*testing.T 应该出现在 f.Fuzz 回调中。

f.Add 可以传任意自定义结构体吗

不能直接传。原生 fuzz 参数使用受支持的基本类型，如 string、[]byte、整数、浮点数和布尔值；复杂对象应在回调内部由这些输入解析得到。

为什么只执行 go test 看不到随机输入

这是默认行为：普通 go test 主要执行种子和已有语料。需要持续变异时，显式增加 -fuzz=FuzzNormalizeName，并用 -fuzztime 设置预算。

记住这一条就够了：testing.F 解决“如何被发现、如何登记种子和目标”，testing.T 解决“这一组输入是否违反属性”。把两层职责分开，入口签名、种子类型和失败语料目录就都能对上。