Go text/template 怎样自定义函数并传递错误

我在把业务校验塞进 Go 模板时，最容易踩的坑不是函数怎么写，而是注册时机和错误怎么回到调用方。稳定做法是：先用 template.FuncMap 声明函数，在 Parse 前调用 Funcs 注册；函数返回一个值，或者返回“值加 error”。当 error 非 nil 时，Execute 会停止执行并把错误交给外层。

先把函数注册在 Parse 之前

模板解析阶段需要知道函数名是否存在，所以不要先 Parse、后补 FuncMap。下面的例子把用户名校验放进 checkName，成功返回规范化文本，失败返回业务错误。

package main

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

var ErrInvalidName = errors.New("用户名不符合要求")

func checkName(name string) (string, error) {
    // 先裁剪输入，避免模板层把空白误当成有效名称。
    name = strings.TrimSpace(name)
    if name == "" {
        return "", ErrInvalidName
    }
    return name, nil
}

func main() {
    funcs := template.FuncMap{
        "checkName": checkName,
    }
    // 解析前注册函数，模板解析器才能识别 {{checkName .Name}}。
    tmpl, err := template.New("welcome").Funcs(funcs).Parse("欢迎，{{checkName .Name}}")
    if err != nil {
        panic(err)
    }

    var buf bytes.Buffer
    // 先写入缓冲区，避免执行失败时把半成品直接发给用户。
    if err := tmpl.Execute(&buf, map[string]string{"Name": "Go 开发者"}); err != nil {
        fmt.Printf("渲染失败: %v\\n", err)
        return
    }
    fmt.Println(buf.String())
}

这里的顺序有两个好处：解析错误和执行错误分开处理；函数名拼错时会在模板解析阶段尽早暴露，而不是等到请求已经开始渲染才发现。

让业务错误完整回到调用方

FuncMap 中的函数可以只返回一个值，也可以返回两个值，第二个值必须是 error。只要这个错误不为 nil，模板执行就会中止。建议用包级哨兵错误或自定义错误承载稳定的判断条件，再由调用方用 errors.Is 或 errors.As 分类处理。

type NameError struct {
    Value string
}

func (e *NameError) Error() string {
    // 错误信息用于日志，分类判断应优先使用类型或哨兵错误。
    return "无效名称: " + e.Value
}

func checkName(name string) (string, error) {
    // 业务规则放在函数内部，模板只负责组合展示文本。
    name = strings.TrimSpace(name)
    if len([]rune(name)) 

不要只比较完整错误字符串。Execute 返回的错误会带着模板执行上下文，底层业务错误仍应通过 errors.Is 或 errors.As 查找。

输出缓冲和函数签名的检查清单

如果模板内容很短，直接写入 http.ResponseWriter 也许问题不大；但只要结果要整体通过校验、审计或缓存，缓冲区就是更稳妥的提交边界。另一个边界是并发：模板构造和修改 FuncMap 不要与执行并行，构造完成后，已准备好的模板才适合被多个请求并发执行。

相关问题

函数能不能在 Parse 之后再新增？

被模板引用的函数应在 Parse 前注册。Parse 后可以通过 Funcs 替换已有函数，例如克隆模板后切换实现，但不能把解析阶段不存在的名字当成正常补注册。

为什么函数返回 error 后模板没有继续输出？

这是 text/template 的设计：第二返回值为非 nil 时，执行停止，Execute 返回该错误。由于写出可能已经发生，调用方应把结果先放入缓冲区。

什么时候只返回一个字符串就够了？

当函数只做确定性的格式化且没有业务失败分支时可以只返回一个值；涉及权限、状态或输入校验时，返回 error 能让调用方明确处理失败。

参考文档：https://pkg.go.dev/text/template