Go fmt.Scanner 自定义扫描规则的实现要点

当 fmt.Sscan、Fscan 或 Sscanf 遇到实现了 fmt.Scanner 的参数时，会把扫描状态和格式动词交给这个类型的 Scan 方法。实现自定义规则的关键不是“从字符串转一次类型”，而是先界定词元、完整校验，再一次性写入指针接收者，避免错误输入留下半更新对象。

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

触发场景：让 fmt 把文本写入领域类型

一个实用场景是读取版本号。输入可能是 v1.24.3 或 1.24.3，业务希望直接得到三个整数字段，而不是每个调用点都重复执行切分和转换。只要 *SemVer 实现 fmt.Scanner，它就能作为 fmt 扫描函数的目标参数。

type SemVer struct {
	Major int
	Minor int
	Patch int
}

// 编译期断言确保指针类型实现 fmt.Scanner。
var _ fmt.Scanner = (*SemVer)(nil)

必须注意接收者。Scan 要把解析结果保存到对象中，值接收者只会修改副本，所以应写成 func (v *SemVer) Scan(...)。调用时也要传 &version；官方文档说明，被扫描参数必须是基本类型指针，或者实现 Scanner 的值。

权限配置：只接受约定的扫描动词

verb 来自格式字符串。无格式的 Sscan、Fscan 通常以 %v 语义调用自定义扫描器；Sscanf 则会传入格式中使用的动词。自定义类型不需要假装支持所有动词，明确接受 v 和 s，其余返回带上下文的错误，接口行为更可预测。

func (v *SemVer) Scan(state fmt.ScanState, verb rune) error {
	// 只开放能表达文本版本号的动词，其他格式直接拒绝。
	if verb != 'v' && verb != 's' {
		return fmt.Errorf("SemVer: 不支持扫描动词 %%%c", verb)
	}

	// 后续阶段负责读取词元、校验三段版本并提交结果。
	return v.scanToken(state)
}

这种动词检查相当于扫描规则的入口权限。它能防止调用方写出 %d 之类看似有效、实际语义不清的代码。错误应该返回给 fmt 扫描函数，由上层决定记录、重试还是拒绝输入，不要在 Scanner 内部打印或吞掉。

流水线阶段：Token、解析与提交

ScanState.Token 可以先跳过空白，再读取连续满足谓词的 Unicode 字符。版本号只允许数字、点和可选的 v 前缀，因此谓词保持很小。Token 遇到第一个不满足条件的字符就停止，适合这种单个、空白分隔的领域值。

func (v *SemVer) scanToken(state fmt.ScanState) error {
	// 词元只允许数字、点和可选前缀 v，避免把标点吞进版本号。
	token, err := state.Token(true, func(r rune) bool {
		return unicode.IsDigit(r) || r == '.' || r == 'v'
	})
	if err != nil {
		return fmt.Errorf("SemVer: 读取词元失败: %w", err)
	}

	// Token 的字节切片是共享数据；这里立刻转成字符串并在返回前完成解析。
	text := strings.TrimPrefix(string(token), "v")
	parts := strings.Split(text, ".")
	if len(parts) != 3 {
		return fmt.Errorf("SemVer: 需要 major.minor.patch，收到 %q", text)
	}

	var values [3]int
	for i, part := range parts {
		if part == "" {
			return fmt.Errorf("SemVer: 第 %d 段为空", i+1)
		}
		n, err := strconv.Atoi(part)
		if err != nil || n 

官方对 Token 的生命周期有特别说明：返回切片指向共享数据，下一次 Token 调用、使用同一 ScanState 的扫描调用，或者当前 Scan 方法返回，都可能覆盖它。因此不要把 token 保存到结构体；需要长期持有原文时，应在方法返回前复制。

门禁规则：先完整校验，再写入接收者

我更推荐“解析到临时对象”的做法。假设原对象是 1.2.3，新输入 2.x.0 在第二段失败；如果边解析边写字段，接收者可能变成 2.2.3 这种输入里从未存在过的混合状态。临时数组和 next 把提交点推迟到所有检查通过之后。

门禁不必过度扩张。SemVer 示例只保证三段非负整数，并没有实现完整语义化版本规范中的预发布标识和构建元数据。如果业务需要完整规范，应该扩展明确的领域解析器，再让 Scan 调用它，而不是在一个越来越长的谓词里塞进所有语法。

调用阶段：Sscan、Sscanf 和 Fscan 共用规则

实现接口后，同一规则可以接入字符串或 Reader。Sscan 适合空白分隔输入；Sscanf 可以匹配固定字面量；Fscan 则从指定 io.Reader 读取。三者最终都把领域值交给同一个 Scan 方法。

func parseExamples() error {
	var a, b, c SemVer

	// 无格式扫描使用默认动词语义。
	if _, err := fmt.Sscan("v1.24.3", &a); err != nil {
		return err
	}

	// 固定前缀由格式字符串匹配，%s 交给 SemVer.Scan。
	if _, err := fmt.Sscanf("release=v2.1.0", "release=%s", &b); err != nil {
		return err
	}

	// Reader 场景复用同一自定义扫描规则。
	reader := strings.NewReader("3.7.9")
	if _, err := fmt.Fscan(reader, &c); err != nil {
		return err
	}
	return nil
}

如果输入值之间没有空白，连续调用 Fscan 还要留意读取器能力。fmt 文档提醒，扫描函数可能多读一个 rune；Reader 同时实现 ReadRune 和 UnreadRune 时可以保存这个字符，bufio.NewReader 能为普通 Reader 补上这组能力。对有明确分隔符的复杂协议，专用解析器通常更稳。

失败处理：让错误保留字段上下文

自定义 Scanner 的错误会沿着 Sscan、Fscan 或 Sscanf 返回。错误文本至少应说明目标类型、失败阶段和原始片段，例如“SemVer 第 2 段不是非负整数”。这样上层不必猜是词元为空、动词不支持还是转换失败。

func TestSemVerScan(t *testing.T) {
	tests := []struct {
		input   string
		want    SemVer
		wantErr bool
	}{
		// 正常值覆盖有前缀和无前缀两种入口。
		{input: "v1.2.3", want: SemVer{1, 2, 3}},
		{input: "10.20.30", want: SemVer{10, 20, 30}},
		// 异常值覆盖缺段、空段和非数字字段。
		{input: "1.2", wantErr: true},
		{input: "1..3", wantErr: true},
		{input: "1.x.3", wantErr: true},
	}

	for _, tt := range tests {
		var got SemVer
		_, err := fmt.Sscan(tt.input, &got)
		if (err != nil) != tt.wantErr {
			t.Fatalf("input=%q err=%v", tt.input, err)
		}
		if err == nil && got != tt.want {
			t.Fatalf("input=%q got=%+v want=%+v", tt.input, got, tt.want)
		}
	}
}

什么时候不要用 fmt.Scanner

fmt.Scanner 最适合已有 fmt 扫描链路、输入是短小文本词元、并且领域类型需要统一解析规则的场景。如果要处理长记录、转义、嵌套语法、可恢复错误或精确位置，独立解析函数、bufio.Scanner 配合 SplitFunc，甚至专用解析器会更清楚。不要因为接口方便，就把一套协议语法全部压进单个 Scan 方法。

相关问题

为什么 Scanner.Scan 要用指针接收者？

扫描结果需要写回调用方对象。值接收者只修改副本，方法即使返回 nil，外部值也不会得到预期更新。

ScanState.Token 返回的 []byte 可以保存吗？

不能直接长期保存。它指向共享数据，后续扫描或 Scan 返回后可能被覆盖；需要保存时应复制。

Token 和 ReadRune 应该选哪个？

空白分隔、字符集合明确的词元优先 Token；需要逐字符处理转义、定界符或回退时再使用 ReadRune 与 UnreadRune。

Sscanf 会保证消耗完整输入吗？

不会。官方文档说明 Sscanf 不一定消耗完整输入，也无法恢复它具体用了多少字符；要求整串严格匹配时应增加外层校验或使用专用解析器。