gin模板变量访问错误主因是作用域混淆和点号误用：.随嵌套动态变化，$.始终指向根对象，$var为局部变量；结构体字段须导出；空值需用with或if防护；管道函数类型必须严格匹配。
模板里变量访问出错，八成是作用域或点号用错了——不是数据没传，而是你没找对位置。
`.`, `$.`, `$var` 三个点号的区别必须分清
在 Gin 模板中，. 不是万能的“当前上下文”，它会随嵌套结构动态变化：
-
.在顶层模板中指向gin.H{}或结构体传入的根对象；进入{{range}}后，.就变成当前循环项（比如切片里的一个字符串或结构体） -
$.name才是始终指向根对象的name字段，哪怕你在五层range里也要用$.name访问最外层数据 -
$var := .field是局部变量赋值，只在当前{{if}}、{{range}}块内有效；变量名必须以$开头，且不能重名（$i和$v是常见安全命名）
错误示例：{{range .items}}<p>{{.title}}</p>
<p>{{.name}}</p>{{end}} —— 如果 .items 是 []string，.title 就会报 can't evaluate field title；正确写法是先确认 .items 类型，或改用 $.name 访问外部字段。
结构体字段必须导出，否则模板里看不到
Go 的模板机制依赖反射，只能访问首字母大写的导出字段。如果你传了一个结构体：
type User struct {
Name string // ✅ 可见
email string // ❌ 模板里读不到
Age int // ✅ 可见
}
即使你用 gin.H{"user": User{email: "a@b.c"}} 传过去，{{.user.email}} 也永远为空。这不是 Gin 的限制，是 Go 语言反射规则本身决定的。
- 调试技巧：在模板里加
{{printf "%#v" .user}}查看实际可见字段 - 临时绕过：用 map 替代结构体，如
gin.H{"user": gin.H{"name": "x", "email": "y"}}
空值和 nil 处理容易 panic
模板里直接写 {{.data.field}} 很危险——如果 .data 是 nil，或者 .data 是 map 但 key 不存在，Gin 会直接返回 500 错误，报 can't evaluate field field 或 nil pointer dereference。
- 安全写法用
{{with .data}}{{.field}}{{end}}，with会自动跳过nil或空值 - 判断是否存在用
{{if .data.field}}前，先确保.data非空；更稳妥的是{{if and .data .data.field}} - 数组/切片判空别只写
{{if .list}}，要写{{if .list}}...{{else}}无数据{{end}}或配合{{range}}的{{else}}分支
尤其注意：Go 模板里 nil 和空字符串 ""、零值 0、空切片 []int(nil) 都算 “empty”，但 map[string]int(nil) 也是 empty，而 map[string]int{} 是非 empty。
函数管道（pipeline）不是万能的，类型必须匹配
{{.Time | formatTime "2006-01-02"}} 看起来很顺，但一旦 .Time 是 string 而不是 time.Time，就会在运行时报 can't apply formatTime to string。
- 内置函数如
len、print、html对类型有隐含要求：len只接受 slice/map/array/string；html输入必须是 string - 自定义函数注册后，务必在文档里写明入参类型，调用前用
{{if .Time}}做兜底，避免 pipeline 中途断裂 - 调试技巧：把 pipeline 拆开写，比如先
{{printf "%#v" .Time}}看类型，再加| formatTime
最常被忽略的一点：模板函数执行顺序是从左到右，但每个函数的返回值类型必须严格匹配下一个函数的输入要求——这不像代码里可以强制类型转换，模板里没有 (int64).String() 这种操作。
