Go vet stdmethods 怎样发现标准接口方法签名问题

给类型写了一个名为 WriteTo、MarshalJSON 或 ReadRune 的方法，代码可能照样编译，但它的参数或返回值一旦偏离标准接口，调用方就会在更晚的地方才发现。stdmethods 的作用正是提前检查这类“名字像，签名不像”的方法。

官方文档：https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/stdmethods

先看一个“能编译但不能实现接口”的例子

下面的类型把 WriteTo 写成只返回 error。方法名没有错，语法也合法，但它不符合 io.WriterTo 要求的 (int64, error) 返回值。

package demo

import "io"

type packet struct{}

// WriteTo 演示一个返回值不完整的熟知方法签名。
func (packet) WriteTo(w io.Writer) error {
	// 这里只保留示例结构，重点是方法签名而不是写入逻辑。
	return nil
}

如果没有接口赋值，这段代码可以通过编译；但运行 go vet -stdmethods ./... 时，检查器会根据 WriteTo 这个方法名提示它应当采用标准签名。错误并不来自方法名本身，而来自调用约定不完整。

stdmethods 实际检查哪些方法

它维护的是一组固定的熟知方法名，例如 Format、GobEncode、MarshalJSON、ReadFrom、ReadRune、Seek、UnmarshalJSON、WriteByte 和 WriteTo。命中方法名后，vet 会把声明的参数、接收者相关约定和返回值与标准接口形状做比较。

建议把检查命令写进本地复现步骤，而不是只依赖编辑器提示：

# 在模块根目录检查当前模块及其子包
go vet -stdmethods ./...

# 只检查指定包，便于缩小诊断范围
go vet -stdmethods ./internal/codec

如果仓库使用默认 vet 集合，也可以直接运行 go vet ./...；显式带上 -stdmethods 更适合排查这个专题。注意 vet 的返回码只表示发现诊断或调用错误，不代表它已经证明整个程序正确。

修复后怎样确认接口关系真的成立

把方法改成标准签名后，再加一条编译期接口断言，能把“vet 的提示”转换为项目自己的硬约束：

package demo

import "io"

type packet struct{}

// WriteTo 返回写入字节数和错误，匹配 io.WriterTo 的契约。
func (packet) WriteTo(w io.Writer) (int64, error) {
	// 示例只返回空写入；真实实现应检查 Write 的返回值并累计字节数。
	return 0, nil
}

// 编译器会在签名偏离时直接报错，避免问题拖到调用点。
var _ io.WriterTo = packet{}

这里有两个层次：stdmethods 负责发现熟知名字下的可疑签名；var _ io.WriterTo = packet{} 负责确认这个具体类型确实满足接口。二者都通过后，再运行测试，才能覆盖实现内部是否正确写入。

它的边界：不是任意接口的通用检查器

自定义接口的方法名如果是 EncodeRecord、FlushBatch 之类，stdmethods 不会因为它看起来像接口方法就自动推断契约。此时应使用接口断言、编译、单元测试或静态分析器补足检查。反过来，熟知方法名也不代表类型一定要实现对应接口：有些类型可能只是出于语义命名，最终仍需结合业务意图判断。

提交前可以按这份清单复查：方法名是否命中熟知列表；参数和返回值是否与目标标准接口一致；是否存在接口断言；go vet -stdmethods ./... 是否在模块根目录执行；测试是否覆盖短写、空输入和底层错误。

相关问题

stdmethods 会检查所有接口吗？

不会。它只针对标准库中预先定义的一组熟知方法名和签名。

vet 通过就能证明 WriteTo 可用吗？

不能。通过只说明没有发现这类签名问题，写入逻辑、错误处理和字节数统计仍需测试。