Go text/template missingkey=error 如何尽早暴露字段拼写错误：执行阶段、零值与测试验收

配置页面上线后，最难排查的一类问题是“模板成功渲染了，但某个字段悄悄空了”。Go 的 text/template 默认允许 map 中不存在的键继续执行，这让 .UserNmae 这类拼写错误可能直到用户看到空白页面才暴露。把模板设置为 missingkey=error 后，错误会在 Execute 阶段返回，测试可以直接把它拦下来。

先做一个会“静默成功”的模板

下面的示例故意把 UserName 写成 UserNmae。数据是 map[string]any，模板解析本身没有办法提前知道这个键是否存在：

package main

import (
    "os"
    "text/template"
)

func main() {
    const source = "用户：{{.UserNmae}}"
    data := map[string]any{"UserName": "Lin"}

    tmpl, err := template.New("profile").Parse(source)
    if err != nil {
        panic(err)
    }
    _ = tmpl.Execute(os.Stdout, data)
}

这个程序可以完成 Parse，执行结果却不是预期的“用户：Lin”。问题不在解析器，而在执行时查找 map 键的策略。

把 missingkey=error 放在模板创建阶段

Option 要在执行前配置到模板上。最小改动是：

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

err = tmpl.Execute(os.Stdout, data)
if err != nil {
    // 这里能拿到字段缺失导致的执行错误
    panic(err)
}

这里的关键顺序是 New、Option、Parse、Execute。missingkey=error 不会把一个拼写错误变成 Parse 错误；模板语法合法时，错误仍会沿着 Execute 返回。把 Execute 的错误丢弃掉，等于又把保护机制关掉了。

用测试把“成功输出”和“缺失错误”分开验收

实际项目里不要依赖标准输出做判断，使用 bytes.Buffer 接收渲染结果更容易测试。一个小型测试函数可以同时覆盖两条路径：

func render(source string, data map[string]any) (string, error) {
    tmpl, err := template.New("profile").
        Option("missingkey=error").
        Parse(source)
    if err != nil {
        return "", err
    }

    var out bytes.Buffer
    err = tmpl.Execute(&out, data)
    return out.String(), err
}

func TestRender(t *testing.T) {
    got, err := render("用户：{{.UserName}}", map[string]any{"UserName": "Lin"})
    if err != nil || got != "用户：Lin" {
        t.Fatalf("success path: got %q, err %v", got, err)
    }

    _, err = render("用户：{{.UserNmae}}", map[string]any{"UserName": "Lin"})
    if err == nil {
        t.Fatal("missing map key should return an Execute error")
    }
}

验收点有两个：正确字段必须产生完整字符串，错误字段必须产生非空错误。若生产代码还需要输出部分结果，应明确记录这个错误，不要把“有一部分 HTML”误当成渲染成功。

几个边界别混在一起

• map 键和 struct 字段不同。 missingkey 主要解决 map 查找为空的行为；struct 字段拼写错误通常在模板解析阶段就会报错。
• Parse 成功不是数据验收成功。 模板字符串和运行时数据是两个阶段，必须保留 Execute 错误。
• text/template 不负责 HTML 转义。 输出 HTML 时应评估 html/template，不能仅靠 missingkey=error 解决注入风险。

常见问题

missingkey=error 会让 Parse 直接失败吗？

不一定。对 map 键来说，模板语法合法时通常仍能 Parse，缺失键会在 Execute 期间返回错误。

为什么 Execute 返回错误后 Buffer 里还有内容？

模板可能已经写出前面的静态文本或已成功解析的字段，错误只说明本次渲染没有完整完成，不能把部分内容当作最终结果。

正确字段也要设置 missingkey=error 吗？

建议统一设置。这样数据结构变更或字段拼写回归时，测试会尽早失败，而不是把空字符串传播到页面。

把检查留在渲染边界

如果模板来自代码仓库，推荐在创建模板时统一调用 Option("missingkey=error")，并让每个 Execute 都返回错误。这样 Parse 负责语法，Execute 负责数据和输出，测试则分别验收成功结果与失败信号。这个边界清楚后，字段改名不再靠线上空白页面提醒。