Go regexp.ExpandString 怎样把捕获组写入替换文本

我第一次把 regexp.ExpandString 用在配置文本转换上时，真正卡住的不是正则本身，而是四个输入没有对齐：匹配区间来自哪里、原文是不是同一个字符串、模板里的 $1 指向哪个捕获组，以及结果到底是覆盖还是追加。结论很明确：先用同一个 Regexp 对同一个 src 调用 FindSubmatchIndex，再把返回的 []int 原样传给 ExpandString；多条结果要复用并接着传入 dst。

这篇只讲标准库 API 的输入契约和容易误判的边界。它适合需要把正则捕获字段转换为配置行、日志字段或中间文本的 Go 开发者。

最小正确组合是：match := re.FindStringSubmatchIndex(src)，然后调用 re.ExpandString(dst, template, src, match)。不要手工拼接匹配下标，也不要把 FindStringSubmatch 返回的字符串切片直接当成 match []int。

先把四个输入对齐

ExpandString 的签名是 ExpandString(dst []byte, template string, src string, match []int) []byte。其中 dst 是已有输出，template 是包含捕获引用的模板，src 是被匹配的原文，match 是匹配区间数组。官方文档要求这个数组来自 FindSubmatchIndex，因为它保存的是每个整体匹配和子匹配在原文中的起止字节偏移。

下面这个小例子把一行配置中的键和值捕获出来，再写成统一的 key=value 形式：

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// 命名捕获组让模板字段不依赖数字位置，后续改动正则时更容易维护。
	re := regexp.MustCompile(`(?P[a-z]+):\s*(?P[^\s]+)`)
	src := "port: 8080"

	// match 必须来自同一个 re 对同一个 src 的 FindSubmatchIndex。
	match := re.FindStringSubmatchIndex(src)
	if match == nil {
		fmt.Println("没有找到配置项")
		return
	}

	// ExpandString 会把 $key 和 $value 替换为对应的捕获文本，并追加到 dst。
	dst := re.ExpandString(nil, "$key=$value", src, match)
	fmt.Println(string(dst))
}

这里的关键不是 MustCompile，而是四个参数来自同一组上下文。若先对 src1 求出下标，之后却把 src2 传进展开，偏移就可能指向另一段文本，结果会变得难以解释。

命名捕获让模板更稳定

模板变量可以写成 $name 或 ${name}。当正则使用 (?P...) 声明命名捕获组时，展开过程会按名称找到对应子匹配。对配置转换这类代码，我更倾向于使用命名捕获，因为增加一个无关的括号时，不会让模板中的数字编号整体漂移。

例如模板是 $key=$value\n，它表达的是两个字段之间的静态映射；ExpandString 不负责重新匹配，也不负责遍历所有匹配。遍历匹配仍由调用方完成，展开只处理当前这一组 match。

数字捕获和边界不要混用

数字引用适合短小的正则，但紧挨着字母时容易产生歧义。$1W 会被当作一个变量名整体解析，而不是“第 1 组后面拼一个字母 W”。需要明确边界时写成 ${1}W。命名引用同样可以使用花括号，例如 ${value}。

下面的示例专门展示边界写法和未匹配组：

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// 第二个捕获组允许为空，用来观察未匹配或空匹配时的输出边界。
	re := regexp.MustCompile(`a(?Px*)b`)
	src := "-ab-axxb-"
	for _, match := range re.FindAllStringSubmatchIndex(src, -1) {
		// 花括号把第 1 组与后面的字面量 W 分开，避免 $1W 被当成变量名。
		out := re.ExpandString(nil, "${1}W:$body", src, match)
		fmt.Printf("%q\n", out)
	}
}

当引用的下标超出范围、名称不存在，或者对应子匹配没有参与匹配时，展开结果会是空字节片段。这个行为不会自动报错，所以模板和正则的配对需要由代码本身保证。若业务上“缺字段”不能被静默接受，应在展开前根据匹配数组或业务字段规则显式判断。

循环追加时保留 dst

ExpandString 会把结果追加到 dst，返回新的字节切片。这样可以把多行匹配合并到一个缓冲区；如果每次都传 nil，就只会得到当前这一条展开结果。

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// 每轮使用同一份 src 和模板，把所有配置行累积到 result。
	re := regexp.MustCompile(`(?P[a-z]+):\s*(?P[^\s]+)`)
	src := "port: 8080\nhost: example"
	result := make([]byte, 0, len(src))

	for _, match := range re.FindAllStringSubmatchIndex(src, -1) {
		// 返回值必须接回 result，否则追加后的切片头不会被保留下来。
		result = re.ExpandString(result, "$key=$value\n", src, match)
	}
	fmt.Print(string(result))
}

这里的容量预留只是减少可能的扩容，不改变展开语义。真正需要记住的是返回值接回原变量，以及每次传入的 src、模板和匹配数组保持同一轮上下文。

把输入和输出边界写进检查清单

我在代码审查时会按下面几项检查：第一，match 是否由 FindSubmatchIndex 生成；第二，求匹配和展开是否使用同一个 src；第三，模板中紧邻字母的数字引用是否使用了花括号；第四，命名捕获名称是否确实存在；第五，业务是否允许未匹配组静默展开为空；第六，循环展开是否接回了返回的 []byte。

如果模板来自配置文件或请求参数，不要把它当成普通文本直接拼接到日志、命令或另一种解释语言中。ExpandString 只负责正则捕获替换，后续输出仍可能进入 HTML、SQL、Shell 或日志系统，应该在对应边界做各自的编码和审计。

常见问题

为什么不能把 FindStringSubmatch 的结果直接传给 ExpandString？

前者返回捕获到的字符串切片，后者需要的是原文偏移组成的 []int，以便从 src 中按区间取值。应改用 FindStringSubmatchIndex 或 FindAllStringSubmatchIndex。

ExpandString 会自动替换原文中的所有匹配吗？

不会。它只展开传入的一个 match。需要处理全部匹配时，调用方遍历匹配数组，并把每次返回的结果继续传给下一次调用。

未匹配的可选捕获组会返回错误吗？

不会自动返回错误，通常会展开为空片段。若空值会破坏业务格式，就应在展开前增加明确的业务判断。

小结

ExpandString 最容易出错的地方不是 API 数量，而是输入契约：匹配区间必须和原文对应，模板引用要有清晰边界，未匹配组要有业务判断，循环追加要接回返回切片。把这四个边界固定下来后，它很适合做轻量的捕获字段重排和文本转换。