Go fmt 处理自定义 Formatter 怎样避免递归

给一个类型实现 fmt.Formatter 后，最容易踩到的坑是：Format 方法内部又把当前值交给 fmt.Fprintf、fmt.Sprintf 或 fmt.Fprint。因为 fmt 会优先识别 Formatter，这次内部调用会再次进入同一个 Format，最后表现为栈递归或无法结束的格式化。

解决办法不是把 Formatter 换成 Stringer，而是在 Format 内部把当前值转换成基础类型或不带方法的 defined type，再交给 fmt；这样输出仍可复用 fmt 的宽度、精度和标志，但不会重新命中原来的 Formatter。

• 先确认递归入口：Format 内部是否把原接收者作为参数传回 fmt。
• 字符串类值优先转成 string(x)，结构体类值可转成无方法的 defined type。
• 根据 verb 决定输出形态，未知动词不要偷偷复用会递归的路径。
• 嵌套字段和自引用容器也要单独检查，避免间接把原类型送回 fmt。

Formatter 为什么会重新调用自己

fmt 处理一个操作数时，会先检查它是否实现了 Formatter。实现后，动词和标志的解释权就交给 Format(state, verb)。因此，下面这种写法看起来像“复用默认格式”，实际却把同一个 Label 再传给了 fmt.Fprintf：

package main

import "fmt"

type Label string

func (x Label) Format(state fmt.State, verb rune) {
	// 这里的 x 仍然是 Label，内部格式化会再次命中 Format。
	fmt.Fprintf(state, "", x)
}

func main() {
	// %v 会触发 Label.Format，随后陷入同一条调用链。
	fmt.Printf("%v\n", Label("ready"))
}

关键不在 %s 还是 %v，而在参数 x 仍保留了原有的方法集。只要它作为操作数重新进入 fmt，Formatter 就可能再次被调用。官方 fmt 文档也用字符串类型的例子说明了这个递归边界。

用基础类型转换切断字符串值的递归

如果接收者本质上是字符串，最直接的断链方式是把它转换成内建 string。内建类型没有 Label.Format，所以 fmt 只会按字符串规则处理它：

package main

import "fmt"

type Label string

func (x Label) Format(state fmt.State, verb rune) {
	// 先转成基础 string，避免再次调用 Label.Format。
	text := string(x)
	switch verb {
	case 'v', 's':
		// 这里使用基础字符串作为参数，调用链已经被切断。
		fmt.Fprintf(state, "", text)
	default:
		// 未约定的动词给出稳定提示，避免误用默认递归路径。
		fmt.Fprintf(state, "", verb)
	}
}

func main() {
	// 现在 %v 与 %s 都能完成一次安全格式化。
	fmt.Printf("%v\n", Label("ready"))
	fmt.Printf("%s\n", Label("ready"))
}

这里的转换只改变“交给谁继续格式化”，没有改变 Label 在业务层的类型含义。若输出只是拼接几个固定片段，也可以使用 io.WriteString 或直接写入 state，同样不要把原接收者再次作为格式化参数。

结构体 Formatter 如何复用默认字段格式

结构体场景通常希望保留字段名、宽度或其他默认规则。可以定义一个与原结构体拥有相同底层结构、但不带方法的类型，再把它作为内部参数：

package main

import "fmt"

type Endpoint struct {
	Host string
	Port int
}

func (e Endpoint) Format(state fmt.State, verb rune) {
	// plainEndpoint 没有 Endpoint 的方法集，不会回到当前 Format。
	type plainEndpoint Endpoint
	switch verb {
	case 'v':
		// 保留 %+v 对字段名的表达能力，同时避免递归。
		fmt.Fprintf(state, "%+v", plainEndpoint(e))
	default:
		// 非 v 动词只输出明确的、不会再次格式化 e 的文本。
		fmt.Fprintf(state, "Endpoint(%s:%d)", e.Host, e.Port)
	}
}

func main() {
	// 结构体转换后的值会按普通结构体规则格式化。
	fmt.Printf("%+v\n", Endpoint{Host: "api", Port: 8080})
}

type plainEndpoint Endpoint 是一个新的 defined type，不会自动继承 Endpoint 的方法。这个技巧适合字段结构简单、默认格式足够清晰的场景；如果结构体包含敏感字段，应该显式挑选字段输出，而不是把整个值交给默认格式化。

verb、flag 与嵌套字段的边界

fmt.State 可以读取当前动词对应的宽度、精度和标志。若自定义输出需要遵循这些约定，可以先用 fmt.FormatString(state, verb) 取出格式串，再把安全转换后的值交给它。注意：安全转换解决的是接收者递归，不会自动替你设计所有动词的语义。

func (e Endpoint) Format(state fmt.State, verb rune) {
	// 只把无方法类型传入 fmt，原 e 不作为内部操作数。
	type plainEndpoint Endpoint
	switch verb {
	case 'v':
		format := fmt.FormatString(state, verb)
		fmt.Fprintf(state, format, plainEndpoint(e))
	default:
		fmt.Fprintf(state, "Endpoint(%s:%d)", e.Host, e.Port)
	}
}

还要检查字段是否间接带回原类型。例如结构体里有一个指针、切片或接口字段，而该字段引用了自身或另一个实现 Formatter 的对象，那么默认格式化仍可能进入另一条循环。自引用数据结构尤其需要避免直接交给 fmt；必要时只输出标识、摘要或有限深度。

常见问题

把 Formatter 改成 Stringer 就一定安全吗？

不一定。String() 内部如果再次用 fmt.Sprintf("%s", x) 传入原值，同样会重新命中 Stringer。断开调用链的核心仍是先转换成基础类型或无方法类型。

为什么代码里要区分 verb？

调用方可能传入 %v、%s、%q 或带标志的变体。明确处理支持的动词，能避免把不适合的输出语义误当成默认格式；未知动词则应给出稳定、非递归的降级文本。

最短修复是不是直接写 string(x)？

对底层就是字符串的类型，通常是最清楚的修复。结构体、指针或带敏感字段的对象不能机械套用，应选择无方法类型、显式字段或有限摘要，确保输出边界符合业务要求。

可以把排查顺序固定为：找到 Format 内部的 fmt 调用，标记所有作为参数传回的对象，再逐个确认它们是否仍实现 Formatter。只要原接收者不再回流，递归问题就从调用链上被切断。