Go text/template 怎么按不同格式复用同一份数据

同一份业务数据，既要生成终端能读的纯文本，又要生成适合提交到知识库的 Markdown，最稳妥的做法不是复制两套结构体，而是让 text/template 管数据绑定，让不同的命名模板管格式。这样字段只维护一份，输出格式可以按模板名切换。

核心写法是：先把 Report 作为统一数据源，用 define 声明多个命名模板，再通过 ExecuteTemplate 把同一份数据分别写入不同缓冲区。模板之间复用字段，格式差异留在模板层。

先把格式差异隔离在模板层

假设程序要发布一份周报，标题、负责人和条目列表是事实数据，纯文本与 Markdown 只是两种排版。先把这三类字段放进一个结构体，模板就不需要知道数据是从数据库、接口还是文件来的。

type Item struct {
    Name  string
    State string
}

type Report struct {
    Title string
    Owner string
    Items []Item
}

这个边界很重要：如果为了两个格式各建一份 ReportText 和 ReportMarkdown，字段变化就必须同步修改两处，模板复用反而变成数据分叉。模板只负责“怎么显示”，数据结构负责“有哪些事实”。

用 define 和 Parse 组成模板集合

命名模板适合表达多个输出入口。下面的模板文本定义一个共享标题片段，再定义 text 和 markdown 两个格式。define 必须放在模板顶层，调用时用 template 动作按名称引用。

{{define "title"}}{{/* 共享标题字段 */}}
标题：{{.Title}}
{{end}}

{{define "text"}}{{/* 纯文本格式保留简单换行 */}}
{{template "title" .}}负责人：{{.Owner}}
条目：
{{range .Items}}- {{.Name}}（{{.State}}）
{{end}}{{end}}

{{define "markdown"}}{{/* Markdown 格式使用标题和列表语法 */}}
# {{.Title}}

负责人：{{.Owner}}

{{range .Items}}- **{{.Name}}**：{{.State}}
{{end}}{{end}}

解析时给根模板一个名字即可。解析阶段只检查模板语法和名称关系，不会替你决定最终使用哪个输出格式，因此可以在程序启动阶段完成。

const layout = `{{define "title"}}标题：{{.Title}}
{{end}}
{{define "text"}}{{template "title" .}}负责人：{{.Owner}}
{{range .Items}}- {{.Name}}（{{.State}}）
{{end}}{{end}}
{{define "markdown"}}# {{.Title}}

负责人：{{.Owner}}
{{range .Items}}- **{{.Name}}**：{{.State}}
{{end}}{{end}}`

// 启动时解析，模板写错就尽早返回错误。
templates, err := template.New("report").Parse(layout)
if err != nil {
    return fmt.Errorf("解析报告模板失败：%w", err)
}

用命名模板选择输出格式

真正输出时，不要把格式判断散落在字段拼接代码里。把格式名当作一个小范围选择值，统一交给 ExecuteTemplate，并为每次渲染准备独立的 bytes.Buffer。这样同一个 Report 可以重复使用，两个结果也不会互相覆盖。

func render(templates *template.Template, name string, report Report) (string, error) {
    var out bytes.Buffer

    // 模板名决定排版，report 始终是同一份业务数据。
    if err := templates.ExecuteTemplate(&out, name, report); err != nil {
        return "", fmt.Errorf("执行模板 %q 失败：%w", name, err)
    }
    return out.String(), nil
}

report := Report{
    Title: "本周发布清单",
    Owner: "林晓",
    Items: []Item{
        {Name: "接口文档", State: "已完成"},
        {Name: "回归检查", State: "待确认"},
    },
}

plain, err := render(templates, "text", report)
if err != nil {
    return err
}
markdown, err := render(templates, "markdown", report)
if err != nil {
    return err
}
fmt.Println(plain)
fmt.Println(markdown)

这里的复用点有两个：report 没有为格式复制，模板中的 .Title、.Owner 和 .Items 也保持同一条字段路径。若要增加邮件纯文本或简短摘要，只需增加新的命名模板，调用方式不变。

这些边界最容易让复用失效

判断是否适合这种方案，可以看三点：数据字段是否相同、变化主要是否发生在排版层、输出格式是否能用清晰的模板名称表达。如果不同格式连数据含义都不同，就不要强行共用一个结构体；如果只是标题符号、列表形式或换行不同，命名模板通常更容易维护。

常见问题

text/template 可以直接复用同一份模板结果吗？

可以复用已解析的模板集合和输入数据，但每次输出应使用自己的 Writer。模板解析完成后，模板可以并行执行；共享同一个 Writer 时，输出可能交错。

为什么不能只调用 Execute？

Execute 适合执行根模板；当一组模板里有多个命名入口时，用 ExecuteTemplate 明确指定名称，意图更清楚，也不会依赖根模板名称是否正好对应目标格式。

输出 HTML 时还用 text/template 吗？

如果内容会进入 HTML 页面，应认真评估 html/template。text/template 不负责 HTML 自动转义，模板作者必须是可信来源，不能把它当作网页输出的安全边界。