Go fmt.Formatter 怎样实现自定义格式化

我第一次给业务值类型补自定义输出时，真正容易出错的不是写出一个 Format 方法，而是把格式字符串里的信息丢掉：%8.2f、%+v 和 %q 进入方法后，分别会以动词、宽度、精度和标志的形式出现在 fmt.State 里。Go 的做法是让类型实现 Format(f fmt.State, verb rune)，由这个方法决定怎样写回 f。

官方资料入口：https://pkg.go.dev/fmt

实现 fmt.Formatter 的关键，是先读懂 fmt.State，再把业务值转换成字符串写入状态；不要在 Format 里再次把同一个值交给 fmt，否则很容易递归。

先把 Formatter 的调用边界看清楚

fmt.Formatter 只有一个方法：Format(fmt.State, rune)。第一个参数是输出状态，第二个参数是调用者写下的格式动词。宽度和精度不是从完整格式字符串里解析，而是通过状态对象读取；状态还提供 Flag 来查询 +、#、- 等标志。

因此，方法的职责可以拆成三块：识别当前动词，读取格式参数，生成最终文本并写入 State。如果只处理 %v 却忽略宽度和精度，调用方虽然能得到文本，但格式化接口的可组合性就会变差。

先用值接收者写一个不会递归的实现

下面用金额值演示最小实现。金额内部保存分，输出时根据精度转成小数；实现内部只调用 strconv 和 io.WriteString，不把 p 再传给 fmt.Fprintf。

package main

import (
    "fmt"
    "io"
    "strconv"
)

type Money struct {
    Cents    int64
    Currency string
}

// Format 让 Money 自己决定常用动词的文本形态，避免把 Money 再交给 fmt 造成递归。
func (m Money) Format(state fmt.State, verb rune) {
    switch verb {
    case 'v', 's':
        precision := 2
        if p, ok := state.Precision(); ok {
            // 精度由调用方提供；这里把它限制为非负值再交给 strconv。
            precision = p
        }
        amount := float64(m.Cents) / 100
        text := m.Currency + " " + strconv.FormatFloat(amount, 'f', precision, 64)
        // 只写生成的字符串，不再用 fmt 格式化 m 本身。
        _, _ = io.WriteString(state, text)
    default:
        // 未知动词保留完整指令，便于调用方发现格式不匹配。
        _, _ = io.WriteString(state, fmt.FormatString(state, verb)+"")
    }
}

func main() {
    price := Money{Cents: 12345, Currency: "CNY"}
    fmt.Printf("默认=%v；两位=%8.2v；未知=%q\\n", price, price, price)
}

这里用值接收者，是因为 Money 本身就是不可变的展示值；如果方法需要修改对象或处理大型结构，才应评估指针接收者。未知动词不应该悄悄退回默认输出，否则调用方写错格式时很难定位。

把动词、宽度和精度变成可检查的输出规则

上面的代码已经读了精度，但还没有处理宽度和左对齐。实际项目里可以把“核心文本生成”和“外层填充”分开：先根据动词得到文本，再读取 Width，最后按 - 标志决定补在左侧还是右侧。宽度是最小字符宽度，不是截断长度。

func pad(state fmt.State, text string) string {
    width, ok := state.Width()
    if !ok || width 

如果把这个辅助函数接入 Format，还要在导入区增加 strings。在中文或其他多字节文本里，len 统计的是字节数；需要严格按显示列宽对齐时，应该另选明确的列宽策略，不能把字节数当成屏幕宽度。

出现异常时按这份清单排查

• 输出完全没进 Format：确认传入的是实现了 Format(fmt.State, rune) 的类型，并检查方法名、参数类型和接收者是否一致。
• 一调用就递归：检查 Format 内是否调用了 fmt.Sprintf("%v", m)、fmt.Fprint(w, m) 这类仍会接触同一值的方法；改成对字段或普通字符串格式化。
• 宽度和精度不生效：不要从 verb 推断全部信息，分别读取 Width、Precision 和 Flag，并区分“未提供”和“提供了零值”。
• 未知格式被吞掉：使用 fmt.FormatString(state, verb) 重建完整指令，再输出明确的诊断文本。
• 写入失败被忽略：示例为保持简洁忽略了 io.WriteString 返回值；封装到真实 io.Writer 时，应保留并处理写入错误。

最后用几个调用场景确认设计

自定义格式化适合金额、版本号、资源标识、日志字段等需要统一展示的值对象。它不适合把复杂业务查询、网络请求或隐式副作用塞进输出方法；格式化应尽量是轻量、可预测的纯展示逻辑。

可以按“默认动词、带精度、带宽度、带标志、未知动词”五种调用场景检查。只要每种场景都能解释动词和状态参数如何影响结果，fmt.Formatter 的实现通常就不会再变成黑盒。

相关问题

• fmt.Formatter 和 Stringer 有什么区别？ Stringer 更适合提供默认字符串，而 Formatter 能读取动词、宽度、精度和标志，控制范围更细。
• Format 里可以调用 fmt.Sprintf 吗？ 可以格式化普通字段或字符串，但不要把当前实现 Formatter 的值再次作为参数传给 fmt。
• 为什么未知动词要保留原始指令？ 这样日志或测试能直接看出调用方传入了什么格式，定位比静默使用默认输出更快。