Golang Printf 与 Sprintf：fmt 格式化动词速查表

fmt 包有三组打印函数，每组都有相同的三种变体：

package main

import (
	"fmt"
	"os"
)

func main() {
	name, score := "Ana", 92.456

	fmt.Println("Player", name, "scored", score)
	fmt.Printf("Player %s scored %.1f\n", name, score)

	msg := fmt.Sprintf("%s: %.0f points", name, score)
	fmt.Println(msg, len(msg))

	fmt.Fprintf(os.Stdout, "%-6s|%6.2f|\n", name, score)

	err := fmt.Errorf("player %q not found", "Ben")
	fmt.Println(err)
}

Println 会在操作数之间加空格，并在末尾加换行。Printf 什么都不加：\n 要你自己写。Print 只在两个相邻操作数都不是字符串时才加空格，这一点出人意料，所以大多数代码都用 Println 或 Printf。

格式化动词

通用

package main

import "fmt"

type User struct {
	Name string
	Age  int
	Tags []string
}

func main() {
	u := User{Name: "Ana", Age: 31, Tags: []string{"admin"}}

	fmt.Printf("%v\n", u)
	fmt.Printf("%+v\n", u)
	fmt.Printf("%#v\n", u)
	fmt.Printf("%T\n", u)
	fmt.Printf("%v\n", &u)

	m := map[string]int{"b": 2, "a": 1}
	fmt.Printf("%v %#v\n", m, m)
}

调试时首选 %+v。指向结构体的指针会打印成 &{...}，而不是一个地址。map 打印时按键排序，所以即使 map 的遍历顺序是随机的，输出也是稳定的。

整数

浮点数

%.2f 是对浮点数精确的二进制值做舍入，所以 fmt.Sprintf("%.2f", 2.675) 得到 2.67：最接近 2.675 的 float64 比它略小一点。永远不要用浮点数来格式化金额；用整数保存以分为单位的金额。

字符串与字节

对 []byte 使用 %s 会把它当作文本打印；%v 打印的是数字（[104 105]）。

其他类型

宽度、精度与填充

在 % 和动词之间，可以放标志、宽度和精度：

package main

import "fmt"

func main() {
	fmt.Printf("|%5d|%-5d|%05d|\n", 42, 42, 42)
	fmt.Printf("|%8.2f|%-8.2f|%.0f|\n", 3.14159, 3.14159, 2.5)
	fmt.Printf("|%10s|%-10s|%.3s|\n", "gopher", "gopher", "gopher")
	fmt.Printf("|%+d|%+d|\n", 5, -5)
	fmt.Printf("|%*d|\n", 7, 42) // width from an argument

	fmt.Println()
	items := []struct {
		name  string
		price float64
	}{{"Keyboard", 49.9}, {"Mouse", 19.5}, {"Monitor", 229}}
	for _, it := range items {
		fmt.Printf("%-10s %8.2f\n", it.name, it.price)
	}
}

注意，2.5 用 %.0f 打印出来是 2：这里 Go 采用四舍六入五成双。对字符串来说，宽度按 rune 计数，而不是按显示列数，所以中日韩字符和 emoji 仍可能让表格错位。要对齐长度不一的文本列，可以交给 text/tabwriter 去计算宽度。

参数索引

%[n] 按位置选取参数，这样同一个参数就可以重复使用：

fmt.Printf("%[2]s %[1]s\n", "world", "hello") // hello world
fmt.Printf("%d %[1]x %[1]b\n", 10)             // 10 a 1010

Errorf 与 %w

fmt.Errorf 根据格式字符串构造一个 error。配合 %w，它还会包装另一个错误，让调用方仍能识别出原错误：

package main

import (
	"errors"
	"fmt"
	"os"
)

func loadConfig(path string) error {
	_, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("load config %s: %w", path, err)
	}
	return nil
}

func main() {
	err := loadConfig("/no/such/file.yaml")
	fmt.Println(err)
	fmt.Println("not exist?", errors.Is(err, os.ErrNotExist))

	// %v formats the same text but does not wrap
	flat := fmt.Errorf("load config: %v", os.ErrNotExist)
	fmt.Println("wrapped?", errors.Is(flat, os.ErrNotExist))
}

调用方可能需要检查原因时用 %w，有意隐藏原因时用 %v。从 Go 1.20 开始，一次 Errorf 调用可以包含多个 %w。错误处理一页会深入讲解错误包装。

用 String() 自定义格式

任何带有 String() string 方法的类型，都能控制 %v、%s 和 Println 如何显示它：

package main

import "fmt"

type Money int64 // cents

func (m Money) String() string {
	return fmt.Sprintf("$%d.%02d", m/100, m%100)
}

func main() {
	price := Money(129950)
	fmt.Println(price)
	fmt.Printf("%v | %s | %d\n", price, price, price)
}

%d 会绕过 String()，打印底层的数字。对于错误类型，对应的方法是 Error() string，它的优先级高于 String()。

动词用错时

fmt 永远不会因为格式错误而 panic。它会把问题直接打印在输出里：

fmt.Printf("%d\n", "oops")
fmt.Printf("%d %d\n", 1)
fmt.Printf("%d\n", 1, 2)

%!d(string=oops)
1 %!d(MISSING)
1
%!(EXTRA int=2)

这样的输出往往会一路带到生产环境，因为它不会让任何东西崩溃。go vet 能在构建时发现这三种问题：

./main.go:8:2: fmt.Printf format %d has arg "oops" of wrong type string
./main.go:9:2: fmt.Printf format %d reads arg #2, but call has 1 arg
./main.go:10:2: fmt.Printf call needs 1 arg but has 2 args

性能说明

fmt 把每个参数都当作 any 接收，并在运行时检查其类型（遇到结构体、切片和 map 时会退回到反射），这用于日志和输出没有问题，但在紧凑的循环里就会产生可测量的开销。转换单个数字时，strconv.Itoa 和 strconv.FormatFloat 比 Sprintf 更快。在循环中构建长字符串时，用 fmt.Fprintf(&b, ...) 写入 strings.Builder，而不是把 Sprintf 的结果拼接起来。