Go text/template 自定义函数怎么在执行前注册

在 Go 的 text/template 里调用自定义函数，关键顺序是：先准备 template.FuncMap，再调用 Funcs，最后 Parse 模板。也就是说，模板中出现的 upper、formatDate 等函数名，必须在解析阶段已经注册；等到 Execute 前才注册，通常已经晚了。

为什么一定要在 Parse 前调用 Funcs

Parse 不只是保存字符串，它还要把模板动作解析成模板树。遇到 {{ upper .Name }} 时，解析器需要知道 upper 是一个可调用的模板函数。因此最小写法是把注册动作链在解析动作之前：

package main

import (
    "fmt"
    "os"
    "strings"
    "text/template"
)

func main() {
    const source = `姓名：{{ upper .Name }}`

    // 先声明模板会用到的函数名，再进入 Parse。
    funcs := template.FuncMap{
        "upper": strings.ToUpper,
    }

    // New、Funcs、Parse 的顺序保证解析器能找到 upper。
    tmpl, err := template.New("user").Funcs(funcs).Parse(source)
    if err != nil {
        fmt.Println("模板解析失败：", err)
        return
    }

    // Execute 只负责把数据交给已经解析好的模板。
    if err := tmpl.Execute(os.Stdout, map[string]string{"Name": "gopher"}); err != nil {
        fmt.Println("模板执行失败：", err)
    }
}

如果把 Funcs 移到 Parse 后面，常见结果是 template: user: function "upper" not defined。这是解析错误，不是数据为空，也不是 Execute 没有传入正确的 map。

函数签名和覆盖规则要一起检查

template.FuncMap 的值必须是函数。函数可以只有一个返回值，也可以返回两个值，其中第二个必须是 error。模板执行时，第二种写法一旦返回非 nil 错误，执行会停止并把错误交给调用方。

例如，函数返回错误时不要只在函数内部打印日志，否则模板调用方无法决定是否中止响应：

func formatCode(s string) (string, error) {
    // 空字符串直接交给 Execute 处理，避免输出一个看似成功的占位值。
    if strings.TrimSpace(s) == "" {
        return "", fmt.Errorf("code 不能为空")
    }
    return "[" + s + "]", nil
}

tmpl, err := template.New("code").Funcs(template.FuncMap{
    "formatCode": formatCode,
}).Parse(`{{ formatCode .Code }}`) // 注册先于解析
if err != nil {
    return err
}
return tmpl.Execute(os.Stdout, map[string]string{"Code": "go"})

用管道传参并在 Execute 时处理错误

注册完成后，函数可以像内置函数一样放进管道。管道左侧结果会作为后续函数的最后一个参数，适合把“取值、转换、格式化”拆成短链：

const source = `{{ .Name | upper | quote }}`

func quote(s string) string {
    // 只负责演示输出边界；真实项目可替换为明确的编码策略。
    return `"` + s + `"`
}

tmpl, err := template.New("user").Funcs(template.FuncMap{
    "upper": strings.ToUpper,
    "quote": quote,
}).Parse(source)
if err != nil {
    return err // Parse 错误通常来自语法或未注册函数
}
if err := tmpl.Execute(os.Stdout, map[string]string{"Name": "go"}); err != nil {
    return err // Execute 错误可能来自函数返回的 error 或 Writer
}

这里的 upper 和 quote 都在解析前加入；模板执行只处理数据和运行期错误。若输出 HTML，应优先评估 html/template 的自动转义语义，而不是把不可信文本直接交给 text/template。

解析后只做同名替换，不把它当成首次注册

官方文档允许在模板解析后再次调用 Funcs，但用途是替换已经存在的同名函数。例如先用测试实现解析模板，再替换成正式实现；或者先 Clone 一个公共模板，再为变体覆盖函数。

tmpl, err := template.New("price").Funcs(template.FuncMap{
    "currency": func(v int) string { return fmt.Sprintf("￥%d", v) },
}).Parse(`{{ currency . }}`)
if err != nil {
    return err
}

// 同名替换发生在解析完成后，不能借此首次引入模板中不存在的函数。
tmpl.Funcs(template.FuncMap{
    "currency": func(v int) string { return fmt.Sprintf("CNY %d", v) },
})

模板构造阶段不要并发修改同一个模板集合；构造完成后，官方文档允许并发执行，但多个执行若共享同一个 io.Writer，输出仍可能互相交错。

常见问题

Funcs 一定只能调用一次吗？

不是。它可以多次调用；解析前用于补齐函数，解析后可替换同名函数。

函数返回两个普通值可以吗？

不可以。双返回值的第二个必须是 error，否则不符合 FuncMap 的函数约束。

模板函数报错应该在 Parse 还是 Execute 处理？

未注册函数和模板语法问题在 Parse 处理；函数运行中返回的错误以及 Writer 错误在 Execute 处理。