Golang HTML/Template包的管道操作符_链式处理数据技巧

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"，比翻文档更快定位问题。