Go text/template Clone 怎么为不同渠道复用模板

如果一套页面要同时输出 Web、邮件和纯文本版本，直接在同一个 *template.Template 上反复 Parse 很容易互相覆盖。更稳妥的做法是：先解析公共定义，再对根模板调用 Clone()，最后在每个副本里追加渠道自己的同名定义。这样复用的是公共模板命名空间，变化留在各自副本中。

Clone 复制的到底是什么

Clone 的重点不是把每个解析结构简单地深拷贝一份，而是复制“关联模板的命名空间”。因此副本仍然能找到公共的 page 和 header，但在副本上再次 Parse 时，新增或重定义的模板只属于这个副本。官方文档也明确说明，常见用途就是先准备公共模板，再在克隆后追加变体定义。

可以把公共部分设计成一个稳定入口：page 负责组合 header 和 body，渠道副本只替换 body。这里的“替换”发生在模板定义层，不是把渲染结果复制后再做字符串替换。

如何为 Web 和邮件分别追加定义

下面的例子用一个订单摘要演示完整关系。公共模板先定义页面骨架；克隆后，两个副本分别重新定义 body。代码中的注释说明了错误处理和输出边界，实际项目可以把模板文本放到 embed.FS 或文件中。

package main

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

type Order struct {
	Number string
	Total  string
}

func main() {
	// 公共模板只负责稳定的组合关系，body 留给渠道副本重定义。
	baseText := `{{define "page"}}{{template "header" .}}{{template "body" .}}{{end}}
{{define "header"}}订单通知：{{.Number}}
{{end}}
{{define "body"}}金额：{{.Total}}
{{end}}`

	base, err := template.New("root").Parse(baseText)
	if err != nil {
		// 解析错误发生在构造阶段，不能拿半成品进入渲染池。
		panic(err)
	}

	web, err := base.Clone()
	if err != nil {
		panic(err)
	}
	// 同名定义只改 Web 副本，不会改 base 或 mail。
	if _, err = web.Parse(`{{define "body"}}应付：{{.Total}}
{{end}}`); err != nil {
		panic(err)
	}

	mail, err := base.Clone()
	if err != nil {
		panic(err)
	}
	// 邮件保留纯文本结构，和 Web 的 body 互不覆盖。
	if _, err = mail.Parse(`{{define "body"}}请在后台核对金额 {{.Total}}。
{{end}}`); err != nil {
		panic(err)
	}

	data := Order{Number: "A-1024", Total: "128.00 元"}
	var webOut, mailOut bytes.Buffer
	// ExecuteTemplate 按公共入口 page 渲染，输出 Writer 各自独立。
	if err = web.ExecuteTemplate(&webOut, "page", data); err != nil {
		fmt.Fprintln(os.Stderr, "Web 渲染失败：", err)
		return
	}
	if err = mail.ExecuteTemplate(&mailOut, "page", data); err != nil {
		fmt.Fprintln(os.Stderr, "邮件渲染失败：", err)
		return
	}
	fmt.Println(webOut.String())
	fmt.Println(mailOut.String())
}

这段代码里，page 在两个副本中都保持不变，解析同名 body 才产生差异。若误把 base.Parse 放在克隆之后的公共流程中，所有已经共享该根模板的后续设计都会变得难以追踪；把渠道解析封装成“克隆一次、解析一次”更容易维护。

三个容易踩到的边界

尤其要区分“模板作者可信”和“数据来自用户”。text/template 的安全模型假设模板作者可信，并不自动为 HTML 输出做安全转义；如果目标是 HTML，官方文档建议使用接口相同但会进行相应转义的 html/template。Clone 解决的是模板组织和隔离，不是输出安全问题。

常见问题

Clone 后还能调用 Funcs 吗？

可以。函数应在模板解析前注册；克隆后也可以替换同名函数。为了让公共模板行为一致，通常在公共模板阶段注册通用函数，渠道差异尽量放进定义而不是函数副作用。

为什么不直接 New 一个模板？

直接 New 只能得到新的关联模板，不会自动带上已有的 page、header 等定义。需要复用公共模板并允许局部变体时，Clone 更贴合这个边界。

Execute 和 ExecuteTemplate 怎么选？

当根模板自身就是要执行的主体时可用 Execute；公共模板由多个命名定义组成时，使用 ExecuteTemplate 明确指定 page 这样的入口，能避免执行到空的根定义。

实际落地时可以把“公共解析、渠道克隆、渠道 Parse、按名执行”封装成小型工厂。只要模板构造阶段不并发修改，执行阶段使用独立 Writer，就能在复用布局的同时保持渠道之间的变更边界。