Go bytes.Runes 怎样把 UTF-8 字节转换为符文切片

如果手里拿的是一段 UTF-8 字节，却需要按 Unicode 字符逐个处理，bytes.Runes 就是直接的转换入口：它把 []byte 按 UTF-8 解释，返回等价的 []rune。因此，中文、表情和其他多字节字符不再被误当成几个独立字节。

最小写法是 runes := bytes.Runes(data)。但要记住：len(data) 是字节数，len(runes) 是符文数；如果输入可能不是合法 UTF-8，应先决定是拒绝、替换还是接受 RuneError。

bytes.Runes 到底转换了什么

Go 的 rune 是 int32 的别名，用来表示一个 Unicode code point。bytes.Runes 的输入是字节切片，函数会把它视为 UTF-8 编码的 code point 序列，返回一个符文切片。它不是把每个字节简单强转成整数，也不是把字节下标重新标记一下。

例如英文字符通常占一个 UTF-8 字节，中文字符通常占三个字节；经过转换后，两者都各自对应一个 rune 元素：

package main

import (
    "bytes"
    "fmt"
)

func main() {
    data := []byte("Go语言")
    runes := bytes.Runes(data)

    // len(data) 统计 UTF-8 字节数，len(runes) 统计符文数量。
    fmt.Printf("bytes=%d runes=%d\n", len(data), len(runes))
    for index, r := range runes {
        // %#U 同时显示码点编号和可读字符，便于核对解码结果。
        fmt.Printf("rune[%d]=%#U\n", index, r)
    }
}

这里的 index 是 []rune 的下标，单位已经从字节变成符文。图中的“字节切片—UTF-8 解码—符文切片”关系可以帮助区分这两个层级。

转换后怎样按符文读取和修改

需要按字符位置读取、替换或截取时，可以先转换为 []rune，再使用普通切片操作。修改完成后，再用 string(runes) 得到字符串；如果还需要字节切片，可以继续转换为 []byte(string(runes))。

package main

import (
    "bytes"
    "fmt"
)

func maskSecondRune(data []byte) string {
    runes := bytes.Runes(data)
    if len(runes) 

不要把原始字节的下标当成符文下标。例如中文的第一个字节可能只是一个多字节编码的开头，直接按这个位置截断会得到非法 UTF-8；先转为符文切片，才能按符文边界切分。

字节数、符文数和显示字符数要分开

同一段文本至少有三种容易混淆的长度：编码占用的字节数、Unicode code point 的数量，以及用户感知的字符数量。bytes.Runes 只解决第二层。

比如一个基础字母和组合重音符可能由两个 code point 组成，但用户通常把它看成一个显示字符。因此，len(bytes.Runes(data)) 不能直接作为输入框“可见字符数”的通用答案。

非法 UTF-8 需要先决定处理策略

如果字节切片来自文件、网络或外部接口，不要默认它一定是合法 UTF-8。可以先用 utf8.Valid 做显式判断；如果继续转换，非法编码会在解码时以 utf8.RuneError 表示，调用方要确认这是否符合业务要求。

package main

import (
    "bytes"
    "fmt"
    "unicode/utf8"
)

func decodeText(data []byte) ([]rune, error) {
    if !utf8.Valid(data) {
        // 外部输入不满足 UTF-8 时先拒绝，避免错误字符悄悄进入业务数据。
        return nil, fmt.Errorf("input is not valid UTF-8")
    }

    // 通过有效性检查后再转换，返回的每个元素都是可接受的符文。
    return bytes.Runes(data), nil
}

func main() {
    runes, err := decodeText([]byte("标题"))
    fmt.Printf("runes=%v err=%v\n", runes, err)
}

如果业务要求“尽量显示文本”，可以选择继续转换并记录错误；如果业务要求数据可逆，例如签名、协议解析或存档，则通常应拒绝非法输入，而不是把原始字节替换成 RuneError 后再保存。

哪些场景不该先调用 bytes.Runes

如果任务是解析固定二进制格式、计算字节长度、读取协议头或定位文件偏移，字节就是正确的抽象层，直接处理 []byte 更清楚。只有当业务真正需要按 Unicode code point 读取、修改或计数时，才把字节转换成符文。

• 需要按文本位置替换字符：先转 []rune，处理后再转回字符串。
• 需要判断输入是否合法：先调用 utf8.Valid，再决定是否转换。
• 需要用户感知的字符数：不要把符文数当成字素簇数量。
• 需要保持原始字节完全可逆：不要用会产生替换字符的宽松处理覆盖原始数据。

常见问题

bytes.Runes 会修改原来的 []byte 吗？

不会把符文修改写回原始字节切片。要修改文本，应修改返回的 []rune，再按需要重新编码。

为什么 len([]byte("中")) 和 len(bytes.Runes([]byte("中"))) 不一样？

前者统计 UTF-8 编码使用的字节数，后者统计解码后的符文元素数；多字节编码并不等于多个 Unicode code point。

bytes.Runes 和 for range 有什么区别？

range 适合一次遍历并同时拿到字节位置和符文；bytes.Runes 会把结果物化成 []rune，适合需要索引、修改或多次访问的场景。