package json

import "encoding/json"

包 json 实现了 RFC 7159 中定义的 JSON 的编码与解码。 JSON 与 Go 值之间的映射关系在 Marshal 和 Unmarshal 函数的文档中描述。

有关本包的介绍,请参阅 "JSON and Go": https://golang.org/doc/articles/json_and_go.html

安全性考量

JSON 标准(RFC 7159)对若干解析器行为的定义较为宽松。因此,许多 JSON 解析器在各种场景下的行为有所不同。解析器的这些差异意味着,使用多个独立 JSON 解析器实现的系统可能会以不同方式解析同一个 JSON 对象。

出于安全目的而依赖 JSON 对象被一致解析的系统,应当仔细理解本解析器的 行为,以及这些行为如何可能导致与其他解析器实现的互操作性问题。

由于 Go 向后兼容性承诺(https://go.dev/doc/go1compat),本包表现出一些 可能导致互操作性问题但无法更改的行为。尤其是以下解析行为可能引发问题:

Example (CustomMarshalJSON)
//go:build goexperiment.jsonv2

package main

import (
	"fmt"
	"log"
	"strings"

	"encoding/json"
)

type Animal int

const (
	Unknown Animal = iota
	Gopher
	Zebra
)

func (a *Animal) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	switch strings.ToLower(s) {
	default:
		*a = Unknown
	case "gopher":
		*a = Gopher
	case "zebra":
		*a = Zebra
	}

	return nil
}

func (a Animal) MarshalJSON() ([]byte, error) {
	var s string
	switch a {
	default:
		s = "unknown"
	case Gopher:
		s = "gopher"
	case Zebra:
		s = "zebra"
	}

	return json.Marshal(s)
}

func main() {
	blob := `["gopher","armadillo","zebra","unknown","gopher","bee","gopher","zebra"]`
	var zoo []Animal
	if err := json.Unmarshal([]byte(blob), &zoo); err != nil {
		log.Fatal(err)
	}

	census := make(map[Animal]int)
	for _, animal := range zoo {
		census[animal] += 1
	}

	fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras:  %d\n* Unknown: %d\n",
		census[Gopher], census[Zebra], census[Unknown])

}

Output:

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3
Example (CustomMarshalJSON)
//go:build !goexperiment.jsonv2

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"strings"
)

type Animal int

const (
	Unknown Animal = iota
	Gopher
	Zebra
)

func (a *Animal) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	switch strings.ToLower(s) {
	default:
		*a = Unknown
	case "gopher":
		*a = Gopher
	case "zebra":
		*a = Zebra
	}

	return nil
}

func (a Animal) MarshalJSON() ([]byte, error) {
	var s string
	switch a {
	default:
		s = "unknown"
	case Gopher:
		s = "gopher"
	case Zebra:
		s = "zebra"
	}

	return json.Marshal(s)
}

func main() {
	blob := `["gopher","armadillo","zebra","unknown","gopher","bee","gopher","zebra"]`
	var zoo []Animal
	if err := json.Unmarshal([]byte(blob), &zoo); err != nil {
		log.Fatal(err)
	}

	census := make(map[Animal]int)
	for _, animal := range zoo {
		census[animal] += 1
	}

	fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras:  %d\n* Unknown: %d\n",
		census[Gopher], census[Zebra], census[Unknown])

}

Output:

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3
Example (TextMarshalJSON)
//go:build !goexperiment.jsonv2

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"strings"
)

type Size int

const (
	Unrecognized Size = iota
	Small
	Large
)

func (s *Size) UnmarshalText(text []byte) error {
	switch strings.ToLower(string(text)) {
	default:
		*s = Unrecognized
	case "small":
		*s = Small
	case "large":
		*s = Large
	}
	return nil
}

func (s Size) MarshalText() ([]byte, error) {
	var name string
	switch s {
	default:
		name = "unrecognized"
	case Small:
		name = "small"
	case Large:
		name = "large"
	}
	return []byte(name), nil
}

func main() {
	blob := `["small","regular","large","unrecognized","small","normal","small","large"]`
	var inventory []Size
	if err := json.Unmarshal([]byte(blob), &inventory); err != nil {
		log.Fatal(err)
	}

	counts := make(map[Size]int)
	for _, size := range inventory {
		counts[size] += 1
	}

	fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
		counts[Small], counts[Large], counts[Unrecognized])

}

Output:

Inventory Counts:
* Small:        3
* Large:        2
* Unrecognized: 3
Example (TextMarshalJSON)
//go:build goexperiment.jsonv2

package main

import (
	"fmt"
	"log"
	"strings"

	"encoding/json"
)

type Size int

const (
	Unrecognized Size = iota
	Small
	Large
)

func (s *Size) UnmarshalText(text []byte) error {
	switch strings.ToLower(string(text)) {
	default:
		*s = Unrecognized
	case "small":
		*s = Small
	case "large":
		*s = Large
	}
	return nil
}

func (s Size) MarshalText() ([]byte, error) {
	var name string
	switch s {
	default:
		name = "unrecognized"
	case Small:
		name = "small"
	case Large:
		name = "large"
	}
	return []byte(name), nil
}

func main() {
	blob := `["small","regular","large","unrecognized","small","normal","small","large"]`
	var inventory []Size
	if err := json.Unmarshal([]byte(blob), &inventory); err != nil {
		log.Fatal(err)
	}

	counts := make(map[Size]int)
	for _, size := range inventory {
		counts[size] += 1
	}

	fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
		counts[Small], counts[Large], counts[Unrecognized])

}

Output:

Inventory Counts:
* Small:        3
* Large:        2
* Unrecognized: 3

Index

Examples

Functions

func Compact

func Compact(dst *bytes.Buffer, src []byte) error

Compact 将经过 JSON 编码的 src(去掉无意义的空白字符)追加到 dst。

func HTMLEscape

func HTMLEscape(dst *bytes.Buffer, src []byte)

HTMLEscape 将经过 JSON 编码的 src 追加到 dst,其中字符串字面量内的 <、>、&、U+2028 和 U+2029 字符被改为 \u003c、\u003e、\u0026、\u2028、\u2029, 以便 JSON 可以安全地嵌入到 HTML <script> 标签内。 出于历史原因,Web 浏览器不遵循 <script> 标签内的标准 HTML 转义, 因此必须使用另一种 JSON 编码。

Example
package main

import (
	"bytes"
	"os"

	"encoding/json"
)

func main() {
	var out bytes.Buffer
	json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`))
	out.WriteTo(os.Stdout)
}

Output:

{"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}
Example
package main

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

func main() {
	var out bytes.Buffer
	json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`))
	out.WriteTo(os.Stdout)
}

Output:

{"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}

func Indent

func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error

Indent 将经过 JSON 编码的 src 的缩进形式追加到 dst。 JSON 对象或数组中的每个元素都从新的缩进行开始, 该行以 prefix 开头,后跟一个或多个 indent 副本(根据缩进嵌套层级而定)。 追加到 dst 的数据不以 prefix 或任何缩进开头,以便更容易嵌入到其他格式化的 JSON 数据中。 尽管 src 开头的前导空白字符(空格、制表符、回车、换行)会被丢弃, 但 src 末尾的尾随空白字符会被保留并复制到 dst。 例如,如果 src 没有尾随空格,dst 也没有; 如果 src 以尾随换行结尾,dst 也会以尾随换行结尾。

Example
package main

import (
	"bytes"
	"encoding/json"
	"log"
	"os"
)

func main() {
	type Road struct {
		Name   string
		Number int
	}
	roads := []Road{
		{"Diamond Fork", 29},
		{"Sheep Creek", 51},
	}

	b, err := json.Marshal(roads)
	if err != nil {
		log.Fatal(err)
	}

	var out bytes.Buffer
	json.Indent(&out, b, "=", "\t")
	out.WriteTo(os.Stdout)
}

Output:

[
=	{
=		"Name": "Diamond Fork",
=		"Number": 29
=	},
=	{
=		"Name": "Sheep Creek",
=		"Number": 51
=	}
=]
Example
package main

import (
	"bytes"
	"log"
	"os"

	"encoding/json"
)

func main() {
	type Road struct {
		Name   string
		Number int
	}
	roads := []Road{
		{"Diamond Fork", 29},
		{"Sheep Creek", 51},
	}

	b, err := json.Marshal(roads)
	if err != nil {
		log.Fatal(err)
	}

	var out bytes.Buffer
	json.Indent(&out, b, "=", "\t")
	out.WriteTo(os.Stdout)
}

Output:

[
=	{
=		"Name": "Diamond Fork",
=		"Number": 29
=	},
=	{
=		"Name": "Sheep Creek",
=		"Number": 51
=	}
=]

func Marshal

func Marshal(v any) ([]byte, error)

Marshal 返回 v 的 JSON 编码。

Marshal 会递归地遍历值 v。 如果遇到的值实现了 Marshaler 且不是 nil 指针,Marshal 会调用 Marshaler.MarshalJSON 来生成 JSON。如果不存在 Marshaler.MarshalJSON 方法,但该值实现了 encoding.TextMarshaler,Marshal 会调用 encoding.TextMarshaler.MarshalText 并将结果编码为 JSON 字符串。 nil 指针例外并非严格必要,而是为了模仿 Unmarshaler.UnmarshalJSON 行为中类似且必要的例外。

否则,Marshal 使用以下依赖于类型的默认编码:

布尔值编码为 JSON 布尔值。

浮点、整数和 Number 值编码为 JSON 数字。 NaN 和 +/-Inf 值将返回一个 UnsupportedValueError。

字符串值编码为强制转换为有效 UTF-8 的 JSON 字符串, 无效字节会被替换为 Unicode 替换字符。 为了使 JSON 可以安全地嵌入 HTML <script> 标签内, 字符串使用 HTMLEscape 编码, 它会将 "<"、">"、"&"、U+2028 和 U+2029 转义为 "\u003c"、"\u003e"、"\u0026"、"\u2028" 和 "\u2029"。 使用 Encoder 时可以通过调用 Encoder.SetEscapeHTML(false) 禁用这种替换。

数组和切片值编码为 JSON 数组,但 []byte 编码为 base64 编码的字符串, 而 nil 切片编码为 JSON null 值。

结构体值编码为 JSON 对象。 每个导出的结构体字段都会成为对象的一个成员,使用字段名作为对象键, 除非该字段因下列原因之一而被省略。

每个结构体字段的编码都可以通过结构体字段标签中 "json" 键下存储的格式 字符串进行定制。该格式字符串给出字段的名称,后面可能跟着一个以逗号分隔的 选项列表。名称可以为空,以便在不覆盖默认字段名的情况下指定选项。

"omitempty" 选项指定:如果字段具有空值,则应从编码中省略该字段。 空值定义为 false、0、nil 指针、nil 接口值,以及长度为零的任意数组、 切片、映射或字符串。

作为一种特殊情况,如果字段标签为 "-",则该字段始终被省略。 注意,名称为 "-" 的字段仍可以通过标签 "-," 生成。

结构体字段标签及其含义的示例:

// 字段在 JSON 中以键 "myName" 出现。
Field int `json:"myName"`

// 字段在 JSON 中以键 "myName" 出现,
// 并且如果其值为空(如上定义),则从对象中省略该字段。
Field int `json:"myName,omitempty"`

// 字段在 JSON 中以键 "Field"(默认值)出现,
// 但如果为空则跳过该字段。
// 注意开头的逗号。
Field int `json:",omitempty"`

// 该字段被本包忽略。
Field int `json:"-"`

// 字段在 JSON 中以键 "-" 出现。
Field int `json:"-,"`

"omitzero" 选项指定:如果字段具有零值,则应从编码中省略该字段, 具体规则如下:

1) 如果字段类型具有 "IsZero() bool" 方法,将使用该方法判断该值是否为零。

2) 否则,如果该值是其类型的零值,则认为它为零。

如果同时指定了 "omitempty" 和 "omitzero",则只要值为空或为零(或两者 皆是),该字段就会被省略。

"string" 选项表示字段以 JSON 编码字符串的形式存储为 JSON。 它仅适用于字符串、浮点、整数或布尔类型的字段。这种额外的编码层级 有时用于与 JavaScript 程序通信:

Int64String int64 `json:",string"`

如果键名是一个非空字符串,且仅由 Unicode 字母、数字以及除引号、 反斜杠和逗号之外的 ASCII 标点组成,则使用该键名。

内嵌结构体字段通常会被序列化,就好像其内部导出的字段是外部结构体的 字段一样,并遵循通常的 Go 可见性规则,但按下一段所述进行修正。 JSON 标签中给出了名称的匿名字段会以该名称处理,而不是作为匿名字段。 接口类型的匿名字段会以该类型名作为其名称处理,而不是作为匿名字段。

在决定序列化或反序列化哪个字段时,结构体字段的 Go 可见性规则会针对 JSON 进行修正。如果同一层级存在多个字段,且该层级是嵌套最浅的层级 (因此也是通常 Go 规则所选择的嵌套层级),则适用以下附加规则:

1) 在这些字段中,如果有任何字段带有 JSON 标签,则只考虑带标签的字段, 即使存在多个原本会冲突的未带标签字段。

2) 如果恰好只有一个字段(根据第一条规则带或不带标签),则选择该字段。

3) 否则存在多个字段,则全部忽略;不会发生错误。

对匿名字段结构体的处理是 Go 1.1 的新特性。 在 Go 1.1 之前,匿名字段结构体会被忽略。要在当前版本和更早版本中 都强制忽略某个匿名字段结构体,请给该字段设置 JSON 标签 "-"。

映射值编码为 JSON 对象。映射的键类型必须是字符串、整数类型,或实现了 encoding.TextMarshaler。映射键会被排序并用作 JSON 对象键,具体应用 以下规则,并遵循上文针对字符串值所述的 UTF-8 强制转换:

指针值编码为所指向的值。 nil 指针编码为 JSON null 值。

接口值编码为接口中包含的值。 nil 接口值编码为 JSON null 值。

通道、复数和函数值无法编码为 JSON。 尝试编码此类值会导致 Marshal 返回一个 UnsupportedTypeError。

JSON 无法表示循环数据结构,Marshal 也不处理它们。 将循环结构传递给 Marshal 会导致错误。

Example
package main

import (
	"fmt"
	"os"

	"encoding/json"
)

func main() {
	type ColorGroup struct {
		ID     int
		Name   string
		Colors []string
	}
	group := ColorGroup{
		ID:     1,
		Name:   "Reds",
		Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
	}
	b, err := json.Marshal(group)
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)
}

Output:

{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}
Example
package main

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

func main() {
	type ColorGroup struct {
		ID     int
		Name   string
		Colors []string
	}
	group := ColorGroup{
		ID:     1,
		Name:   "Reds",
		Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
	}
	b, err := json.Marshal(group)
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)
}

Output:

{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}

func MarshalIndent

func MarshalIndent(v any, prefix, indent string) ([]byte, error)

MarshalIndent 类似于 Marshal,但会应用 Indent 来格式化输出。 输出中的每个 JSON 元素都会在新的一行开始,该行以 prefix 开头,后面根据 缩进嵌套层级跟着 indent 的一份或多份副本。

Example
package main

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

func main() {
	data := map[string]int{
		"a": 1,
		"b": 2,
	}

	b, err := json.MarshalIndent(data, "<prefix>", "<indent>")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))
}

Output:

{
<prefix><indent>"a": 1,
<prefix><indent>"b": 2
<prefix>}
Example
package main

import (
	"fmt"
	"log"

	"encoding/json"
)

func main() {
	data := map[string]int{
		"a": 1,
		"b": 2,
	}

	b, err := json.MarshalIndent(data, "<prefix>", "<indent>")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(b))
}

Output:

{
<prefix><indent>"a": 1,
<prefix><indent>"b": 2
<prefix>}

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal 解析 JSON 编码的数据,并将结果存储在 v 所指向的值中。 如果 v 为 nil 或不是指针,Unmarshal 返回一个 InvalidUnmarshalError。

Unmarshal 使用 Marshal 所用编码的逆过程,根据需要分配映射、切片和指针, 并遵循以下附加规则:

将 JSON 反序列化到指针时,Unmarshal 首先处理 JSON 为字面量 null 的情况。 在这种情况下,Unmarshal 将该指针设为 nil。否则,Unmarshal 将 JSON 反序列化到该指针所指向的值中。如果指针为 nil,Unmarshal 会为其分配一个 新值供其指向。

将 JSON 反序列化到实现了 Unmarshaler 的值时,Unmarshal 会调用该值的 Unmarshaler.UnmarshalJSON 方法,包括输入为 JSON null 的情况。 否则,如果该值实现了 encoding.TextUnmarshaler 且输入是一个 JSON 带引号字符串,Unmarshal 会以该字符串去引号后的形式调用 encoding.TextUnmarshaler.UnmarshalText。

将 JSON 反序列化到结构体时,Unmarshal 会将传入的对象键与 Marshal 所用的 键(结构体字段名或其标签)进行匹配,忽略大小写。如果多个结构体字段与某个 对象键匹配,则优先选择大小写完全匹配的字段,而不是不区分大小写匹配的字段。

传入的对象成员按观察到的顺序处理。如果对象包含重复的键,后出现的重复项 将替换或合并到先前的值中。

将 JSON 反序列化到接口值时,Unmarshal 会在该接口值中存储以下之一:

将 JSON 数组反序列化到切片时,Unmarshal 会将切片长度重置为零,然后逐个 将元素追加到切片。作为一种特殊情况,将空 JSON 数组反序列化到切片时, Unmarshal 会用一个新的空切片替换该切片。

将 JSON 数组反序列化到 Go 数组时,Unmarshal 会将 JSON 数组元素解码到 对应的 Go 数组元素中。如果 Go 数组小于 JSON 数组,多余的 JSON 数组元素 会被丢弃。如果 JSON 数组小于 Go 数组,多余的 Go 数组元素会被设为零值。

将 JSON 对象反序列化到映射时,Unmarshal 首先建立一个要使用的映射。 如果映射为 nil,Unmarshal 会分配一个新映射。否则 Unmarshal 会复用现有 映射,保留已有的条目。然后 Unmarshal 将 JSON 对象中的键值对存储到映射中。 映射的键类型必须为任意字符串类型、整数,或实现了 encoding.TextUnmarshaler。

如果 JSON 编码的数据包含语法错误,Unmarshal 返回一个 SyntaxError。

如果某个 JSON 值不适合给定的目标类型,或者某个 JSON 数字溢出了目标类型, Unmarshal 会跳过该字段并尽可能完成反序列化。如果没有遇到更严重的错误, Unmarshal 会返回一个 UnmarshalTypeError,描述最早出现的此类错误。 在任何情况下,都不能保证问题字段之后所有剩余字段都会被反序列化到目标对象中。

JSON null 值反序列化到接口、映射、指针或切片时,会将该 Go 值设为 nil。 由于 null 在 JSON 中常用来表示“不存在”,将 JSON null 反序列化到任何其他 Go 类型都不会对值产生影响,也不会产生错误。

反序列化带引号的字符串时,无效的 UTF-8 或无效的 UTF-16 代理对不会被视为 错误。它们会被替换为 Unicode 替换字符 U+FFFD。

Example
package main

import (
	"fmt"

	"encoding/json"
)

func main() {
	var jsonBlob = []byte(`[
	{"Name": "Platypus", "Order": "Monotremata"},
	{"Name": "Quoll",    "Order": "Dasyuromorphia"}
]`)
	type Animal struct {
		Name  string
		Order string
	}
	var animals []Animal
	err := json.Unmarshal(jsonBlob, &animals)
	if err != nil {
		fmt.Println("error:", err)
	}
	fmt.Printf("%+v", animals)
}

Output:

[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
Example
package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	var jsonBlob = []byte(`[
	{"Name": "Platypus", "Order": "Monotremata"},
	{"Name": "Quoll",    "Order": "Dasyuromorphia"}
]`)
	type Animal struct {
		Name  string
		Order string
	}
	var animals []Animal
	err := json.Unmarshal(jsonBlob, &animals)
	if err != nil {
		fmt.Println("error:", err)
	}
	fmt.Printf("%+v", animals)
}

Output:

[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]

func Valid

func Valid(data []byte) bool

Valid 报告 data 是否是有效的 JSON 编码。

Example
package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	goodJSON := `{"example": 1}`
	badJSON := `{"example":2:]}}`

	fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON)))
}

Output:

true false
Example
package main

import (
	"fmt"

	"encoding/json"
)

func main() {
	goodJSON := `{"example": 1}`
	badJSON := `{"example":2:]}}`

	fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON)))
}

Output:

true false

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder 从输入流中读取并解码 JSON 值。

Example

This example uses a Decoder to decode a stream of distinct JSON values.

package main

import (
	"fmt"
	"io"
	"log"
	"strings"

	"encoding/json"
)

func main() {
	const jsonStream = `
	{"Name": "Ed", "Text": "Knock knock."}
	{"Name": "Sam", "Text": "Who's there?"}
	{"Name": "Ed", "Text": "Go fmt."}
	{"Name": "Sam", "Text": "Go fmt who?"}
	{"Name": "Ed", "Text": "Go fmt yourself!"}
`
	type Message struct {
		Name, Text string
	}
	dec := json.NewDecoder(strings.NewReader(jsonStream))
	for {
		var m Message
		if err := dec.Decode(&m); err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%s: %s\n", m.Name, m.Text)
	}
}

Output:

Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!
Example

This example uses a Decoder to decode a stream of distinct JSON values.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	const jsonStream = `
	{"Name": "Ed", "Text": "Knock knock."}
	{"Name": "Sam", "Text": "Who's there?"}
	{"Name": "Ed", "Text": "Go fmt."}
	{"Name": "Sam", "Text": "Go fmt who?"}
	{"Name": "Ed", "Text": "Go fmt yourself!"}
`
	type Message struct {
		Name, Text string
	}
	dec := json.NewDecoder(strings.NewReader(jsonStream))
	for {
		var m Message
		if err := dec.Decode(&m); err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%s: %s\n", m.Name, m.Text)
	}
}

Output:

Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!
func NewDecoder
func NewDecoder(r io.Reader) *Decoder

NewDecoder 返回一个从 r 读取数据的新解码器。

该解码器会引入自己的缓冲,并可能从 r 读取 超出所请求 JSON 值的数据。

func (*Decoder) Buffered
func (dec *Decoder) Buffered() io.Reader

Buffered 返回 Decoder 缓冲区中剩余数据的读取器。 该读取器在下次调用 Decoder.Decode 之前有效。

func (*Decoder) Decode
func (dec *Decoder) Decode(v any) error

Decode 从其输入中读取下一个经过 JSON 编码的值, 并将其存储到 v 指向的值中。

有关将 JSON 转换为 Go 值的详细信息, 请参见 Unmarshal 的文档。

Example (Stream)

This example uses a Decoder to decode a streaming array of JSON objects.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"strings"
)

func main() {
	const jsonStream = `
	[
		{"Name": "Ed", "Text": "Knock knock."},
		{"Name": "Sam", "Text": "Who's there?"},
		{"Name": "Ed", "Text": "Go fmt."},
		{"Name": "Sam", "Text": "Go fmt who?"},
		{"Name": "Ed", "Text": "Go fmt yourself!"}
	]
`
	type Message struct {
		Name, Text string
	}
	dec := json.NewDecoder(strings.NewReader(jsonStream))

	// read open bracket
	t, err := dec.Token()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%T: %v\n", t, t)

	// while the array contains values
	for dec.More() {
		var m Message
		// decode an array value (Message)
		err := dec.Decode(&m)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Printf("%v: %v\n", m.Name, m.Text)
	}

	// read closing bracket
	t, err = dec.Token()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%T: %v\n", t, t)

}

Output:

json.Delim: [
Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!
json.Delim: ]
Example (Stream)

This example uses a Decoder to decode a streaming array of JSON objects.

package main

import (
	"fmt"
	"log"
	"strings"

	"encoding/json"
)

func main() {
	const jsonStream = `
	[
		{"Name": "Ed", "Text": "Knock knock."},
		{"Name": "Sam", "Text": "Who's there?"},
		{"Name": "Ed", "Text": "Go fmt."},
		{"Name": "Sam", "Text": "Go fmt who?"},
		{"Name": "Ed", "Text": "Go fmt yourself!"}
	]
`
	type Message struct {
		Name, Text string
	}
	dec := json.NewDecoder(strings.NewReader(jsonStream))

	// read open bracket
	t, err := dec.Token()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%T: %v\n", t, t)

	// while the array contains values
	for dec.More() {
		var m Message
		// decode an array value (Message)
		err := dec.Decode(&m)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Printf("%v: %v\n", m.Name, m.Text)
	}

	// read closing bracket
	t, err = dec.Token()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%T: %v\n", t, t)

}

Output:

json.Delim: [
Ed: Knock knock.
Sam: Who's there?
Ed: Go fmt.
Sam: Go fmt who?
Ed: Go fmt yourself!
json.Delim: ]
func (*Decoder) DisallowUnknownFields
func (dec *Decoder) DisallowUnknownFields()

DisallowUnknownFields 使 Decoder 在目标是结构体且输入包含 与目标中任何非忽略、导出字段都不匹配的对象键时返回错误。

func (*Decoder) InputOffset
func (dec *Decoder) InputOffset() int64

InputOffset 返回当前解码器位置的输入流字节偏移量。 该偏移量给出了最近返回的 token 的末尾和下一个 token 的开头的位置。

func (*Decoder) More
func (dec *Decoder) More() bool

More 报告当前正在解析的数组或对象中是否还有另一个元素。

func (*Decoder) Token
func (dec *Decoder) Token() (Token, error)

Token 返回输入流中的下一个 JSON token。 在输入流末尾,Token 返回 nil, io.EOF。

Token 保证其返回的分隔符 [ ] { } 被正确嵌套和匹配: 如果 Token 在输入中遇到意外的分隔符,它将返回错误。

输入流由基本 JSON 值——bool、string、number 和 null—— 以及标记数组和对象开始与结束的 Delim 类型的分隔符 [ ] { } 组成。 逗号和冒号会被省略。

Example

This example uses a Decoder to decode a stream of distinct JSON values.

package main

import (
	"fmt"
	"io"
	"log"
	"strings"

	"encoding/json"
)

func main() {
	const jsonStream = `
	{"Message": "Hello", "Array": [1, 2, 3], "Null": null, "Number": 1.234}
`
	dec := json.NewDecoder(strings.NewReader(jsonStream))
	for {
		t, err := dec.Token()
		if err == io.EOF {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%T: %v", t, t)
		if dec.More() {
			fmt.Printf(" (more)")
		}
		fmt.Printf("\n")
	}
}

Output:

json.Delim: { (more)
string: Message (more)
string: Hello (more)
string: Array (more)
json.Delim: [ (more)
float64: 1 (more)
float64: 2 (more)
float64: 3
json.Delim: ] (more)
string: Null (more)
<nil>: <nil> (more)
string: Number (more)
float64: 1.234
json.Delim: }
Example

This example uses a Decoder to decode a stream of distinct JSON values.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	const jsonStream = `
	{"Message": "Hello", "Array": [1, 2, 3], "Null": null, "Number": 1.234}
`
	dec := json.NewDecoder(strings.NewReader(jsonStream))
	for {
		t, err := dec.Token()
		if err == io.EOF {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%T: %v", t, t)
		if dec.More() {
			fmt.Printf(" (more)")
		}
		fmt.Printf("\n")
	}
}

Output:

json.Delim: { (more)
string: Message (more)
string: Hello (more)
string: Array (more)
json.Delim: [ (more)
float64: 1 (more)
float64: 2 (more)
float64: 3
json.Delim: ] (more)
string: Null (more)
<nil>: <nil> (more)
string: Number (more)
float64: 1.234
json.Delim: }
func (*Decoder) UseNumber
func (dec *Decoder) UseNumber()

UseNumber 使 Decoder 将数字反序列化为 interface 值时 使用 Number 而不是 float64。

type Delim

type Delim rune

Delim 是一个 JSON 数组或对象分隔符,为 [ ] { 或 } 之一。

func (Delim) String
func (d Delim) String() string

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder 将 JSON 值写入输出流。

func NewEncoder
func NewEncoder(w io.Writer) *Encoder

NewEncoder 返回一个写入 w 的新编码器。

func (*Encoder) Encode
func (enc *Encoder) Encode(v any) error

Encode 将 v 的 JSON 编码写入流, 去掉无意义的空白字符, 并在末尾追加一个换行符。

有关将 Go 值转换为 JSON 的详细信息, 请参见 Marshal 的文档。

func (*Encoder) SetEscapeHTML
func (enc *Encoder) SetEscapeHTML(on bool)

SetEscapeHTML 指定是否应在 JSON 引号字符串内 转义有问题的 HTML 字符。 默认行为是将 &、< 和 > 转义为 \u0026、\u003c 和 \u003e, 以避免在 HTML 中嵌入 JSON 时可能出现的某些安全问题。

在转义会影响输出可读性的非 HTML 环境中, SetEscapeHTML(false) 会禁用此行为。

func (*Encoder) SetIndent
func (enc *Encoder) SetIndent(prefix, indent string)

SetIndent 指示编码器将后续每个编码值格式化, 就像由包级函数 Indent(dst, src, prefix, indent) 缩进一样。 调用 SetIndent("", "") 会禁用缩进。

type InvalidUTF8Error deprecated

type InvalidUTF8Error struct {
	S string // 导致该错误的整个字符串值
}

在 Go 1.2 之前,当尝试编码包含无效 UTF-8 序列的字符串值时, Marshal 会返回一个 InvalidUTF8Error。 从 Go 1.2 起,Marshal 改为通过将无效字节替换为 Unicode 替换字符 U+FFFD 来将该字符串强制转换为有效 UTF-8。

Deprecated: 不再使用;保留仅为保持兼容性。

func (*InvalidUTF8Error) Error
func (e *InvalidUTF8Error) Error() string

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

InvalidUnmarshalError 描述传递给 Unmarshal 的无效参数。 (Unmarshal 的参数必须是非 nil 指针。)

func (*InvalidUnmarshalError) Error
func (e *InvalidUnmarshalError) Error() string

type Marshaler

type Marshaler interface {
	MarshalJSON() ([]byte, error)
}

Marshaler 是由能够将自身序列化为有效 JSON 的类型所实现的接口。

type MarshalerError

type MarshalerError struct {
	Type reflect.Type
	Err  error
	// contains filtered or unexported fields
}

MarshalerError 表示调用 Marshaler.MarshalJSON 或 encoding.TextMarshaler.MarshalText 方法时产生的错误。

func (*MarshalerError) Error
func (e *MarshalerError) Error() string
func (*MarshalerError) Unwrap
func (e *MarshalerError) Unwrap() error

Unwrap 返回底层错误。

type Number

type Number string

Number 表示一个 JSON 数字字面量。

func (Number) Float64
func (n Number) Float64() (float64, error)

Float64 将该数字以 float64 返回。

func (Number) Int64
func (n Number) Int64() (int64, error)

Int64 将该数字以 int64 返回。

func (Number) String
func (n Number) String() string

String 返回该数字的字面量文本。

type RawMessage

type RawMessage []byte

RawMessage 是一个原始的编码 JSON 值。 它实现了 Marshaler 和 Unmarshaler, 可用于延迟 JSON 解码或预计算 JSON 编码。

Example (Marshal)

This example uses RawMessage to use a precomputed JSON during marshal.

package main

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

func main() {
	h := json.RawMessage(`{"precomputed": true}`)

	c := struct {
		Header *json.RawMessage `json:"header"`
		Body   string           `json:"body"`
	}{Header: &h, Body: "Hello Gophers!"}

	b, err := json.MarshalIndent(&c, "", "\t")
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)

}

Output:

{
	"header": {
		"precomputed": true
	},
	"body": "Hello Gophers!"
}
Example (Marshal)

This example uses RawMessage to use a precomputed JSON during marshal.

package main

import (
	"fmt"
	"os"

	"encoding/json"
)

func main() {
	h := json.RawMessage(`{"precomputed": true}`)

	c := struct {
		Header *json.RawMessage `json:"header"`
		Body   string           `json:"body"`
	}{Header: &h, Body: "Hello Gophers!"}

	b, err := json.MarshalIndent(&c, "", "\t")
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)

}

Output:

{
	"header": {
		"precomputed": true
	},
	"body": "Hello Gophers!"
}
Example (Unmarshal)

This example uses RawMessage to delay parsing part of a JSON message.

package main

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

func main() {
	type Color struct {
		Space string
		Point json.RawMessage // delay parsing until we know the color space
	}
	type RGB struct {
		R uint8
		G uint8
		B uint8
	}
	type YCbCr struct {
		Y  uint8
		Cb int8
		Cr int8
	}

	var j = []byte(`[
	{"Space": "YCbCr", "Point": {"Y": 255, "Cb": 0, "Cr": -10}},
	{"Space": "RGB",   "Point": {"R": 98, "G": 218, "B": 255}}
]`)
	var colors []Color
	err := json.Unmarshal(j, &colors)
	if err != nil {
		log.Fatalln("error:", err)
	}

	for _, c := range colors {
		var dst any
		switch c.Space {
		case "RGB":
			dst = new(RGB)
		case "YCbCr":
			dst = new(YCbCr)
		}
		err := json.Unmarshal(c.Point, dst)
		if err != nil {
			log.Fatalln("error:", err)
		}
		fmt.Println(c.Space, dst)
	}
}

Output:

YCbCr &{255 0 -10}
RGB &{98 218 255}
Example (Unmarshal)

This example uses RawMessage to delay parsing part of a JSON message.

package main

import (
	"fmt"
	"log"

	"encoding/json"
)

func main() {
	type Color struct {
		Space string
		Point json.RawMessage // delay parsing until we know the color space
	}
	type RGB struct {
		R uint8
		G uint8
		B uint8
	}
	type YCbCr struct {
		Y  uint8
		Cb int8
		Cr int8
	}

	var j = []byte(`[
	{"Space": "YCbCr", "Point": {"Y": 255, "Cb": 0, "Cr": -10}},
	{"Space": "RGB",   "Point": {"R": 98, "G": 218, "B": 255}}
]`)
	var colors []Color
	err := json.Unmarshal(j, &colors)
	if err != nil {
		log.Fatalln("error:", err)
	}

	for _, c := range colors {
		var dst any
		switch c.Space {
		case "RGB":
			dst = new(RGB)
		case "YCbCr":
			dst = new(YCbCr)
		}
		err := json.Unmarshal(c.Point, dst)
		if err != nil {
			log.Fatalln("error:", err)
		}
		fmt.Println(c.Space, dst)
	}
}

Output:

YCbCr &{255 0 -10}
RGB &{98 218 255}
func (RawMessage) MarshalJSON
func (m RawMessage) MarshalJSON() ([]byte, error)

MarshalJSON 返回 m 作为 m 的 JSON 编码。

func (*RawMessage) UnmarshalJSON
func (m *RawMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON 将 *m 设置为 data 的副本。

type SyntaxError

type SyntaxError struct {
	Offset int64 // 错误发生在读取 Offset 个字节之后
	// contains filtered or unexported fields
}

SyntaxError 是对 JSON 语法错误的描述。 如果 JSON 无法被解析,Unmarshal 将返回 SyntaxError。

func (*SyntaxError) Error
func (e *SyntaxError) Error() string

type Token

type Token any

Token 持有以下类型之一的值:

type UnmarshalFieldError deprecated

type UnmarshalFieldError struct {
	Key   string
	Type  reflect.Type
	Field reflect.StructField
}

UnmarshalFieldError 描述一个导致未导出(因此不可写)结构体字段的 JSON 对象键。

Deprecated: 不再使用;保留仅为保持兼容性。

func (*UnmarshalFieldError) Error
func (e *UnmarshalFieldError) Error() string

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value  string       // JSON 值的描述 - "bool"、"array"、"number -5"
	Type   reflect.Type // 它无法赋值到的 Go 值的类型
	Offset int64        // 读取 Offset 字节后发生错误
	Struct string       // 包含该字段的结构体类型名称
	Field  string       // 从根节点到该字段的完整路径,包含内嵌结构体
}

UnmarshalTypeError 描述一个不适合某个特定 Go 类型值的 JSON 值。

func (*UnmarshalTypeError) Error
func (e *UnmarshalTypeError) Error() string

type Unmarshaler

type Unmarshaler interface {
	UnmarshalJSON([]byte) error
}

Unmarshaler 是由能够反序列化自身 JSON 描述的类型所实现的接口。 可以假定输入是某个 JSON 值的有效编码。如果 UnmarshalJSON 希望在返回后 保留数据,它必须复制 JSON 数据。

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

UnsupportedTypeError 在尝试编码不受支持的值类型时由 Marshal 返回。

func (*UnsupportedTypeError) Error
func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError

type UnsupportedValueError struct {
	Value reflect.Value
	Str   string
}

UnsupportedValueError 在尝试编码不受支持的值时由 Marshal 返回。

func (*UnsupportedValueError) Error
func (e *UnsupportedValueError) Error() string