Go template 的 pipeline 是值传递流而非链式调用，每个函数接收上游结果作为第一个参数，类型必须严格匹配，否则 panic；应优先在 Go 层预处理、用 with 安全访问、自定义函数首参设 interface{} 并做断言、safeHTML 必须置于 pipeline 末尾。
Go template 里 pipeline 不是函数调用链，而是值传递流
很多人写 {{ .Name | title | upper }} 以为它像 JS 的 .map().filter() 那样“链式调用”，其实不是——pipeline 是从左到右把前一个结果作为**第一个参数**传给后一个函数。比如 title 接收字符串，upper 也接收字符串，所以能串；但一旦中间产出的是 int，后面接 lower 就直接 panic：executing "xxx" at <.id lower>: error calling lower: interface conversion: interface {} is int, not string</.id>。
实操建议：
-
pipeline每个环节的输入类型必须匹配函数签名，查文档看func(string) string还是func(interface{}) string - 自定义函数返回
interface{}时，下游函数得自己做类型断言，模板里做不到 - 别依赖
pipeline做复杂逻辑，该在 Go 层预处理就预处理，模板只负责展示
内置函数 index 和 slice 在 pipeline 中容易越界或 panic
index 取 map 或 slice 元素、slice 截取字符串/slice，看着简单，但在 pipeline 里出错不报具体位置，只说 error calling index: cannot index type interface{} 或更模糊的 panic: runtime error: index out of range。
常见错误现象：
立即学习“go语言免费学习笔记（深入）”；
-
{{ .Items | index 0 | title }}—— 如果.Items是 nil slice，index直接 panic，不会静默返回空 -
{{ .Text | slice 0 10 }}—— 如果.Text长度不足 10，会 panic，不是截到末尾 -
{{ .Data | index "user" | index "name" }}—— 中间任意一层为 nil 或非 map 类型，立刻崩
实操建议：
- 用
with包一层再操作：{{ with index .Items 0 }}{{ . | title }}{{ end }} - 字符串截取优先用自定义安全函数，比如
safeSlice .Text 0 10，内部做长度判断 - 避免多层
index嵌套，结构深就提前在 handler 里解包成扁平字段
自定义函数参与 pipeline 时，参数顺序和接收方式常被忽略
注册自定义函数时，比如 tpl.Funcs(template.FuncMap{"add": func(a, b int) int { return a + b }})，在 pipeline 里写 {{ .A | add .B }} 是对的，但写成 {{ add .A .B }} 就不是 pipeline 了——前者是 .A 传给 add 当第一个参数，.B 当第二个；后者是普通函数调用，不走 pipeline 流程。
容易踩的坑：
- 函数定义是
func(string, int) string，却在 pipeline 里只传一个值：{{ .Str | format }}→ 缺少int参数，模板编译失败 - 想让函数接收整个 pipeline 上游结果 + 额外参数，但忘了 Go 函数参数顺序固定，
pipeline只能塞第一个 - 函数返回
error，但模板不处理，panic 时堆栈不显示函数名，难定位
实操建议：
- 所有自定义函数，第一个参数尽量设为
interface{}，内部用类型断言，提高 pipeline 兼容性 - 需要多个动态参数？改用
map[string]interface{}打包传入，比如{{ .Data | format (dict "width" 80 "align" "left") }} - 函数内尽早检查输入，
if v, ok := val.(string); !ok { return "" }，别让 panic 穿透到模板层
HTML 自动转义与 pipeline 的交互很隐蔽
template.HTML 类型能绕过自动转义，但它和 pipeline 组合时容易失效。比如 {{ .RawHTML | safeHTML }} 看起来没问题，但如果 .RawHTML 是 string 类型，safeHTML 返回的仍是 string，不是 template.HTML，浏览器照样当纯文本渲染。
关键点在于：safeHTML 函数本身只是把 string 转成 template.HTML，但它必须是 pipeline 的**最终输出**，且上游不能有其他函数把它又转回 string（比如再接个 lower）。
实操建议：
- 确保
safeHTML是 pipeline 最后一环：{{ .RawHTML | safeHTML }}✅，{{ .RawHTML | safeHTML | upper }}❌（upper返回string） - 不要在 Go 层用
fmt.Sprintf拼 HTML 后塞进模板，那只是 string；要用template.HTML(...)显式转换 - 调试时打印
printf "%T" .RawHTML，确认类型是template.HTML而非string
真正麻烦的从来不是语法怎么写，而是 pipeline 每一步的类型和生命周期都藏在运行时，而错误信息又极其简陋。多打几个 printf "%T"，比翻文档更快定位问题。
