testing.F.Fuzz 组织最小种子并限制输入范围的设计

写 fuzz test 时，种子不是越多越好，范围也不是交给 f.Add 就结束了。更稳妥的做法是先把被测函数真正关心的输入边界写出来，再用少量种子覆盖正常值、边界值和一个能触发错误处理的代表值；进入 f.Fuzz 后，再用守卫把明显不属于本问题的随机输入提前排除。

下面用“根据协议和端口生成端点字符串”的小例子说明这套设计。重点不是实现一个 URL 库，而是看清种子语料、范围限制和两种运行模式分别负责什么。

先把 fuzz target 的输入边界说清楚

假设被测函数只接受 http 或 https，端口范围是 1 到 65535，协议字符串也不希望无限增长。这个边界可以先写成一张小表：

这里的“有效范围”是文章示例定义的业务边界，不是 Go fuzzing 引擎的全局配置。引擎仍可能生成范围外的字符串和整数，所以真正的限制要在目标函数中表达。

用 f.Add 放入最小种子组合

f.Add 把一组参数注册为 seed corpus。每次调用的参数类型和顺序，都要与 f.Fuzz 传入的随机参数对应。种子的任务是快速走过关键路径，不是把所有可能输入列成测试数据表。

package endpoint_test

import (
    "fmt"
    "testing"
)

func endpoint(scheme string, port int) (string, error) {
    if scheme != "http" && scheme != "https" {
        return "", fmt.Errorf("unsupported scheme: %s", scheme)
    }
    if port  65535 {
        return "", fmt.Errorf("invalid port: %d", port)
    }
    return fmt.Sprintf("%s://service:%d", scheme, port), nil
}

func FuzzEndpoint(f *testing.F) {
    f.Add("http", 80)   // 常用正常值，先进入主路径
    f.Add("https", 443) // 第二个协议分支，避免只测 http
    f.Add("http", 1)    // 下边界；最大端口由 fuzz 输入覆盖

    f.Fuzz(func(t *testing.T, scheme string, port int) {
        // 范围守卫只保留本例关心的输入，减少无效执行噪声。
        if len(scheme) > 5 || port  65535 {
            return
        }
        if scheme != "http" && scheme != "https" {
            return // 未知协议属于本例之外，不在这里断言业务结果
        }

        got, err := endpoint(scheme, port)
        if err != nil {
            t.Fatalf("endpoint(%q, %d): %v", scheme, port, err)
        }
        if got == "" {
            t.Fatal("endpoint returned an empty string") // 有效输入不能得到空结果
        }
    })
}

这组种子只有三个，但分别表达了常用协议、另一个有效分支和端口下边界。端口 65535 不一定要手工再加一条，因为范围守卫允许 fuzz 引擎在变异过程中自行探索它；如果这个最大值曾经触发过缺陷，则应该把它保留为明确种子或回归语料。

范围守卫应该放在什么位置

范围守卫要放在 fuzz target 的最前面，先筛掉长度过大、整数越界和不属于本场景的枚举值。这样做有三个好处：目标函数的断言只面对真正的业务输入，运行时间不会被无关输入大量占用，读者也能一眼看出“测试了什么”。

但早返回不是断言成功。它只表示该输入不在当前性质的适用域中。如果你把所有输入都用 return 掉，fuzz 过程可能很快结束，却没有验证任何有价值的路径。至少要让种子进入有效域，并让守卫后的代码包含可观察的不变量。

还要区分“输入范围”和“失败条件”。例如端口为 0 可能是无效业务值；如果你的 API 明确要求它报错，那么应单独写种子和断言错误，而不是把它静默跳过：

func TestEndpointRejectsZeroPort(t *testing.T) {
    got, err := endpoint("http", 0)
    if err == nil {
        t.Fatalf("endpoint returned %q, want an error", got) // 明确记录无效端口的契约
    }
}

换句话说，fuzz target 适合验证有效域内的性质；少量单元测试适合精确验证已知的错误边界。两者组合比把所有规则都塞进一个 fuzz 回调更容易维护。

代码种子和 testdata/fuzz 怎么选

Go 的 seed corpus 有两种常见来源：在 fuzz 函数里调用 f.Add，或者把语料文件放到包内的 testdata/fuzz/FuzzEndpoint 目录。两者都会在普通 go test 时执行，也能作为开启 fuzz 后的起点。

短小、稳定、能直接说明边界的输入，放在 f.Add 里更直观；曾经由 fuzz 发现、需要长期回归的复杂输入，放入目录更适合版本管理。文件语料的编码格式由 Go fuzzing 定义，不要手工把任意日志或 JSON 直接改名塞进去。

例如，项目中可以保留 endpoint_test.go 和 testdata/fuzz/FuzzEndpoint/corpus-http；语料文件本身使用 Go 定义的编码格式，不额外插入注释：

go test fuzz v1
string("http")
int(80)

种子语料的参数类型和顺序必须与目标函数一致。若目标函数改成 func(t *testing.T, port int, scheme string)，原先按字符串再整数编码的文件就不能继续当作同一条语料使用。调整签名时，应同步检查目录语料和 f.Add 调用。

先用 go test 做回归，再开启 fuzz

运行顺序可以分成两层。第一层只跑已有种子，确认种子本身不会让测试失败：

# 先执行种子语料，适合日常回归和快速定位
go test -run=FuzzEndpoint

# 只跑当前包的全部测试时，也会执行该 fuzz test 的种子
go test

第二层才让引擎持续生成变异输入，并用时长控制这次探索成本：

# 用短时长观察覆盖路径；持续时间按 CI 或本地资源调整
go test -fuzz=FuzzEndpoint -fuzztime=30s

如果 fuzz 找到失败输入，Go 会把最小化后的输入写入该 fuzz test 的 seed corpus，之后普通 go test 也会再次执行它。这个行为使“随机发现的问题”变成可重复的回归样例；修复缺陷后不要随意删除那条语料，除非它已不再代表有效的回归价值。

用几个指标判断种子是否过多

本例没有把“种子数量越多越好”当作优化目标。可以用下面的三个问题做轻量复盘：

1. 每条种子是否对应一个不同的关键分支？ 如果三条输入都走同一个路径，只保留最能说明边界的一条。
2. 普通 go test 是否足够快？ 种子会默认回归，复杂语料过多会直接增加每次测试时间。
3. 范围守卫之后是否仍有有效执行？ 可以观察 fuzz 输出里的执行与新覆盖变化；如果全部输入都早返回，应重新设计种子和输入域。

边界与常见误区

1. 把 f.Add 当成输入白名单。 它只是提供种子，不会阻止引擎生成其它值；范围判断必须写在 fuzz target 内。
2. 只测一个正常样例。 至少加入不同正常分支和一个关键边界，否则引擎的初始覆盖可能过窄。
3. 在 fuzz 回调里吞掉真正的错误。 对业务上应该失败的输入，要用单元测试或明确的 fuzz 性质断言它。
4. 修改参数顺序却不迁移目录语料。 f.Add 和 testdata/fuzz 都依赖目标参数的类型与顺序。
5. 把 fuzztime 当成覆盖率保证。 30 秒只是本次探索的资源上限，不能替代对关键边界的显式种子设计。

小结

设计 testing.F.Fuzz 时，可以把职责拆成三层：用少量 f.Add 种子把关键路径和边界送入语料，用 fuzz target 的范围守卫定义当前性质的适用域，再用 go test 和 -fuzz 分别承担回归与探索。需要长期保留的复杂失败输入则放入 testdata/fuzz/FuzzEndpoint，让随机发现的问题沉淀为可重复测试。

相关问题

f.Add 的种子越多，模糊测试越好吗？

不一定。种子应覆盖不同关键路径、边界和已知回归；重复走同一条路径的样本只会增加普通测试的固定成本。

能不能只用范围守卫，不写 f.Add？

可以运行，但初始语料更难稳定覆盖你关心的分支。对小而明确的输入域，显式种子通常能更快建立基线。

fuzz 找到的失败输入应该放在哪里？

Go 会按 fuzz test 名称写入对应的 seed corpus 目录。修复后保留它作为回归样例，并用普通 go test 确认该输入仍能重复执行。

范围守卫会不会让 fuzz 失去意义？

如果守卫只排除业务无关的超长或越界输入，并保留完整的有效域，它是在收窄问题而不是关闭 fuzz。若有效执行几乎为零，就应检查守卫是否过严。