Go json.Encoder 怎样避免把 HTML 字符转成转义序列

如果 Go 输出的 JSON 中出现 \u003c、\u003e 或 \u0026，通常不是数据被改坏，而是 encoding/json 的默认 HTML 转义。对于不会嵌入 HTML 的普通接口、文件或消息内容，可以给 json.Encoder 调用 SetEscapeHTML(false)，让 &、、> 保持原字符。

要注意，这个开关是“输出环境选择”，不是通用的安全加固。JSON 可能进入 HTML、内联脚本或模板时，应保留默认值；只有下游明确把它当作独立 JSON 文本处理，且转义影响了协议可读性或兼容性，才关闭。

最小写法是：创建 json.NewEncoder 后调用 enc.SetEscapeHTML(false)，再执行 Encode。默认行为会转义 &、、>，关闭后只改变字符串表示，不改变 JSON 值。

默认 HTML 转义到底改了什么

json.NewEncoder 默认打开 HTML 转义。字符串里的三个字符会分别写成 \u0026、\u003c、\u003e。这是 JSON 字符串中的合法转义表示，接收端解析后仍会得到原来的字符。

package main

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

type Message struct {
    Body string `json:"body"`
}

func main() {
    value := Message{Body: "Go & JSON"}

    var out bytes.Buffer
    // 默认配置会保护可能被嵌入 HTML 的 JSON 字符串。
    if err := json.NewEncoder(&out).Encode(value); err != nil {
        // 编码或写入失败都要让调用方知道，不能只打印半截 JSON。
        panic(err)
    }
    fmt.Print(out.String())
}

上面的输出中，尖括号和连字符可能显示为 Unicode 转义，但它仍然是同一个 JSON 字符串。接收端使用标准 JSON 解析器读取时，通常不需要额外“反转义”。

怎样让非 HTML 输出保留原始字符

在确认 JSON 不会被拼进 HTML 的情况下，直接对同一个 Encoder 设置关闭：

package main

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

type Message struct {
    Body string `json:"body"`
}

func main() {
    value := Message{Body: "Go & JSON"}
    var out bytes.Buffer
    enc := json.NewEncoder(&out)

    // 该输出会交给独立 JSON 消费者，不会作为 HTML 片段解释。
    enc.SetEscapeHTML(false)
    if err := enc.Encode(value); err != nil {
        // Encode 既可能返回序列化错误，也可能返回 Writer 错误。
        panic(err)
    }
    fmt.Print(out.String())
}

此时 JSON 文本中的 、& 会更接近原始内容。Encode 仍会在每个值后追加换行，这是 Encoder 的流式输出约定；如果协议不接受末尾换行，要在协议层明确处理，而不是把 HTML 转义开关当成格式化开关。

按下游环境决定是否关闭

关键判断不是“转义后看起来丑不丑”，而是接收方把这段字节当作什么。只要 JSON 仍会进入 HTML 解析上下文，就不要为了日志可读性关闭保护。

Encoder、Marshal 和 HTMLEscape 有什么区别

SetEscapeHTML 是 *json.Encoder 的方法。它影响之后通过这个 Encoder 执行的 Encode，不会修改已经生成的字符串，也不会改变另一个 Encoder 的配置。

// Encoder 适合需要控制输出选项或连续写入的场景。
enc := json.NewEncoder(writer)
enc.SetEscapeHTML(false)
if err := enc.Encode(payload); err != nil {
    // writer 的网络或文件错误必须向上返回。
    return err
}

// Marshal 没有 SetEscapeHTML 参数；不要把 Encoder 的开关写到 Marshal 上。
data, err := json.Marshal(payload)
if err != nil {
    return err
}
_ = data

// HTMLEscape 的方向相反：它把 JSON 文本转成适合 HTML 的转义形式。
safe := json.HTMLEscape(data)
_ = safe

如果项目已经统一使用 json.Marshal，又确实需要关闭这项行为，通常应调整为写入 bytes.Buffer 的 Encoder，再根据协议决定是否去掉末尾换行。不要对 JSON 字符串做未经规则约束的全局替换，否则可能误伤字段内容或破坏转义。

最后用三项检查固定输出契约

1. 确认渲染位置：只要会进入 HTML 或脚本上下文，就保留默认 HTML 转义。
2. 确认消费者：独立 JSON 解析器、文件或消息队列可以按可读性评估是否关闭。
3. 确认 API 形态：需要 SetEscapeHTML 时使用 Encoder，并统一处理 Encode 的错误和末尾换行。

这样处理后，\u003c 不再被误认为乱码，SetEscapeHTML(false) 也不会被误用成“所有场景都应该关闭”的开关。

常见问题

关闭 HTML 转义会改变 JSON 数据吗？

不会改变解析后的字符串值，主要改变的是 JSON 文本表示；接收端仍应按 JSON 解析，而不是按 HTML 片段拼接。

为什么调用 SetEscapeHTML(false) 后输出仍然有转义？

检查是否真的使用了配置过的 Encoder 执行 Encode，以及是否在别处又调用了 json.Marshal、模板转义或二次序列化。

Encoder 输出为什么多了换行？

Encode 会在每个 JSON 值后追加换行，方便流式传输和调试；若协议要求严格无换行，应在明确了解协议后再处理字节边界。