Go text/template FuncMap 的模板函数注入

在 Go text/template 中注入自定义函数，核心就是把函数放进 template.FuncMap，再在模板解析前调用 Funcs。这样模板里的函数名才会被识别，执行阶段会按函数签名传参；如果函数返回非空错误，Execute 会停止并把错误交给调用方。

官方地址：https://pkg.go.dev/text/template

最稳的写法是：先准备 FuncMap，再调用 New(...).Funcs(funcMap).Parse(...)，最后 Execute。不要等 Parse 完成后才首次注册模板中要使用的函数。

FuncMap 必须在 Parse 前注册

FuncMap 的键是模板中使用的函数名，值是对应的 Go 函数。Funcs 会把这些函数加入模板函数表，而模板解析器需要在 Parse 时就知道函数名是否存在，所以“注册、解析、执行”应该保持这个顺序。

package main

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

type ViewData struct {
	Name string
	Role string
}

func main() {
	// 键名必须和模板里的函数名一致，值是允许模板调用的 Go 函数。
	funcMap := template.FuncMap{
		"upper": strings.ToUpper,
		"label": func(role string) string {
			return "角色：" + role
		},
	}

	// 先注入 FuncMap，再 Parse；解析器才能识别 upper 和 label。
	tmpl, err := template.New("profile").
		Funcs(funcMap).
		Parse("姓名：{{upper .Name}}，{{label .Role}}")
	if err != nil {
		// 解析错误通常来自模板语法或函数名，不能继续执行半成品模板。
		panic(err)
	}

	var out bytes.Buffer
	// Execute 只负责把数据应用到已经解析好的模板，并把输出写入 Buffer。
	if err := tmpl.Execute(&out, ViewData{Name: "Lin", Role: "开发者"}); err != nil {
		panic(err)
	}
	fmt.Println(out.String())
}

如果把 Funcs 放到 Parse 之后，模板第一次解析时可能直接报“函数未定义”。这不是执行数据为空，而是模板构建顺序不对。函数名也要使用可作为模板标识符的名称，不能把带空格或不合法符号的字符串当作函数名。

用单返回值函数完成最小注入

最简单的模板函数接收一个或多个参数，返回一个值。模板调用时不需要写 Go 的括号，参数直接跟在函数名后面；模板中的字段、常量和前一个管道结果，都可以成为函数参数。

func renderProfile(data ViewData) (string, error) {
	// 单返回值函数适合格式化、拼接或把输入转换成展示文本。
	funcMap := template.FuncMap{
		"badge": func(role string) string {
			if role == "" {
				// 空值返回统一的展示文本，避免模板出现空标签。
				return "未设置角色"
			}
			return "【" + role + "】"
		},
	}

	// 模板参数 .Role 会按函数声明的 string 类型传入 badge。
	tmpl, err := template.New("profile").Funcs(funcMap).Parse("{{.Name}} {{badge .Role}}")
	if err != nil {
		return "", fmt.Errorf("解析模板：%w", err)
	}

	var out bytes.Buffer
	// 继续向上返回 Execute 错误，调用方可以决定是否重试或记录日志。
	if err := tmpl.Execute(&out, data); err != nil {
		return "", fmt.Errorf("执行模板：%w", err)
	}
	return out.String(), nil
}

这里的关键不是把所有业务逻辑都塞进模板函数，而是只注入模板确实需要的展示动作。函数越小，参数类型和输出边界越容易维护；需要访问数据库、修改全局状态或执行副作用的逻辑，不适合直接作为模板函数暴露。

函数签名与 Execute 错误边界

FuncMap 中的函数必须满足两种返回形式之一：只返回一个值，或者返回两个值且第二个值的类型是 error。第二种形式很适合把“模板无法继续完成”的原因返回给调用方；当第二个返回值为非 nil 时，模板执行会终止。

func lookupLabel(role string) (string, error) {
	// 返回值加 error 让模板可以把无法识别的业务值交给 Execute 处理。
	switch role {
	case "研发":
		return "研发团队", nil
	case "运营":
		return "运营团队", nil
	default:
		return "", fmt.Errorf("未知角色 %q", role)
	}
}

func renderWithError(role string) error {
	funcMap := template.FuncMap{
		"label": lookupLabel,
	}

	// 只要模板会调用 label，就必须在 Parse 前将它放入 FuncMap。
	tmpl, err := template.New("role").Funcs(funcMap).Parse("团队：{{label .Role}}")
	if err != nil {
		return fmt.Errorf("解析模板：%w", err)
	}

	var out bytes.Buffer
	// role 不在允许范围时，label 返回的 error 会沿 Execute 返回。
	if err := tmpl.Execute(&out, map[string]string{"Role": role}); err != nil {
		return fmt.Errorf("执行模板：%w", err)
	}
	fmt.Println(out.String())
	return nil
}

不要只在模板外层判断输出字符串是否为空来代替错误处理。业务函数已经知道失败原因时，直接返回 error 更清楚；调用方也能区分模板解析失败、数据字段不匹配和自定义函数主动返回的错误。

用管道组合参数并理解可赋值规则

模板函数的实参必须能够赋值给 Go 函数的参数类型。类型不匹配时，错误通常在执行阶段出现。管道的规则也很重要：前一个命令的结果会作为下一个函数的最后一个参数，所以函数声明要按这个位置设计。

func renderPipeline(data ViewData) (string, error) {
	funcMap := template.FuncMap{
		// 管道结果会作为最后一个参数传入 joinLabel。
		"joinLabel": func(prefix, value string) string {
			return prefix + "：" + value
		},
		"upper": strings.ToUpper,
	}

	// "角色" 是显式参数，.Role 经过 upper 后成为最后一个管道参数。
	tmpl, err := template.New("pipeline").Funcs(funcMap).Parse(
		"{{joinLabel \"成员\" (.Role | upper)}}",
	)
	if err != nil {
		return "", fmt.Errorf("解析管道模板：%w", err)
	}

	var out bytes.Buffer
	// 数据字段类型和函数参数保持 string，才能稳定完成执行。
	if err := tmpl.Execute(&out, data); err != nil {
		return "", fmt.Errorf("执行管道模板：%w", err)
	}
	return out.String(), nil
}

排查模板函数不生效时，可以按三个位置看：函数名是否真的在 FuncMap 中、Parse 是否发生在注入之后、执行时的实参类型是否与函数签名可赋值。如果函数返回两值，第二值还必须是 error，否则 Funcs 会拒绝这个函数。

解析后替换同名函数的适用场景

Funcs 不只可以在解析前调用。官方文档还允许在模板已经解析后，用同名函数替换旧实现；替换后的函数会在执行时生效。这个能力适合在模板结构固定时切换展示策略，但首次注册仍应放在解析前。

func renderWithReplacement(data ViewData) (string, error) {
	// 先提供一个可解析的函数，确保模板中的名字在 Parse 时存在。
	tmpl, err := template.New("replace").Funcs(template.FuncMap{
		"label": func(role string) string {
			return "旧标签：" + role
		},
	}).Parse("{{label .Role}}")
	if err != nil {
		return "", fmt.Errorf("解析模板：%w", err)
	}

	// 同名函数替换影响后续 Execute，不会改变已经解析好的模板结构。
	tmpl.Funcs(template.FuncMap{
		"label": func(role string) string {
			return "新标签：" + role
		},
	})

	var out bytes.Buffer
	// 模板构建完成后再并发执行时，不要继续修改共享模板的函数表。
	if err := tmpl.Execute(&out, data); err != nil {
		return "", fmt.Errorf("执行模板：%w", err)
	}
	return out.String(), nil
}

如果多个请求共享同一个模板实例，建议在应用初始化阶段完成函数表配置，之后只并发执行；不要一边执行一边替换函数。需要 HTML 输出时，优先考虑 html/template，它与 text/template 接口相近，但会针对 HTML 输出提供自动转义。

结论与常见问题

template.FuncMap 的使用顺序可以固定成一条配方：准备函数映射、在 Parse 前调用 Funcs、解析模板、执行并处理错误。单返回值函数适合简单转换；值加 error 的函数能让 Execute 及时停止；参数需要满足可赋值规则，管道结果会落到下一个函数的最后一个参数。

为什么模板里写了函数名，Parse 还是报未定义？

最常见原因是函数没有放进 FuncMap，或者调用 Funcs 的时机晚于 Parse。先构造函数映射，再链式调用 template.New(...).Funcs(funcMap).Parse(...)。

FuncMap 中的函数能不能返回两个普通值？

不能。模板函数只支持单个返回值，或两个返回值且第二个必须是 error。两个普通值不符合模板函数约定，应改成一个结构体或其他单值结果。

函数返回 error 后，模板还会继续输出吗？

不会继续正常执行。只要第二个返回值是非 nil 的 error，执行会停止并由 Execute 返回错误；调用方仍应考虑此前已经写入 Writer 的部分输出。

注册后的函数表可以在并发执行时修改吗？

不建议这样做。模板解析和构建阶段应先完成函数表配置，模板准备好后可以安全并发执行；如果确实要替换同名函数，应在没有并发执行的初始化或切换阶段完成。