Go json.Encoder.SetEscapeHTML 关闭 HTML 转义后有哪些变化

如果你发现 Go 输出的 JSON 里出现了 \u003c、\u003e 或 \u0026，通常不是数据被改坏，而是 encoding/json 的 Encoder 默认开启了 HTML 字符转义。需要更易读的普通 API 响应或日志时，可以对当前编码器调用 SetEscapeHTML(false)；如果 JSON 会直接嵌入 HTML，则应保留默认行为，并把它当作输出边界的一层保护。

官方文档：https://pkg.go.dev/encoding/json#Encoder.SetEscapeHTML

关键点是：这个选项只改变 JSON 字符串的转义表示，不改变 JSON 的字段结构，也不等于给不可信内容做完整的 HTML 安全处理。

默认输出为什么看起来像变了

json.NewEncoder 创建的编码器默认会把字符串中的 &、 和 > 转成 \u0026、\u003c 和 \u003e。解码后它们仍然代表原字符，所以这是表示层变化，不是业务字段被替换。

package main

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

func main() {
    payload := map[string]string{"text": "Go&JSON"}

    // 默认模式优先照顾可能嵌入 HTML 的 JSON 输出。
    if err := json.NewEncoder(os.Stdout).Encode(payload); err != nil {
        panic(err)
    }
    fmt.Println()

    encoder := json.NewEncoder(os.Stdout)
    // 普通接口或日志不需要 HTML 嵌入时，关闭当前编码器的字符转义。
    encoder.SetEscapeHTML(false)
    if err := encoder.Encode(payload); err != nil {
        panic(err)
    }
}

这段代码的两次编码都产生合法 JSON：前者更偏向 HTML 承载安全，后者保留原字符以提高可读性。SetEscapeHTML 只作用于调用它的 encoder，不会改变包级别的全局规则。

先看 JSON 要被谁消费

是否关闭转义，不应该由“看起来舒服”单独决定，而要看输出会不会作为 HTML 的一部分继续解析。

尤其要注意，“接口响应的 Content-Type 是 JSON”与“这段 JSON 会被服务端拼进 HTML”是两种不同承载方式。前者可以根据客户端和日志需求调可读性，后者则不应为了好看关闭默认保护。

把配置限制在具体编码器实例

排查时常见的误区是把 JSON 结果先转成字符串，再用 strings.Replace 去替换 Unicode 转义。这样既容易误伤原本就包含反斜杠的内容，也让编码责任散落在业务代码里。更稳妥的做法是，在确定输出承载场景后，直接配置负责写出的 Encoder。

func writeReadableJSON(w io.Writer, value any) error {
    encoder := json.NewEncoder(w)
    // 该函数只服务普通 JSON 输出，不负责把结果嵌入 HTML。
    encoder.SetEscapeHTML(false)
    // Encode 自带换行，便于日志和逐条响应阅读。
    return encoder.Encode(value)
}

func writeEmbeddedJSON(w io.Writer, value any) error {
    encoder := json.NewEncoder(w)
    // HTML 承载场景保留默认转义，不在这里追求原字符可读性。
    return encoder.Encode(value)
}

两个函数的差别清楚地表达了安全边界：配置跟着输出用途走，调用方不需要猜某个全局开关是否已经被其他模块修改。

用测试固定输出契约

回归测试不要只断言整段字符串，因为字段顺序、编码器换行或格式化设置也可能让字符串断言变脆。这里同时检查“关闭转义后的可读文本”和“解码后仍是同一数据”，把表示契约与数据契约分开。

func TestSetEscapeHTML(t *testing.T) {
    value := map[string]string{"text": ""}

    var buf bytes.Buffer
    encoder := json.NewEncoder(&buf)
    // 测试普通 JSON 输出的可读表示契约。
    encoder.SetEscapeHTML(false)
    if err := encoder.Encode(value); err != nil {
        t.Fatal(err)
    }
    if !strings.Contains(buf.String(), "") {
        t.Fatalf("output keeps escaped characters: %q", buf.String())
    }

    var decoded map[string]string
    // 再解码一次，确认关闭转义没有改变业务数据。
    if err := json.Unmarshal(buf.Bytes(), &decoded); err != nil {
        t.Fatal(err)
    }
    if decoded["text"] != "" {
        t.Fatalf("decoded value changed: %#v", decoded)
    }
}

在真实项目中还可以为默认模式补一个相反的断言，确认 HTML 承载的编码器仍然输出 \u003c 一类安全表示。测试的重点不是绑定某个漂亮字符串，而是把“是否转义”和“数据是否保持不变”写成两个可读的契约。

最容易踩到的三个边界

• 关闭转义不是清洗 HTML。 它只改变 JSON 字符串的编码表示，不会替你过滤标签、属性或脚本上下文中的不可信输入。
• 不要把 API 响应和 HTML 内嵌数据混为一谈。 同一个结构体，在两个承载场景下可以使用不同的编码器配置。
• 不要用字符串替换修复显示问题。 如果只是日志难读，应调整编码器；如果是前端展示，应在解析 JSON 后按目标 HTML 上下文安全渲染。

相关问题

SetEscapeHTML(false) 会让 JSON 失效吗？

不会。它只让部分字符以原字符形式出现在 JSON 字符串里，JSON 结构仍由编码器负责生成；是否安全要结合后续承载上下文判断。

为什么不直接使用 json.Marshal？

json.Marshal 没有一个对应的编码器实例可配置。如果需要控制是否进行 HTML 转义、持续写入或设置缩进，应使用 json.NewEncoder，并把配置留在具体输出函数中。