直接实现 render.render 接口无法安全替换 gin 默认 html 渲染器，因为 gin 内部硬编码依赖未导出的 *gin.htmlrender 类型断言，且要求结构体必须包含签名正确的 instance() 方法用于模板克隆，缺失或不符即 panic。
直接实现 render.Render 接口无法安全替换 Gin 的默认 HTML 渲染器，因为 Gin 内部硬编码依赖未导出的 *gin.htmlRender 类型断言，且要求结构体必须包含 Instance() 方法用于模板克隆 —— 缺失或签名不符会立刻 panic。
为什么 c.SetHTMLRender() 传入自定义结构体会 panic
Gin 在初始化 HTML 渲染路径时，会做类型断言：if r, ok := render.(interface{ Instance() render.Render }); ok。但真正被接受的只有 *gin.htmlRender（小写首字母，未导出），它内部封装了 template.Template 和克隆逻辑。你实现的结构体哪怕也叫 HTMLRender，只要没嵌入原生类型或没按完全一致的字段签名构造，就会触发：panic: interface conversion: render.Render is not *gin.htmlRender: missing method Instance。
- 错误现象：启动时报 panic，堆栈指向
c.HTML()调用前的渲染器初始化阶段 - 根本原因：Gin 不是靠接口匹配，而是靠具体指针类型匹配 + 方法存在性双重校验
- 安全做法：要么用
gin.HTMLRender原生类型并调用其Clone()，要么彻底绕过c.SetHTMLRender()，改用中间件 +c.Render()手动控制流程
想统一注入用户/配置变量？别碰 Render 接口，用中间件 + c.Render()
不需要重写整个渲染器就能实现「每次渲染都自动带 user、siteName 等通用数据」。最稳的方式是在路由处理前把数据塞进 c.Keys，再在 c.Render() 前合并：
- 注册中间件：
r.Use(func(c *gin.Context) { c.Set("user", getCurrentUser(c)); c.Next() }) - 渲染时手动合并：
c.Render(http.StatusOK, gin.HTML{Template: t, Name: "index.tmpl"}, merge(gin.H{"title": "Home"}, c.Keys)) - 避免陷阱：不要在
Render()方法里直接修改传入的data map[string]interface{}，它可能被复用；每次都新建 map 并 copy - 性能影响：一次 map copy 开销极小，远低于模板解析本身，无需过度优化
需要多模板/继承/不同目录结构？用 gin-contrib/multitemplate
原生 LoadHTMLGlob() 只支持单个 template.Template 实例，无法处理 base.html + home.html 这类块继承结构。这时应引入社区成熟方案：
- 安装：
go get -u github.com/gin-contrib/multitemplate - 关键点：它不是替换
Render接口，而是实现了render.HTMLRender接口，并在Instance()中返回新multitemplate.Renderer实例，完美绕过 Gin 的类型检查 - 模板组织示例：
renderer.AddFromDir("admin", "./templates/admin/*")，然后c.HTML(200, "admin/dashboard.tmpl", data) - 注意路径：它不自动处理
{{ template "header" . }}的跨目录引用，base.html必须和子模板在同一个AddFromDir()范围内，或显式AddFromFiles()加载全部
PureJSON 渲染 HTML 字符串时不转义？别用 JSON，换 PureJSON
当后端返回含 HTML 标签的字符串（如富文本内容），用 c.JSON() 会导致 <p></p> 变成 \u003cp\u003e —— 这是 Go json 包默认开启 escapeHTML 的结果。修复方式极简单：
- 改用
c.PureJSON(http.StatusOK, data)，它底层调用json.Encoder且显式设SetEscapeHTML(false) - 对比差异：
c.JSON()→{"content":"<b>hello</b>"}；c.PureJSON()→{"content":"<b>hello</b>"} - 风险提示：仅当确认前端已做 XSS 过滤或内容可信时才用
PureJSON；否则应在前端用DOMPurify等库净化 - 不推荐自己封装：别写
json.NewEncoder(w).SetEscapeHTML(false)，容易漏掉 header 设置或 error 处理
真正难的不是实现接口，而是理解 Gin 在哪一层做了隐式绑定 —— 它的 HTML 渲染链路从 SetHTMLRender 到 c.HTML 再到最终 template.Execute，中间穿插了至少三次类型断言和克隆操作。跳过其中任意一环，都可能让程序在某个看似无关的请求里突然崩溃。
