Go vet printf 误报时的签名修正方案

go vet 的 printf 分析器不仅检查 fmt.Printf，还会识别把参数继续传给格式化函数的自定义包装器。当一个包装器既接受动态文本，又带 ...any 可变参数时，检查器会把它理解成 printf 风格函数；随后把动态字符串作为第一个参数传入，就可能出现“non-constant format string”一类告警。最稳妥的修正不是关闭检查，而是把纯文本入口与格式化入口拆成两个签名明确的函数。

官方说明：https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/printf

一、为什么看似误报

printf 分析器会检查格式串语法、占位符数量和实参类型，也能识别 log.Printf 以及自定义包装器。下面的函数名和实现都表达“格式化”，但调用方有时把它当普通文本输出，因此产生语义冲突。

package logger

import "fmt"

func Logf(format string, args ...any) {
    // 该签名明确表示第一个参数是格式串。
    fmt.Printf(format, args...)
}

func Example(message string) {
    // 动态文本被放进格式串位置，vet 会对此保持警惕。
    Logf(message)
}

如果 message 中恰好包含百分号，未来又增加参数，行为可能与调用者预期不同。检查器并不知道业务上“这里绝不会格式化”，它只能依据签名、函数名和包装关系判断。

二、按真实语义拆分签名

纯文本入口只接收一个字符串，不保留无意义的 ...any；格式化入口保留 format string, args ...any，名称使用 Printf、Errorf 等清晰后缀。这样调用点本身就能表达意图。

package logger

import "fmt"

func Log(message string) {
    // 纯文本不解释百分号占位符。
    fmt.Print(message)
}

func Logf(format string, args ...any) {
    // 格式化入口只处理明确的格式串调用。
    fmt.Printf(format, args...)
}

func Example(message string, count int) {
    // 动态值作为普通字符串参数输出。
    Log(message)
    // 固定格式串与参数数量、类型都可静态检查。
    Logf("processed %d items", count)
}

三、不能拆函数时如何修正调用

若公共 API 暂时不能改签名，调用动态文本时应把固定格式串写在第一个参数位置，把动态值作为普通参数传入。

package logger

func UseExisting(message string) {
    // 固定格式串明确要求按字符串输出动态内容。
    Logf("%s", message)
}

这不是为了“讨好 vet”，而是消除格式串与数据之间的歧义。对于错误值可使用 "%v"，需要 Go 语法表示时可选择 "%q" 或 "%#v"，但应根据输出需求明确选择。

四、签名修正的判断表

结构化字段不应伪装成 printf 参数。若第二组参数是键值字段，应使用专门类型，例如 ...slog.Attr，避免 ...any 同时承担格式化和字段传递两种职责。

五、批量迁移调用点

迁移时先按调用形态分类：只有一个动态字符串的调用改到纯文本入口；存在固定格式串和参数的调用保留在 Logf；格式串本身来自配置或用户输入时，优先改成 Log("...")，确实需要模板能力则使用受控模板机制，不要把不可信输入直接当 printf 格式串。

package logger

func Migrate(name string, n int) {
    // 纯文本拼接结果进入非格式化入口。
    Log("worker=" + name)
    // 固定格式串继续进入格式化入口。
    Logf("worker=%s jobs=%d", name, n)
}

六、常见误区

1. 给函数改名就一定能消除告警吗？

不一定。分析器还能根据函数体中的转发关系推断包装器。名称、签名和实现应共同反映真实语义，不能只做表面改名。

2. 可以直接关闭 printf 检查吗？

不建议。该检查还能发现占位符数量错误、类型不匹配和格式串语法问题。应先修正 API 语义；只有自定义分析环境确有特殊约束时，才在项目级统一配置。

3. Logf(text) 在运行时没出错，为什么还要改？

因为它把数据放在格式串位置，使接口契约含糊。改成 Log(text) 或 Logf("%s", text) 后，调用者、审查工具和后续维护者都能得到同一语义。