Go text/template 怎样在模板中注册带错误返回值的函数

Go 的 text/template 支持直接注册返回 (T, error) 的函数：先把函数放入 FuncMap，调用 Funcs 注册，再 Parse 模板。执行时第二个返回值为 nil，模板继续使用第一个值；第二个返回值非 nil，当前执行立即失败，错误交给 Execute 的调用方。模板里不需要、也不能照搬 Go 的双变量错误接收写法。

让模板中的业务规则可以失败

设想一个任务状态导出：数据包含任务名称和内部状态码，模板通过函数把状态码转成可读文本。已知状态可以展示，未知状态意味着导出数据不符合约定。如果简单返回空串，整份报告看起来可能成功，却丢失了关键字段；返回 error 可以让调用方拒绝交付这次报告。

这是一组原创示例场景，不是生产故障复盘。下面先说明返回签名和注册时机，再给出完整写法。相关语义依据 官方 FuncMap 文档和 Execute 文档；本例未执行本地测试，文中的结果均为按规则推导的预期。

先确认返回签名与注册时机

FuncMap 本质上是函数名称到 Go 函数值的映射。普通模板函数应有一个返回值，或两个返回值且第二个类型恰为 error。此处 T 可以是 string、数值或其他模板可继续使用的类型。零返回值、三个返回值、第二个值为 bool 的函数，不满足这套返回契约。不要把执行阶段的业务失败，与注册阶段的错误签名混为一谈。

新名称必须在 Parse 之前加入。解析后可以替换已有同名函数，但这不应被当作并发请求期间热改配置的手段；初始化时完成构造更清楚。Parse 不会因为注册了函数就预先执行它，也无法替代运行时的数据判断。本文谈的是服务端 Go 模板能力，不存在浏览器支持矩阵。

把失败留给 Go 调用层

下例保留一个明确的领域错误 ErrUnknownState。stateLabel 只负责转换和判断，Render 负责模板初始化及输出边界，调用方再通过 errors.Is 区分错误原因。模板文本是受信任的程序常量，业务数据通过 Execute 参数传入，而不是拼进模板源码。

package main

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

// ErrUnknownState 表示数据含有本导出格式不认识的状态。
var ErrUnknownState = errors.New("未知任务状态")

type Task struct {
    Name string
    State string
}

func stateLabel(state string) (string, error) {
    switch state {
    case "ready":
        return "待处理", nil
    case "done":
        return "已完成", nil
    default:
        // 错误文本不附带完整业务数据，保留可识别的原因。
        return "", ErrUnknownState
    }
}

func Render(task Task) (string, error) {
    // 函数必须在模板文本被解析前注册。
    funcs := template.FuncMap{"stateLabel": stateLabel}
    t, err := template.New("task-report").Funcs(funcs).
        Parse("任务={{.Name}}；状态={{stateLabel .State}}")
    if err != nil {
        return "", fmt.Errorf("解析报告模板: %w", err)
    }

    // 先写到本次调用独占的缓冲区，失败时不交付半成品。
    var buf bytes.Buffer
    if err := t.Execute(&buf, task); err != nil {
        return "", fmt.Errorf("生成任务报告: %w", err)
    }
    return buf.String(), nil
}

func main() {
    text, err := Render(Task{Name: "库存核对", State: "archived"})
    if errors.Is(err, ErrUnknownState) {
        // 调用方决定业务反馈，不把半成品当报告输出。
        fmt.Println("报告未生成：状态不受支持")
        return
    }
    if err != nil {
        fmt.Println("报告未生成")
        return
    }
    fmt.Println(text)
}

这组输入的 archived 不在允许列表中，预期走“状态不受支持”分支。把 State 改为 done，预期 Render 返回“任务=库存核对；状态=已完成”。失败时 Render 返回空串和非 nil 错误，模板已经写入缓冲区的名称前缀不会被当成最终报告交付。这不是回滚：只是没有把缓冲内容发布到外部。

函数原始错误会被模板执行错误包裹，Render 又以 %w 包裹一次，因此不应使用 err == ErrUnknownState 判断。这里使用 errors.Is 沿错误链查找原因；如果要读取 template.ExecError 的模板名称等信息，可按其实际值类型使用 errors.As。需要注意，底层 Writer 的写入错误与模板计算错误并非同一种失败，不能假设所有 Execute 返回错误都一定是 ExecError。

模板也可以写成 {{.State | stateLabel}}，管道结果作为后一个命令的最后一个参数。无论直接调用还是管道，非 nil error 都会中止当前执行；在后面再接一个“默认值函数”，无法捕获前面已经发生的执行错误。

旧模板兼容应放在数据准备层

如果旧报告允许状态字段缺省，应先明确“字段为空”和“状态非法”是不是同一含义。可选字段可以在数据准备层变成“未提供”，而非空但未知的值仍可返回错误。不要为了兼容而把所有异常变成空串，更不要让模板中的每个位置分别决定同一状态的默认含义。

同理，模板的 missingkey 选项处理的是 map 取值缺失时的策略，不会自动改变自定义函数的 error 返回行为。业务结构体字段、map 键缺失、函数参数类型不匹配，应分别处理。对所有无法正确生成的情况，调用层都检查 Execute 的错误；对允许降级的情况，在执行前生成明确的展示数据。

如果后续把结果写入 HTTP 响应，先渲染成功再写正文，可以避免模板计算失败时已提交业务正文或状态码。若最终网络写入本身失败，仍可能只传出部分字节；bytes.Buffer 不能把网络发送变成事务。保存文件同样要另行设计临时文件、关闭错误和替换策略，不能把“缓冲渲染成功”解释为“文件保存成功”。

避免副作用与错误输出泄露

模板函数更适合只读、短时、可重复的格式转换。不要让它边渲染边扣库存、写数据库或触发外部动作：中途失败时，已经发生的副作用不会因 Execute 返回 error 而撤销。缓冲方案也要考虑输出规模；大报表不应无上限占用内存，应限制输入记录数或使用有容量限制的输出设计。

示例把模板构造放在 Render 中是为了集中展示注册顺序。实际高频调用可以初始化一次、完成构造后共享执行，但每次应使用独立的 Writer 或缓冲区，注册函数捕获的共享状态也必须符合并发要求。不要在正在执行时修改 FuncMap 配置和模板结构。

text/template 不会自动进行 HTML 上下文转义。输出纯文本报告可以使用它；生成浏览器页面应考虑 html/template 的上下文转义机制。两者都不是用来执行任意不受信任模板的安全沙箱，尤其不能把能够访问文件、网络或敏感对象的函数暴露给不受信任的模板作者。对外反馈使用受控业务提示，完整执行错误按日志脱敏规则保留，不直接把内部模板细节返回给终端用户。

模板能用两个变量接收值和错误吗？

不能照搬 Go 的 value, err := fn()。模板引擎对第二个 error 有专门处理；需要局部降级时，先在 Go 层决定展示值。

函数返回空字符串和 nil 算失败吗？

不算。空字符串是合法结果，是否允许应由你的函数契约明确决定。

为什么注册成功，执行时仍会报错？

注册确认的是名称与函数返回签名等要求；实际参数、数据状态和 Writer 都要到执行时才能参与计算和输出。

可维护的写法是：把带错误返回的函数在解析前注册，把错误留在 Go 调用链里，把最终输出放到渲染成功之后交付。这三点比在模板中层层拼接兜底逻辑更容易保持一致。