Go template 如何安全渲染可选片段：模板运行与缺失键策略的边界

页面里有一段可选的配送说明，数据里没有这个字段时，Go 模板可能仍然返回成功，只是把空值渲染出来。要让“字段缺失”和“字段存在但内容为空”分开处理，关键是先明确 Execute 的默认行为，再决定是否启用 missingkey=error。

可选片段不要靠默认空字符串判断。稳定做法是：允许缺失的字段用显式分支兜底，必须存在的字段在模板执行前启用 missingkey=error，并始终检查 Execute 的错误返回。

先复现：缺失键为什么会变成“成功的空结果”

先把问题缩小到一个模板和一份 map 数据。模板里同时放一个必有的订单号和一个可能不存在的配送说明，观察 模板数据 进入 Execute 后，缺失键 如何影响 渲染结果。

package main

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

func main() {
    const source = `订单号：{{.OrderID}}
配送说明：{{.DeliveryNote}}`

    data := map[string]string{"OrderID": "A-1007"}
    tmpl := template.Must(template.New("order").Parse(source))

    var buf bytes.Buffer
    err := tmpl.Execute(&buf, data)
    fmt.Printf("err=%v\\n%s\\n", err, buf.String())
}

这里的 Execute 通常会返回 nil，缺失的 DeliveryNote 只留下空白。这个结果先别下结论：它适合“没有说明就不展示”的可选文案，却不适合把收件人、订单号这类必填字段静默吞掉。

图：模板数据 经过 Execute，遇到 缺失键 后仍可能得到成功的 渲染结果。

把必填字段改成可验证的失败

如果业务约定配送说明必须出现，就不要依赖默认策略。创建模板时加上 Option("missingkey=error")，再把输出先写进缓冲区。这样可以围绕 missingkey=error、Execute、错误返回 和 输出检查 建立一条清楚的验收路径。

func renderOrder(data map[string]string) (string, error) {
    const source = `订单号：{{.OrderID}}
配送说明：{{.DeliveryNote}}`

    tmpl, err := template.New("order").
        Option("missingkey=error").
        Parse(source)
    if err != nil {
        return "", err
    }

    var buf bytes.Buffer
    if err := tmpl.Execute(&buf, data); err != nil {
        return "", fmt.Errorf("render order: %w", err)
    }
    return buf.String(), nil
}

这时缺少 DeliveryNote 会让 Execute 返回错误，调用方拿到的是空字符串和明确错误，而不是一段看起来正常的半成品页面。模板解析错误和执行错误都要处理，不能只包住 Parse。

图：严格模式把 missingkey=error 接到 Execute，通过 错误返回 阻断不完整输出，再做 输出检查。

可选片段应该交给显式分支

严格模式解决的是“必须存在”的字段。对于配送说明这种确实可选的片段，更稳妥的做法是把可选性写进数据模型或模板分支，而不是把所有缺失键都当成错误。

type OrderView struct {
    OrderID      string
    DeliveryNote string
    HasDelivery  bool
}

const source = `订单号：{{.OrderID}}
{{if .HasDelivery}}配送说明：{{.DeliveryNote}}{{end}}`

调用方先决定 HasDelivery 是否成立，模板只负责展示。这样“字段不存在”和“业务上不展示”不会混成同一个空字符串；如果字段来自不可信输入，也不要把用户输入当作模板源码再次解析。

三个容易漏掉的验收点

不要只看 Execute 是否报错

Execute 返回 nil 只能说明这次执行没有报告错误。仍要检查关键字段是否满足业务约束，尤其是写入 HTTP 响应前，最好先使用 bytes.Buffer 完成输出检查。

Parse 和 Execute 是两类错误

模板语法错误通常在 Parse 阶段出现，数据缺失或执行期函数错误则可能在 Execute 阶段出现。两个返回值都要保留上下文，日志里写清模板名和业务对象编号。

严格策略不要覆盖可选业务

missingkey=error 适合把契约写死的字段；可选片段用显式布尔字段、指针或专用视图结构表达。策略越清楚，模板越容易测试。

常见问题

Execute 返回 nil 就代表页面完整吗？

不代表。它只说明模板执行没有返回错误；默认缺失键可能已经被渲染为空值，完整性仍需业务字段检查。

可以只使用 missingkey=error 吗？

不建议。它适合必填字段，若把可选字段也放进严格模板，正常的“无配送说明”会被当成失败。应通过视图数据中的显式状态区分两者。

为什么要先写 bytes.Buffer？

先缓冲可以在提交响应前检查错误和关键内容，失败时返回统一错误页，避免客户端收到半截模板。

小结

Go 模板的安全边界不在某一个选项，而在字段契约是否清楚：必填字段使用 missingkey=error 并检查 Execute，可选片段使用显式分支，输出先进入缓冲区再提交。把这三件事固定下来，缺字段就不会悄悄变成难排查的空页面。