Fuzz 的失败输入应直接删除还是加入回归测试

通常不要直接删除。Go Fuzz 找到的失败输入如果揭示了真实实现缺陷，正确做法是先修复代码，用日志给出的子测试名重放，确认通过后把 testdata/fuzz/FuzzXxx/哈希 文件提交到仓库。它会成为 seed corpus 的一部分，以后执行普通 go test 也会运行，从而阻止同一缺陷复发。

需要删除或替换的例外主要有三类：Fuzz 断言本身写错、测试依赖全局状态导致结果不确定、失败文件含不应提交的敏感数据。即便如此，也不该“删掉让测试变绿”，而是先修正测试契约或状态依赖，再保留一个安全、最小、能表达边界的回归种子。

官方文档：https://go.dev/doc/security/fuzz/

为什么失败文件不是一次性垃圾

Go 原生 Fuzz 从 1.18 起进入标准工具链。官方文档说明，模糊测试使用覆盖率引导变异输入；失败时会尝试把输入缩减到更小、更易读但仍能复现的问题值，然后写入 testdata/fuzz。这个文件此后会作为种子由默认 go test 执行。

所以失败文件保存的不是“那次随机运行的噪声”，而是一个已经证明可以打破当前契约的具体反例。直接删除它，会失去三样东西：

• 稳定重放缺陷的最小输入；
• 代码修复是否有效的直接检查；
• 未来重构时防止同类问题复发的回归资产。

我会把它看成自动生成的表驱动测试数据，只是文件名由内容哈希表示，编码格式由 Go 工具维护。

先分清三种语料放在哪里

最容易混淆的是后两项。Fuzz 引擎为了扩展覆盖率，会在 Go 构建缓存中维护 generated corpus；它属于本地探索缓存。真正触发失败并写到包内 testdata/fuzz 的输入，则已经升级为可持久回归的 seed corpus。清理本地缓存和删除仓库失败语料，不是同一件事。

一个实际场景：缺少分隔符导致 panic

假设服务接收 name:value 格式，最初实现直接按下标读取第二段。常规测试只覆盖了包含冒号的输入，看起来没有问题。

package pair

import "strings"

// SplitPair 演示一个缺少长度检查的旧实现
func SplitPair(raw string) (string, string) {
    parts := strings.SplitN(raw, ":", 2)
    // raw 不含冒号时 parts 只有一个元素，这里会触发越界 panic
    return parts[0], parts[1]
}

Fuzz 测试不需要猜每个输入的左右值，只要表达一个基本契约：函数不能 panic；当输入包含冒号时，拆开后重新拼接必须等于原字符串。

package pair

import (
    "strings"
    "testing"
)

func FuzzSplitPair(f *testing.F) {
    // 两个种子分别覆盖正常值和空字段边界
    f.Add("name:value")
    f.Add(":empty-left")

    f.Fuzz(func(t *testing.T, raw string) {
        left, right := SplitPair(raw)
        // 对含冒号输入检查拆分后的往返性质
        if strings.Contains(raw, ":") && left+":"+right != raw {
            t.Fatalf("往返失败: raw=%q left=%q right=%q", raw, left, right)
        }
    })
}

工具很容易生成不含冒号的字符串，旧实现因此 panic。官方列出的失败原因包括 panic、测试显式失败、不可恢复错误和单次目标执行超时；发现失败后，引擎会尝试最小化输入。对于这个例子，最小反例通常就是一个不含冒号的短字符串，价值远高于一大段随机字符。

修复后怎样重放并纳入回归

真正的问题是 API 没定义“缺少分隔符”时怎么返回。与其让下标访问 panic，不如用 strings.Cut 返回显式的 ok，调用方可以区分合法空字段和格式错误。

package pair

import "strings"

// SplitPair 按第一个冒号拆分，并显式返回格式是否有效
func SplitPair(raw string) (left, right string, ok bool) {
    left, right, found := strings.Cut(raw, ":")
    if !found {
        return "", "", false
    }
    return left, right, true
}

Fuzz target 也要同步新契约：无冒号输入必须返回 ok=false；有冒号输入必须能无损拼回。

package pair

import (
    "strings"
    "testing"
)

func FuzzSplitPair(f *testing.F) {
    // 保留正常输入，同时加入缺少分隔符的显式边界种子
    f.Add("name:value")
    f.Add("plain")

    f.Fuzz(func(t *testing.T, raw string) {
        left, right, ok := SplitPair(raw)
        hasSeparator := strings.Contains(raw, ":")

        // ok 必须与输入是否含分隔符保持一致
        if ok != hasSeparator {
            t.Fatalf("格式判断不一致: raw=%q ok=%v", raw, ok)
        }
        if ok && left+":"+right != raw {
            t.Fatalf("往返失败: raw=%q left=%q right=%q", raw, left, right)
        }
    })
}

接下来先用失败日志给出的完整子测试名重放，再运行全部测试，最后继续 Fuzz。命令中的哈希应替换为本机失败日志给出的真实值。

# 精确重放 Go 输出中记录的最小失败输入
go test -run='^FuzzSplitPair/失败语料哈希$' ./...

# 运行普通测试，确认 testdata/fuzz 中的语料已经成为回归用例
go test ./...

# 修复后继续探索其他输入，避免只处理当前一个反例
go test -run='^$' -fuzz='^FuzzSplitPair$' -fuzztime=30s ./...

三步都通过后，把实现、Fuzz target 和 testdata/fuzz/FuzzSplitPair/... 一起提交。不要手工编辑 corpus 文件的格式，也不要把哈希内容复制成一堆重复的 f.Add。

哪些失败文件应该保留，哪些要先处理

“测试写错了”并不等于输入毫无价值。它可能揭示了此前没有定义的 API 边界。先把业务契约说清楚，再决定保留、替换还是删除。真正应该避免的是：为了消除红灯，既不修实现，也不修断言，只删文件。

和手写回归用例相比，失败语料有什么不同

手写表格适合表达可读的业务案例，Fuzz 失败文件适合精确保留机器找到的字节级反例。两者可以共存：

• 如果反例非常直观，例如空字符串或缺少冒号，可以额外写一个具名表格用例说明业务含义，但仍可保留原始 corpus。
• 如果反例包含无效 UTF-8、控制字节或多个参数，保留工具生成格式通常更可靠。
• 如果同一根因出现很多哈希文件，应在修复后检查它们是否覆盖不同分支；不要仅因为文件多就全部删除。

官方规定 f.Add 的参数类型和顺序必须与 fuzz target 一致，corpus 文件也遵守同一约束。若重构改变了 target 参数签名，旧语料可能不再可读；这时应设计迁移或重新编码，而不是在没有记录的情况下清空目录。

采用时还要注意哪些风险

失败输入会不会泄露业务数据？

Fuzz 变异通常从种子和生成语料出发。如果把生产请求、密钥或个人信息当种子，失败文件可能保留其中片段。种子一开始就应使用合成数据；发现敏感内容时不得提交，应该撤销暴露值并构造能触发同一路径的安全等价输入。

超时输入也要永久保留吗？

先判断超时是否稳定。死循环、极端复杂度和稳定的资源放大属于真实缺陷，应该保留；由共享环境、网络或机器负载造成的偶发超时，应先把 target 改成快速、确定、无外部依赖，再生成可重现语料。

修复后 corpus 文件名会变化吗？

文件名来自语料内容的哈希。只要保留同一输入，通常无需重命名。不要把文件名当业务标识；代码评审应关注它复现的契约和对应修复。

可以只把失败值复制到注释里吗？

不够。注释不会被测试执行。应保留 corpus 文件或把安全、可读的最小值加入 f.Add / 具名测试，同时确保普通 go test 能自动覆盖它。

一个实用的提交清单

• 确认失败能用日志给出的子测试名稳定重放。
• 判断问题在实现、测试契约还是外部非确定性。
• 修复后运行普通 go test，确保失败语料已成为回归种子。
• 检查语料是否含密钥、个人信息、生产内容或不必要的大文件。
• 为难懂反例在提交说明中记录根因，不手工改写 corpus 编码。
• 实现、测试和最小失败语料一起提交，再继续受限时长的 Fuzz。

最终判断很简单：真实缺陷对应的失败输入，应当从“随机发现”升级为“永久回归”；错误测试和不稳定环境要先修正，再保留能表达真实边界的安全语料。删除文件只能是分析后的结果，不能是让测试恢复绿色的捷径。