不用html/template而选text/template，是因为配置文件、CLI输出等场景无需XSS防护和自动转义，其安全机制反成负担且性能开销大；text/template更轻量，适合纯字符串替换。
为什么不用 html/template 而要自己写？
因为你要渲染的不是 HTML 页面，而是配置文件、CLI 输出、日志模板或 API 响应体——这些场景不需要转义、不涉及 XSS 防御，html/template 的安全机制反而成了负担，且性能开销明显。Go 自带的 text/template 更合适，但它默认仍启用部分上下文感知（比如对 url 函数的特殊处理），而轻量级模块的核心诉求是：纯字符串替换 + 零副作用 + 显式可控。
text/template 的最小可用封装要点
直接用 template.New + Parse + Execute 是可行的，但容易踩三个坑：
-
template.New的名字只是内部标识，和文件名/路径无关；若重复用相同名字调用多次，第二次会 panic：template: xxx is defined more than once - 未显式设置
FuncMap时，index、len等基础函数不可用，报错：function "index" not defined - 模板字符串含非法语法（如漏掉
{{或多出}}）时，Parse不报错，但Execute才 panic，调试成本高
建议封装成一个函数，强制校验：
func Render(tmplStr string, data interface{}) (string, error) {
t := template.New("").Funcs(template.FuncMap{
"lower": strings.ToLower,
"upper": strings.ToUpper,
"join": strings.Join,
})
t, err := t.Parse(tmplStr)
if err != nil {
return "", fmt.Errorf("parse template: %w", err)
}
var buf strings.Builder
err = t.Execute(&buf, data)
if err != nil {
return "", fmt.Errorf("execute template: %w", err)
}
return buf.String(), nil
}
如何支持嵌套结构体与 map 混合访问？
Go 模板天然支持 .Field、.MapKey、.Slice.0 这类链式访问，但有个关键限制：字段必须是导出的（首字母大写）。如果传入的是 map[string]interface{}，里面嵌套了 struct，而 struct 字段是小写，那模板里取不到值，也不会报错，只会静默输出空字符串。
立即学习“go语言免费学习笔记（深入）”；
解决方式只有两个：
- 确保所有被模板访问的字段都是导出字段（最简单，也最推荐）
- 改用
mapstructure或自定义MarshalJSON把私有字段转成 map 再传入（增加序列化开销，仅在无法改结构体时考虑）
另外注意：range 遍历 map 无序，不要依赖顺序；遍历 slice 时用 $index, $value := range .Items，避免误把索引当值。
模板缓存与并发安全怎么做？
*template.Template 是并发安全的，但 Parse 不是——不能在多个 goroutine 中同时对同一个模板对象调用 Parse。所以常见错误是每次请求都 template.Must(template.New("").Parse(...))，既浪费 CPU 又丢失复用优势。
正确做法是预编译并缓存：
- 启动时一次性
Parse所有已知模板字符串，存进sync.Map或全局 map（key 为模板名） - 若模板来自用户输入（如 API 动态传入），需加限流 + 编译超时（用
context.WithTimeout包裹Parse），否则恶意模板可能触发无限循环或栈溢出 - 避免用
template.Must在运行时——它 panic，不适合动态场景
轻量级不等于“不设防”，模板即代码，动态解析必须带边界控制。
