Go html/template URLQuery 如何安全拼查询参数

在搜索页里把关键词拼进 href，最容易踩的坑不是少写一个问号，而是把“查询值转义”和“完整 URL 信任”混在一起。使用 html/template 时，普通字符串放进带引号的 URI 属性，模板会按上下文做 URL 与属性转义；多个参数则应先用 url.Values 构造查询串。

先分清 html/template 里的 URLQuery 到底指什么

搜索“Go html/template URLQuery”时，实际可能指三件事：模板 URI 上下文的自动转义、template.URLQueryEscaper 这个单值辅助函数，以及 url.Values.Encode() 生成完整查询串。它们的输入边界不同。

模板 href 里的单个关键词交给上下文转义

如果页面只需要一个搜索词，保持数据类型为普通 string，模板写成带引号的属性即可。不要把用户输入先转成 template.URL，也不要在新模板里手工叠加旧式 urlquery 管道。

package main

import (
    "html/template"
    "log"
    "os"
)

func main() {
    // 让普通字符串进入 href，由 html/template 根据 URI 属性上下文转义。
    const page = `搜索`
    data := struct {
        Keyword string
    }{Keyword: "Go 并发 & 超时"}

    // 解析阶段建立上下文，执行阶段只提供不可信数据。
    tmpl := template.Must(template.New("search").Parse(page))
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        // 输出失败要返回错误，避免把半截 HTML 当成完整响应。
        log.Fatal(err)
    }
}

这里的关键是属性值有引号，并且数据没有被包装成安全类型。模板会把空格、中文和 & 等字符编码到 URL 属性可接受的形式；浏览器读取链接时再按 URL 规则解释它们。图中的“模板 URI 边界”表示这个静态关系，不是某次运行的截图。

多个参数用 url.Values 统一编码

当链接同时包含关键词、页码和筛选项，直接写 "?q=" + q + "&page=" + page 会把编码责任分散到每个字段，重复键、空值和特殊字符都容易处理不一致。更稳的做法是先在 Go 代码中组装查询值，再把结果作为普通字符串交给模板。

package main

import (
    "html/template"
    "net/url"
    "os"
)

type SearchPage struct {
    Query string
}

func main() {
    values := url.Values{}
    // Set 表示单值键；Add 可用于保留多个同名标签。
    values.Set("q", "Go & URLQuery")
    values.Set("page", "2")
    values.Add("tag", "模板")
    values.Add("tag", "安全")

    // Query 是完整查询串，不是可信 URL；模板仍应按属性上下文处理它。
    data := SearchPage{Query: values.Encode()}
    tmpl := template.Must(template.New("search").Parse(
        `下一页`,
    ))
    // Execute 的错误必须向上返回，不能静默忽略响应写入失败。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

Encode() 会按键排序并对每个值编码，重复的 tag 也会保留。输出中的 & 在 HTML 属性里通常会显示为 & 的源码实体形式，但浏览器解析后仍是参数分隔符；不要为了“看起来像 URL”再手动替换实体。

URLQueryEscaper 只处理单值，不负责整条链接

template.URLQueryEscaper 适合已经明确知道“这里是一项查询值”的场景，例如给自定义模板函数准备一个值。它返回的是适合嵌入查询的转义文本，不应拿来包住 https:// 完整地址，更不应把不可信结果转换成 template.URL 以逃避上下文检查。

escaped := template.URLQueryEscaper(keyword)
// escaped 只能作为查询值使用；多个键值对仍应交给 url.Values.Encode。

新代码优先让 html/template 根据出现位置自动处理。只有在边界非常清楚、并且调用方确实需要单值编码时，才显式使用这个辅助函数；重复编码会让服务端收到不同于用户原意的值。

发布前用五项检查确认安全边界

• 数据类型保持普通 string，没有把用户输入声明为 template.HTML 或 template.URL。
• 模板属性使用引号，查询串中的多个参数由 url.Values 生成。
• 没有把已经编码的值再次调用编码函数，也没有手动替换 &。
• 外部跳转地址与站内查询链接分开处理；查询参数不能改变固定的路径和协议。
• 用包含空格、中文、&、+ 和重复键的输入做结果检查，确认服务端解析到预期值。

相关问题

html/template 里还能写 urlquery 吗？

历史模板可能仍允许它作为管道末端，但新模板应优先依赖上下文自动转义，避免重复编码和上下文不匹配。

为什么输出源码里出现了 &？

这是 HTML 属性对 & 的实体表示，浏览器解析后仍会把它作为查询参数分隔符。

什么时候才可以使用 template.URL？

只有完整 URL 来自已信任、已约束的来源，并且确实需要保留其安全类型时才考虑；用户可控查询值不属于这个范围。