Go fmt.Formatter怎样为自定义类型实现格式化输出怎样完成一个可复用的最小示例

自定义类型实现 Format(fmt.State, rune) 后，就能控制 fmt 的格式化输出。最小可复用方案是先明确支持哪些动词，再把类型转换成普通字符串或底层数值，使用 State 中的标志、宽度和精度继续委托格式化。关键是不要在 Format 内再次用同一自定义类型调用 fmt，否则容易递归。

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

1. 能力背景：这是标准库扩展点，并非新发布功能

fmt.Formatter 适合“同一个值需要多种展示方式”的场景。本文保留生态能力解读到快速试用的结构，但不把长期存在的接口包装成一条新版本新闻。示例使用 Go 1.20 加入的 fmt.FormatString 来复用格式指令，因此整个示例要求 Go 1.20 或更新的受支持工具链。

我会拿业务编号举例：十进制展示是 T-42，引用展示给它加 Go 字符串引号，十六进制则针对底层数字 42 输出。先确定这些含义，比一开始就支持所有 fmt 动词更容易维护。Formatter 的实现可以决定自己的协议，读者不能假设自定义类型的每个动词都遵守底层整数的默认行为。

2. 适用场景：区分展示形式、诊断形式和传输数据

编号出现在命令行表格中时需要宽度，日志说明中可能希望引用，排查底层数值时又需要十六进制。这三种需求可以在一个 Format 中选择。展示结果不是数据库主键序列化格式，也不是 JSON 或 URL 编码规则；要传输稳定业务数据，应另定义明确的编码函数。

本例把 %v 映射到字符串格式，所以 %+v 与 %#v 不承担额外的结构诊断或 Go 源码还原语义。这是刻意收窄的契约。如果团队需要 %#v 输出可重建表达式，就应额外处理该组合，不要因为使用了 Formatter 就默认已经支持它。

3. 快速试用：实现完整 Format 方法

package main

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

// TicketID 的展示形式与数值表示分开定义。
type TicketID uint64

func (id TicketID) Format(state fmt.State, verb rune) {
 switch verb {
 case 's', 'v':
  // 转成普通字符串后再委托 fmt，避免再次调用自己的 Format。
  text := "T-" + strconv.FormatUint(uint64(id), 10)
  _, _ = fmt.Fprintf(state, fmt.FormatString(state, 's'), text)
 case 'q':
  text := "T-" + strconv.FormatUint(uint64(id), 10)
  _, _ = fmt.Fprintf(state, fmt.FormatString(state, 'q'), text)
 case 'x', 'X':
  // 十六进制以底层数值为准，不是展示字符串的字节编码。
  _, _ = fmt.Fprintf(state, fmt.FormatString(state, verb), uint64(id))
 default:
  // 不支持的动词输出明确诊断，诊断本身不再格式化 TicketID。
  _, _ = io.WriteString(state, "%!"+string(verb)+"(TicketID="+
   strconv.FormatUint(uint64(id), 10)+")")
 }
}

var _ fmt.Formatter = TicketID(0)

func main() {
 id := TicketID(42)
 // 这些例子覆盖默认展示、对齐、引用和数值十六进制。
 fmt.Printf("默认=%v\n", id)
 fmt.Printf("右对齐=[%10s] 左对齐=[%-10s]\n", id, id)
 fmt.Printf("引用=%q 十六进制=%#x\n", id, id)
 // 精度用于展示截断，不能用这个结果作为完整业务标识。
 fmt.Printf("截断=%.3s\n", id)
}

保存为 main.go 后运行 go run main.go 即可尝试。按代码语义，默认展示应为 T-42，引用形式为 "T-42"，%#x 为 0x2a；对齐示例用方括号帮助观察空格。它们是预期值，本文没有宣称运行了代码或提供真实终端截图。

fmt.State 提供 Flag、Width、Precision 和 Write；动词则单独通过 verb 参数传入。FormatString 把当前标志、宽度和精度组合成格式指令。这里 s、v 分支都使用 s 作为委托动词，因为它们已经被定义为展示字符串；x、X 分支使用原动词并传 uint64(id)，从而保留数值格式语义。

Format 内的 Fprintf 传入的是 string 或 uint64，它们不再带有 TicketID 的方法集，因此不会重新进入 TicketID.Format。实现采用值接收者，TicketID 值本身就满足接口；若改为指针接收者，调用时传值还是传指针会影响是否匹配 Formatter。

4. 和 Stringer、手写拼接相比怎样选择

如果需求只是让日志里的默认名称更友好，String() string 往往就够了。需要随动词、宽度或精度改变展示时，我才会选择 Formatter。两者同时存在时，Formatter 在适用的 fmt 格式化路径中优先于 Stringer，不要指望 Format 处理不支持的动词时自动回退到 String 方法。

手写拼接适合固定协议输出，因为结果不会受调用者的格式串影响。Formatter 适合遵循 fmt 的调用习惯，却也意味着宽度和精度进入了展示接口。例如 %.3s 在本例中会把 T-42 截为 T-4；若用于业务编号传输，结果就不完整。不能将截断展示再次当成真实编号提交。

不希望依赖 FormatString 的旧工具链，可以手动读取 State 并构造受限的格式指令；但要处理“没有指定精度”和“明确指定精度为零”的区别，Width、Precision 返回的布尔值不能忽略。更稳妥的兼容方式是明确最低工具链，或者仅提供固定 String 展示，不需要为了兼容而把所有规则重新实现一遍。

5. 采用风险：格式化不能掩盖错误和资源成本

Format 没有 error 返回值，本例在方法内部使用 fmt.State 的写入能力，并忽略内部写入返回值。这不代表真实输出设备不会失败。需要向文件或网络写出时，调用方仍应检查外层 Fprintf 的错误；如果业务转换本身可能失败，应先调用显式返回 error 的转换函数，再把成功结果交给 fmt。不要在 Format 中做网络请求或复杂业务操作。

本例没有声称零分配。数字转字符串、构造展示字符串和重建格式指令都会有成本。如果某个批处理热点只需要固定数值编码，可以考虑 strconv 的追加接口与调用方管理的缓冲；但是否值得替换，应通过实际负载测量，而不是从“自定义接口”推导出更高性能。

格式串最好由程序控制。允许外部输入任意宽度或精度，会让展示长度和资源开销不易预测。对于可能包含敏感字段的自定义类型，还应明确支持哪些输出，而不是把 %#v 作为默认泄露全部内部状态的出口。本例编号不包含秘密，不代表同样的做法可直接用于凭据类型。

为什么实现后 %T 仍显示类型？类型展示有自己的 fmt 规则，不能假设所有格式都进入 Format。为什么 %x 和把 String 结果转十六进制不同？本例明确选择底层整数，后者则是字符串字节。如何避免无限递归？在委托前转成 string、uint64 或不携带相关方法的明确基础表示，并避免再次传入同一 TicketID。

我会在多种展示语义确实共用同一业务类型时采用这个接口；仅有单一字符串展示时继续用 Stringer，稳定传输则独立设计编码。接口优先级、State 和 FormatString 的细节见 fmt 官方文档。