Go utf16.AppendRune 怎样把字符追加到16位码元切片

如果你已经有一个 []uint16 缓冲区，还想把 Go 的 rune 逐个追加为 UTF-16 码元，直接使用 unicode/utf16.AppendRune 即可。关键点只有一个：必须接住函数返回的切片，因为追加后可能发生扩容；它不会把结果只写进原来的切片变量。

官方文档：https://pkg.go.dev/unicode/utf16#AppendRune

把已有切片和 rune 传给 utf16.AppendRune，再把返回值重新赋给切片变量。有效字符会按 UTF-16 追加；非法 Unicode 码点会追加 U+FFFD 的编码。

先确认 AppendRune 的输入输出边界

该函数的签名是 func AppendRune(a []uint16, r rune) []uint16。第一个参数是已有的 16 位码元切片，第二个参数是一个 Unicode 码点，返回值是追加完成后的切片。它适合“已有前缀 + 新字符”的构建场景，不负责字节序，也不负责把文件内容从一种编码转换成另一种编码。

把返回值重新接回缓冲区

最容易漏掉的是返回值。切片本身包含指针、长度和容量，追加时如果容量不够，函数需要换一块底层数组；即使当前容量足够，把返回值接回也能让代码对两种情况保持一致。

package main

import (
	"fmt"
	"unicode/utf16"
)

func main() {
	// 预置一个前缀，演示 AppendRune 会在末尾继续追加。
	units := []uint16{'A'}
	for _, r := range []rune{'中', '😀'} {
		// 必须接住返回值，扩容后新的切片头信息才不会丢失。
		units = utf16.AppendRune(units, r)
	}
	fmt.Println(len(units))
}

这里的 'A' 和 '中' 都只需要一个 UTF-16 码元；'😀' 位于辅助平面，会占用两个 uint16 码元。因此不能用“追加了几个 rune”推断最终切片长度。

处理非法码点并区分编码与解码

Go 的 rune 是有符号整数类型，但不是每个整数都是可编码的 Unicode 码点。根据官方文档，传入非法值时，AppendRune 会追加替换字符 U+FFFD 的 UTF-16 编码；这比把非法值静默当成普通字符更容易解释结果。

还要区分编码和解码：AppendRune 是把一个 rune 追加成 UTF-16 码元；需要从 []uint16 还原 rune 序列时，才使用同一包中的 utf16.Decode。代理项、字节序和文件转码属于别的边界，不要把它们混进这个追加函数的职责里。

用小型构建函数封装边界

如果调用方本来就持有一组 rune，可以把追加动作收进一个小函数。函数仍然返回切片，调用者既可以从空切片开始，也可以传入已有前缀。

package textunits

import "unicode/utf16"

// AppendRunes 把 runes 追加到已有 UTF-16 缓冲区，并保留前缀。
func AppendRunes(dst []uint16, runes []rune) []uint16 {
	for _, r := range runes {
		// AppendRune 负责非法码点的 U+FFFD 替换，调用方只接收返回切片。
		dst = utf16.AppendRune(dst, r)
	}
	return dst
}

这个封装没有预先猜测容量，也没有手动拆分代理项，适合先把职责写清楚。若后续有明确的性能数据，再针对容量估算做优化；不要把容量优化和 UTF-16 编码规则混为一谈。

常见问题

AppendRune 会修改传入切片吗？

它会把编码追加到传入切片所代表的缓冲区，并返回扩展后的切片。调用方应始终使用返回值，不要依赖旧切片的长度和容量。

一个 rune 一定对应一个 uint16 吗？

不一定。基本平面字符通常占一个码元，辅助平面字符需要两个码元，非法值则按 U+FFFD 处理。

什么时候用 utf16.Decode？

当你手里已经是 UTF-16 的 []uint16，需要恢复为 rune 序列时使用；它与 AppendRune 的方向相反。

总结：使用 utf16.AppendRune 时记住“传入已有 []uint16、接收返回切片、按码点边界理解长度、把非法值视为 U+FFFD”四点，就能覆盖大多数逐字符构建场景。