生成 HTML 邮件时，模板结构和业务数据最好分开：用 html/template 解析邮件骨架，把订单标题、客户备注等数据作为执行参数传入，再把结果交给邮件发送层。它会根据数据所在的 HTML、属性或 URL 上下文自动转义；真正需要警惕的是把外部字符串误标成 template.HTML。

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

实用的邮件渲染边界是：模板作者控制结构，业务数据默认按不可信文本处理，执行成功后才把完整结果交给发送器。

先把邮件骨架和数据模型分开

邮件模板可以包含标题、问候语和订单列表，业务代码只准备数据。解析阶段先处理模板语法错误，执行阶段再处理数据或函数错误；两类错误都不能被忽略，否则发送层可能拿到空内容或半成品。

package main

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

type MailData struct {
    Title   string
    Message string
}

func renderMail(data MailData) (string, error) {
    const source = `
{{.Title}}
{{.Message}}
`

    // 解析错误说明模板本身不可用，不能带着错误继续发送。
    tmpl, err := template.New("order-mail").Parse(source)
    if err != nil {
        return "", fmt.Errorf("parse mail template: %w", err)
    }

    var buf bytes.Buffer
    // 执行成功后才返回完整 HTML，避免发送半成品内容。
    if err := tmpl.Execute(&buf, data); err != nil {
        return "", fmt.Errorf("execute mail template: %w", err)
    }
    return buf.String(), nil
}

这里的 Message 即使包含尖括号，也只是文本数据。生产代码可以把模板放在文件或嵌入式资源中，把解析放到启动阶段；每次发送只执行模板，减少重复解析。

让 html/template 按上下文决定怎么转义

自动转义不是简单地把所有内容替换成同一种实体。插入正文时需要保护标签边界，放进属性时要保护引号，放进 URL 参数时还要处理 URL 上下文。这样模板仍能保持原有结构，而数据不能借机改变结构。

邮件场景里尤其容易忽略链接属性。用户提供的显示名称可以作为普通文本，但跳转地址需要先经过业务层的协议、域名和用途检查；模板自动转义解决的是结构安全，不等于替业务规则验证链接是否应该发送。

执行成功后再交给邮件发送器

渲染函数返回完整字符串，发送函数只接收成功结果。不要一边执行模板一边向网络连接写邮件正文，否则中途报错时，调用方很难撤回已经发出的半段内容。

邮件客户端还可能过滤脚本、外链样式或部分 HTML 标签，这是兼容性问题，不应通过关闭转义来解决。更稳妥的方式是只使用邮件客户端普遍支持的结构，并为关键文字准备纯文本版本。

template.HTML 只能跨过可信边界

template.HTML 表示调用者愿意为这段 HTML 的安全性负责。比如由服务端固定生成的加粗标签可以有明确来源；用户评论、客户姓名和第三方接口返回值都应该继续保持 string，不要先拼接再强转。

func trustedBadge() template.HTML {
    // 片段由程序固定生成，不接收用户输入，才有资格标记为可信 HTML。
    return template.HTML(`已付款`)
}

func unsafeFragment(raw string) template.HTML {
    // 不能把外部字符串直接强转为 template.HTML，这会绕过上下文保护。
    return template.HTML(raw)
}

更好的设计是让可信片段在小范围函数中产生，并在函数签名或注释中写清来源。若只是想展示用户输入中的换行或简单格式，应先把需求拆成结构化字段，让模板决定标签，而不是把一段 HTML 交给调用方。

常见问题

邮件模板为什么不直接使用 text/template

text/template 不理解 HTML 上下文。它适合纯文本邮件；只要输出包含 HTML，就应优先使用 html/template。

Execute 返回错误时还要发送邮件吗

不发送。先记录模板名和业务标识，修复或降级到纯文本模板后再发，避免收件人收到结构残缺的内容。

自动转义能替代链接白名单吗

不能。自动转义保护文档结构，协议、域名、跳转场景和业务权限仍要在数据进入模板前检查。

把模板作者和数据提供者分开，普通数据坚持使用字符串，渲染完成后再发送，邮件模板的可维护性和安全边界就会清楚很多。