模板无法直接获取URL查询参数,必须在handler中用c.Query()或c.DefaultQuery()显式提取并传入c.HTML()的数据结构,如gin.H{"username": c.DefaultQuery("username", "guest")},模板中才能通过{{ .username }}安全访问。

模板里拿不到 URL 查询参数,得靠后端传
Gin 的 HTML 模板(html/template)本身没有访问 HTTP 请求上下文的能力,c.Query("xxx") 这类方法只能在 handler 函数里调用。模板渲染时,请求早已结束,它只接收你显式传入的数据。直接在 {{ .QueryParam }} 里试图读取 query 是无效的——Go 模板不会自动注入请求参数。
常见错误现象:{{ .username }} 渲染为空,但你在浏览器地址栏明明写了 ?username=alice;或者模板里写 {{ $.Query "username" }},结果报错 function "Query" not defined。
- 必须在 handler 中显式调用
c.Query("username")或c.DefaultQuery("username", "guest")取值 - 把结果作为字段塞进传给
c.HTML()的数据结构里,比如gin.H{"username": username} - 模板中只能通过
{{ .username }}访问这个字段,不能反向从 URL 解析
如何安全传参:避免空值和 XSS
直接把 c.Query("q") 塞进模板可能引发两个问题:一是参数缺失时返回空字符串,导致模板逻辑断裂;二是用户输入未转义,造成 XSS。别依赖前端传什么就信什么。
- 优先用
c.DefaultQuery("q", "")或c.DefaultQuery("q", "all")提供 fallback,防止.q在模板中为 nil 导致 panic - 如果参数要插入 HTML 属性或 JS 字符串,务必用 Go 模板的自动转义机制:
{{ .q }}是安全的,但{{ .q | safeHTML }}或{{ .q | js }}要慎用 - 对搜索关键词这类敏感字段,建议额外做长度截断或正则过滤,比如只允许字母、数字、空格、短横线:
regexp.MustCompile(`[^a-zA-Z0-9\s\-]`).ReplaceAllString(q, "")
带数组参数的场景怎么处理
当 URL 是 /search?tag=go&tag=web&tag=api 这种多值 query 时,模板没法直接展开 range,因为 c.Query("tag") 只返回第一个值。必须用 c.QueryArray("tag") 显式获取切片。
- handler 中:
tags := c.QueryArray("tag"),然后传入gin.H{"tags": tags} - 模板中:
{{ range .tags }}{{ . }}{{ end }}才能正确遍历 - 注意:
c.GetQueryArray("tag")返回([]string, bool),适合需要判断参数是否存在的情况 - 如果前端传的是
?filter[status]=active&filter[role]=admin这类嵌套格式,Gin 不原生支持解析成 map,得手动拆解或改用c.ShouldBindQuery(&struct{})
为什么不用中间件统一注入?
有人想写个中间件自动把所有 query 参数塞进模板上下文,比如 c.Set("query", c.Request.URL.Query()),再在模板里用 {{ .query.Get "page" }}。这看似省事,但实际埋了坑:
-
url.Values是map[string][]string,模板里.query.Get调用会失败(Go 模板不支持方法链式调用) - 中间件注入后,所有模板都带冗余数据,容易混淆真实业务字段,比如
.page和.query.page含义重叠 - URL 参数常需校验、转换(如
page转成 int),这些逻辑放在 handler 更清晰可控,模板只负责展示 - 性能上无优势:一次
c.Query是 O(1),反复从 map 查不如直接传已处理好的值
真正容易被忽略的是:query 参数名和模板字段名不一致时,没人检查拼写错误。比如 handler 传了 "user_name",模板却写 {{ .username }},静默失败。建议在 struct 绑定或 gin.H 字面量里用明确 key,必要时加注释。











