Go fmt.Formatter 为什么会覆盖默认字符串格式化
我第一次给一个 Go 类型同时加上 String() 和 Format() 时,最容易误判的一点是:以为 Format 只是对默认字符串格式做一层补充。实际上,fmt 处理参数时会先检查它是否实现了 fmt.Formatter。一旦命中,控制权就交给 Format,不会再自动调用同一个值的 String()。
结论:同一类型同时实现fmt.Formatter和fmt.Stringer时,Formatter 优先。只有当类型没有接管当前格式,或根本没有实现 Formatter,Stringer 才有机会参与字符串类格式化。要保留 Stringer 的结果,必须在 Format 中显式委托。
先区分 Stringer 和 Formatter
Stringer 只约定一个无参数方法:
type Stringer interface {
String() string
}
它适合描述一个类型的默认文本形式,例如日志、调试信息或普通的 fmt.Println 输出。Formatter 则接收 fmt.State 和格式动词:
type Formatter interface {
Format(f State, verb rune)
}
这意味着实现者可以读取宽度、精度和标志,并决定是否写出完全不同的结果。它不是“Stringer 的备用入口”,而是更靠近格式化分派器的自定义出口。

最小 Formatter 配方:先处理动词,再写入 State
为了让规则看得清楚,可以设计一个带有名称和编号的值。默认文本由 String 提供,Format 只对 %v 和 %s 给出带编号的显示:
package main
import "fmt"
type UserID struct {
Name string
ID int
}
// String 提供不带格式参数时的默认文本。
func (u UserID) String() string {
return u.Name
}
// Format 接管字符串类动词,并把结果写入 fmt.State。
func (u UserID) Format(state fmt.State, verb rune) {
switch verb {
case 'v', 's':
// 这里明确写出自定义格式,因此不会自动回退到 String。
fmt.Fprintf(state, "%s(#%d)", u.Name, u.ID)
default:
// 未处理的动词给出稳定提示,避免静默产生误导文本。
fmt.Fprintf(state, "%%!%c(UserID=%s)", verb, u.Name)
}
}
func main() {
user := UserID{Name: "Lin", ID: 42}
fmt.Println(user)
fmt.Printf("%s\n", user)
fmt.Printf("%q\n", user)
}
这里最关键的不是输出长什么样,而是谁拥有最终决定权:fmt.Println 和 %s 都会进入 Format;String() 仍然存在,但不会被 fmt 自动补进 Format 的结果里。对于 %q,示例选择显式给出未处理提示,避免读者误以为所有动词都会得到同样的自定义文本。
为什么 Stringer 没有被调用
Go 官方 fmt 源码中的方法处理顺序可以概括成两层:先断言参数是否为 Formatter,命中就调用 Format 并结束这次方法分派;没有命中时,针对 %v、%s、%x、%X、%q 等字符串可接受的动词,才继续检查 error 和 Stringer。
因此下面这种写法不会形成“Formatter 失败后自动调用 Stringer”的链:
// Format 一旦被调用,fmt 不会再替你调用 String。
func (u UserID) Format(state fmt.State, verb rune) {
// 即使这里什么都不写,String() 也不会自动补上结果。
}
这也是排查“我明明写了 String,为什么日志变空”的第一处检查点:看类型的实际方法集是否新增了 Format,再看 Format 是否真的向 state 写入了内容。
如果想保留 Stringer,必须显式委托
有时 Formatter 只想增加宽度、包一层前缀,主体文本仍希望由 Stringer 维护。这时可以在 Format 中显式调用 String(),再根据动词组合输出:
// Format 复用 String 的主体文本,同时保留 %q 的引号语义。
func (u UserID) Format(state fmt.State, verb rune) {
text := u.String()
switch verb {
case 'v', 's':
// %v 和 %s 使用同一份主体文本,但附加稳定的业务标识。
fmt.Fprintf(state, "%s(#%d)", text, u.ID)
case 'q':
// %q 需要交给 fmt 处理转义与引号,而不是手写引号。
fmt.Fprintf(state, "%q", text)
default:
// 未覆盖的动词保留可识别的错误形态。
fmt.Fprintf(state, "%%!%c(UserID=%s)", verb, text)
}
}
这里的调用是普通的 Go 方法调用,不是 fmt 的隐式回退。也正因为如此,若 String() 内部又通过 fmt.Sprintf 格式化同一个实现了 Formatter 的对象,就可能再次进入 Format;委托时应只格式化基础字段,避免递归。

宽度、精度和标志不要直接丢掉
fmt.State 不只有 Write,还提供 Width、Precision 和 Flag。如果自定义类型承诺支持这些格式参数,就要从 State 读取它们;如果暂时不支持,也应在文档中明确,而不是让调用者以为参数已经生效。
// FormatString 还原触发 Format 的完整格式指令,适合做透传。
func (u UserID) Format(state fmt.State, verb rune) {
directive := fmt.FormatString(state, verb)
// 这里把原始指令作为诊断前缀,便于发现调用方传入的动词和参数。
fmt.Fprintf(state, "[%s] %s", directive, u.String())
}
如果 Format 需要把格式继续交给一个基础值,fmt.FormatString 可以根据 State 和动词重建类似 %+8.2f 的指令。它不会替你完成委托,但能避免手动拼接标志、宽度和精度时漏掉参数。
什么时候只用 Stringer
如果需求只是“这个类型默认打印成一段人类可读文本”,优先实现 Stringer,让 fmt 保留自身对不同动词的处理。只有当你确实需要读取格式状态、支持多个动词,或者必须控制输出布局时,才实现 Formatter。
| 需求 | 更合适的接口 | 原因 |
|---|---|---|
| 普通日志和默认展示 | Stringer | 实现简单,不接管全部格式动词 |
| 按动词切换十进制、调试或引号形式 | Formatter | Format 能看到 verb 和 State |
| Formatter 只想复用默认文本 | Formatter 中显式调用 String() | fmt 不会自动回退 |
| 需要保留宽度、精度、标志 | Formatter + State | 格式参数必须由自定义实现读取或透传 |
最后检查这三个坑
- 方法接收者改变方法集:
Format写在值接收者还是指针接收者上,会影响参数是否真的实现 Formatter。 - Format 必须写入传入的
fmt.State;空方法不会触发 Stringer 兜底。 - 自定义格式化内部不要再次格式化同一个 Formatter 对象,必要时只格式化基础字段,避免递归。
把规则记成一句话就够了:Stringer 提供默认文本,Formatter 接管格式分派;一旦接管,是否使用 Stringer 由你的 Format 方法明确决定。
相关问题
Formatter 会自动调用 Stringer 吗?不会。Format 被选中后,必须由 Format 自己调用 String。
只实现 Stringer 能处理 %q 吗?在字符串可接受的格式场景中,fmt 可以使用 Stringer 的结果,再按对应动词处理;但它不会给你 Formatter 那样的 State 控制权。
Format 里为什么推荐用 Fprintf(state, ...)?因为 State 实现了 io.Writer,使用 Fprintf 可以把结果直接写回当前格式化缓冲,并减少手动拼接。
Go binary.LittleEndian.AppendUint32 怎样向缓冲区追加整数
- 上一篇
- Go binary.LittleEndian.AppendUint32 怎样向缓冲区追加整数
- 下一篇
- Go math/big.Rat.Scan 的 %f 与 %v 为什么采用相同读取规则
-
- Golang · Go问答 | 8分钟前 | go · math/big.Rat.Scan fmt.Scanner Go有理数
- Go math/big.Rat.Scan 的 %f 与 %v 为什么采用相同读取规则
- 270浏览 收藏
-
- Golang · Go问答 | 25分钟前 | 切片 · 标准库 · Go问答 · Go encoding/binary AppendUint32 binary.LittleEndian 小端字节序
- Go binary.LittleEndian.AppendUint32 怎样向缓冲区追加整数
- 327浏览 收藏
-
- Golang · Go问答 | 34分钟前 | 标准库 · 错误处理 · 模板 · Go问答 · Go 自定义函数 text/template 模板解析 template.FuncMap
- Go template.FuncMap 怎样给模板注入自定义函数
- 286浏览 收藏
-
- Golang · Go问答 | 39分钟前 |
- Go flag.FlagSet.VisitAll 为什么看不到未显式设置的参数
- 323浏览 收藏
-
- Golang · Go问答 | 40分钟前 | go · Go JSONHandler ReplaceAttr log/slog
- Go log/slog JSONHandler 为什么会把时间写成 RFC3339
- 240浏览 收藏
-
- Golang · Go问答 | 41分钟前 |
- Go cgo.Handle 为什么不能把 Go 指针直接传给 C
- 181浏览 收藏
-
- Golang · Go问答 | 41分钟前 |
- Go unsafe.Slice 为什么要求指针和长度匹配
- 349浏览 收藏
-
- Golang · Go问答 | 43分钟前 |
- Go runtime/debug.FreeOSMemory 什么时候适合主动调用
- 222浏览 收藏
-
- Golang · Go问答 | 52分钟前 |
- Go token.File.Name 怎样取回注册时的源码文件名
- 182浏览 收藏
-
- Golang · Go问答 | 53分钟前 | 标准库 · Go问答 · Go 文档注释 ast go/doc go/parser.ParseComments
- Go go/parser.ParseComments 为什么影响文档注释提取
- 172浏览 收藏
-
- Golang · Go问答 | 1小时前 |
- Go go/ast.Inspect 为什么不能直接修改遍历节点
- 116浏览 收藏
-
- Golang · Go问答 | 1小时前 | go · Go context runtime/trace NewTask
- Go runtime/trace.NewTask 为什么需要在 goroutine 边界传递 Context
- 278浏览 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 485次学习
-
- PubMedQA
- 深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
- 1107次使用
-
- H2O EvalGPT
- H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
- 1099次使用
-
- LMArena
- LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
- 1270次使用
-
- HELM
- 深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
- 1212次使用
-
- MMBench
- MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
- 1059次使用
-
- Go map 并发写 panic 怎么办:从共享 map 到可控写入路径
- 2026-06-30 123浏览
-
- goalng 结构体 方法集 接口实例详解
- 2022-12-30 250浏览
-
- Go Ginrest实现一个RESTful接口
- 2023-02-24 462浏览
-
- go语言标准库fmt包的一键入门
- 2023-01-24 335浏览
-
- go语言中的defer关键字
- 2023-02-17 150浏览

