FuncMap 是 map[string]interface{}，用于将导出函数映射为模板可调用名称；必须在 Parse 前通过 Funcs() 注册，函数需首字母大写、签名严格匹配（如 func(string) string），不支持匿名函数、闭包或类型自动转换。
FuncMap 是什么，为什么不能直接在模板里调用自定义函数
Go 的 template 包默认只提供有限的内置函数（如 print、len、eq），所有自定义逻辑必须通过 FuncMap 显式注入。不注入就调用，运行时会 panic：function "xxx" not defined —— 这不是语法错误，而是模板执行期找不到函数的 runtime 错误。
关键点在于：FuncMap 是一个 map[string]interface{}，键是模板中使用的函数名，值是 Go 函数（签名必须符合模板引擎约束）。
- 函数必须是可导出的（首字母大写），否则
reflect无法访问 - 参数和返回值类型受限：只支持基本类型、指针、切片、map、struct，且不能有多个返回值（除非最后一个为
error） - 注入必须在调用
Parse或ParseFiles之前完成，之后修改FuncMap不生效
如何正确构造和注入 FuncMap
最常见错误是把函数定义写在模板解析之后，或用了匿名函数导致不可反射。正确做法是先声明函数变量（或定义命名函数），再构造成 map 注入。
例如，想在模板中用 add 做加法：
立即学习“go语言免费学习笔记（深入）”；
func add(a, b int) int {
return a + b
}
funcMap := template.FuncMap{
"add": add, // 注意：这里必须是函数名，不是调用 add()
}
tmpl := template.New("test").Funcs(funcMap)
tmpl, _ = tmpl.Parse("{{add 1 2}}") // 输出：3
- 不要写成
"add": add(1,2)（这是调用，不是函数值） - 如果函数带
error返回，模板会自动检查并中止渲染（比如html.EscapeString就是这种签名） - 多个函数可以一次性注入，
Funcs支持链式调用：tmpl.Funcs(fm1).Funcs(fm2)
常见陷阱：参数类型不匹配与 panic 场景
模板传参时不做类型转换，函数签名必须严格匹配。比如定义了 func formatTime(t time.Time) string，但模板里传的是字符串 {{formatTime "2024-01-01"}}，就会 panic：can't call method on string。
- 安全做法：在函数内部做类型断言或使用
interface{}+ 类型判断，但代价是失去编译期检查 - 更推荐：用不同函数名区分，比如
formatTime和formatTimeStr，各自处理明确类型 - nil 指针传入会导致 panic，尤其在
struct字段为 nil 时调用方法 —— 模板不会帮你做空判断 - 注意闭包捕获变量：若在循环中构造函数并注入，容易所有函数共享同一个变量（常见于动态生成函数名场景）
FuncMap 跨模板复用与作用域限制
FuncMap 绑定在 *template.Template 实例上，不是全局注册。这意味着 template.New("a").Funcs(fm) 和 template.New("b").Funcs(fm) 是两个独立实例，互不影响。
- 若需多模板共享，建议封装一个工厂函数，统一注入：
newTemplate(name string) *template.Template - 子模板（
{{template "sub" .}}）继承父模板的FuncMap，无需重复注入 - 使用
template.Must包裹Parse可提前暴露函数未定义类错误，避免运行时才发现 - FuncMap 中的函数无法访问模板上下文以外的状态（比如 HTTP request），如需，得靠闭包捕获，但要注意 goroutine 安全和内存泄漏
真正麻烦的不是注入本身，而是函数签名和模板传参之间的隐式契约 —— 一旦不匹配，错误只在渲染那一刻爆发，且堆栈不指向模板行号。调试时最好在函数入口加 fmt.Printf 或用 recover 捕获 panic 并打印当前数据。
