Go text/template.Option 怎样设置缺失键行为

Go 模板访问 map 中不存在的键时，行为由 Template.Option 的 missingkey 选项决定。新代码通常应在模板执行前明确选择 missingkey=error、missingkey=zero 或默认策略，避免把缺字段的结果悄悄写进邮件、配置文件或页面。

官方地址：https://pkg.go.dev/text/template#Template.Option

最实用的判断是：允许字段缺失就保留默认策略，需要稳定零值就选 zero，缺字段必须阻止提交就选 error。无论选择哪种模式，都要检查 Execute 返回的错误。

升级范围：只改变缺失键的处理方式

Template.Option 接收一个或多个逗号分隔的选项字符串。本文只关注 missingkey，它主要影响模板通过键访问 map 时找不到元素的情况，不会替你校验业务字段是否完整，也不会改变模板语法解析规则。

这里的“升级”不是把所有模板都机械改成报错，而是把原本隐含的缺失键策略写成显式配置，再根据调用方是否能接受不完整结果做选择。

旧写法风险：默认结果可能掩盖数据契约缺口

旧代码常见的写法是直接解析模板并执行，不单独声明缺失键策略。它的优点是兼容已有模板，风险是调用方可能只看到一个成功生成的字符串，却不知道某个字段根本没有传入。

package main

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

func main() {
    // 模板读取 map 中不存在的 subject 键，用来说明默认策略的边界。
    tmpl := template.Must(template.New("mail").Parse("主题：{{.subject}}"))
    data := map[string]string{"body": "服务将在今晚维护"}
    var out bytes.Buffer

    // Execute 的错误仍然要检查，不能只根据 out.String() 是否非空判断成功。
    if err := tmpl.Execute(&out, data); err != nil {
        fmt.Println("模板执行失败：", err)
        return
    }
    fmt.Println(out.String())
}

如果旧模板确实把缺失字段当成可选内容，这种写法可以保留；但如果输出会直接进入外部通知或配置发布，就应该把“缺字段是否允许继续”提升为显式决策。

新写法：在 Execute 前选择三种策略

最小迁移动作是在创建模板或解析模板时调用 Option。选项要在执行前设置，并且应与该模板的数据契约放在一起，避免不同调用点各自采用不同默认值。

package main

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

func render(mode string) error {
    // 把缺失键策略作为模板构造参数，便于迁移时集中比较行为。
    tmpl, err := template.New("config").Option("missingkey=" + mode).Parse("host={{.host}}")
    if err != nil {
        return err
    }

    data := map[string]string{"port": "8080"}
    var out bytes.Buffer
    // error 模式会让 Execute 返回错误；提交前必须先检查它。
    if err := tmpl.Execute(&out, data); err != nil {
        return fmt.Errorf("execute template: %w", err)
    }
    fmt.Printf("%s -> %q\n", mode, out.String())
    return nil
}

func main() {
    // 三种模式对应不同的数据完整性要求，而不是三种排错等级。
    for _, mode := range []string{"default", "zero", "error"} {
        if err := render(mode); err != nil {
            fmt.Println(mode, "模板未提交：", err)
        }
    }
}

迁移到 error 时，要特别注意 Execute 可能已经向目标 io.Writer 写入了一部分内容后才返回错误。因此不要把同一个缓冲区直接当作最终文件或响应提交；先写入临时缓冲区，成功后再转交下游。

回归检查：确认升级没有改变可选字段语义

把默认策略改成显式配置后，建议至少覆盖下面四类数据。它们能帮助你区分“字段确实可选”和“调用方漏传字段”这两种完全不同的问题。

1. 完整数据：所有模板键都有值，三种策略都应正常生成结果。
2. 缺失字符串键：分别观察默认、零值和报错模式，确认调用方的预期与配置一致。
3. 空值与缺失：显式传入空字符串不等于没有键，测试时不要把两者混成一类。
4. 部分输出：执行失败时丢弃临时缓冲区，不要把已经写出的片段作为成功响应。

如果模板用于配置发布或账单生成，推荐使用 missingkey=error 并把错误连同模板名称记录下来；如果模板用于可选展示字段，zero 更容易让输出保持稳定。默认策略适合兼容旧行为，但不应成为没有数据契约时的长期替代品。

常见问题

missingkey=error 是解析阶段报错吗？

不是。它针对模板执行时的数据访问；模板语法本身仍由 Parse 检查，缺失 map 键通常要到 Execute 结合实际数据时才暴露。

为什么传入空字符串还不算缺失键？

空字符串是已经存在的值，缺失键则是 map 中没有对应元素。若业务需要把空字符串也视为无效，应在模板执行前做数据校验，不能只依赖 missingkey。