Go json.Encoder.SetEscapeHTML 为什么会改变字符串输出

如果 Go 接口返回的字符串里有 、> 或 &，你可能会看到它们变成 \\u003c、\\u003e、\\u0026。这通常不是原始数据被改写，而是 encoding/json 的默认 HTML 安全转义。需要保留可读的符号时，使用 json.NewEncoder 创建编码器，再调用 SetEscapeHTML(false)。

这篇只讨论字符串输出的差异：默认策略适合可能嵌入 HTML 的 JSON；纯接口、配置文件或日志等非 HTML 场景，可以按协议要求关闭转义。

先看默认输出和关闭转义后的差异

把同一个结构交给两个独立的编码器，比较的是 JSON 文本，不是 Go 字符串本身。下面的代码只用于说明编码关系，示例中的结果是静态示意。

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
)

func main() {
    value := map[string]string{"html": "
 & ready"}

    // 默认开启 HTML 转义，适合可能嵌入 HTML 的 JSON 文本。
    var escaped bytes.Buffer
    if err := json.NewEncoder(&escaped).Encode(value); err != nil {
        panic(err)
    }

    // 仅关闭 HTML 字符转义，不改变 JSON 的引号、结构和换行规则。
    var readable bytes.Buffer
    encoder := json.NewEncoder(&readable)
    encoder.SetEscapeHTML(false)
    if err := encoder.Encode(value); err != nil {
        panic(err)
    }

    fmt.Printf("默认: %s", escaped.String())
    fmt.Printf("关闭转义: %s", readable.String())
}

默认结果中的 <、> 和 & 属于 JSON 字符串里的转义表示；解析 JSON 后，接收方仍会得到原来的字符序列。关闭后只是让 JSON 文本更直观，不等于关闭 JSON 的基础字符串转义。

SetEscapeHTML 到底改变了哪些内容

Go 官方文档把这个方法定义为：指定 JSON 引号字符串中的问题 HTML 字符是否转义，默认行为会把 &、、> 写成 Unicode 转义形式。它影响的是编码后的文本表现，不会改变字段名、数组结构、数字或布尔值。

因此，下面几件事要分开判断：

• 可读性：日志、配置导出或人工查看时，关闭后更容易直接看到符号。
• 嵌入位置：JSON 会被拼进 HTML 时，保留默认转义更稳妥。
• 调用范围：SetEscapeHTML 是 *json.Encoder 的方法，不能直接配置一次就影响全局的 json.Marshal。

另外，Encoder.Encode 会在每个 JSON 值后追加换行。如果你要生成签名、拼接协议帧或比较精确字节，应把这一个换行也纳入边界判断。

按输出场景做选择

如果响应体只是普通 JSON 接口，客户端会按 JSON 规则解析，那么两种文本通常表示同一组字符串值。是否关闭应由接口的兼容约定决定：已有客户端依赖转义文本时不要随意切换；新接口若强调人类可读，可以明确记录编码策略。

如果 JSON 会直接进入 HTML、脚本或模板内容，优先保留默认值。官方文档给出的理由正是避免把 JSON 放入 HTML 时产生安全问题。不要为了“看起来漂亮”而全局关闭它，也不要把 SetEscapeHTML(false) 当作 HTML 输出编码器；网页上下文仍需使用对应的 HTML 或脚本安全处理。

如果使用的是 json.Marshal，它没有接收 Encoder 选项的入口。要控制 HTML 转义，应改成写入 bytes.Buffer 的 Encoder；如果只是需要紧凑或缩进格式，则分别考虑 Marshal、MarshalIndent 或 SetIndent，不要把不同问题混在一起。

常见误区和快速判断

1. 看到 \\u003c 就认为数据损坏：先区分“JSON 文本”与“解析后的字符串值”。
2. 以为关闭 HTML 转义会关闭所有字符转义：引号、反斜杠和控制字符仍要遵守 JSON 语法。
3. 只在一处改了 Encoder，却用另一处的 json.Marshal 结果做对比：确认调用链使用的是同一种编码器。
4. 忽略 Encode 末尾换行：做哈希、签名或字节级快照时要明确是否去掉它。

一句话总结：SetEscapeHTML(false) 改的是 JSON 字符串的 HTML 安全转义表现，不是业务数据；非 HTML 场景可以为可读性关闭，HTML 嵌入场景应保留默认值，并在接口约定中固定选择。

相关问题

SetEscapeHTML(false) 会影响中文吗？它主要控制 HTML 相关字符的转义，不是中文字符开关；是否出现 Unicode 表示还要看具体字符串和编码路径。

为什么 Encoder 输出末尾多一个换行？Encode 按流式编码设计，每次写入一个 JSON 值后追加换行；需要精确无换行文本时应在协议层明确处理。