Go regexp.Regexp ExpandString 怎样把命名捕获组展开到模板

Go 的 regexp.Regexp.ExpandString 适合处理“正则负责找到结构，模板负责重新排列字段”的场景。关键写法是：先用 FindAllStringSubmatchIndex 得到匹配在源字符串中的字节索引，再把同一个 dst 传给 ExpandString，让命名捕获组填入模板。这样不需要手动按下标切字符串，也不会因为字段顺序变化而重写拼接逻辑。

官方文档：https://pkg.go.dev/regexp#Regexp.ExpandString

ExpandString 解决的是什么问题

ExpandString 的签名是 ExpandString(dst []byte, template string, src string, match []int) []byte。它与 Expand 的职责相同，但模板和源数据使用字符串，返回值仍然是字节切片，方便调用方控制追加缓冲区。match 应来自同一个正则对象的 FindStringSubmatchIndex 或 FindAllStringSubmatchIndex。

如果只是把一个完整匹配替换成固定文本，ReplaceAllString 更直接；如果需要把命名捕获组放进新的字段顺序、多个匹配连续写入结果，ExpandString 更合适。

先让命名捕获组产生可用索引

命名组使用 RE2 语法中的 (?P...)。下面把配置文本中的键和值转成统一的等号格式。代码块中的索引是字节位置，不能把它当成字符数量再自行换算。

package main

import (
    "fmt"
    "regexp"
)

func main() {
    // 命名捕获组让模板可以按业务含义引用字段。
    re := regexp.MustCompile(`(?m)^(?P[a-z][a-z0-9_]*)\s*:\s*(?P[^#\r\n]+?)\s*$`)
    source := "host: api.internal\nport: 8080\n"

    // -1 表示找出全部非重叠匹配，并保留每个子组的起止字节索引。
    matches := re.FindAllStringSubmatchIndex(source, -1)
    for _, match := range matches {
        // 每个 match 都能交给 ExpandString 读取 $key 和 $value。
        fmt.Println(match)
    }
}

索引数组中前两个数字是完整匹配的起止位置，后面每两个数字对应一个捕获组。某个可选组没有匹配时，对应位置会是负数；不要直接用它切片。

用 ExpandString 复用 dst 完成字段重排

真正的展开过程只需要一个模板和一个结果缓冲区。模板中的 $key、${value} 会被替换为对应的捕获内容；每次调用都把结果追加到 dst 尾部。

package main

import (
    "fmt"
    "regexp"
)

func main() {
    // 只捕获需要输出的键和值，避免在模板里依赖数字下标。
    re := regexp.MustCompile(`(?m)^(?P[a-z][a-z0-9_]*)\s*:\s*(?P[^#\r\n]+?)\s*$`)
    source := "host: api.internal\nport: 8080\n"
    template := "$key=$value\n"
    output := make([]byte, 0, len(source))

    // 同一块 output 持续接收每个匹配的展开结果。
    for _, match := range re.FindAllStringSubmatchIndex(source, -1) {
        output = re.ExpandString(output, template, source, match)
    }

    // ExpandString 不负责打印或转成 string，使用方决定最终消费方式。
    fmt.Print(string(output))
}

host=api.internal
port=8080

这里的性能重点不是“调用一次 API 就一定更快”，而是让调用方能复用 dst，并把最终输出的生命周期掌握在自己手里。若结果大小大致可估算，可以预留容量；如果输出可能很大，仍要根据实际数据控制上限。

模板变量的边界要先写清楚

模板变量可以写成 $name 或 ${name}。变量名会尽可能向后读取字母、数字和下划线，因此相邻文本可能被误认为变量名。字段名后面紧跟普通字符时，优先用花括号形式。

package main

import (
    "fmt"
    "regexp"
)

func main() {
    // 花括号把变量名与后续文字分开，避免 $nameSuffix 被当成一个组名。
    re := regexp.MustCompile(`(?P[a-z]+)`)
    match := re.FindStringSubmatchIndex("go")
    dst := re.ExpandString(nil, "${name}_suffix=$$", "go", match)

    // $$ 表示一个字面量美元符号，而不是新的捕获组引用。
    fmt.Println(string(dst))
}

go_suffix=$

引用不存在的组、超出范围的组或没有参与本次匹配的组时，ExpandString 会写入空片段。它不会替你报错，所以模板由配置驱动时，应在启动阶段检查关键组名，或者在业务层明确缺省值策略。

Expand、ExpandString 和 ReplaceAllString 怎么选

这三个 API 都建立在同一套捕获组规则上。不要把 ReplaceAllString 的替换字符串直接当成普通文本：它同样会解释捕获组变量；如果要完全按字面替换，应使用对应的 Literal 版本。

常见问题

为什么 ExpandString 的 match 不能随便传一个空切片？

因为它依靠 match 中的字节起止位置从 src 取完整匹配和子组内容。应使用同一正则对象返回的 SubmatchIndex 结果；没有匹配时，先判断结果是否为 nil。

命名组和数字组可以混用吗？

可以。数字变量按子表达式位置引用，命名变量按 (?P...) 查找。工程代码更建议优先使用命名组，让模板不受捕获组顺序调整影响。

为什么结果里少了一段内容？

先检查变量是否写成了连续的更长名字，再检查可选组是否在本次匹配中没有命中。需要输出字面量美元符号时使用 $$，需要把变量名与普通文字分隔时使用 ${name}。

总结

使用 ExpandString 的稳定路径可以概括为：正则定义命名组，SubmatchIndex 提供位置，模板决定输出顺序，dst 负责承接连续结果。字符串输入选 ExpandString，字节输入选 Expand；如果不需要自己管理索引，才优先考虑 ReplaceAllString。把变量边界和未匹配策略提前写进模板约定，后续修改正则结构时会更安全。