Go text/template.Template.Clone 怎样复制模板集合再独立修改

如果一套模板只有一个输出版本，直接 Parse 后执行就够了；一旦同一份页眉、页脚或公共片段要派生出多个版本，继续在原对象上解析就容易把变体互相覆盖。text/template.Template.Clone 解决的正是这个问题：它复制已经关联的模板命名空间，之后对副本调用 Parse，新增定义只进入副本。

官方地址：https://pkg.go.dev/text/template

实用记法是：先把公共模板解析完整，再 Clone；副本只负责自己的变体，原模板负责公共版本。Clone 解决命名空间隔离，Parse 负责增加或重定义模板，ExecuteTemplate 负责选择最终输出入口。

1. 先分清 Template、关联模板和命名空间

一个 *template.Template 不只代表一段字符串。通过 define 或 New 建立的模板会和它关联，关联关系形成一个可以按名称查找的命名空间。主模板可以调用命名模板，调用方通常用 ExecuteTemplate 指定实际输出入口。

下面先建立一个公共模板集合。代码故意把页眉、正文和页脚拆成命名模板，后面变体只替换正文。

package main

import (
	"bytes"
	"fmt"
	"log"
	"text/template"
)

func buildBase() *template.Template {
	// 先解析公共片段，后续副本只从这套命名空间派生。
	const source = `{{define "header"}}[公共页眉]{{end}}
{{define "body"}}默认正文：{{.}}{{end}}
{{define "footer"}}[公共页脚]{{end}}`

	tmpl, err := template.New("page").Parse(source)
	if err != nil {
		// 模板语法错误属于构建阶段错误，不能把半成品交给执行阶段。
		log.Fatal(err)
	}
	return tmpl
}

func render(tmpl *template.Template, name string, data string) (string, error) {
	var buf bytes.Buffer
	// 明确选择命名模板，避免把关联集合中的名称误当成输出入口。
	err := tmpl.ExecuteTemplate(&buf, name, data)
	return buf.String(), err
}

func main() {
	base := buildBase()
	output, err := render(base, "body", "公共内容")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(output)
}

这里的 base 是公共模板集合，body 是其中一个已定义名称。生产代码可以把 ExecuteTemplate 的输出入口固定成约定名称，也可以在调用前用 Lookup 判断名称是否存在。

2. Clone 复制的是命名空间，不是完全独立的文本快照

官方文档对 Clone 的描述有一个容易被忽略的重点：实际表示不会逐份复制，但关联模板的命名空间会复制。因此，Clone 的价值不是把每个字符重新拷贝一遍，而是让副本后续的模板关联操作与原对象分开。

这也解释了为什么不应把“直接在原模板上连续 Parse 多个版本”当成隔离方案：同名定义可能被后一次解析替换，调用方无法再从对象本身判断某次输出属于哪个版本。Clone 后，每个副本都有自己的关联名称集合。

3. 在副本上 Parse 变体，原模板保持公共版本

下面的示例为公共模板派生 compact 和 detail 两个副本。变体使用同名的 body 定义，从而让同一个输出入口呈现不同正文。

func buildVariants() (*template.Template, *template.Template, error) {
	base := buildBase()

	compact, err := base.Clone()
	if err != nil {
		// Clone 错误要在创建变体时处理，不要延后到 Execute 才猜原因。
		return nil, nil, fmt.Errorf("clone compact template: %w", err)
	}
	if _, err := compact.Parse(`{{define "body"}}紧凑正文：{{.}}{{end}}`); err != nil {
		// Parse 失败时只丢弃当前副本，公共模板仍保持可复用。
		return nil, nil, fmt.Errorf("parse compact variant: %w", err)
	}

	detail, err := base.Clone()
	if err != nil {
		return nil, nil, fmt.Errorf("clone detail template: %w", err)
	}
	if _, err := detail.Parse(`{{define "body"}}详细正文：{{.}}；附加说明：可继续扩展{{end}}`); err != nil {
		return nil, nil, fmt.Errorf("parse detail variant: %w", err)
	}
	return compact, detail, nil
}

关键点有两个。第一，Parse 返回的仍然是接收者，适合在副本上继续链式组装；第二，变体解析失败时不要用半成品继续执行，直接返回带上下文的错误更容易定位。空白或只有注释的定义不会替换已有正文，这是模板重定义时也要留意的边界。

4. 用 ExecuteTemplate 选择不同变体的输出

副本准备好后，可以分别执行同名的 body。原模板仍输出“默认正文”，两个副本分别输出自己的正文，这就是 Clone 带来的独立修改效果。

func printVariants() error {
	base := buildBase()
	compact, detail, err := buildVariants()
	if err != nil {
		return err
	}

	for _, item := range []struct {
		label string
		tmpl  *template.Template
	}{
		{"base", base},
		{"compact", compact},
		{"detail", detail},
	} {
		text, err := render(item.tmpl, "body", "订单摘要")
		if err != nil {
			// 记录变体名称，避免多个 Execute 错误混在一起。
			return fmt.Errorf("render %s: %w", item.label, err)
		}
		fmt.Printf("%s => %s\n", item.label, text)
	}
	return nil
}

如果希望选择的是命名模板而不是副本，可以把 ExecuteTemplate 的名称换成 header、footer 等已关联定义。名称不存在或没有定义时，执行会返回错误；因此在动态模板名称来自配置时，应先做名称映射或调用 Lookup。

5. Clone、Parse 和 Execute 的错误边界

把三个阶段分开，排查会简单很多：

当前 text/template 的官方实现把关联模板分组保存在共享结构中，Clone 时复制关联名称到新的命名空间；源代码还保留了函数映射和选项的对应关系。应用层不需要依赖这些内部字段，只要遵守“构造阶段不并发修改、构造完成后并发执行”的边界即可。多个 goroutine 可以安全地执行同一套已构造模板，但不要让它们同时对同一集合继续 New 或 Parse。

6. 一份可复用的 Clone 工作流

1. 创建并解析公共模板，先处理公共函数和公共命名模板。
2. 对每个输出版本调用一次 Clone，把副本放入有明确名称的结构中。
3. 只在对应副本上 Parse 变体定义，同名定义的覆盖范围保持在副本内。
4. 执行时显式调用 ExecuteTemplate，不要依赖模板集合的默认名称。
5. 记录变体名和阶段错误；所有模板构造完成后，再把只读模板交给并发执行。

这种方式适合“公共骨架相同、局部内容不同”的场景，例如邮件摘要、文本报告和多租户消息格式。若每个版本完全无关，分别 Parse 往往更直观；若需要 HTML 自动转义，则应改用 html/template 并重新评估其转义语义，不能仅凭 text/template 的行为作结论。

常见问题

Clone 会把模板字符串完整深拷贝吗？

不应把它理解成字符串级深拷贝。它重点复制关联模板的命名空间，让副本后续的解析不会把新名称或变体安装回原对象。

为什么不直接对 base 连续调用 Parse？

连续解析适合组装同一套模板；当多个版本重定义同名模板时，原对象会进入最后一次定义的状态，版本隔离不再清晰。需要派生版本时先 Clone 更稳妥。

Clone 完成后能不能并发执行？

可以把构造完成的模板用于并发执行，但共享 Writer 可能让输出互相交错。模板构造本身仍应集中完成，避免并发 Parse 或 New。