Go template.Clone 怎么复用基础模板并覆盖局部块

Go 的 template.Clone 很适合“公共骨架固定、少数区块因场景变化”的模板。做法是先解析一份包含默认 block 的基础模板，再为每个场景克隆一个独立的关联模板命名空间，最后只在副本中重新定义同名块。这样欢迎通知、告警通知可以共享页头、页尾和字段约定，又不会互相覆盖。

官方文档：https://pkg.go.dev/text/template

block 等价于“定义一个命名模板并在当前位置调用它”；Clone 会复制当前模板及全部关联模板的命名空间。克隆后对副本调用 Parse，同名且非空的定义会替换副本中的旧定义，原模板保持不变。

项目目标与目录

这个小项目生成三种纯文本通知：基础模板使用默认标题和正文，欢迎模板覆盖标题与正文，告警模板也覆盖这两个块；公共签名 footer 始终来自基础模板。项目只需要标准库：

# 创建示例模块与入口文件
mkdir template-clone-demo
cd template-clone-demo
go mod init example.com/template-clone-demo

最终只保留 go.mod、main.go 和 main_test.go。为了让示例容易看清，模板字符串直接写在 Go 文件中；生产项目可以把相同结构迁移到 ParseFS 和 embed.FS。

先定义可独立工作的基础模板

基础模板必须自己就能执行。两个 block 分别提供默认主题和正文，footer 是普通关联模板。根模板命名为 base，后面统一通过 ExecuteTemplate 执行它。

package main

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

type Notice struct {
    Name    string
    Project string
    Level   string
}

const baseText = `{{define "base" -}}
Subject: {{block "subject" .}}General notice{{end}}

{{block "body" .}}Hello {{.Name}}, {{.Project}} has an update.{{end}}

{{template "footer" .}}
{{- end}}

{{define "footer"}}-- Operations Team{{end}}
`

func newBase() (*template.Template, error) {
    // 先建立完整的关联模板集合，保证默认版本可直接执行
    return template.New("root").Option("missingkey=error").Parse(baseText)
}

func render(t *template.Template, data Notice) (string, error) {
    var out bytes.Buffer
    // 显式执行根模板，避免依赖 Parse 后当前模板名称
    if err := t.ExecuteTemplate(&out, "base", data); err != nil {
        return "", fmt.Errorf("execute base: %w", err)
    }
    return out.String(), nil
}

block "subject" . 会先定义名为 subject 的模板，再把当前数据点传给它并在原位置执行。若后续没有覆盖，就使用块体中的 General notice。missingkey=error 让字段缺失在执行阶段直接报错，比生成半成品通知更容易排查。

克隆后覆盖欢迎通知的局部块

欢迎通知只需要重新定义 subject 和 body。官方文档说明，Clone 复制关联模板命名空间；之后在副本上继续 Parse，新增或替换的定义只属于副本。

const welcomeOverlay = `
{{define "subject"}}Welcome to {{.Project}}{{end}}
{{define "body"}}Hello {{.Name}}, your workspace is ready.{{end}}
`

func cloneWith(base *template.Template, overlay string) (*template.Template, error) {
    cloned, err := base.Clone()
    if err != nil {
        return nil, fmt.Errorf("clone template: %w", err)
    }

    // 在副本中解析同名定义，只替换副本的局部块
    if _, err := cloned.Parse(overlay); err != nil {
        return nil, fmt.Errorf("parse overlay: %w", err)
    }
    return cloned, nil
}

这里不要把覆盖文本解析回 base，否则后续所有基于它的执行都会看到新定义。克隆动作应该发生在基础模板已经解析完成之后，覆盖动作发生在克隆之后。

再做一个互不影响的告警变体

第二个副本使用同样的辅助函数，但换成告警块。两个副本都源自同一个基础模板，却拥有独立的关联模板命名空间：

const alertOverlay = `
{{define "subject"}}[{{.Level}}] {{.Project}} alert{{end}}
{{define "body"}}{{.Name}}, please check {{.Project}} immediately.{{end}}
`

func main() {
    base := template.Must(newBase())
    welcome := template.Must(cloneWith(base, welcomeOverlay))
    alert := template.Must(cloneWith(base, alertOverlay))

    data := Notice{Name: "Lin", Project: "Search API", Level: "HIGH"}

    // 分别执行基础版本和两个变体，输出内容互不污染
    for _, item := range []struct {
        name string
        tmpl *template.Template
    }{
        {name: "base", tmpl: base},
        {name: "welcome", tmpl: welcome},
        {name: "alert", tmpl: alert},
    } {
        text, err := render(item.tmpl, data)
        if err != nil {
            panic(err)
        }
        fmt.Printf("== %s ==\n%s\n", item.name, text)
    }
}

核对结果时关注三点：基础版本仍包含 General notice；欢迎版本出现 Welcome to Search API；告警版本出现 [HIGH] Search API alert。三个版本都应包含公共签名 Operations Team。

ExecuteTemplate 为什么要指定 base

一个 *template.Template 可以关联多个命名模板。Parse 遇到 define 或 block 时，会把它们加入关联集合，而定义本身会从当前模板正文中移除。显式调用 ExecuteTemplate(writer, "base", data)，可以稳定地选择包含整体骨架的根模板。

如果直接调用 Execute，执行的是接收者自身对应的模板；当入口名称、文件名或解析顺序变化时，很容易执行到空的 root。把根模板名称固定为 base，调用点就不依赖当前模板的名字。

用测试确认覆盖没有串到基础模板

模板复用最值得测试的不是某一个字符串，而是“默认定义仍在、每个副本只看到自己的覆盖”。将下面内容保存为 main_test.go：

package main

import (
    "strings"
    "testing"
    "text/template"
)

func TestCloneOverridesAreIsolated(t *testing.T) {
    base := template.Must(newBase())
    welcome := template.Must(cloneWith(base, welcomeOverlay))
    alert := template.Must(cloneWith(base, alertOverlay))
    data := Notice{Name: "Lin", Project: "Search API", Level: "HIGH"}

    cases := []struct {
        name string
        tmpl *template.Template
        want string
        deny string
    }{
        {"base", base, "General notice", "Welcome to"},
        {"welcome", welcome, "Welcome to Search API", "[HIGH]"},
        {"alert", alert, "[HIGH] Search API alert", "General notice"},
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got, err := render(tc.tmpl, data)
            if err != nil {
                t.Fatalf("render: %v", err)
            }
            // 同时检查期望文本存在、其他变体文本不存在
            if !strings.Contains(got, tc.want) || strings.Contains(got, tc.deny) {
                t.Fatalf("unexpected output: %q", got)
            }
            if !strings.Contains(got, "Operations Team") {
                t.Fatalf("missing shared footer: %q", got)
            }
        })
    }
}

# 运行隔离性测试
go test ./...

测试通过后，可以确认三个模板共享同一套结构约定，但运行结果彼此隔离。若基础模板也出现了欢迎标题，通常是把 overlay 解析到了原模板，而不是 clone 上。

集成到服务时注意构造与执行边界

模板构造阶段会修改关联模板集合，官方文档说明这一阶段不能安全地并发进行。推荐在程序启动时一次性解析基础模板并创建所有变体，之后只读保存。构造完成后，模板可以并发执行；不过多个执行若共享同一个 Writer，输出仍可能交错，所以每个请求应使用自己的响应 Writer 或缓冲区。

常见问题

Clone 会复制所有关联模板吗？

会。官方文档说明它复制当前模板以及全部关联模板的命名空间。副本后续新增或替换定义不会影响原模板。

block 和 template 有什么区别？

block 是“带默认实现的 define 加 template 调用”的简写，适合提供可覆盖插槽；template 只调用已经存在的命名模板。

能不能只覆盖一个块？

可以。overlay 只需要定义希望替换的名称，未重新定义的 block 和普通关联模板会继续沿用基础版本。

html/template 也能这样用吗？

可以，html/template 提供对应的 Clone 和 block 机制，并会执行上下文相关转义。网页输出应优先用它，不要用 text/template 生成未转义 HTML。