Go x/text/encoding/charmap EncodeRune 怎样判断字符能否编码

在 Go 中，UTF-8 字符串能保存的字符，不一定都能被某个单字节字符集表示。要在写文件、拼接协议字段或兼容旧系统前做一次明确判断，可以直接调用 Charmap.EncodeRune：它返回目标字符集中的一个 byte，以及表示是否成功的 bool。

本文只解决一个问题：如何判断一个 rune 能否被 golang.org/x/text/encoding/charmap 编码。关键结论是，不要用返回字节是否为零来判断成功，而要看第二个返回值 ok。

官方文档：https://pkg.go.dev/golang.org/x/text/encoding/charmap

理解 EncodeRune 的返回值

charmap.Charmap 表示一个 8 位字符集。它的 EncodeRune 方法签名是：

func (m *Charmap) EncodeRune(r rune) (b byte, ok bool)

r 是要尝试编码的 Unicode 码点，b 是目标字符集中的单字节结果，ok 表示这个字符是否属于该字符集的可表示范围。ok=false 时，b 不应该被当作有效输出继续写入。

还有一个容易忽略的边界：NUL 字符的编码字节可能正好是 0，但它仍然可能是合法可编码字符。因此，正确写法是判断 ok，而不是判断 b == 0。

用 EncodeRune 预判单个字符

下面用 Windows-1252 做一个最小判断器。它可以表示常见西欧字符和欧元符号，但不能覆盖所有 Unicode 字符；示例中的中文字符会走不可编码分支。

package main

import (
	"fmt"

	"golang.org/x/text/encoding/charmap"
)

func main() {
	// 选取一个 ASCII 字符、一个扩展字符和一个超出字符集范围的字符。
	samples := []rune{'A', '€', '中'}

	for _, r := range samples {
		b, ok := charmap.Windows1252.EncodeRune(r)
		if !ok {
			// ok=false 表示目标 Charmap 无法表示当前 rune。
			fmt.Printf("%q: 不可编码\n", r)
			continue
		}

		// b 是目标字符集中的单字节，不是 UTF-8 字符串。
		fmt.Printf("%q: 0x%02X\n", r, b)
	}
}

判断时可以按下面的三步理解：

1. 把要写入旧系统的字符当作 rune 传给 EncodeRune。
2. 先读取 ok，只有为 true 时才使用 b。
3. 遇到 false 时记录字符位置，并根据业务决定报错、替换或回退到 UTF-8。

返回的 b 是目标编码的字节，不应直接用 string(b) 当成 UTF-8 文本展示。若要向用户显示原文，保留原始 rune；若要写入目标文件，才把这个字节追加到目标字节切片。

把判断接入整段字符串转换

当业务要求“只要有一个字符无法表示就拒绝整条记录”时，可以在转换前逐个 rune 检查。Go 的 range 会给出 UTF-8 字节偏移，这比用字符计数更适合报告原文位置。

package main

import (
	"fmt"

	"golang.org/x/text/encoding/charmap"
)

// firstUnsupported 返回第一个无法被目标 Charmap 表示的 UTF-8 字节偏移。
func firstUnsupported(m *charmap.Charmap, s string) (offset int, r rune, found bool) {
	for offset, r := range s {
		// 这里只做能力判断，不提前生成目标字节流。
		if _, ok := m.EncodeRune(r); !ok {
			return offset, r, true
		}
	}

	return -1, 0, false
}

func main() {
	input := "Cafe € 中"
	offset, r, found := firstUnsupported(charmap.Windows1252, input)
	if found {
		// offset 是原 UTF-8 字符串中的字节位置，不是 rune 序号。
		fmt.Printf("位置 %d 的 %q 无法编码\n", offset, r)
		return
	}

	fmt.Println("整段文本可以编码")
}

这个检查器适合表单导入、批量写旧格式文件等需要“全有或全无”的场景。如果业务允许部分字符替换，可以在同一处记录 offset 和 rune，再把替换策略写清楚，不要静默丢失原文。

区分 EncodeRune 与 NewEncoder

EncodeRune 解决的是“这个单独的 rune 能不能表示”。如果目标是把一整段 UTF-8 字符串转换成目标编码，通常应使用 NewEncoder 创建 encoding.Encoder，让转换器处理整段输入和错误返回。

package main

import (
	"fmt"

	"golang.org/x/text/encoding/charmap"
)

func main() {
	input := "Cafe €"

	// Encoder.Bytes 接收 UTF-8 字节，并返回目标 Charmap 的字节。
	out, err := charmap.Windows1252.NewEncoder().Bytes([]byte(input))
	if err != nil {
		// 目标字符集无法表示某个 rune 时，保留错误并停止发布字节。
		fmt.Printf("转换失败：%v\n", err)
		return
	}

	fmt.Printf("目标字节长度：%d\n", len(out))
}

如果数据来自文件或网络流，则可以把编码器交给 transform.NewWriter。它适合边读边写的路径，但关闭包装 Writer 仍然重要，因为转换器可能还有尚未刷出的字节。

package main

import (
	"bytes"
	"fmt"
	"io"

	"golang.org/x/text/encoding/charmap"
	"golang.org/x/text/transform"
)

func main() {
	var dst bytes.Buffer
	writer := transform.NewWriter(&dst, charmap.Windows1252.NewEncoder())

	// Writer 负责把写入的 UTF-8 文本转换成目标字节流。
	_, writeErr := io.WriteString(writer, "Cafe €")
	closeErr := writer.Close()
	if writeErr != nil || closeErr != nil {
		// 同时检查 Write 和 Close，避免漏掉收尾阶段的转换错误。
		fmt.Printf("流式转换失败：write=%v close=%v\n", writeErr, closeErr)
		return
	}

	fmt.Printf("已生成 %d 个目标字节\n", dst.Len())
}

简单选择规则是：要提前给用户指出哪一个字符有问题，用 EncodeRune；要转换完整字符串，用 NewEncoder；要把大量数据持续写向目标流，用 transform.NewWriter。

整理生产环境决策清单

把 EncodeRune 放入正式业务时，可以按下面的顺序做决定：

最重要的边界只有两个：ok 才是可编码性判断，b 只是目标字符集中的一个字节；以及单字符预判和整段转换是两个不同层次的问题。把这两点分开，编码失败就能被明确记录，而不是在下游变成乱码。

常见问题

EncodeRune 返回的 byte 为 0，是不是编码失败？

不一定。应以第二个返回值 ok 为准，因为某些字符的合法目标字节本来就可能是零。

为什么不直接判断 rune 是否小于 256？

目标 Charmap 的映射不等于简单的数值范围判断。是否可表示必须交给具体的 Charmap 查询。

遇到 ok=false 时能否自动换成问号？

可以，但这是业务策略，不是 EncodeRune 自动完成的结果。需要替换时应显式记录替换发生过，避免静默数据损失。