Go x/text/secure/bidirule New 怎样接入双向规则转换器

如果你要在 Go 中接入 RFC 5893 定义的双向字符规则校验，bidirule.New() 的定位很明确：它返回一个实现 transform.Transformer 的校验器，负责判断输入标签是否符合 Bidi Rule，而不是替你重新排版或渲染文本。

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

最短接入方式是创建一次 Transformer，再交给 transform.String 处理字符串；如果需要处理网络流或分块字节，则直接调用 Transform。无效输入要识别 bidirule.ErrInvalid，一次任务结束后复用同一个实例前要调用 Reset。

New 返回什么：它是校验型 Transformer

bidirule.New() 没有参数，返回 *bidirule.Transformer。这个类型实现了 transform.Transformer，因此可以放进 x/text/transform 提供的转换链中。包文档说明，它会验证输入是否遵守 Bidi Rule；包本身仍处于开发中，API 可能在未来变化。

这里有一个容易混淆的边界：转换器接口的名字叫 Transformer，并不意味着结果一定会“改写成另一种文字”。在这个包里，重点是验证输入规则。验证成功时可以得到处理后的字节，验证失败时通过 ErrInvalid 告知调用方。

先用 transform.String 接入字符串

如果输入已经是 Go 字符串，优先用 transform.String 可以让示例更直接。它会把字符串交给 Transformer，并把转换结果和错误一起返回。下面的代码把无效输入作为业务错误处理，而不是把它当成普通空字符串。

package main

import (
	"errors"
	"fmt"

	"golang.org/x/text/secure/bidirule"
	"golang.org/x/text/transform"
)

func validateLabel(label string) (string, error) {
	// New 返回的是规则校验器，真正的转换由 transform.String 驱动。
	t := bidirule.New()
	result, _, err := transform.String(t, label)
	if err != nil {
		// ErrInvalid 说明输入没有通过 Bidi Rule，调用方应拒绝或单独记录。
		if errors.Is(err, bidirule.ErrInvalid) {
			return "", fmt.Errorf("label rejected by Bidi Rule: %w", err)
		}
		return "", err
	}
	return result, nil
}

func main() {
	// 示例只展示接入方式，实际标签应来自业务输入并经过长度限制。
	value, err := validateLabel("example")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(value)
}

这段代码的关键不是打印结果，而是错误分层：ErrInvalid 代表规则不通过，其他错误代表转换过程本身出现了不同问题。生产代码可以把第一类映射为参数校验失败，避免把它误记成系统故障。

分块输入怎么接：看懂 Transform 的返回值

当输入来自读取器、网络协议或其他分块来源时，可以直接调用 Transform(dst, src, atEOF)。返回的 nDst 表示写入了多少目标字节，nSrc 表示消费了多少源字节。源缓冲区没有全部消费时，要保留未消费部分再拼接下一块，不能简单丢弃。

最后一块输入要把 atEOF 设为 true，这样转换器才知道当前标签已经结束。目标缓冲区太小会得到 transform.ErrShortDst，源数据不完整且还没到 EOF 时可能得到 transform.ErrShortSrc；这两类情况与 bidirule.ErrInvalid 的含义不同。

func transformChunk(t *bidirule.Transformer, src []byte, final bool) ([]byte, error) {
	// 目标缓冲区预留余量，避免把“目标空间不足”误判成输入非法。
	dst := make([]byte, len(src)*2+16)
	nDst, nSrc, err := t.Transform(dst, src, final)
	if err != nil {
		// ErrInvalid 是规则拒绝；短缓冲错误则应由上层补充输入或空间后重试。
		return nil, fmt.Errorf("transform %d source bytes: %w", nSrc, err)
	}
	// nSrc 只是本次消费量；调用方应保存 src[nSrc:] 以便继续处理。
	return append([]byte(nil), dst[:nDst]...), nil
}

如果你要把多个分块拼成完整结果，推荐在循环中维护“未消费源数据”和输出缓冲区，并以 nSrc 推进输入位置。只有确认最后一块已经送入并且没有剩余未消费数据，才算完成一次标签检查。

为什么一次任务结束后要 Reset

文档明确说明 Transformer 有状态，并且 Transform 需要在不同使用之间重置。这里的“一次使用”可以理解为一次完整标签或一次独立业务任务，而不是一次单独的函数调用。

func reuseTransformer(t *bidirule.Transformer, first, second []byte) error {
	// 第一项任务结束后清理内部状态，第二项不能继承第一项的上下文。
	t.Reset()
	buf := make([]byte, len(second)*2+16)
	_, _, err := t.Transform(buf, second, true)
	if err != nil {
		return fmt.Errorf("second label rejected after reset: %w", err)
	}
	_ = first // 第一项应在调用方完成收尾后再进入下一项。
	return nil
}

更常见的写法是每个独立输入创建一个新的 bidirule.New()，这样生命周期最容易理解；只有在对象创建成本、调用频率或封装结构确实需要时，才在任务边界复用并显式调用 Reset。不要在多个 goroutine 间无锁共享同一个 Transformer。

只想要布尔结果时用 ValidString

如果业务只需要判断一整个字符串是否符合规则，不需要把它接到转换链里，可以使用 bidirule.ValidString。它直接返回布尔值，适合表单校验或进入后续处理前的快速门槛。

func acceptLabel(label string) bool {
	// 只需要真假结论时，ValidString 比手动组装 Transformer 更直观。
	return bidirule.ValidString(label)
}

两种方式不要混为一谈：ValidString 只给出是否通过；New 配合 Transform 则能接入分块处理，并让调用方获得具体错误类别和消费进度。

接入时的排查清单

• 依赖是否已经加入模块：golang.org/x/text/secure/bidirule 与 golang.org/x/text/transform 要来自同一套模块版本。
• 是不是把 Transformer 当成格式化器使用：它的核心职责是验证 Bidi Rule，不负责界面方向布局。
• 分块调用是否保存了 src[nSrc:]：未消费字节被丢弃会造成后续判断失真。
• 最后一块是否传入 atEOF=true：没有结束信号时，转换器不能完成完整输入边界判断。
• 是否区分 ErrInvalid、ErrShortSrc 与 ErrShortDst：它们分别对应规则拒绝、源数据不完整和目标空间不足。
• 是否跨任务复用了同一个实例：复用前调用 Reset，并避免并发共享。

常见问题

New 会把阿拉伯文或希伯来文转换成另一种文字吗？

不会。它的主要作用是按照 Bidi Rule 验证标签是否合规，不能替代排版引擎或显示方向处理。

什么时候选 ValidString，什么时候选 New？

只需要真假结果时选 ValidString；需要接入 transform 管道、处理分块输入或区分错误类别时选 New。

Transform 返回 ErrInvalid 后还能继续使用吗？

先结束当前输入并根据业务决定拒绝或记录。若要把同一个实例用于下一项独立任务，应先调用 Reset，不要假设错误后状态自动清空。

为什么不用一次性把所有输入拼成字符串？

小输入可以这样做；对流式数据或已分块的读取过程，直接处理分块能减少额外拼接。此时必须认真处理 nSrc、atEOF 和目标缓冲区大小。

总结：bidirule.New() 的正确接入路径是“创建校验型 Transformer—选择字符串或分块调用—识别 ErrInvalid—在独立任务之间 Reset”。只做布尔判断时直接用 ValidString，不要把两个 API 的职责混在一起。