Go x/text/runes 转换器链为什么仍需处理输出空间不足

先说结论：runes 只提供字符级转换器，transform.Chain 只负责把多个转换器按顺序接起来，它不会替调用方把有限的 dst 缓冲区自动扩容。只要直接调用低层的 Transform，就必须先处理本轮产生的 nDst、消费的 nSrc，再判断是否为 transform.ErrShortDst。

如果是一次性转换完整字符串，优先用 transform.String 或 transform.Bytes；如果是流式写入，用 transform.NewWriter 并在结束时调用 Close。只有需要精细控制内存、分块或下游协议时，才手动循环 Transform。

官方文档：https://pkg.go.dev/golang.org/x/text/runes

先区分转换器链与输出空间

runes 包处理的是 UTF-8 文本中的 rune。比如 runes.Remove 可以删除满足集合条件的字符，runes.Map 可以映射字符，runes.If 可以按集合把输入分发给不同的转换器。这些函数返回的是实现了 transform.Transformer 的转换器。

transform.Chain 的职责是按顺序应用转换器。例如下面的链先做兼容分解，再删除组合附加符，最后重新组合：

package main

import (
    "fmt"
    "unicode"

    "golang.org/x/text/runes"
    "golang.org/x/text/transform"
    "golang.org/x/text/unicode/norm"
)

func main() {
    // 先分解字符，再删除组合附加符，最后重新组合成 NFC 形式。
    chain := transform.Chain(
        norm.NFD,
        runes.Remove(runes.In(unicode.Mn)),
        norm.NFC,
    )

    // 高层入口负责准备结果空间，适合一次性转换完整字符串。
    result, _, err := transform.String(chain, "résumé")
    if err != nil {
        panic(err)
    }
    fmt.Println(result) // resume
}

这里的关键不是链里有几个转换器，而是每个转换阶段都可能改变字节数量。分解可能让一个字符变成多个码点，删除可能减少字节，重新组合又可能把多个码点合成一个字符。因此，调用者不能用“输出一定不大于输入”或“给一个和输入同样大的数组就够了”作为假设。

一次性转换优先使用高层入口

transform.String 和 transform.Bytes 会创建结果并调用转换器的 Reset。它们仍然使用底层转换契约，但把结果空间和多轮调用的细节封装起来，适合配置清晰、输入完整且结果需要一次拿到的场景。

返回值里的 n 表示已经消费到输入的哪个位置；当 err == nil 时，官方约定是整个输入都已处理。不要只接收第一个字符串结果而忽略错误，也不要在错误发生时把原始输入直接当成转换成功。

func normalizeText(src string) (string, error) {
    // 这个链把变音符号拆开并移除，适合生成搜索键或比较键。
    chain := transform.Chain(
        norm.NFD,
        runes.Remove(runes.In(unicode.Mn)),
        norm.NFC,
    )

    // String 会管理内部输出空间，并在返回前重置转换器状态。
    result, _, err := transform.String(chain, src)
    if err != nil {
        return "", fmt.Errorf("normalize text: %w", err)
    }
    return result, nil
}

对于本身可能包含非法 UTF-8 的输入，要先决定业务策略。runes.Map 和 runes.Remove 的文档说明，非法字节会在交给映射函数或集合判断前按 utf8.RuneError 处理；如果希望显式把非法序列替换成替代字符，可以把 runes.ReplaceIllFormed() 放进链中。这个选择应写在接口约定里，不能靠缓冲区大小“碰巧”决定。

手动 Transform 时为什么必须循环

直接调用 Transform(dst, src, atEOF) 时，返回的两个数量都必须保留：

• nDst：本轮已经写入 dst[:nDst] 的输出，必须先追加到最终结果。
• nSrc：本轮已经消费的输入，下一轮只能继续处理 src[nSrc:]。
• transform.ErrShortDst：目标空间不足，可能已经产生部分输出，也可能已经消费部分输入；它不代表本轮输出无效。
• transform.ErrShortSrc：源数据不足以完成当前转换；在真正的流式输入中应保留未消费字节，等下一块数据到达。

下面的例子故意使用很小的目标缓冲区，展示正确的消费顺序。循环不能因为看到 ErrShortDst 就重放整个 src，否则已经消费的前缀可能被重复转换。

func convertWithSmallDst(t transform.Transformer, src []byte) ([]byte, error) {
    // 复用转换器前清掉上一次调用留下的内部状态。
    t.Reset()

    var output bytes.Buffer
    rest := src
    dst := make([]byte, 8) // 故意很小，用来演示 ErrShortDst 的处理。

    for {
        nDst, nSrc, err := t.Transform(dst, rest, true)

        // 即使同时返回错误，也必须先保存本轮已经生成的字节。
        if nDst > 0 {
            _, _ = output.Write(dst[:nDst])
        }
        // nSrc 之前的输入已经被转换器消费，下一轮不能重复传入。
        rest = rest[nSrc:]

        switch err {
        case nil:
            if len(rest) != 0 {
                return nil, fmt.Errorf("transform stopped with %d bytes left", len(rest))
            }
            return output.Bytes(), nil
        case transform.ErrShortDst:
            // 可能还有待写出的内部结果；保留 rest，继续调用即可。
            continue
        case transform.ErrShortSrc:
            return nil, fmt.Errorf("incomplete UTF-8 input: %w", err)
        default:
            return nil, fmt.Errorf("transform failed: %w", err)
        }
    }
}

这个循环还有一个容易忽略的细节：即使 ErrShortDst 这一轮已经把 rest 全部消费完，也不能立即返回。转换器内部可能还有没有放入 dst 的结果，下一轮传入空的 src 仍然需要把它排空，直到返回 nil。

流式写入时要处理 Writer 的收尾

如果数据来自文件、HTTP 响应或消息流，不建议先把所有内容拼成一个大字符串。transform.NewWriter 会把写入的数据交给转换器，并把转换结果继续写给下游 io.Writer。转换器可能需要等待更多字节才能完成一个字符，也可能在最后一次写入后仍保留内部状态，所以写完后必须调用 Close。

func writeNormalized(dst io.Writer, data []byte) error {
    // 流式链与一次性 String 使用相同的字符处理规则。
    chain := transform.Chain(
        norm.NFD,
        runes.Remove(runes.In(unicode.Mn)),
        norm.NFC,
    )
    writer := transform.NewWriter(dst, chain)

    // Write 失败时不要继续 Close，先把下游错误返回给调用方。
    if _, err := writer.Write(data); err != nil {
        return fmt.Errorf("write transformed data: %w", err)
    }
    // Close 会以 atEOF=true 刷新转换器内部残留的尾部数据。
    if err := writer.Close(); err != nil {
        return fmt.Errorf("close transformed writer: %w", err)
    }
    return nil
}

把 Close 当成可选步骤是流式场景最常见的截断原因。尤其是输入被分成多次 Write 时，某一块的末尾可能只是一个多字节序列的前缀；Writer 会先缓存它，下一次写入或最终 Close 才能完成转换。

遇到输出空间不足时的排查顺序

可以按下面的顺序快速判断，不需要先怀疑 runes 删除字符的规则：

最后记住：transform.Chain 解决的是“多个转换器按什么顺序组合”，Transform 解决的是“这一轮向哪里写、从哪里读、读写了多少”。这两个层次没有互相替代关系。把链路和缓冲区契约分开理解，ErrShortDst 就只是一次正常的分块信号，而不是转换失败。

常见问题

为什么给 dst 分配和 src 一样长还不够？

字符转换可能改变 UTF-8 字节数，尤其是分解、映射和重新组合同时出现时。固定容量不能由输入长度直接推断，低层调用应循环处理 ErrShortDst。

ErrShortDst 返回时 nSrc 一定是零吗？

不一定。转换器可能已经消费了一部分输入并生成了一部分输出，因此必须先记录 nDst 与 nSrc，不能用错误值覆盖这两个结果。

使用 transform.NewWriter 后还需要手动调用 Transform 吗？

通常不需要。Writer 已经封装了分块转换；调用方负责检查每次 Write 的错误，并在结束时调用 Close 完成刷新。