Go x/text/transform Span 怎样跳过无需变换的前缀

Span 是 transform.SpanningTransformer 的方法。调用它可以取得一个已确认转换前后字节相同的前缀长度 n；保留 src[:n]，再根据返回状态处理剩余部分，就能避免对这段前缀重复生成转换输出。n 是源字节数，且接口不保证它一定是最长的原样前缀。

官方地址：https://pkg.go.dev/golang.org/x/text/transform

把无需改写的文本与待转换部分分开

考虑一个导入文本的功能：大多数内容已经符合目标宽度规则，只有后部偶尔出现需要折叠的字符。用户关心的是导入后的文字正确、原文能按需要保留。底层若把无需改写的前缀识别出来，输出组装就可以直接采用原字节，而把转换工作集中在后面的部分。

我会把它放在文本处理层，界面只接收最终结果和失败状态。Span 的细节不应变成用户必须选择的开关。也不能为了启用这项机制，就额外改动字号、大小写或原文展示规则：是否需要变换，完全取决于当前转换器。

用 Span 返回值保留原样前缀

下面用支持 Span 的 width.Fold 演示完整输入的处理。它进行规范宽度折叠；本例的重点是如何把前缀与后缀接起来，不是介绍一种新的通用文本标准化规则。

package prefixfold

import (
    "fmt"

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

// FoldWithPrefix 对一个完整输入做宽度折叠，返回独立的输出字节切片。
func FoldWithPrefix(src []byte) ([]byte, error) {
    rule := width.Fold
    rule.Reset()
    // true 表示本次输入已经到达结尾，不再等待下一块数据。
    n, err := rule.Span(src, true)
    result := append([]byte(nil), src[:n]...)
    if err == nil {
        return result, nil
    }
    if err != transform.ErrEndOfSpan {
        return nil, fmt.Errorf("识别原样前缀: %w", err)
    }
    remaining := src[n:]
    var buffer [256]byte
    for {
        // 沿用 Span 后的状态，不在这里 Reset，也不用会重置状态的辅助函数。
        written, consumed, nextErr := rule.Transform(buffer[:], remaining, true)
        result = append(result, buffer[:written]...)
        remaining = remaining[consumed:]
        if nextErr == nil {
            return result, nil
        }
        if nextErr != transform.ErrShortDst {
            return nil, fmt.Errorf("转换后缀: %w", nextErr)
        }
        // 本例用固定宽度转换器；无进展时退出，避免错误重试形成死循环。
        if written == 0 && consumed == 0 {
            return nil, fmt.Errorf("转换未取得进展: %w", nextErr)
        }
    }
}

项目需依赖 golang.org/x/text 模块。代码先把确定相同的前缀复制到结果中，然后沿用同一个转换器处理剩余输入。它返回独立切片，意味着调用方以后修改 src 不会改变结果；这也意味着“跳过前缀转换”并不等于“完全不复制前缀”。

例如输入中前面是普通 ASCII，后面包含全角拉丁字符时，原样部分可直接保留，后缀由宽度转换器决定如何输出。示例未执行，没有附加某个输入的实测 n 值，也不声称它比现有辅助函数更快。

按错误状态判断是否需要继续

容易漏掉的情况是 n == len(src) 但仍然返回 ErrEndOfSpan：转换器可能还需要输出附加字节。因此代码没有单凭 n 到达结尾就直接返回，而是仍让 Transform 处理可能为空的 remaining。

本例把 atEOF 固定为 true，只接收完整输入；它将 Span 的其他错误直接返回，失败时不向调用方交付部分结果。网络分块处理不能照搬这点：在尚未结束时传入 false，并保存 src[n:] 等待更多数据，才有机会正确处理跨块字符。

让后续 Transform 沿用当前状态

Span 可能修改转换器状态。它不是没有副作用的“预览检查”。已经承认前缀被消费后，后面的 Transform 应沿用该状态；若中间重新 Reset，带状态转换器就会失去先前上下文。

同样，transform.Bytes、transform.String 等便捷入口会调用 Reset。不能在任意转换器上机械地写成“Span 后把剩余片段交给这些函数”，并假设与持续转换完全相同。示例直接调用 Transform，先记下输出和消费量，再判断错误。

遇到 ErrShortDst 时，代码追加本次已产生的字节并前移输入，再使用暂存区继续处理。256 字节暂存区服务于本例的宽度转换，不应被宣传为适用于所有自定义转换器的通用缓冲区大小；通用封装还需按自身约定处理更大的原子输出需求。

这项优化适合放在哪一层

我倾向于在确实需要自己组装输出、复用已有存储或维护流式状态的地方使用 Span。若只是将一个短字符串完整转换，直接使用包提供的转换方法通常更清楚。多加一次 Span 调用，不自动等于更好的性能。

若要判断是否值得采用，应比较相同数据和相同输出所有权约定下的耗时、分配以及输入分布。原样前缀长度、实际发生转换的位置和输出复制策略都会影响收益；没有数据就不下“零分配”或“显著提速”的结论。

常见问题：所有 Transformer 都有 Span 吗？只有实现 SpanningTransformer 的对象才提供该能力。n 是字符数吗？不是，是源字节数。Span 会写出目标内容吗？它识别并消费相同前缀，不向目标缓冲区复制。n 到结尾就一定结束吗？还要看错误状态，不能忽略可能需要补出的输出。

参考：SpanningTransformer 状态和返回约定；width.Transformer 的 Span 支持。