Go vet printf 如何发现格式化参数类型错误

如果一段 Go 日志把 %d 写在格式字符串里，却传入了字符串，编译器通常不会替你检查出这个语义错误。此时可以先运行 go vet -printf ./...：它会把格式动词、参数数量和参数类型放在一起分析，并在问题处给出诊断。

要定位格式化参数类型错误，先用 go vet -printf 缩小到包，再根据“动词需要什么类型、调用实际传了什么值”修复；它是静态启发式检查，不是对程序正确性的完整证明。

官方文档：https://pkg.go.dev/cmd/vet

先确定 go vet printf 检查什么、覆盖哪些包

go vet 默认执行一组检查，printf 是其中专门负责格式化调用的一项。为了排查日志、错误信息或字符串拼接问题，可以先在模块根目录执行：

# 只检查当前模块下所有包，先缩小格式化调用的排查范围
go vet -printf ./...

# 只检查当前目录对应的包，适合处理一个小型复现目录
go vet -printf

如果命令返回非零退出码，表示工具调用出错或报告了问题；返回 0 只说明这次检查没有报告问题。它依赖启发式规则，所以不要把 0 当成“所有日志都正确”，也不要把一条报告当成运行时行为的完整证明。需要查看当前工具支持的检查项时，可以运行：

# 查看 printf 检查的说明和可用参数
go tool vet help printf

用最小示例复现格式动词与参数类型不匹配

先建一个只包含错误调用的文件，刻意让 %d 接收字符串：

package main

import "fmt"

func main() {
	// %d 需要整数，这里故意传入 string，让 vet 给出明确诊断
	fmt.Printf("订单号=%d\n", "A-1024")
}

运行 go vet -printf . 后，典型诊断会指出 %d 得到了错误类型。读这条信息时不要只盯着行号，而要同时对照三个位置：格式串里的动词、逗号后的实参以及实参的静态类型。把值改成整数，或把动词改为适合字符串的 %s，才是完整修复。

按诊断类型修复数量、类型和格式串问题

格式化检查并不只发现类型错误。可以把常见报告按“格式串和参数是否一一对应”来读：

特别要留意最后一种情况：当 message 本身含有百分号时，直接把它当格式串可能产生误格式化。若只是输出一段文本，用固定格式串承载它更清楚：

func printMessage(message string) {
	// 把动态文本作为参数传入，避免文本里的百分号被当成格式指令
	fmt.Printf("%s\n", message)
}

如果是 fmt.Errorf，还要分清普通格式化与 %w 的错误包装语义；不要为了让检查安静而随意把错误指针、字符串和整数互换。

让自定义日志包装函数也进入 printf 检查

项目通常不会到处直接调用 fmt.Printf，而是包一层日志函数。只要包装函数把 format 参数和可变参数转发给 fmt.Sprintf 或 log.Printf，vet 往往能推断它是 printf wrapper：

package main

import (
	"fmt"
	"log"
)

func logf(format string, args ...any) {
	// 先用同样的 format 和 args 形成消息，保留 printf 的参数关系
	message := fmt.Sprintf(format, args...)
	// 固定输出格式，避免再次引入动态格式串风险
	log.Printf("业务日志: %s", message)
}

func handleUser() {
	// 这里的 %s 需要字符串；如果传入整数，vet 可以沿包装链路提示
	logf("用户=%s", 1001)
}

如果包装路径被动态调用、接口分派或其他控制流遮挡，自动推断可能不够。这时可以通过 go tool vet help printf 查看 -funcs 说明，再把团队约定的格式化函数显式列进去。工程上更重要的是保持包装函数签名稳定：第一个参数是 format，后面是可变参数，并在实现中把它们原样转发。

在持续集成里，可以把 go vet -printf ./... 放在单元测试之前。这样格式化错误会在合并前暴露，但仍应结合测试和代码审查判断业务语义；vet 负责提供一条高价值的静态线索。

常见问题

为什么 go vet 不报出所有格式化问题？

printf 检查使用静态信息和启发式规则，动态拼接、反射或复杂的函数间接调用可能无法完全判断。它适合发现常见错误，不是完整的运行时验证。

%v 能不能解决所有类型不匹配？

%v 更宽松，但不代表表达意图更好。日志协议、错误信息和机器可读输出仍应选择明确的格式动词，让类型约束继续帮助代码审查。

自定义日志函数一定要手动配置 -funcs 吗？

不一定。能够被分析器识别为 printf wrapper 的函数通常会自动检查；只有包装关系无法推断时，才考虑使用 -funcs 指定额外的格式化函数。