Go 编码Reader 读取 UTF-8 半个字符时怎么办

io.Reader 读到 UTF-8 字符的一部分是正常的字节流行为，不需要让每次 Read 都凑齐一个汉字。若调用方按字符消费，我会让一个持续存在的 bufio.Reader 使用 ReadRune；若必须批量处理，则保留当前块末尾未完成的字节，与下一块拼接后再解码。

我不会把“每块转成字符串就能打印”当作接口保证。真正需要确定的是：输入是否约定为 UTF-8、非法字节是拒绝还是替换、流结束时残留的半个编码如何处理。下面用可复现的单字节来源说明这些取舍，不冒充亲历事故或本机实测。官方文档：https://pkg.go.dev/io、https://pkg.go.dev/bufio、https://pkg.go.dev/unicode/utf8。

我会先把读取边界和字符边界分开

假设接收端使用一个小缓冲读取包含汉字和表情的文本。UTF-8 的一个码点可能占多个字节，而 Read 只承诺返回读取到的字节数，不承诺字符边界，也不承诺把缓冲区填满。加大缓冲只是减少某些边界出现的机会，不会消除这个条件。

直接把每块转为 string 会保留该块字节，但不会替你校验、补齐或修复 UTF-8。如果随后对这个独立字符串做 range、转为 rune 切片或送入替换非法编码的组件，半个编码就可能被当作错误。反过来，按顺序原样转发原始字节不一定需要先做字符解码，前提是后续接收方按连续字节流处理，而不是把每块当成独立完整文本。

因此我的接口判断是：需要字节传输就保留字节，需要码点语义就引入有状态解码；不要让底层一次 Read 的大小决定上层字符定义。

让同一个缓冲读取器负责解码

这里可以分成“字节来源组”和“解码消费组”。字节来源组包含“底层 Reader、读取片段、残留字节”；解码消费组包含“缓冲读取器、ReadRune、字符消费者”。底层 Reader 提供读取片段，读取片段可能包含未完成的残留字节；缓冲读取器管理尚未消费的字节，ReadRune 依赖缓冲并向字符消费者提供码点。

我会在进入读取阶段时创建一次 bufio.Reader，之后统一从它读取。不要每次循环都给原始 Reader 包一个新的缓冲器，也不要混用原始 Reader.Read 与缓冲器.ReadRune。缓冲器可能已经预读了更多字节，绕开它继续读会让调用方跳过仍留在旧缓冲中的内容。

同样，若处理函数可能提前退出并把输入交给其他逻辑，接口就应让调用方持有并继续使用同一个缓冲器，或明确返回剩余状态。下面的简化接口拥有整个读取阶段，遇到错误就结束，不支持把原始 Reader 无损交回后续消费者。

用单字节来源写一个完整示例

我会先用“每次最多返回一个字节”的来源考察边界，而不是依赖网络恰好怎样分包。以下 main.go 是完整示例，读取成功时逐个输出码点；对于非法或截断 UTF-8，选择返回错误。

package main

import (
    "bufio"
    "fmt"
    "io"
    "os"
    "unicode/utf8"
)

// 人为把底层读取切成单字节，模拟字符跨 Read 边界。
type byteSource struct {
    data []byte
}

func (s *byteSource) Read(p []byte) (int, error) {
    if len(p) == 0 {
        return 0, nil
    }
    if len(s.data) == 0 {
        return 0, io.EOF
    }
    p[0] = s.data[0]
    s.data = s.data[1:]
    if len(s.data) == 0 {
        // Reader 允许最后一次同时返回数据和 EOF。
        return 1, io.EOF
    }
    return 1, nil
}

// 本接口拥有整个读取阶段；emit 失败即停止，已消费的字符不会回滚。
func consumeUTF8(src io.Reader, emit func(rune) error) error {
    reader := bufio.NewReader(src)
    var offset int64
    for {
        r, size, err := reader.ReadRune()
        if err != nil {
            if err == io.EOF {
                return nil
            }
            return fmt.Errorf("字节位置 %d 读取失败: %w", offset, err)
        }
        // 非法编码消耗一字节；合法 U+FFFD 的 UTF-8 宽度是三字节。
        if r == utf8.RuneError && size == 1 {
            return fmt.Errorf("字节位置 %d 存在非法或截断的 UTF-8", offset)
        }
        if err := emit(r); err != nil {
            return fmt.Errorf("字节位置 %d 消费失败: %w", offset, err)
        }
        offset += int64(size)
    }
}

func run() error {
    source := &byteSource{data: []byte("A湖🙂\uFFFD")}
    return consumeUTF8(source, func(r rune) error {
        // 字符宽度是编码字节数，不是屏幕列宽。
        _, err := fmt.Fprintf(os.Stdout, "%U %q\n", r, r)
        return err
    })
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

代码里的输入包含 ASCII、汉字、表情和一个合法编码的 U+FFFD。按定义，消费者应依次收到这四个码点，不因底层单字节读取而丢失汉字或表情；合法 U+FFFD 也不应被拒绝。这是读者执行时的预期，不是本文的终端输出。

这里最容易忽略的是 size。ReadRune 遇到非法 UTF-8 时会消耗一个字节并返回 RuneError，宽度为 1，而不是保证返回一个非空 err。合法 U+FFFD 本身也等于 RuneError 这个码点，但它的 UTF-8 编码宽度为 3，因此不能只比较 r 是否等于 RuneError。

这个函数还把消费者错误与读取错误分别包装。已经交给 emit 的前缀不会回滚；如果一条记录必须整体通过后才能提交，应在有长度上限的记录缓冲中完成检查，再进行业务提交。逐码点输出适合流式消费，不意味着整个输入具有事务原子性。

批量解码时我会保留哪些状态

如果按批处理更符合业务，我会明确保存“当前片段、待解码缓冲、完整编码前缀”和“残留后缀、流结束状态、错误策略”。当前片段并入待解码缓冲；完整编码前缀与残留后缀属于该缓冲的不同部分。流结束状态决定后缀能否继续等待，错误策略决定无效字节怎样处置。

utf8.FullRune 判断缓冲开头是否已经足以解码一个结果。返回 false 且输入尚未结束时，应保留这些字节，不立即替换；返回 true 后仍要用 DecodeRune 判断结果是否是宽度为 1 的 RuneError。FullRune 对明显无效编码也可能返回 true，它不是 Valid 的同义词。

每轮先解码已有的完整前缀，仅把不足一个编码的后缀留到下一轮。对合法 UTF-8，未完成后缀最多只有三个字节，但这只约束编码尾部，不约束应用自己积攒的整行、整条消息或完整结果，不能据此宣称内存总量天然有界。

自己写 Read 循环时，要先处理 n 大于零的字节，再处理同时返回的 err。Reader 允许最后一次返回数据加 io.EOF，也允许下一次才返回 EOF。遇到 EOF 时仍有未完成编码，就按接口选择报错或替换，不能一直等待不存在的下一块。非 EOF 的读取失败也不能被当成正常结束。

手写批量解码还应限制输入与缓冲规模，并处理反复出现的零字节、nil 错误，避免忙循环。若没有明确的批处理收益，我更倾向于前面的 ReadRune 方案，减少自己维护状态的范围；它不替代底层连接的读取超时或取消机制。

把错误策略写进接口而不是靠显示猜测

若底层错误发生在一个不完整编码后，读取器可能先把已经缓冲的尾字节作为非法编码交给调用方。本例选择报告首先观察到的编码失败，不声称一定同时保留原始传输故障。需要同时保留这两类信息时，应设计专门的读取与解码错误模型。

读者可将完整示例保存为 main.go 后执行：

# 在独立示例目录执行，观察每个码点是否只被消费一次。
go run main.go

本文没有执行命令。进一步可把 data 改成一个合法汉字的前两个字节，检查截断被拒绝；再放入单个非法字节，检查错误位置；还应覆盖空输入及消费者返回错误的情况。不要把能打印出替代符当作严格解码通过。

ReadFull 读满四个字节就能解决吗？

不能作为通用方案。UTF-8 编码长度不同，任意固定四字节边界仍可能落在下一个码点中间。ReadFull 适合协议规定的固定长度字段，不是通用字符读取器。

用 Scanner 的 ScanRunes 可以吗？

可以用于接受其替代行为的码点扫描，但 ScanRunes 会把错误编码映射成替代字符，不能据此区分原本合法的 U+FFFD。严格拒绝非法编码时，我会保留原始字节宽度信息，并按选定接口处理错误。

一个 rune 就是屏幕上的一个字符吗？

不一定。组合音标、表情序列等可能由多个码点组成。ReadRune 解决 UTF-8 码点边界，不保证字素簇或屏幕列宽；界面光标移动和视觉截断需要另一个层次的规则。

对我来说，稳妥的设计是把“字节来源、解码状态、错误策略、业务提交”分别写清楚。这样网络和文件的分块方式可以变化，调用方也不会再把半个 UTF-8 编码误当成已经完成的字符。