Go json.Encoder 什么时候应该关闭 HTML 字符转义

我在把 Go 结构体同时输出到 API 响应和配置文件时，遇到过一个很容易被误判的问题：原字符串里的 、>、& 出现在 JSON 中时，encoding/json 默认会把它们写成 \u003c、\u003e、\u0026。这不是数据损坏，而是 v1 JSON 编码器为了 HTML 嵌入场景保留的默认行为。

我的判断规则很简单：JSON 会被放进 HTML 的 或其他 HTML 上下文时，保留默认转义；它只是普通 API、配置文件、消息体或需要人读的文本时，才考虑对这个 Encoder 调用 SetEscapeHTML(false)。关闭后只是让非 HTML 输出更直观，不会改变 Go 字符串本身，也不替代下游的上下文安全处理。

默认转义到底改变了什么

json.NewEncoder 创建的 Encoder 默认开启 HTML 字符转义。官方文档明确说明，默认会在 JSON 字符串中转义 &、 和 >，典型结果分别是 \u0026、\u003c 和 \u003e。这样做是为了降低把 JSON 嵌入 HTML 时的风险。

例如下面这段代码的两个 Encoder 使用同一个输入对象，区别只在输出策略：

package main

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

func main() {
    value := map[string]string{
        "title": " & JSON",
    }

    var safe bytes.Buffer
    safeEncoder := json.NewEncoder(&safe)
    // 默认保持 HTML 字符转义，适合可能嵌入 HTML 的 JSON。
    if err := safeEncoder.Encode(value); err != nil {
        panic(err)
    }

    var readable bytes.Buffer
    readableEncoder := json.NewEncoder(&readable)
    // 普通 JSON 文本不需要 HTML 嵌入保护时，保留字符更易读。
    readableEncoder.SetEscapeHTML(false)
    if err := readableEncoder.Encode(value); err != nil {
        panic(err)
    }

    fmt.Printf("默认：%s", safe.String())
    fmt.Printf("关闭：%s", readable.String())
}

前者会把尖括号和连接符写成 Unicode 转义，后者更接近读者在 Go 字符串中看到的内容。两者都仍然是合法 JSON；解析器读取后，字符串值仍然是 & JSON。

先看 JSON 要被谁消费

是否关闭转义，不应该由“看起来更漂亮”单独决定，而要看输出的下一站。下面这个表是我在项目里最常用的取舍：

这里的“可关闭”是条件建议，不是安全承诺。只要同一份 JSON 可能被直接拼进 HTML，或者会从普通 API 再转交给 HTML 模板，就应当把边界责任放在最终上下文处理处，不要把 false 当成全局优化开关。

什么时候值得调用 SetEscapeHTML(false)

我通常只在三个信号同时成立时关闭：输出是 JSON 文本而不是 HTML 片段；下游按 JSON 解析而不是把字符串直接拼到页面；团队确实需要保留原字符来阅读、比较或排查。最常见的例子是生成配置文件、写消息队列载荷、导出测试快照，或者返回给只消费 JSON 的内部接口。

把开关放在创建 Encoder 之后、第一次 Encode 之前，作用范围就很清楚：

func encodeReadableJSON(v any) ([]byte, error) {
    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    // 该函数只服务于普通 JSON 文本，不把结果直接嵌入 HTML。
    enc.SetEscapeHTML(false)
    // Encode 会在一个 JSON 值后追加换行，适合配置文件和文本快照。
    if err := enc.Encode(v); err != nil {
        return nil, fmt.Errorf("encode JSON: %w", err)
    }
    return buf.Bytes(), nil
}

如果调用方需要紧凑的单行结果，可以改用 json.Marshal，但要接受它没有 SetEscapeHTML 这个实例级开关；需要同时控制转义策略和流式写入时，继续使用 Encoder 更合适。

和缩进、错误处理一起使用

关闭转义并不妨碍格式化输出。对于需要人工检查的配置文件，我会把 SetEscapeHTML(false) 和 SetIndent 放在同一个编码函数里，并保留 Encode 的错误返回：

func writeConfig(w io.Writer, cfg Config) error {
    enc := json.NewEncoder(w)
    // 配置文件由人和程序共同读取，保留可读字符并使用两格缩进。
    enc.SetEscapeHTML(false)
    enc.SetIndent("", "  ")
    // 将底层 Writer 的错误原样向上返回，避免误报写入成功。
    if err := enc.Encode(cfg); err != nil {
        return fmt.Errorf("write config JSON: %w", err)
    }
    return nil
}

这个版本有两个容易忽略的细节：一是 Encode 会在 JSON 值后写入换行，二是 Writer 失败时必须处理错误。它们和 HTML 转义没有直接关系，却决定了生成配置或快照时能不能可靠落盘。

几个我踩过的误区

• 把 Unicode 转义当成数据丢失：JSON 解析后会还原为原字符，先区分“文本表示”与“解析后的值”。
• 在 Marshal 上寻找开关：SetEscapeHTML 是 Encoder 方法；如果必须控制它，就不要在前面先调用 Marshal。
• 把关闭转义当成 HTML 解码：SetEscapeHTML(false) 只影响本次编码是否写出这些转义，不会改写输入字符串，也不会替下游清理 HTML。
• 为了日志可读而全局关闭：日志、API、模板注入和消息转发可能有不同消费边界，应在最靠近输出的位置设置，而不是封装成全局默认。

最后的选择口诀

会进入 HTML，就保留默认转义；只作为普通 JSON 文本传输或保存，并且需要人读，就可以在专用 Encoder 上调用 SetEscapeHTML(false)。如果下游边界还没有确定，先保持默认值，等数据真正离开应用时再按消费上下文决定。

官方 API 说明：https://pkg.go.dev/encoding/json#Encoder.SetEscapeHTML

相关问题

关闭 HTML 转义后，JSON 还合法吗？

只要字符串和其他值仍按 JSON 规则编码，关闭的是额外的 HTML 字符转义，不是 JSON 语法转义，因此仍是合法 JSON。

为什么同一个结构体用 Marshal 看不到这个开关？

Marshal 是包级函数，没有 Encoder 实例可配置。如果输出必须保留 、>、&，请改用 NewEncoder 后调用 SetEscapeHTML(false)。

API 返回 JSON 时必须关闭吗？

不必须。默认转义和关闭转义都能被 JSON 客户端正确解析，是否关闭主要取决于协议约定、调试可读性和数据是否会进入 HTML 边界。