Go x/text/transform Append 怎样向已有缓冲区追加转换内容

Go 的 transform.Append(t, dst, src) 会保留 dst 已有内容，将 src 的转换结果追加到它后面，并返回新的结果切片、已消费的源字节数 n 和错误。调用方必须接住返回的 result；它可能与原 dst 使用不同的底层数组。

官方文档入口：https://pkg.go.dev/golang.org/x/text/transform。这个接口适合已有记录前缀、还要拼入转换文本的场景。它可以减少应用显式创建临时结果再 append 的环节，但不能仅凭采用该接口就承诺更快或没有分配。

把转换结果直接追加到已有前缀

例如正在组装一条文本记录，缓冲区已有 label=，后面需要写入经过 width.Fold 处理的名称。无需先让应用取得一份独立的转换结果，再拼到前缀后面，可以直接交给 Append。

package recordtext

import (
    "fmt"

    "golang.org/x/text/transform"
    "golang.org/x/text/width"
)

// BuildLabel 构造一条独立记录；输入与目标缓冲区不重叠。
func BuildLabel(text string) ([]byte, error) {
    // 这是初始容量选择，不是输出长度或零分配保证。
    dst := make([]byte, 0, 256)
    dst = append(dst, "label="...)
    src := []byte(text)
    result, consumed, err := transform.Append(width.Fold, dst, src)
    if err != nil {
        // 失败时不将部分记录作为完整结果提交。
        return nil, fmt.Errorf("转换名称失败，已消费 %d 字节: %w", consumed, err)
    }
    return result, nil // 必须返回 Append 给出的切片。
}

以全角名称 Ａ１２ 为输入，按该规则推导的预期文本为 label=A12。前缀不参与转换，Append 转换的是 src。本文没有执行代码，也没有给出分配次数或耗时数据。

图中的 dst、已有前缀、src、Transformer、result、追加内容六个节点解释组成关系：dst 包含已有前缀，result 包含该前缀和追加内容；追加内容来自 Transformer 对 src 的处理。它是数据结构说明，不是内存分配轨迹。

三个返回值分别表示什么

Append 文档说明它转换 src[:n]，当 err==nil 时 n 等于 len(src)，并且调用时会 Reset 转换器。成功时需要计算追加字节数，可以用 len(result)-oldLen，其中 oldLen 应在调用前保存；这与 n 不是同一个量。

如果直接写 result, n, err := ...，后续继续写入时就要使用 result。如果习惯复用变量，可写 dst, n, err = ... 并提前声明 n、err。结果切片头不会自动替换其他变量持有的旧切片头。

给缓冲区容量留余量但不承诺零分配

预留容量可以为常见记录减少扩容机会，但转换内容的字节长度可能变大或变小。256 只是示例的容量预算；超出时仍可能分配，内部转换器也可能有自己的成本。不要把 make([]byte, 256) 当成等价写法：那会让已有长度变为 256，追加从这个长度之后开始，而不是从空缓冲区开始。

图中的长度、容量、底层数组、旧切片头、结果切片头、调用方六个节点区分切片视图与存储。旧切片头和结果切片头都描述切片，可能关联同一底层数组，也可能关联不同数组；调用方后续应保存结果切片头。图不承诺某次调用一定复用或一定扩容。

示例为 src 单独构造字节输入，避免让源内容与追加目标共享重叠区域。需要特殊的重叠内存用法时，不应从普通 append 的经验推断任意 Transformer 都支持原地转换。

多条独立记录与连续字节流要分开

Append 每次调用会 Reset，因此适合把每次 src 视作一段独立输入。它不是通过多次调用就自动保留跨块状态的增量接口。若一个 UTF-8 字符、字符集解码单元或规范化上下文可能跨读取块，不能对每块分别 Append 后宣称等同于处理整个流。

持续输入应选择 transform.Reader 或 Writer 等保持当前转换状态的接口，或正确实现底层 Transform 的状态和末尾处理。多条独立记录则可以分别转换，并在记录成功后提交；不要为了复用同一个缓冲区而混淆记录边界和读取块边界。

错误和复用时保留哪些信息

转换失败时，result 与 n 可以帮助定位已处理的源范围，但部分结果不能默认当作完整业务记录。本文的函数选择丢弃失败记录；若应用需要保留排查材料，应另存源输入及错误，不要直接写入正常结果队列。

只把 result 截短能否撤销一切修改？截短只改变切片视图，不会清除底层数组，也不能恢复其他共享视图。需要隔离的结果应采用独立缓冲区和明确提交策略。

buf[:0] 能复用吗？可以用于开始新记录，但此前返回给消费者的切片可能仍引用同一数组。消费者还未读完时不要覆盖它；需要长期保存时复制结果或转移独占所有权。

Append 比 Bytes 一定省内存吗？它更贴合已有目标切片的追加用途，但具体收益取决于容量、转换器和数据规模。只有测量过实际负载才能判断，不应把接口选择写成固定性能结论。

已有前缀且处理独立文本时，Append 能让结果组装更直接。接住返回切片、把 n 当源字节数、明确容量与所有权，才是正确复用缓冲区的基础。