Go unicode/utf8.AppendRune 怎样把 Rune 追加到字节缓冲区

如果程序已经有一个 []byte 缓冲区，只想再追加一个 Unicode 字符，不必手动计算 UTF-8 的 1 到 4 个字节。unicode/utf8.AppendRune 会把 Rune 编码后追加到切片末尾，并返回扩展后的切片；关键是一定要接住返回值。

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

最直接的写法是 buf = utf8.AppendRune(buf, r)。它适合“已有字节缓冲区 + 追加一个 Rune”的场景；如果 Rune 非法，函数会追加 utf8.RuneError 的 UTF-8 编码，而不是返回一个额外的错误值。

先看清 AppendRune 的函数契约

函数签名是 func AppendRune(p []byte, r rune) []byte。第一个参数是追加前的字节切片，第二个参数是要编码的 Rune，返回值可能因为容量不足而指向新的底层数组。因此，下面的赋值不是形式要求，而是完整调用的一部分。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    // 返回值可能改变切片长度，必须写回 buf。
    buf := utf8.AppendRune([]byte("Go: "), '界')
    fmt.Printf("%s，字节数=%d，合法UTF-8=%v\n", string(buf), len(buf), utf8.Valid(buf))
}

这里的 '界' 是一个 Rune，追加后会占用 3 个 UTF-8 字节；len(buf) 统计的是字节数，不是字符数。需要按字符数量处理文本时，应另外使用 utf8.RuneCount 或 utf8.RuneCountInString。

把 Rune 追加到已有字节缓冲区

在日志行、协议字段或增量文本构造中，缓冲区通常已经有前缀。可以连续调用 AppendRune，每次都把返回值重新赋给同一个变量：

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    buf := make([]byte, 0, 16)
    // 先追加 ASCII，再追加多字节 Rune，顺序由调用顺序决定。
    buf = append(buf, "状态: "...)
    buf = utf8.AppendRune(buf, '中')
    buf = utf8.AppendRune(buf, '✓')

    // 追加后再转成字符串，避免把每个 Rune 先单独转成字符串。
    fmt.Println(string(buf))
}

预留容量可以减少扩容，但不能改变“接住返回值”的要求。容量足够时可能复用原数组，容量不足时也可能分配新数组；调用方不应该依赖底层数组是否改变，只依赖返回切片中的内容和长度。

非法 Rune 会得到什么结果

合法 Unicode 标量值不能落在代理项范围，也不能超过 utf8.MaxRune。当传入负数或超过上限的 Rune 时，AppendRune 会追加替代字符 utf8.RuneError 的编码。这个行为适合把输入统一转换成可传输的 UTF-8，但如果业务必须拒绝坏数据，就要在追加前显式检查。

package main

import (
    "fmt"
    "unicode/utf8"
)

func main() {
    candidates := []rune{'A', -1, utf8.MaxRune + 1}
    for _, r := range candidates {
        // 先校验可以区分“拒绝输入”和“让库替换为 RuneError”。
        if !utf8.ValidRune(r) {
            fmt.Printf("拒绝非法 Rune: %d\n", r)
            continue
        }
        buf := utf8.AppendRune(nil, r)
        fmt.Printf("接受 %U，占用 %d 字节\n", r, len(buf))
    }
}

如果不做校验而直接追加，结果仍然是合法 UTF-8 字节序列，但原始非法值已经被替换，后续程序无法从字节中恢复它。是否接受替换，应由协议或业务约定决定。

AppendRune 与其他写入方式怎么选

不要把 len(string(r)) 当成所有场景的追加方案：它会先构造一个临时字符串。对于少量、非性能敏感的代码，这种写法也能工作；当目标就是增量构造字节缓冲区时，AppendRune 的意图更清晰。

最后记住这三个边界

1. AppendRune 返回的是扩展后的切片，调用形式应写成 buf = utf8.AppendRune(buf, r)。
2. UTF-8 的字节长度与 Rune 数量不是一回事，中文和符号通常占用多个字节。
3. 非法 Rune 默认变成 utf8.RuneError；需要严格输入时，先用 utf8.ValidRune 拒绝。

相关问题

AppendRune 会不会修改原来的字节切片？

它会复用容量足够的底层数组，也可能在容量不足时分配新数组。调用方只应使用返回切片，不要依赖底层数组是否复用。

为什么追加中文后 len 变大很多？

len([]byte("中")) 统计 UTF-8 字节数，而不是人类看到的字符数；需要字符数量时使用 Rune 统计函数。

可以用 AppendRune 追加换行吗？

可以，传入 '\n' 即可；如果要追加固定字符串，直接使用 append 往往更直观。