Go x/text/encoding/charmap DecodeByte 为什么不需要处理多字节边界

处理 Windows-1252、ISO-8859-1 这类单字节编码时，Go x/text/encoding/charmap DecodeByte 不需要等待“下一个字节”，因为 Charmap 的模型就是一个 8-bit 字符集：输入的每个 byte 都能独立查到一个 rune。它既不是 UTF-8 解码器，也不会把相邻两个字节拼成一个字符。

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

单字节编码决定了 DecodeByte 的边界

pkg.go.dev 对 Charmap 的定义是 8-bit character set encoding。这个定义已经给出了关键答案：输入空间固定为 0 到 255 的单个字节，编码表负责把它映射到 Unicode 码点。函数签名 DecodeByte(b byte) rune 也没有缓存、索引或“是否还差一个字节”的返回值，因此调用之间不存在待完成的字符。

所谓“多字节边界”，通常出现在一个字符可能跨越多个输入字节的编码里。那类解码器必须保留状态，判断当前字节是独立字符、前导字节还是后续字节；Charmap 不承担这件事。

DecodeByte 适合处理一个已知编码字节

下面的例子用 Windows-1252 的单个字节 0xE7 查表。它表示拉丁小写 ç；示例只说明 API 语义，不把一次调用当成完整文本解码。

package main

import (
    "fmt"

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

func main() {
    // 0xE7 在 Windows-1252 中对应 Unicode 字符 ç。
    const raw byte = 0xE7
    decoded := charmap.Windows1252.DecodeByte(raw)

    // DecodeByte 只做单字节查表，返回值已经是 rune。
    fmt.Printf("byte=0x%X rune=%U text=%c\n", raw, decoded, decoded)
}

这里不需要保存上一次的字节，也不需要先判断 raw 是否是“首字节”。如果换成另一张 Charmap，同一个数值可能对应不同字符，所以输入编码的声明必须和实际数据一致。

完整文本转换应交给 NewDecoder

当输入不止一个字节时，仍然可以利用单字节编码的独立性逐个处理，但业务代码通常应使用 NewDecoder。它实现了 encoding.Encoding 的解码接口，能把字节流转换成 UTF-8；代码更清楚，也避免把读取、缓冲和输出拼接散落在循环里。

package main

import (
    "fmt"
    "golang.org/x/text/encoding/charmap"
)

func main() {
    // Windows-1252 的字节序列：Garçon，其中 ç 是单个 0xE7。
    src := []byte{'G', 'a', 'r', 0xE7, 'o', 'n'}
    text, err := charmap.Windows1252.NewDecoder().Bytes(src)
    if err != nil {
        // 转换失败时保留错误，不把不完整结果当成成功文本。
        panic(fmt.Errorf("decode Windows-1252: %w", err))
    }
    fmt.Println(string(text))
}

对于 Charmap，DecodeByte 和 NewDecoder 的差别不在“一个处理单字节、一个处理多字节”，而在调用层次：前者是单个映射操作，后者是面向完整字节序列或 Reader 的转换器。

看到多字节编码时不要硬套 Charmap

Shift JIS、EUC-JP 等编码可能让一个字符占用多个字节，官方的 golang.org/x/text/encoding/japanese 包单独提供了这些编码。把它们的原始字节逐个送进 charmap.Windows1252.DecodeByte，得到的只是 Windows-1252 表中的两个独立字符，结果不会自动恢复成日文。

用三个检查点判断是否选对 API

1. 先确认协议、文件或数据库字段声明的字符集，不要从乱码结果反推编码。
2. 再看一个字符是否可能由多个输入字节组成；若可能，直接选择对应的状态型解码器。
3. 转换后统计替换字符 � 或错误返回，区分“编码表不匹配”和“字节边界处理错误”。

因此，DecodeByte 不处理多字节边界不是功能缺失，而是 Charmap 的设计前提：每个输入字节都是一个完整编码单元。只要数据确实属于对应的 8-bit 字符集，逐字节查表就是稳定、可预测的行为。

相关问题

• DecodeByte 返回的是 byte 还是 rune？ 返回 rune，表示查表后的 Unicode 字符。
• 为什么同一个 byte 换一张 Charmap 会变成不同字符？ 因为 byte 只是数值，字符含义由所选编码表决定。
• 完整文件是否应该手写 DecodeByte 循环？ 可以用于明确的低层查表场景；一般文本转换更适合 NewDecoder。