Go 的 html/template 会根据插值所在的 HTML、属性、URL 等上下文处理普通数据。可信模板搭配不可信字符串是它的基本使用方式；template.HTML 等类型则表示调用者主动提供可信内容，不会替你清洗输入。模板函数一旦返回这些类型，也承担同样的信任责任。

我在本文中选择一个检索结果页作为设计示例：名称只显示为文字，检索参数进入固定链接，状态标记来自代码内固定片段。这不是一次新版本发布或线上事故记录，而是对标准库用法的取舍说明。官方文档：https://pkg.go.dev/html/template；信任模型说明：https://go.dev/src/html/template/doc.go。

我把示例收窄到一个检索结果页

设计这个例子时，我不想先造一个“任何字符串都能变成 HTML”的工具。这样的工具看起来省事，实际却把每个调用点变成信任判断点。这里需要的功能只有三项：显示标题与名称、拼出检索参数、选择一个状态标记。

因此我把页面结构保留在应用维护的 pageSource 中，PageData 只带 Title、Name、Query 和 Status。即使名称看起来像标签，也先把它当作用户希望展示的文字，而不是页面结构。这种限制少了一点自由，却让输入来自哪里、最终应扮演什么角色更容易说清。

如果允许外部用户提供模板源码，问题就变了。html/template 假定模板作者可信，不是用于执行任意不可信模板的隔离沙箱。不要把用户字符串拼进源码后再 Parse，指望它和通过 Execute 传入数据具有相同边界。

同一段文字为什么会有不同的转义

我最看重的不是“把尖括号换成实体”这一个动作，而是插值所在位置的含义。名称位于段落文本中时，应作为文本表达；同一名称位于 title 属性中时，还要服从属性的语法；Query 位于固定 href 的查询参数位置，又是另外一类上下文。

所以没有必要先对所有数据统一做一次 HTMLEscapeString 再传模板。提前处理容易让本来该展示的字符再次被转义，也把调用者和模板引擎的责任混在一起。我的选择是保留普通字符串，让模板根据最终位置处理，而不是手工拼一整段 HTML。

模板仍要写成清晰、可分析的结构。示例使用固定属性名与引号包围的属性值，不让数据决定标签名、属性名或整段脚本。自动转义不等于业务许可：链接是否允许跳往某个站点，仍需应用自己决定。

保留字符串数据，给固定标记一个小出口

下面是完整的 main.go。示例只输出 HTML 文本，不启动服务，也不声称已经在本机或浏览器中运行。名称中的 strong 标签是用于观察文本处理的合成内容，不代表真实用户输入。

package main

import (
    "bytes"
    "fmt"
    "html/template"
    "os"
    "strings"
)

// 模板源码由应用维护，外部数据只进入字段
const pageSource = `

{{trim .Title}}
{{.Name}}
继续检索
{{badge .Status}}

`

type PageData struct {
    Title string
    Name string
    Query string
    Status string
}

func badge(status string) template.HTML {
    // 只选择固定标记，不拼接status或其他外部字符串
    switch status {
    case "ready":
        return template.HTML("已准备")
    default:
        return template.HTML("待处理")
    }
}

func render(data PageData) ([]byte, error) {
    funcs := template.FuncMap{
        "trim": strings.TrimSpace, // 返回普通string，仍交给上下文转义
        "badge": badge,
    }
    t, err := template.New("search").Funcs(funcs).Parse(pageSource)
    if err != nil { return nil, fmt.Errorf("parse page: %w", err) }

    // 先写缓冲区，执行失败时不交付半份页面
    var buf bytes.Buffer
    if err := t.Execute(&buf, data); err != nil {
        return nil, fmt.Errorf("execute page: %w", err)
    }
    return buf.Bytes(), nil
}

func main() {
    data := PageData{
        Title: "  文档检索  ",
        Name: "Lin & Co",
        Query: "go & templates",
        Status: "ready",
    }
    page, err := render(data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    // 示例只输出HTML文本，不启动浏览器或HTTP服务
    if _, err := os.Stdout.Write(page); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

按模板语义推导，Title 的前后空格会被 trim 去掉；Name 中看起来像标签的内容应作为文字展示，而不是把名称加粗。Query 的空格与连接符应按所在 URL 查询位置处理。badge 返回的固定 strong 片段则作为 HTML 标记表达“已准备”。这些是预期，不是实测输出记录。

我把 Execute 的结果先写进 bytes.Buffer，是为了在出错时不向调用方交付半份页面。迁移到 HTTP Handler 时，也应先处理渲染错误，再设置适当响应头和写入正文；不要在执行失败后仍把残留缓冲区当成功页面发送。

模板函数的返回类型也是信任声明

trim 接收字符串、返回字符串，只做空白清理，没有改变数据的信任等级。badge 的返回类型却是 template.HTML；它之所以在这个例子里可控，是因为只按状态选择两个完全固定的字面量，不把 Status 拼进标签、属性或文字片段。

这也是我不愿提供通用 safeHTML 函数的原因。把任意字符串强转为 template.HTML，含义不是“检查过并清洗好了”，而是“我保证它适合按可信 HTML 使用”。函数封装得越短，这份保证也不会凭空消失。

如果状态标记不需要由 Go 函数返回 HTML，我更倾向在可信模板里用条件分支选择固定标签，数据仍保持字符串。这里保留 badge，是为了让可信片段的来源具体可追溯，而不是推荐把所有界面片段搬进函数。

template.HTML、template.URL、template.JS 等类型各有自己的上下文语义，不是通用“关闭安全处理”按钮。不能因为某段数据在一个位置看起来可用，就把同一可信类型随意搬到其他位置；更不应该用强转来消除模板报错。

从拼接 HTML 迁移时，我会保留哪些限制

输出 HTML 时应使用 html/template，而不是只换一个包名却保留原来的字符串拼接逻辑。text/template 适合一般文本，并不自动提供这里需要的 HTML 上下文处理。对于外部提交的富文本，自动转义会把它作为文字；如果业务必须保留一部分标签，需要另外定义可信的清洗策略与允许范围，不在本文里临时写一个正则当清洗器。

URL 也值得单独看。示例把路由固定为 /search，只让 Query 填一个参数；它没有实现外链、重定向或域名允许列表。若以后改成完整 URL 输入，就要增加协议、目的地与业务权限约束。不能将模板对 URL 的处理解释为“所有能输出的链接都已获业务授权”。

哪些页面适合这套做法

对由应用维护模板的服务端页面，我会优先采用普通字符串数据加上下文转义。对允许用户编写模板、运行自定义逻辑的平台，或者需要接收任意富文本的编辑器，这套小示例还不够，不能把它当成完整隔离或清洗方案。

我的结论是把可信类型的入口保持得少而明确：多数模板函数返回普通类型；确需可信片段时，能指出片段由谁生成、包含什么、为什么适用于当前位置。自动转义负责输出表达，业务负责决定什么内容有资格被信任。

为什么名称里的标签没有生效？

因为 Name 是普通字符串，模板按文本位置处理它。若需求只是显示名称，这是正确行为，不应该为了让标签生效而直接强转。

能否把所有模板函数返回值都改成 template.HTML？

不应该。普通格式化函数没有理由声明输出可信 HTML。只有明确适合对应上下文、且来源可控的内容，才应考虑这种类型。

看到 ZgotmplZ 应该怎么处理？

它可能是模板对不适合 URL 或 CSS 等上下文内容的过滤标记，应回到字段来源和模板位置判断原因，而不是立刻转成可信类型绕过处理。相关含义与错误请查官方文档。

具体规则可查 上下文说明、HTML 类型文档及 Go 官方信任模型源码注释。