Go x/text/runes Map 怎样替换指定 Unicode 字符

如果输入文本里混着 ASCII 连字符、非断行连字符和全角连字符，直接按字节替换很容易漏掉 Unicode 变体。Go 的 golang.org/x/text/runes 提供的 Map 更适合这个任务：映射函数接收一个 rune，识别目标码点后返回统一字符，其余字符原样返回。

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

Map 的核心是 rune 映射，不是字节替换

runes.Map 的签名是 Map(mapping func(rune) rune) Transformer。它把输入中的 rune 交给回调函数，再把回调返回的 rune 放回输出。下面的例子把几种常见的 Unicode 连字符统一为 ASCII 半角连字符，业务字符串中的普通字母、空格和数字不受影响。

package main

import (
    "fmt"
    "log"
    "unicode"

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

func main() {
    normalizeHyphen := runes.Map(func(r rune) rune {
        // 只替换 Unicode 的 Hyphen 集合，其他 rune 必须原样返回。
        if unicode.Is(unicode.Hyphen, r) {
            return '-'
        }
        return r
    })

    input := "订单‐编号﹣A－17"
    output, _, err := transform.String(normalizeHyphen, input)
    if err != nil {
        // 转换器出错时停止继续使用不完整的文本结果。
        log.Fatal(err)
    }
    fmt.Println(output)
}

这个回调的关键不是“把字符串搜索一遍”，而是按 Unicode 码点判断。unicode.Is 让多个连字符变体共享规则；如果只需要替换一个明确字符，也可以直接写 if r == '‐'。示例的输出目标是把目标连字符归一到 -，不是改变其他字符的编码。

用 transform.String 连接 Transformer 与字符串

Map 返回的是 transform.Transformer，本身描述“怎样转换”，不会自动修改原字符串。面向字符串时，调用 transform.String，并检查返回的 error。需要反复使用同一转换器时，每次独立转换都应把返回结果和错误一起处理，避免把上一次状态误当成当前结果。

如果输入来自文件或网络，先确认上游是否已经是合法 UTF-8。Map 的文档边界是：非法输入字节会在传给映射函数前转换为 utf8.RuneError。这意味着它不是一个原始字节修复器；需要明确替换非法序列时，应把 ReplaceIllFormed 作为独立策略放进转换链。

Map、Remove 与非法 UTF-8 的边界

选择 API 时可以先问一个问题：目标字符是否还要保留一个新的字符？要“换成另一个码点”选 Map；要“完全删掉”选 Remove；要处理不完整的 UTF-8 字节序列，则使用明确的非法输入策略。三者可以组合，但不要把删除需求写成一个难读的映射特例。

package main

import (
    "fmt"
    "unicode"

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

func main() {
    // Remove 表达“删除重音标记”，与 Map 的替换语义分开。
    removeMarks := runes.Remove(runes.In(unicode.Mn))
    text, _, err := transform.String(removeMarks, "café")
    if err != nil {
        // 生产代码应把转换错误交给调用方，而不是静默吞掉。
        panic(err)
    }
    fmt.Println(text)
}

不要为了追求“一条函数解决所有问题”而隐藏边界：Map 的回调返回一个 rune，Remove 的意图是让匹配字符不再进入输出，非法 UTF-8 则需要单独记录输入质量和替换策略。对外部字节流，建议在入口处明确使用 transform.Bytes 或解码器，并在日志中保留错误处理结果。

相关问题

Map 能直接替换字节序列吗？

不能把它当作字节级替换器。Map 的回调参数是 rune，输入中的非法字节还会先按文档规则转成 utf8.RuneError 再参与映射。

只删除某个 Unicode 字符应该怎么写？

用 runes.Remove 配合 runes.Predicate 或已有的 Unicode 集合表达删除意图；只有需要把它换成另一个字符时才使用 Map。

同一个 Transformer 可以处理多次字符串吗？

可以通过 transform.String 处理字符串；该入口会重置转换器状态并返回本次结果。调用方仍应检查错误，不要复用旧的输出变量。