Go regexp用 Expand 生成结构化替换文本的实践示例

Go regexp.Regexp.Expand 适合把已经匹配到的文本重新排成固定格式：正则表达式负责找到字段，FindSubmatchIndex 负责给出字段在源文本中的字节范围，Expand 再按模板引用把这些字段追加到结果缓冲区。它不会重新执行匹配，也不会替你校验输出是不是合法 JSON。

因此最小可靠写法是“先取索引，再展开模板”。命名捕获组适合让模板可读，数字引用适合短模板；批量处理时复用 dst，还要特别留意 $1x 的引用解析和可选分组的空值。

准备 Expand 所需的匹配索引

Expand 的四个参数分别是目标缓冲区、模板、源文本和匹配索引。最容易出错的是最后一个参数：不能把 FindStringSubmatch 得到的字段文本直接传进去，而应使用 FindStringSubmatchIndex 或字节切片对应的 FindSubmatchIndex。索引按整体匹配、第一组、第二组的顺序成对出现，未匹配的可选组会用负数表示。

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// 三个命名捕获组分别保存级别、服务名和消息内容。
	re := regexp.MustCompile(`^(?P[A-Z]+)\s+(?P[a-z-]+):\s+(?P.+)$`)
	src := []byte("WARN checkout: inventory timeout")

	// Expand 需要的 match 必须来自带 Index 后缀的方法。
	match := re.FindSubmatchIndex(src)
	if match == nil {
		fmt.Println("没有匹配")
		return
	}

	// 先给出空 dst，Expand 会把模板展开结果追加到它。
	template := []byte("level=$level service=$service message=$message")
	result := re.Expand(nil, template, src, match)
	fmt.Println(string(result))
}

这段代码的输出是 level=WARN service=checkout message=inventory timeout。Expand 通过正则中的命名捕获组查找模板变量，再从 src 的索引范围截取内容；它没有把结果转换成结构化对象，结构的字段分隔符仍由模板决定。

用命名捕获组生成结构化替换文本

日志清洗、配置迁移和文本协议转换都可以采用同一套路：把输入中的一行字段映射成稳定的 key=value 记录。模板中字段名必须与正则里的 (?P...) 一致，字段顺序、分隔符和换行符则由模板明确控制。

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// (?m) 让 ^ 和 $ 按行工作，每行只抽取一次结构化记录。
	re := regexp.MustCompile(`(?m)^(?P[A-Z]+)\s+(?P[a-z-]+):\s+(?P.+)$`)
	src := []byte("INFO api: request accepted\nERROR worker: queue full\n")
	template := []byte("level=$level\tservice=$service\tmessage=$message\n")

	// 复用一个结果缓冲区，按匹配出现的顺序追加每条记录。
	result := make([]byte, 0, len(src)+32)
	for _, match := range re.FindAllSubmatchIndex(src, -1) {
		// match 与当前 src 配套，不能跨源文本复用旧索引。
		result = re.Expand(result, template, src, match)
	}
	fmt.Print(string(result))
}

输出中的每一行都有相同字段顺序，后续可以再交给按制表符读取的程序。这里选择制表符而不是直接声称输出为 JSON，是因为 Expand 只负责字节替换；如果消息里出现引号、换行或制表符，严格 JSON 仍需要额外的转义和编码步骤。

处理数字引用与字面美元符号

数字引用很短，但相邻字符会改变解析结果。官方规则是变量名尽可能取长，所以 $1x 会被当作名为 1x 的引用，而不是第 1 组后接字母 x。需要明确边界时使用大括号。模板中的普通美元符号也不能直接写成单个 $，要用 $$。

命名引用同样建议在字段名相邻时使用大括号，例如 ${service}_raw。如果引用的名字不存在、索引超出范围，或对应的可选分组本次没有匹配，Expand 会放入空片段，不会返回错误。因此对必填字段应在匹配前后自行检查，而不能把空输出误认为字段真的为空。

package main

import (
	"fmt"
	"regexp"
)

func main() {
	// code 是可选组；没有 code 时，Expand 会把 $code 展开为空。
	re := regexp.MustCompile(`^(?P[a-z]+)(?:-(?P[0-9]+))?$`)
	src := []byte("task")
	match := re.FindSubmatchIndex(src)
	if match == nil {
		return
	}

	// ${kind} 明确引用边界，$$ 保留字面美元符号。
	template := []byte("name=${kind}_raw cost=$$5 code=$code")
	fmt.Println(string(re.Expand(nil, template, src, match)))
}

这段示例会得到 name=task_raw cost=$5 code=。若业务不允许 code 为空，应在输出前根据 match 中对应的负索引判断，或者把它设计为必选捕获组。

批量追加并确认边界

批量转换时，FindAllSubmatchIndex 会返回不重叠匹配的索引列表；每个索引都只对应同一个 src。把 dst 预留到合理容量可以减少扩容，但容量不是正确性的前提，Expand 仍会返回新的切片头，调用方必须接住返回值。

如果源数据是 string，可以改用 FindAllStringSubmatchIndex 与 ExpandString。后者仍返回 []byte，这是为了让调用方继续控制结果缓冲区；它并不改变引用规则，也不会自动复制未匹配的原始文本。

• 只要替换字段：用 FindAllSubmatchIndex 加 Expand，结果按模板顺序写入。
• 要保留原文：额外维护上一次匹配结束位置，把未匹配区间手工追加到 dst，Expand 本身不会做全量替换。
• 要严格结构化：先把匹配结果映射到结构体，再用编码器输出；不要把未转义的消息直接拼成 JSON。

常见问题

Expand 为什么不直接接收 FindStringSubmatch 的结果？

因为 Expand 需要知道捕获内容在源字节切片中的起止位置。应使用带 Index 后缀的方法，或自行提供与源文本对应的索引对。

可选捕获组没有匹配时会返回错误吗？

不会。对应引用会展开为空；必填字段需要由调用方检查匹配索引或输出结果。

Expand 能不能直接把整段文本做替换？

不能。它只把一个模板追加到 dst。批量替换要遍历匹配并自行处理匹配之间的原文区间，或根据场景选择其他 Regexp.ReplaceAll 方法。