Go text/template 缺少 map 键时怎么让它直接报错

用 Go 的 text/template 渲染配置、邮件或通知时，map 少了一个键，默认行为往往不是失败，而是继续把空值写进结果。要让必填键缺失时立即暴露，关键配置只有一个：在模板构造阶段设置 Option("missingkey=error")，并始终检查 Execute 返回的错误。

必填字段使用 missingkey=error；可选字段先在进入模板前补齐，避免把“允许为空”和“拼写错误”混在一起。

先看清三种缺省行为的差别

text/template 的点语法会把 map 键当作索引。例如模板中的 {{.email}} 读取 map[string]any 的 email 键。键不存在时，missingkey 决定模板继续、返回零值，还是把执行变成错误。

这里最容易误判的是 zero。如果 map 的值类型是 string，缺键得到空字符串；如果值类型是 int，得到 0；如果是 any，零值是 nil，打印时仍可能看到 。所以“没有报错”不等于“数据完整”。

在模板构造阶段打开严格模式

把策略放在创建模板的链式调用中，能让模板的行为和它的定义放在一起。示例只演示必填的 name 和 email，数据缺少 email 时，错误会从 Execute 返回。

package main

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

func main() {
    // 把必填键的缺失交给 Execute 返回错误。
    tmpl, err := template.New("mail").
        Option("missingkey=error").
        Parse("收件人：{{.name}}，邮箱：{{.email}}")
    if err != nil {
        log.Fatal(err) // 模板语法错误在 Parse 阶段处理。
    }

    data := map[string]any{"name": "林舟"} // 故意缺少 email。
    var output bytes.Buffer
    err = tmpl.Execute(&output, data) // 缺键会让执行返回错误。
    if err != nil {
        log.Printf("模板渲染失败：%v", err)
        return
    }
    log.Print(output.String()) // 只有 Execute 成功才使用结果。
}

Option 接受字符串参数，未知选项会触发 panic，因此选项名应写成固定常量或集中配置。实际业务里不要把 Execute 的错误吞掉，也不要只依据 output.Len() 判断成功；写入器可能已经得到部分内容，但这不能抵消模板执行失败。

把缺键当成配置错误处理

严格模式的价值不只是打印一条错误，而是把错误边界推回渲染调用方。调用方可以记录模板名和业务上下文，再决定返回接口错误、跳过通知，或触发重试。Execute 返回的通常是带模板信息的执行错误，保留原始 error 比重新拼接字符串更可靠。

如果调用方需要区分执行错误，可以使用 errors.As 提取 template.ExecError；如果只是记录和返回，直接包装原错误即可。Parse 失败与 Execute 失败也要分开处理：前者说明模板本身不能构造，后者说明当前数据不满足模板约定。

可选字段不要和必填字段共用同一假设

严格模式会让 {{if .email}} 这类对缺失键的访问也暴露错误，它不会自动理解“这个字段是可选的”。因此，模板执行前应先归一化输入，把可选键显式放进去：

data := map[string]any{
    "name":  user.Name,  // 必填字段由业务对象提供。
    "email": user.Email, // 可选字段缺省时使用空字符串。
}

// 模板仍使用 missingkey=error，新增字段漏传时会尽早失败。

另一种做法是按职责拆分模板：配置类模板启用严格模式，允许稀疏数据的展示模板在进入渲染层前完成默认值填充。不要为了兼容一个可选字段，把所有模板退回默认策略。

常见问题

missingkey=error 应该放在 Parse 前吗？

推荐放在 New 后、Parse 前，模板策略更清晰；核心要求是模板执行前已经设置该选项。

map 的键拼错会在编译时发现吗？

不会。模板字符串和运行时数据分离，键是否存在要到执行阶段才能判断，严格模式能把这类错误及时变成 Execute 返回值。

什么时候用 missingkey=zero？

只有当业务明确把“缺失”和“类型零值”视为同一含义时才用；否则优先使用严格模式并在输入层补齐可选字段。