Go text/template 如何给模板提供自定义函数

Go 的 text/template 默认只提供内置函数。要在模板里调用自己的函数，关键不是把函数写在 Go 文件里，而是把它放进 template.FuncMap，并且在第一次 Parse、ParseFiles 或 ParseGlob 之前完成绑定。顺序错误时，模板会在解析阶段报“未定义函数”；函数签名或返回值不合适，则会在注册或执行阶段暴露问题。

先用 FuncMap 把函数名接到模板

模板只认识注册时的名字，不认识 Go 代码里的函数名。下面的例子把 upper 暴露给模板，并在解析前完成绑定：

package main

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

func main() {
    const source = `标题：{{ upper .Title }}`

    // FuncMap 的键是模板中实际调用的函数名。
    funcs := template.FuncMap{
        "upper": func(s string) string {
            // 只做展示层转换，不在模板函数里修改业务数据。
            return strings.ToUpper(s)
        },
    }

    // 必须先 Funcs，再 Parse；解析器此时才能识别 upper。
    tmpl, err := template.New("page").Funcs(funcs).Parse(source)
    if err != nil {
        // 模板通常在启动阶段加载，解析失败应直接暴露。
        panic(err)
    }
    if err := tmpl.Execute(os.Stdout, map[string]string{"Title": "go template"}); err != nil {
        // Execute 错误不能只记录后继续返回半成品响应。
        panic(err)
    }
}

这里的链式调用等价于先创建模板、再调用 Funcs、最后 Parse。函数名最好短而明确，避免把数据库查询、网络请求或带副作用的动作直接塞进模板层。

函数签名和错误返回要提前定好

FuncMap 的值必须是函数。函数可以返回一个值，也可以返回两个值且第二个值必须是 error。第二种形式适合日期格式化、数据转换等可能失败的操作：

func formatPrice(cents int64) (string, error) {
    // 先拒绝不符合业务边界的金额，避免模板生成误导性文本。
    if cents 

上面的片段需要补充 fmt 和 text/template 导入。若 formatPrice 返回错误，Execute 会停止并返回包装后的执行错误；调用方应把它当作渲染失败处理，而不是继续发送不完整页面。

生产环境的初始化顺序怎么检查

模板通常在程序启动时加载，建议把函数表和模板加载封装成一个构造函数，让错误在服务接收请求前暴露：

如果使用 ParseFiles 或 ParseGlob，顺序完全相同：先在返回的模板对象上调用 Funcs，再加载文件。解析完成后不要在并发请求中随意改写函数表；需要不同函数集合时，创建独立模板实例。

常见问题

为什么 FuncMap 注册了，Parse 还是提示函数不存在？

最常见原因是先调用了 Parse，或实际解析的是另一个模板对象。把创建、Funcs 和 Parse 放在同一段初始化代码里，并检查模板文件是否被重新解析。

模板函数能不能直接访问数据库？

技术上可以通过闭包做到，但不建议把不可预测的 I/O 放在渲染表达式里。先在业务层准备数据，模板函数只负责格式化和简单判断，更容易限时、测试和审计。

已经 Parse 完还能调用 Funcs 吗？

可以覆盖已有函数，但新增函数不能依赖已经完成的解析结果。为了让模板源码和函数集合一一对应，生产代码仍应固定为先 Funcs、后 Parse。