fmt.Stringer — String() string

1. 为什么需要 fmt.Stringer，以及 fmt 如何使用它

当你刚开始写程序时，感觉输出不过就是“把数字和字符串显示出来”。但一旦你的程序里出现了带多个字段的结构体（struct）（而我们现在已经有了），默认输出很快就会变成一团乱麻：哪个是字段，哪个是值，为什么会这样打印，为什么读起来这么费劲。更糟的是看日志——每个结构体都“随便打印一下”，然后你就像考古学家一样盯着古老遗迹： “嗯……这里曾经有个 Done 字段……大概吧……”

Go 里有一个很好的原则：如果某个类型对你的程序很重要，它就应该能够用字符串进行合理表示。不一定总是需要，但至少在调试、日志和用户输出场景里应该可以。这里标准库就能帮上忙。

fmt.Stringer 接口，以及 fmt 内部的检查

最舒服的一点是：你不需要“改造” fmt，不需要自己写打印器，也不需要造一个方轮子。fmt 包里已经约定好：如果某个值能够自己转成字符串，那么 fmt 就会愉快地使用它。

这个约定由 fmt.Stringer 接口表达。在这节课里，我们把接口简单理解成“一个方法的契约”（不深入接口值和 nil 陷阱）：如果某个类型有这个签名的方法，那它就符合这个契约。

下面就是 Stringer 的核心形式：

type Stringer interface {
    String() string
}

这个思路和 fmt 处理错误的方式很像：error 是一个拥有 Error() string 方法的值，fmt 会通过这个方法打印它。Stringer 也是同样的逻辑，只不过用于“普通”类型。

为了“看到”这个机制，最好把它想成一张小流程图：

flowchart TD
    A["fmt.Println(x)"] --> B{"x implements String() string?"}
    B -- yes --> C["call x.String()"]
    C --> D[print the resulting string]
    B -- no --> E[use default fmt formatting]
    E --> D

注意，这不是魔法。它只是检查“这个值有没有 String() 方法”。

2. 示例：让 Task 更好看

我们继续扩展教学应用：一个小小的“任务管理器”。我们还不会直接跳到真正的 CLI（那是另一天的内容），但数据模型已经可以做得更友好：有任务，有标题，还有完成标志。

先从一个简单结构体开始，看看它“默认”是怎么打印的：

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func main() {
	t := Task{ID: 1, Title: "Read about Stringer", Done: false}
	fmt.Println(t) // {1 Read about Stringer false}
}

这种输出……嗯……“技术上没错”。但从人的角度看，你并不总能迅速看懂哪个字段对应哪个值。我们给它加上 String()。

重要的是：String() 方法应该返回字符串，而不是自己打印。打印是 fmt 的工作，你的工作是提供一个漂亮的表示。

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	if t.Done {
		return fmt.Sprintf("#%d %q (done)", t.ID, t.Title)
	}
	return fmt.Sprintf("#%d %q (todo)", t.ID, t.Title)
}

func main() {
	t := Task{ID: 1, Title: "Read about Stringer", Done: false}
	fmt.Println(t) // #1 "Read about Stringer" (todo)
}

注意 %q：它会把字符串放在引号里，并对特殊字符进行转义。对于调试来说，它通常比单纯的 %s 更有用，因为你能立刻看到空格、制表符和其他“隐形艺术家”。

而现在魔法出现了：fmt.Println() 不再执行“结构体默认输出”，而是调用我们的 t.String()。

3. String() 的 receiver：T 还是 *T

这里开始进入一个很关键的点：前面课程里的知识终于会在“真实世界”里生效，而不只是练习题里“把点往右挪 10 格”。我们已经知道：

• func (t Task) ... — value receiver，得到的是副本。
• func (t *Task) ... — pointer receiver，得到的是地址。

不过 String() 有一个特点：它几乎不应该修改对象。它是一个“照镜子并描述所见”的方法。如果镜子会改变脸，那这个镜子就很可疑。

所以通常的做法是：把 String() 写成 value receiver。

还有一个更实用的原因：如果 String() 定义在 Task（值）上，那么 Task 和 *Task 都能漂亮打印。反过来，如果你把 String() 定义在 *Task 上，那么漂亮输出只对指针有保证，而值可能会“按默认方式”打印——这正是 method set 的直接结果。

我们看一个小例子对比一下：

package main

import "fmt"

type Note struct {
	Text string
}

func (n *Note) String() string {
	return "NOTE: " + n.Text
}

func main() {
	n := Note{Text: "don't forget about receiver"}
	fmt.Println(n)  // {don't forget about receiver}
	fmt.Println(&n) // NOTE: don't forget about receiver
}

为什么会这样？因为 Note（值）并不一定在自己的 method set 里拥有 String()，如果这个方法只定义在 *Note 上。而 *Note 能“看到”更多方法。

为了便于理解，这里有一张简明表格：

func (t T) String() string

func (t *T) String() string

还有一个细节：如果你为 String() 使用 pointer receiver，就要记住它可能是一个 nil 指针。今天我们不深入接口细节，但基本的谨慎还是要有：如果方法定义在 *T 上，那么内部的 t 可能是 nil，任何字段访问（t.Title）都会导致 panic。

4. 面向状态的 String()：switch 和 default

任务里经常会有“状态”：新建、进行中、已完成、已取消。在 Go 中，一个常见做法是基于 int 定义命名类型和常量。为了不把 0、1、2 直接显示给用户，我们会编写 String()。

这种 String() 的经典模式是 switch + default，其中 default 返回某种可诊断的内容。这是很好的实践：未知值应该被打印成能让你看出“它是未知的”，而不是悄悄撒谎。

给任务加上状态：

package main

import "fmt"

type Status int

const (
	StatusTodo Status = iota
	StatusDone
)

func (s Status) String() string {
	switch s {
	case StatusTodo:
		return "todo"
	case StatusDone:
		return "done"
	default:
		return fmt.Sprintf("Status(%d)", int(s))
	}
}

现在更新 Task 和它的 String()：

package main

import "fmt"

type Status int

const (
	StatusTodo Status = iota
	StatusDone
)

func (s Status) String() string {
	switch s {
	case StatusTodo:
		return "todo"
	case StatusDone:
		return "done"
	default:
		return fmt.Sprintf("Status(%d)", int(s))
	}
}

type Task struct {
	ID     int
	Title  string
	Status Status
}

func (t Task) String() string {
	return fmt.Sprintf("#%d %q [%s]", t.ID, t.Title, t.Status)
}

func main() {
	t1 := Task{ID: 1, Title: "Understand Stringer", Status: StatusTodo}
	t2 := Task{ID: 2, Title: "Be happy", Status: StatusDone}

	fmt.Println(t1) // #1 "Understand Stringer" [todo]
	fmt.Println(t2) // #2 "Be happy" [done]
}

注意：我们在 Task.String() 里用 %s 格式化 t.Status。但 %s 期待的是字符串。为什么这样能工作？因为 Status 实现了 Stringer，而 fmt 知道如何通过 String() 提取字符串表示。

5. Stringer 与格式化：%v 和“原始”字段

当你添加了 String() 之后，你就得到了非常适合人看的输出。但反过来，有时在调试时你又想看到结构体的全部字段，而 String() 只展示“漂亮橱窗”。

这不是 bug，而是规律：如果 fmt 看到了 String()，它就会认为你比它更清楚该如何打印这个类型。

我们来看一下：

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	if t.Done {
		return "done: " + t.Title
	}
	return "todo: " + t.Title
}

func main() {
	t := Task{ID: 10, Title: "debug output", Done: false}

	fmt.Println(t)        // todo: debug output
	fmt.Printf("%v\n", t) // todo: debug output
	fmt.Printf("%T\n", t) // main.Task
}

这有时非常不错。但如果你临时想看“原始”对象，可以用一个简单技巧：创建一个没有方法的临时类型别名，并把值转换过去。它看起来有点“黑客”，但其实很诚实也很透明：你是在告诉编译器“把它当成另一个没有 String() 的类型”。

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	return fmt.Sprintf("Task#%d %q", t.ID, t.Title)
}

type rawTask Task

func main() {
	t := Task{ID: 10, Title: "look at fields", Done: false}

	fmt.Println(t)                  // Task#10 "look at fields"
	fmt.Printf("%+v\n", rawTask(t)) // {ID:10 Title:look at fields Done:false}
}

没错，这只是一个小技巧。但当你不想为了调试删掉 String() 时，它很有用。

6. 好的 String()：简洁和防止递归

对于 String() 方法，很容易想做“最聪明、最通用”的事，然后不小心制造无限递归，或者把简单输出变成一个庞然大物。现实里，String() 应该是朴素的。这里是褒义。

第一条规则：不要有副作用。String() 不应该修改字段、写文件、增加计数器、发送网络请求，或者“顺手”修复数据库。因为 fmt 可能会在你意想不到的时候调用 String()：你在日志里打印了结构体，在错误里输出了它，或者在别的地方调试了一下——然后“普通的 println”突然开始改变程序行为。

第二条规则：不要 panic。如果 String() panic，那么调试输出本身就会变成一颗地雷。最好返回类似 "<invalid>" 这样的内容，或者优雅地处理异常值。

第三条规则：不要通过 %v 再格式化自己，否则就会递归。下面是一个“不要这样做”的例子：

package main

import "fmt"

type Task struct {
	Title string
}

func (t Task) String() string {
	return fmt.Sprintf("%v", t) // bad: fmt will call String() again
}

func main() {
	fmt.Println(Task{Title: "boom"})
}

这会导致无限尝试打印 t，而它又会再次调用 String()，然后又调用 fmt.Sprintf()，如此循环——直到栈耗尽。

正确的写法是显式格式化字段：

package main

import "fmt"

type Task struct {
	Title string
}

func (t Task) String() string {
	return fmt.Sprintf("Task{title=%q}", t.Title)
}

func main() {
	fmt.Println(Task{Title: "ok"}) // Task{title="ok"}
}

7. 常见错误

错误 1：把 String() 定义在 *T 上，然后打印值 T，再感到困惑。
这看起来很无害：“我明明已经写了 String() 啊。”但 method set 可不会体谅粗心。如果 String() 只挂在 *T 上，那么对类型为 T 的 x，fmt.Println() 可能会打印默认结构体格式，而不是你漂亮的文本。最简单的办法是把 String() 写成 value receiver，因为这个方法本来就不该修改对象，而且对两种情况都安全。

错误 2：String() 修改对象状态。
有时你会想在 String() 里“顺手”修正数据：去掉空格、给空字段填默认值、调整状态。问题在于，打印不应该改变程序语义。String() 应该是个纯函数：看一眼，返回字符串，然后离开。如果你需要数据归一化，请单独写一个方法，比如 Normalize()。

错误 3：通过 fmt.Sprintf("%v", x) 递归调用自己进行打印。
这是经典问题，尤其常见于初学者：“我只是想写得通用一点。”但 fmt 和 Stringer 的行为正是你要求的那样，所以递归是诚实的、无限的、并且毫不留情。解决方法很简单：直接格式化字段，不要试图“再把整个对象打印一遍”。

错误 4：输出太“重”——多行、所有字段、巨大的嵌套结构。
有时人们会把 String() 变成一个迷你内存转储：“把所有东西都打印出来，肯定最清楚。”实际上这会毁掉可读性。好的 String() 通常只显示 2–4 个关键字段：标识符、名称、状态。其余内容根据需要用单独的诊断打印。

错误 5：在枚举的 String() 里忘记 default。
今天你有 StatusTodo 和 StatusDone，明天某处就可能意外写入 Status(123)（解析错误、逻辑 bug、脏数据）。如果 String() 不会显示未知值，你得到的要么是空白，要么是误导性的文本。合理的 default 会返回类似 Status(123) 的内容，让问题立刻可见。对于类似 enum 的类型，这种带诊断信息的 default 是 String() 的稳定实践。

1

任务

Go SELF, 第 22 级, 课程 3

已锁定

个人名片

个人名片

打开

1

任务

Go SELF, 第 22 级, 课程 3

已锁定

交通信号灯模式

交通信号灯模式

打开

1

任务

Go SELF, 第 22 级, 课程 3

已锁定

标记坐标

标记坐标

打开

1

任务

Go SELF, 第 22 级, 课程 3

已锁定

订单与转储

订单与转储

打开