Go regexp.Expand 如何把捕获组写入缓冲区

我第一次用 regexp.Expand 时，卡住的地方不是正则本身，而是把“捕获到的文本”和“捕获文本在原字符串中的位置”混在了一起。这个方法接收的不是 []string，而是 FindSubmatchIndex 产生的字节偏移切片。把这条关系理顺后，模板替换就很直接：先找匹配，再让 Expand 把 $key、$1 等变量追加进已有缓冲区。

regexp.Expand 的四个输入先对齐

Expand(dst, template, src, match) 可以理解成一台“按索引取片段的模板拼接器”。src 是原始字节，match 告诉它每个匹配组在 src 中的起止位置，template 决定输出顺序，dst 则是承接结果的缓冲区。它返回追加后的切片，所以可以在多次匹配之间复用同一个结果。

下面这段代码把一行 key: value 转成 key=value。代码没有直接读取捕获文本，而是把索引交给 ExpandString：

package main

import (
    "fmt"
    "regexp"
)

func main() {
    // 命名捕获组让模板中的 $key、$value 更容易阅读。
    re := regexp.MustCompile(`(?m)(?P\w+):\s+(?P\w+)$`)
    src := "port: 8080\nmode: safe\n"
    result := make([]byte, 0, len(src))

    // 每个 match 都包含完整匹配和各捕获组的字节起止位置。
    for _, match := range re.FindAllStringSubmatchIndex(src, -1) {
        // 返回值要重新赋给 result，才能保留此前匹配追加的内容。
        result = re.ExpandString(result, "$key=$value\n", src, match)
    }
    fmt.Print(string(result))
}

这里的 dst 初始容量只是一个可选的分配提示，不改变替换语义。若使用字节输入，就把原文、模板和方法换成 []byte 版本的 Expand。

FindSubmatchIndex 返回的不是文本，而是偏移对

假设正则是 (?P\w+):\s+(?P\w+)，一次匹配的索引数组会按下面的顺序排列：

这也解释了为什么不能把 FindStringSubmatch 的结果直接传给 Expand：前者给的是字符串列表，后者需要的是每一组在原始输入中的字节位置。捕获组没有匹配到时，对应位置可能是负数，Expand 会把这个变量当成空片段处理，而不是主动报错。

模板变量的三个容易误判的边界

数字组可以写成 $1，命名组可以写成 $key 或 ${key}。当变量后面紧跟字母、数字或下划线时，解析器会尽可能把它们一起当作名字。因此 $1x 会优先按名为 1x 的组解析，不等于“第 1 组加字母 x”；需要后缀时写成 ${1}x。如果要输出字面量美元符号，用 $$。

实际使用中我更偏向命名组：正则改动捕获组顺序后，$key 仍然表达原来的意图。数字组适合很短的临时模板，但要把模板和正则放在同一处，避免后续维护者猜索引。

循环拼接时的检查清单

• 匹配来源是否是 FindSubmatchIndex、FindAllSubmatchIndex 或字符串对应方法？
• 是否把 Expand/ExpandString 的返回值重新赋回缓冲区？
• 是否区分“只生成匹配结果”和“保留原文其他部分”？后者需要自己拼接未匹配区间。
• 模板是否需要 ${1}suffix 或 $$ 这样的边界写法？

常见问题

regexp.Expand 会自动返回完整替换后的原文吗？

不会。它只把模板展开后追加到 dst，原文中匹配之间的内容要由调用方自行保留或拼接。

Expand 和 ExpandString 应该怎么选？

原文和模板本来就是字节切片时选 Expand；两者是字符串时选 ExpandString。两者都返回 []byte，便于调用方控制缓冲区。

捕获组没有匹配到会发生什么？

对应模板变量会得到空片段。需要区分“空字符串本来就是合法结果”和“捕获组没有参与匹配”时，应在展开前结合索引切片自行判断。