编码输出函数

json 包提供的编码解码函数，包括序列化、反序列化、格式化和配置化编码。

序列化函数

Marshal

签名：func Marshal(value any, cfg ...Config) ([]byte, error)

将 Go 值序列化为 JSON 字节切片。100% 兼容 encoding/json.Marshal：无 cfg 调用 json.Marshal(v) 与标准库完全一致。

通过可选的尾随 Config 可控制编码行为（缩进、数字处理等），与 Processor.Marshal 形成包级/实例级镜像。

// 兼容 encoding/json（无 cfg）
data, err := json.Marshal(map[string]any{"name": "test"})
if err != nil {
    panic(err)
}
fmt.Println(string(data)) // {"name":"test"}

// 带配置（非破坏性可选参数）
data, err = json.Marshal(value, json.PrettyConfig())

Unmarshal

签名：func Unmarshal(data []byte, value any, cfg ...Config) error

将 JSON 字节切片反序列化到 Go 值。100% 兼容 encoding/json.Unmarshal：无 cfg 调用 json.Unmarshal(data, &v) 与标准库完全一致。

通过可选的尾随 Config 可控制安全限制、数字保留等，与 Processor.Unmarshal 形成镜像。

var result struct {
    Name string `json:"name"`
}
// 兼容 encoding/json（无 cfg）
err := json.Unmarshal([]byte(`{"name":"test"}`), &result)

// 带配置
err = json.Unmarshal(data, &v, json.SecurityConfig())

MarshalIndent

签名：func MarshalIndent(v any, prefix, indent string, cfg ...Config) ([]byte, error)

带缩进的序列化。100% 兼容 encoding/json.MarshalIndent：无 cfg 调用 json.MarshalIndent(v, prefix, indent) 与标准库完全一致。

通过可选的尾随 Config 可附加配置；prefix 与 indent 参数会覆盖 Config 中的对应字段。

// 兼容 encoding/json（无 cfg）
data, err := json.MarshalIndent(user, "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(string(data))

// 带配置
data, err = json.MarshalIndent(v, "", "  ", json.SecurityConfig())

格式化函数

Compact

签名：func Compact(dst *bytes.Buffer, src []byte, cfg ...Config) error

压缩 JSON，移除不必要的空白字符，将结果写入 dst。兼容 encoding/json.Compact（buffer 形式）。

var buf bytes.Buffer
err := json.Compact(&buf, []byte(`{"name": "test"}`))
if err != nil {
    panic(err)
}
fmt.Println(buf.String()) // {"name":"test"}

CompactString

签名：func CompactString(jsonStr string, cfg ...Config) (string, error)

以字符串输入/字符串输出形式压缩 JSON，移除不必要的空白字符。是 Processor.Compact 的包级镜像，与 Prettify（镜像 Processor.Prettify）对称。

Compact vs CompactString

• Compact(dst, src)：buffer 形式，兼容 encoding/json.Compact，镜像 Processor.CompactBuffer
• CompactString(s)：字符串形式，镜像 Processor.Compact

compact, err := json.CompactString(`{
    "name": "Alice",
    "age": 30
}`)
// compact == `{"name":"Alice","age":30}`

// 带配置（例如保留原始数字格式）
cfg := json.DefaultConfig()
cfg.PreserveNumbers = true
compact, err = json.CompactString(jsonStr, cfg)

Indent

签名：func Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

格式化 JSON 并添加缩进，将结果写入 dst。兼容 encoding/json.Indent。

var buf bytes.Buffer
err := json.Indent(&buf, []byte(`{"name":"test"}`), "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(buf.String())
// {
//   "name": "test"
// }

HTMLEscape

签名：func HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

HTML 转义 JSON 内容，将 <、>、& 等特殊字符（以及 U+2028、U+2029）替换为对应的 Unicode 转义序列，结果写入 dst。无返回值。

var buf bytes.Buffer
json.HTMLEscape(&buf, []byte(`{"html":"<script>alert(1)</script>"}`))
fmt.Println(buf.String())
// {"html":"\u003cscript\u003ealert(1)\u003c/script\u003e"}

Prettify

签名：func Prettify(jsonStr string, cfg ...Config) (string, error)

使用默认的漂亮打印缩进格式化 JSON 字符串，返回格式化后的字符串。

pretty, err := json.Prettify(`{"name":"Alice","age":30}`)
if err != nil {
    panic(err)
}
fmt.Println(pretty)
// {
//   "name": "Alice",
//   "age": 30
// }

配置化编码函数

Encode

签名：func Encode(value any, cfg ...Config) (string, error)

将 Go 值编码为 JSON 字符串，支持可选配置参数。

已废弃

Encode 在功能上与 EncodeWithConfig 完全相同（两者委托同一实现）。请改用 EncodeWithConfig，或在 []byte 输出可接受时使用 Marshal。Encode 将在未来的主版本中移除。

result, err := json.Encode(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

带配置

result, err := json.Encode(user, json.SecurityConfig())

EncodePretty

签名：func EncodePretty(value any, cfg ...Config) (string, error)

将 Go 值编码为格式化的 JSON 字符串（带缩进），支持可选配置参数。

result, err := json.EncodePretty(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

带配置

result, err := json.EncodePretty(user, json.PrettyConfig())

EncodeWithConfig

签名：func EncodeWithConfig(value any, cfg ...Config) (string, error)

使用指定配置将 Go 值编码为 JSON 字符串。适合需要精细控制编码行为的场景。

// 使用漂亮打印配置
result, err := json.EncodeWithConfig(data, json.PrettyConfig())
if err != nil {
    panic(err)
}
fmt.Println(result)

使用安全配置

result, err := json.EncodeWithConfig(data, json.SecurityConfig())

批量编码函数

EncodeBatch

签名：func EncodeBatch(pairs map[string]any, cfg ...Config) (string, error)

将键值对批量编码为 JSON 对象字符串。

result, err := json.EncodeBatch(map[string]any{
    "name":  "Alice",
    "age":   30,
    "email": "[email protected]",
})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"age":30,"email":"[email protected]","name":"Alice"}

EncodeFields

签名：func EncodeFields(value any, fields []string, cfg ...Config) (string, error)

仅编码指定字段，实现字段过滤输出。

user := struct {
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password"`
}{
    Name: "Alice", Email: "[email protected]", Password: "secret",
}

// 仅输出公开字段
result, err := json.EncodeFields(user, []string{"name", "email"})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"name":"Alice","email":"[email protected]"}

EncodeStream

签名：func EncodeStream(values any, cfg ...Config) (string, error)

将多个值编码为 JSON 数组流（array stream）。values 通常是切片或可枚举集合，输出形如 [v1,v2,...] 的 JSON 数组字符串。

values := []map[string]any{
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
}

result, err := json.EncodeStream(values)
if err != nil {
    panic(err)
}
fmt.Println(result)

Processor 格式化方法

Processor 类型提供额外的格式化方法。使用 json.New() 创建 Processor（返回 (*Processor, error)）：

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

Processor.CompactBuffer

签名：func (p *Processor) CompactBuffer(dst *bytes.Buffer, src []byte, cfg ...Config) error

压缩 JSON 字节并写入 dst 缓冲区。包级 Compact 函数委托给此方法。

var buf bytes.Buffer
err := p.CompactBuffer(&buf, []byte(`{"name": "Alice"}`))
// buf.String() => {"name":"Alice"}

Processor.Indent

签名：func (p *Processor) Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

将缩进格式的 JSON 写入 dst 缓冲区。与 encoding/json.Indent 兼容。

var buf bytes.Buffer
err := p.Indent(&buf, []byte(`{"name":"Alice"}`), "", "  ")

Processor.HTMLEscape

签名：func (p *Processor) HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

将 HTML 转义后的 JSON 写入 dst 缓冲区，无返回值。与 encoding/json.HTMLEscape 兼容。

var buf bytes.Buffer
p.HTMLEscape(&buf, []byte(`{"html":"<script>"}`))

TIP

完整的 Processor 文档请参阅 Processor。

配置预设

以下辅助函数返回预配置的 Config 值，可传递给任何接受 ...Config 的函数：

// 默认配置
cfg := json.DefaultConfig()

// 漂亮打印配置
cfg = json.PrettyConfig()

// 安全配置
cfg = json.SecurityConfig()

TIP

完整的 Config 字段文档请参阅 配置。

相关

• 查询获取函数 - Get, GetString 等查询操作
• 修改函数 - Set, Delete 等修改操作
• 文件操作 - LoadFromFile, SaveToFile 等文件操作
• 配置 - Config 类型和选项
• 接口 - Processor, Encoder, Decoder 类型