Go x/text/runes 字符过滤为什么不能按字节索引理解

我在处理一段同时包含英文、中文和空白字符的输入时，最容易犯的错是把字符串下标当成“第几个字符”。Go 的字符串保存的是 UTF-8 字节序列，而 golang.org/x/text/runes 的过滤器面对的是解码后的 rune。所以，按字节切片、按 rune 判断、再重新编码，是三个不同层次的动作。

官方资料：https://pkg.go.dev/golang.org/x/text/runes

字符过滤不能按字节索引理解：len(s) 和 s[i] 的单位是字节，runes.Remove、runes.Map、runes.If 的判断单位是 rune。要做过滤，先让 Transformer 按 UTF-8 处理，再在输出字符串上重新计算位置。

字节下标和 rune 过滤不是同一种索引

以“Go语言”为例，英文字符通常占 1 个 UTF-8 字节，中文字符通常占 3 个字节。字符串下标只能定位某个字节，不能保证定位到一个完整字符的开头；如果从中文字符的中间切开，再把结果当成 UTF-8 文本传给过滤器，问题已经发生在过滤之前。

package main

import "fmt"

func main() {
	s := "Go语言"

	// len 和 s[i] 面向字节；range 同时给出字节起点和解码后的 rune。
	fmt.Println("字节数:", len(s))
	fmt.Printf("第 2 个字节: %#x\n", s[1])
	for bytePos, r := range s {
		// bytePos 是 UTF-8 字节偏移，不是第几个 rune。
		fmt.Printf("字节偏移=%d, rune=%q\n", bytePos, r)
	}
}

这里的 bytePos 可能跳过多个字节，正是因为一个 rune 可以由多个 UTF-8 字节组成。如果业务需要“第几个字符”，可以先转成 []rune，或使用 utf8.RuneCountInString；不要拿 len(s) 直接当字符数量。

先用 Set 或 Predicate 描述要过滤的 rune

runes.Set 的核心方法是 Contains(r rune) bool。也就是说，过滤条件接收的是一个 rune，而不是一个字节。固定的 Unicode 范围可以用 runes.In 或 runes.NotIn，需要业务条件时可以用 runes.Predicate。

package main

import (
	"fmt"
	"unicode"

	"golang.org/x/text/runes"
	"golang.org/x/text/transform"
)

func main() {
	input := "  Go语言\t过滤空白  "

	// Predicate 接收 rune；unicode.IsSpace 会识别 Unicode 空白字符。
	spaceSet := runes.Predicate(unicode.IsSpace)
	removeSpace := runes.Remove(spaceSet)

	// transform.String 负责把字符串交给 Transformer，并返回新的字符串。
	cleaned, _, err := transform.String(removeSpace, input)
	if err != nil {
		// 过滤器出错时不要继续使用不完整结果。
		panic(err)
	}
	fmt.Println(cleaned)
}

这个例子并没有检查 input[i] == ' '。如果只判断 ASCII 空格，会漏掉制表符、换行符以及其他 Unicode 空白；如果用字节下标扫描多字节字符，还可能把一个字符拆开。把判断封装成 Set 后，过滤器的输入单位就明确了。

Remove、Map 和 If 都在 rune 层工作

runes.Remove 删除命中集合的 rune，runes.Map 为每个 rune 调用映射函数，runes.If 则根据集合命中情况在两个 Transformer 之间选择。它们都实现了 transform.Transformer，通常通过 transform.String、transform.Bytes 或流式 Reader 使用。

package main

import (
	"fmt"
	"unicode"

	"golang.org/x/text/runes"
	"golang.org/x/text/transform"
	"golang.org/x/text/width"
)

func main() {
	input := "Ａ Go Ｂ"

	// Set 判断的是 rune；命中 ASCII 以外的 rune 时使用宽度折叠。
	isASCII := runes.Predicate(func(r rune) bool {
		return r 

这里的重点不是选哪一种宽度转换，而是 isASCII 接收到的是 rune。若把输入先拆成单字节，再自己判断是否属于 ASCII，代码就同时承担了解码、边界处理和转换三个职责，很容易在中文或其他多字节文字上出现错误。

分块读取时，不要把每个字节块当成独立字符串

完整字符串可以交给 transform.String，但文件、网络流或大文本常常按块读取。一个 UTF-8 字符可能刚好被拆到两个块中；此时对每块单独调用字符串转换，会把“半个字符”误认为非法输入。transform.NewReader 用 Reader 包装输入，让 Transformer 参与连续的读取过程。

package main

import (
	"io"
	"strings"
	"unicode"

	"golang.org/x/text/runes"
	"golang.org/x/text/transform"
)

func readWithoutUnicodeSpaces(src io.Reader) (string, error) {
	// 过滤器仍然按 rune 判断；Reader 负责把流式字节交给 Transformer。
	t := runes.Remove(runes.Predicate(unicode.IsSpace))
	reader := transform.NewReader(src, t)

	// ReadAll 只负责收集转换后的结果，不再手动按字节拼接字符。
	data, err := io.ReadAll(reader)
	if err != nil {
		return "", err
	}
	return string(data), nil
}

func example() (string, error) {
	// strings.Reader 模拟连续输入；真实场景可以替换成文件或网络 Reader。
	return readWithoutUnicodeSpaces(strings.NewReader("Go 语言"))
}

如果业务必须自己管理块边界，就要把“未完成的 UTF-8 字节”保留下来，等下一块到达后再解码。通常让 transform.Reader 或同类流式封装承担这件事更稳妥。不要因为某一次块大小恰好没有切开中文，就把偶然结果当成字节索引是安全的。

非法 UTF-8 不是普通字符过滤条件

runes 的不同 Transformer 对非法输入有明确但不完全相同的处理约定。runes.Map 和 runes.Remove 的文档说明，非法输入字节在交给映射函数或集合判断前会以 utf8.RuneError 参与处理；runes.If 会用 RuneError 决定选择哪个分支，但非法字节会原样传给相应 Transformer。

如果目标是把所有非良构 UTF-8 统一替换成替换字符，可以显式使用 runes.ReplaceIllFormed()。不要把“遇到 RuneError”简单理解成原文一定包含 U+FFFD；它也可能是解码非法输入时产生的替代表示。

package main

import (
	"fmt"

	"golang.org/x/text/runes"
	"golang.org/x/text/transform"
)

func main() {
	input := []byte{'A', 0xff, 'B'}

	// ReplaceIllFormed 将不属于良构 UTF-8 序列的字节替换为 RuneError。
	t := runes.ReplaceIllFormed()
	output, _, err := transform.Bytes(t, input)
	if err != nil {
		panic(err)
	}
	// output 是新切片；不要把它当作 input 的原地修改结果。
	fmt.Printf("%q\n", string(output))
}

如果过滤器本身可能返回错误，要检查 transform.String 或 transform.Bytes 的错误结果。官方文档还说明，Bytes 会返回新的字节切片；错误发生时可能返回 nil，因此不能只看部分输出就认为转换成功。

转换完成后，再重新计算位置和长度

过滤会改变字节数量，映射也可能把一个 rune 变成另一个占用不同字节数的 rune。任何保存下来的旧字节偏移，都只对旧字符串有效。需要字符位置时，按需求选择下面两种方式：

package main

import (
	"fmt"
	"unicode/utf8"
)

func main() {
	s := "Go语言"
	filtered := "Go语"

	// 过滤后的字符串已经是新值，旧字符串的 byte offset 不再适用。
	fmt.Println("新字符串字节数:", len(filtered))
	fmt.Println("新字符串 rune 数:", utf8.RuneCountInString(filtered))

	// 只有确实需要按 rune 序号访问时，才创建 rune 切片。
	runes := []rune(filtered)
	if len(runes) > 1 {
		fmt.Printf("第 2 个 rune: %q\n", runes[1])
	}
	_ = s
}

把这类问题归纳成三个判断

1. 先问输入是不是完整、良构的 UTF-8；如果是分块流，不要把块边界当字符边界。
2. 再问过滤条件的单位是什么；runes.Set、Predicate 和 Map 面向 rune，不面向字节。
3. 最后问位置是在转换前还是转换后；过滤或映射之后，长度和偏移都必须重新计算。

只要把“字节存储”“rune 语义”“Transformer 输出”分开，golang.org/x/text/runes 的行为就不再神秘。它不是帮你把字节下标变成字符下标，而是提供一组面向 UTF-8 文本转换的 Transformer。

相关问题

• len(s) 为什么比字符数大？ 因为 len 统计的是 UTF-8 字节数；需要 rune 数时使用 utf8.RuneCountInString。
• runes.Remove 能不能原地修改字符串？ 不能把字符串当作可变字节数组；转换函数返回新的结果。
• 非法字节应该直接删除吗？ 先明确协议要求。需要统一替换时使用 ReplaceIllFormed，不要把错误输入悄悄当作正常字符。
• 为什么不能对每个网络块分别调用 transform.String？ 因为块可能从一个 UTF-8 字符中间切开，应使用连续的 Reader/Transformer 处理边界。