Go text/template Option missingkey 如何选择错误策略

我在模板渲染里最容易踩到的坑，不是把 missingkey 拼错，而是没有先决定“缺一个 map key 到底算不算失败”。text/template 的 Option 提供三种明确策略：default（也可写 invalid）保持默认兼容行为，zero 返回 map 元素类型的零值，error 让执行立即返回错误。配置文件、通知文本可以容忍缺省；账单、权限、部署清单更适合严格失败。

先分清缺键、空值和模板字段问题

模板表达式 {{.profile.nickname}} 常被误解成“只要没有 nickname 就报错”。实际上，.profile 这一步通常先从 map 取值；只有当它确实是 map 且键不存在时，missingkey 才介入。键存在但值是空字符串、0 或 nil，属于数据值问题，不能靠换策略变成必填校验。

我会先给字段分组：展示性字段允许缺省，控制性字段必须存在；然后再选策略。还要注意 text/template 面向可信模板作者且不会自动转义 HTML。若目标是 HTML 输出，应单独评估 html/template 的安全模型，不能把两个包混为一谈。

三种 missingkey 策略对应三类结果

这里有一个容易忽略的取舍：zero 不是“更安全的 error”，它只是把缺键转换成元素类型零值。例如 map 的元素类型是 string，结果会接近空字符串；如果业务把空字符串当成合法值，缺键就可能被悄悄吞掉。严格数据合同优先用 error，兼容性优先才考虑 default。

在模板构造阶段固定 Option，并保留 Execute 错误

Option 接收简单字符串或 key=value 形式；未知选项会 panic，所以配置值不要直接拼接成不可控字符串。更稳妥的做法是集中创建模板，再把运行期执行错误交给调用方处理：

package main

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

func render(data map[string]string) (string, error) {
    // 把严格策略固定在模板构造边界，避免不同调用点各用一套规则。
    tmpl, err := template.New("notice").
        Option("missingkey=error").
        Parse("用户：{{.name}}，区域：{{.region}}")
    if err != nil {
        // Parse 只处理模板语法；语法错误应在启动或加载阶段暴露。
        return "", fmt.Errorf("parse template: %w", err)
    }

    var out bytes.Buffer
    // 缺键属于执行期数据错误，保留 Execute 的原始上下文给上层处理。
    if err := tmpl.Execute(&out, data); err != nil {
        return "", fmt.Errorf("execute template: %w", err)
    }
    return out.String(), nil
}

示例没有使用 template.Must 包裹包含运行期数据的执行错误。Must 适合初始化阶段就应该永远成功的固定模板；对于请求、任务或用户数据触发的错误，返回 error 更容易记录字段、选择降级或让任务重试。另一个边界是：即使 Execute 返回错误，写入器里也可能已经留下部分结果，调用方不要把这段缓冲区当成完整文档继续发送。

用字段清单把错误策略落到团队约定

我通常把模板变量表和策略放在同一份评审清单里，而不是只在代码中留下一个孤立字符串：

• 可选字段：确认缺失后展示 是否能被读者接受；不能接受时在数据准备阶段填充显式占位值。
• 必填字段：使用 missingkey=error，在 Execute 处记录模板名和业务对象标识。
• 零值有业务含义时：不要用 zero 隐藏缺失；先区分“缺键”和“键存在但值为空”。

测试至少覆盖完整 map、缺少一个键、键存在但值为空三组输入。这样能证明策略真的命中了 map 缺键，而不是把空值误当成缺键。每次新增模板变量，也同步更新清单和测试数据，避免模板改了、调用方却没有感知。

常见问题

missingkey=error 会在 Parse 阶段报错吗？

通常不会。它控制执行 map 缺失键时的行为；模板语法和函数名问题仍由 Parse 阶段处理。

missingkey=zero 能保证字段一定有值吗？

不能。它只返回 map 元素类型的零值，业务必填校验仍应在数据准备或 Execute 错误处理层完成。

text/template 和 html/template 可以直接互换吗？

接口相近但用途不同。生成 HTML 时应使用并单独评估 html/template 的自动转义行为，不能只替换 import 就假设安全模型相同。

最终选择可以压缩成一句话：可选展示用 default，需要类型零值才用 zero，结果缺字段就不可交付时用 error；无论选哪种，都把它和模板变量清单、Execute 错误处理放在同一个边界内维护。