Go fmt.Formatter怎样为自定义类型实现格式化输出为什么结果为空或不符合预期

给自定义类型实现 fmt.Formatter 时，最容易忽略的不是方法签名，而是“内容必须写到 fmt.State”。Format 的返回值会被忽略；如果方法没有调用 Write 或通过 fmt.Fprintf 写入状态，输出就可能为空。另一个高频问题是，在 Format 内再次用原类型执行 %v，从而递归调用自己。

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

先看懂 Format 收到的 State

fmt.Formatter 只有一个方法：Format(state fmt.State, verb rune)。verb 是调用方写在格式串里的动词，例如 v、s 或 q；state 则提供输出目标以及格式控制信息。

fmt.State 主要有四类能力：Write 写出字节，Width 读取宽度，Precision 读取精度，Flag 检查 +、#、0 等标志。下面的实现只在方法内部生成文本，最后明确写入状态。

用值接收者实现一个安全的格式化类型

package main

import "fmt"

type Metric struct {
    Name  string
    Value float64
}

// metricPlain 是没有 Format 方法的别名类型，用来避免递归调用。
type metricPlain Metric

func (m Metric) Format(state fmt.State, verb rune) {
    // 只接受本例定义的动词，未知动词给出可定位的格式错误。
    if verb != 'v' && verb != 's' && verb != 'q' {
        fmt.Fprintf(state, "%%!%c(%T=%v)", verb, m, metricPlain(m))
        return
    }

    // 精度由调用方控制；没有精度时使用适合日志的默认值。
    precision := 2
    if p, ok := state.Precision(); ok {
        precision = p
    }
    text := fmt.Sprintf("%s=%.*f", m.Name, precision, m.Value)
    if state.Flag('#') {
        // # 让调用方请求更接近结构体的可读形式。
        text = fmt.Sprintf("Metric{name:%q,value:%.*f}", m.Name, precision, m.Value)
    }
    if verb == 'q' {
        text = fmt.Sprintf("%q", text)
    }

    // Format 没有返回值，必须把最终文本写入 State。
    _, _ = state.Write([]byte(text))
}

func main() {
    m := Metric{Name: "latency_ms", Value: 12.3456}
    fmt.Printf("%v\n", m)     // latency_ms=12.35
    fmt.Printf("%#.1v\n", m)  // Metric{name:"latency_ms",value:12.3}
    fmt.Printf("%q\n", m)     // "latency_ms=12.35"
}

这里用值接收者，所以 Metric 和 *Metric 都能找到 Format。如果改成指针接收者，只有 *Metric 实现了 fmt.Formatter，把值传给 fmt.Printf 时就会退回默认格式，这正是“为什么结果不一样”的常见原因。

为什么会出现空输出或递归

可以按下面的顺序排查：

• 方法执行但没有内容：确认每个分支最终都调用了 state.Write 或 fmt.Fprintf(state, ...)，不能只拼接局部变量。
• 只有某些动词异常：检查 switch 是否覆盖了调用方使用的动词。未知动词应明确回退或输出诊断，不要静默丢弃。
• 输出反复嵌套：不要在 Metric.Format 中写 fmt.Fprintf(state, "%v", m)；这会再次命中同一个方法。转换成 metricPlain(m) 后再格式化，或直接写字段。
• 值与指针结果不同：核对接收者类型。指针接收者需要调用方传入指针，集合或接口字段也要留意实际动态类型。

把宽度、精度和回退边界定清楚

fmt.Formatter 不会自动替你解释业务字符串。宽度是最小输出宽度，精度的含义取决于你的类型；示例把精度解释为小数位数，并没有声称所有自定义类型都应如此。若要重建调用方的完整格式指令，可以使用 fmt.FormatString(state, verb)，它会把标志、宽度、精度和动词拼回字符串。

建议在调用侧覆盖四组情况：%v 默认输出、%s 或 %q 的专用分支、带宽度/精度的格式串，以及值和指针两种传参方式。这样能快速区分是格式化逻辑没有写出，还是接口方法集合没有命中。

常见问题

为什么实现了 String 方法却没有进入 Format？

Stringer 和 Formatter 是两个不同接口。调用格式和动态类型会影响方法选择；需要读取宽度、精度或标志时，应直接实现 Format。

Format 里能不能继续使用 fmt.Sprintf？

可以，但不要把实现了同一 Format 方法的原值再次作为 %v 参数传入。优先传字段、基础类型或无方法的别名类型，避免递归。

输出为空时先看哪里？

先看所有分支是否写入 fmt.State，再看动词是否命中，最后核对接收者是值还是指针。这个顺序通常比先调整格式串更快定位问题。

小结

实现 fmt.Formatter 的关键是三点：用 State 读取调用方的格式意图；让每个有效分支明确写出内容；在需要再次格式化时使用别名类型或字段，切断递归。把动词、接收者和宽度精度当成接口边界管理，空输出和“看起来没生效”的问题就会变成可定位的分支。