json.Encoder 输出 HTML 字符的转义边界与处理方案

Go 的 encoding/json.Encoder 默认会把 JSON 字符串中的 、> 和 & 转成 Unicode 转义，另外处理 U+2028、U+2029。这个行为适合把 JSON 放进 HTML 的 标签；如果输出只是普通 API 响应、日志或文件，转义后的结果可能不利于阅读。处理方法不是修改字符串，而是在创建 Encoder 后按输出边界调用 SetEscapeHTML(false)。

默认输出为什么看起来像变成了 Unicode 转义

假设接口返回一段带标签的文本：

type Payload struct {
    // Text 保留用户输入，编码阶段不在这里做字符串替换。
    Text string `json:"text"`
}

payload := Payload{Text: "Go & 文本"}

把它交给默认的 Encoder 后，JSON 字符串中的尖括号和连字符会以 \u003c、\u003e、\u0026 表示。它仍然是合法 JSON，解码后文本也能还原；变化发生在“序列化后的字节”这一层，而不是 Go 字符串本身。

用 SetEscapeHTML(false) 保留可读字符

普通 JSON API 通常不需要把内容放进 HTML 脚本块，可以把开关放在这个 Encoder 实例上：

var buf bytes.Buffer
enc := json.NewEncoder(&buf)
// 非 HTML 嵌入场景优先保留原字符，方便日志、文件和接口调试阅读。
enc.SetEscapeHTML(false)
if err := enc.Encode(payload); err != nil {
    // 编码失败时不要把不完整的 buf 当成成功响应。
    return err
}
fmt.Print(buf.String())

这时 Text 字段会更接近原始内容，例如 "Go & 文本"。Encode 仍会在整个 JSON 值后追加换行，这是流式编码器的行为；如果协议不接受尾部换行，需要在边界层明确处理，而不是把 HTML 转义开关当成格式化开关。

这个开关的边界：编码可读性不等于上下文安全

SetEscapeHTML(false) 只影响 Encoder 写出的 JSON 字符串。它不会给 HTML 模板自动加安全转义，也不会替代 JavaScript 字符串编码、URL 编码、CSP 或响应头配置。尤其不要先关闭转义，再把 JSON 字节直接拼进页面代码；如果数据要进入浏览器上下文，应让模板引擎或专门的序列化方案承担对应上下文的编码。

还要注意它只作用于当前 Encoder。项目中同时存在 API 响应和页面初始化数据时，建议在各自的输出函数里创建 Encoder，避免共享一个已经修改过的实例，让配置意外跨请求或跨场景传播。

发布前用四项检查固定行为

1. 确认输入是合法 UTF-8 字符串，并记录接口实际的输出上下文。
2. 为含有 、>、& 的样例写断言，不要只断言没有报错。
3. 检查 Content-Type 是否为预期的 application/json，并确认没有把 JSON 字节拼入 HTML。
4. 如果调用了 SetEscapeHTML(false)，在代码旁说明“普通 JSON 输出”这一前提，后续迁移时再复核。

var got bytes.Buffer
enc := json.NewEncoder(&got)
// 断言关闭转义只改变 JSON 文本表示，不改变字段值语义。
enc.SetEscapeHTML(false)
if err := enc.Encode(Payload{Text: " &"}); err != nil {
    t.Fatal(err)
}
if !strings.Contains(got.String(), `" &"`) {
    t.Fatalf("unexpected JSON: %s", got.String())
}

常见问题

SetEscapeHTML(false) 会关闭 JSON 的引号和反斜杠转义吗？

不会。它针对 HTML 相关字符；JSON 语法本身需要的引号、反斜杠等转义仍由编码器处理。

json.Marshal 能直接关闭 HTML 转义吗？

不能通过 Marshal 参数切换。需要创建 Encoder，设置开关后写入目标；如果只拿到字节切片，应重新审视输出边界，而不是手工替换转义串。

关闭转义后浏览器一定不安全吗？

不能这样推断。风险取决于 JSON 被放入的上下文；普通 JSON 响应与直接嵌入脚本不是同一种边界，关键是不要把一套策略混用。

参考：https://pkg.go.dev/encoding/json#Encoder.SetEscapeHTML、https://pkg.go.dev/encoding/json#HTMLEscape