Go unicode/utf8.FullRune 怎样判断字节序列是否足够解码

在 Go 里处理网络、文件或消息分块时，最容易误判的一件事是：当前收到的字节不一定已经够解码出一个完整的 UTF-8 字符。直接对半个中文字符调用解码，会把“数据还没到齐”和“数据本身非法”混在一起。此时可以先调用 utf8.FullRune(buf)，判断字节切片开头是否已经包含一个完整的 UTF-8 编码；返回 true 后，再用 utf8.DecodeRune 取出首个字符。

官方地址：https://pkg.go.dev/unicode/utf8#FullRune

FullRune 只回答“首个字符的字节够不够”，不回答“整段缓冲区是否全部合法”。完整性由 FullRune 判断，合法性由 Valid 判断，实际消费字符则交给 DecodeRune。

先用一个三字节字符看懂边界

ASCII 字符通常占一个字节，分块时不容易暴露问题；中文字符、表情或其他非 ASCII 字符可能占用多个字节。以“界”为例，它的 UTF-8 字节序列是三个字节。只收到前两个字节时，缓冲区开头仍然不是一个完整字符，应该把它留在缓冲区里，等待下一块数据补齐。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    // “界”在 UTF-8 中占三个字节，这里故意按两个边界观察。
    full := []byte("界")
    fmt.Println(utf8.FullRune(full))     // true
    fmt.Println(utf8.FullRune(full[:2])) // false

    // ASCII 字符只占一个字节，收到一个字节就已经完整。
    fmt.Println(utf8.FullRune([]byte("A"))) // true
}

空切片也会返回 false，因为它连首个字符的起始字节都没有。需要注意的是，FullRune 检查的是“开头的一个编码是否已经有足够字节”，不是要求缓冲区长度刚好等于一个字符。

把 FullRune 接到一个最小消费函数

分块读取的核心动作可以拆成两步：先判断首个字符是否收齐，再用 DecodeRune 取得字符和它占用的字节宽度。只有在第二步成功获得宽度后，才能从缓冲区移除已经消费的前缀。

package main

import "unicode/utf8"

// consumeFirstRune 只消费缓冲区开头的一个 UTF-8 字符。
// 返回 false 表示数据暂时不够，调用方应保留原切片等待下一块。
func consumeFirstRune(buf []byte) (rune, []byte, bool) {
    if !utf8.FullRune(buf) {
        // 多字节字符的前缀尚未收齐，不能提前丢弃。
        return 0, buf, false
    }

    r, size := utf8.DecodeRune(buf)
    // size 是首个字符占用的字节数，按它保留后续字节。
    return r, buf[size:], true
}

这个函数的关键不是把所有字节一次转成字符串，而是让“未完成的尾部”继续留在同一块缓冲区。下一次收到数据时，调用方把新字节追加到尾部，再重新判断首个字符即可。

分块读取时为什么要保留尾部残片

假设当前缓冲区包含一个 ASCII 字符和一个中文字符的前两个字节：A 加上“界”的不完整前缀。此时 FullRune(buf) 仍然会返回 true，因为缓冲区开头的 A 已经完整。消费掉它之后，剩余的两个字节才会成为新的开头，并在下一轮返回 false。

package main

import "unicode/utf8"

func consumeAvailable(buf []byte) []byte {
    for len(buf) > 0 && utf8.FullRune(buf) {
        // 这里可以把 r 交给上层；示例只展示字节边界的移动。
        _, size := utf8.DecodeRune(buf)
        buf = buf[size:]
    }
    // 循环停止时，buf 可能正好是一个不完整的多字节前缀。
    return buf
}

因此，FullRune 不意味着“整个缓冲区已经可以清空”。它只保证当前开头可以前进一个字符。循环结束后保留下来的切片通常就是要等待下一块输入的残片。

FullRune、Valid 和 DecodeRune 各自回答什么

这三个 API 都和 UTF-8 有关，但判断目标不同。把它们放在同一个分块管道里时，可以按下面的职责理解：

• utf8.FullRune：首个 UTF-8 编码是否已经有足够字节。它适合解决“现在要不要继续等数据”。
• utf8.Valid：整段字节是否完全由合法 UTF-8 符文组成。它适合解决“这段输入是否符合编码约束”。
• utf8.DecodeRune：解码首个编码，并返回符文与宽度。它适合解决“已经决定消费时，应该前进多少字节”。

官方文档特别说明，非法编码会被 FullRune 当作一个完整的错误符文，因为解码时会以宽度 1 的 RuneError 处理。因此，如果业务要求拒绝非法字节，不能只看 FullRune，还要在合适的边界调用 Valid 或根据 DecodeRune 的结果制定错误策略。

不完整前缀与非法序列不要用同一条分支处理

当 FullRune 返回 false 时，常见原因是多字节字符只收到了一部分，正确动作通常是暂存并继续读取。若收到的是非法起始字节，FullRune 可能返回 true，此时 DecodeRune 会以错误符文和宽度 1 表示它。两种情况的后续策略不同：

package main

import "unicode/utf8"

func readOne(buf []byte) (rune, int, bool) {
    if !utf8.FullRune(buf) {
        // 还缺字节：保留 buf，不把它当成坏数据丢弃。
        return 0, 0, false
    }

    r, size := utf8.DecodeRune(buf)
    if r == utf8.RuneError && size == 1 {
        // 这里是一个宽度为 1 的非法编码，可按协议决定拒绝或替换。
        return r, size, true
    }
    return r, size, true
}

如果协议要求整段输入必须是合法 UTF-8，可以在消息边界处调用 utf8.Valid(buf)；如果协议允许流式处理，则可以逐个消费并记录错误位置。不要因为分块尚未收齐就立刻把数据标记为非法，也不要因为 FullRune 返回 true 就默认整段都合法。

上线前检查这四个边界

1. 空输入：空切片不是完整字符，不能直接用 DecodeRune 的结果代替等待判断。
2. 首字符之外的字节：FullRune 只看开头，首字符完整并不代表后面的多字节字符也完整。
3. 切片移动：消费后必须按 DecodeRune 返回的 size 移动，不能固定按一个字节截断。
4. 非法数据策略：是否替换、记录或拒绝要由协议决定，FullRune 不负责业务错误处理。

如果输入来自固定大小的网络读取缓冲区，建议把“接收新字节”和“消费完整字符”分成两个动作。这样即使一个字符跨越多次读取，也只会停留在待处理缓冲区，不会被错误地拆成两个字符。

常见问题

FullRune 返回 true 就能调用 DecodeRune 吗？

可以把它作为“首个编码已有足够字节”的前置判断，但不代表这个编码一定合法。DecodeRune 仍可能返回 RuneError 和宽度 1，调用方要按业务需要识别这种错误。

FullRune 会判断整个 []byte 吗？

不会。它只检查切片开头的一个 UTF-8 编码。若要判断整段输入是否全部合法，使用 utf8.Valid；若要连续处理整段数据，则循环调用 DecodeRune 并保留循环结束时的不完整尾部。

为什么不直接把字节转成 string？

直接转换会把“等待下一块数据”的边界交给更高层，流式协议往往仍然需要自己维护残片和错误策略。先用 FullRune 明确首字符是否收齐，可以让读取、解码和异常处理的职责更清楚。

结语

使用 utf8.FullRune 的核心是先判断首个字符是否完整，再决定是否消费；不要把它当成整段 UTF-8 校验器。分块输入中，未收齐的前缀应保留，收齐后用 DecodeRune 返回的宽度前进，真正需要拒绝非法编码时再交给 Valid 或明确的错误分支处理。