Package json

import "encoding/json"
Overview
Index
Examples

Overview ▾

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

有关此程序包的介绍,请参见" JSON和Go": https : //golang.org/doc/articles/json_and_go.html

示例(CustomMarshalJSON)

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3

示例(TextMarshalJSON)

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

Index ▾

func Compact(dst *bytes.Buffer, src []byte) error
func HTMLEscape(dst *bytes.Buffer, src []byte)
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
func Valid(data []byte) bool
type Decoder
    func NewDecoder(r io.Reader) *Decoder
    func (dec *Decoder) Buffered() io.Reader
    func (dec *Decoder) Decode(v interface{}) error
    func (dec *Decoder) DisallowUnknownFields()
    func (dec *Decoder) More() bool
    func (dec *Decoder) Token() (Token, error)
    func (dec *Decoder) UseNumber()
type Delim
    func (d Delim) String() string
type Encoder
    func NewEncoder(w io.Writer) *Encoder
    func (enc *Encoder) Encode(v interface{}) error
    func (enc *Encoder) SetEscapeHTML(on bool)
    func (enc *Encoder) SetIndent(prefix, indent string)
type InvalidUTF8Error
    func (e *InvalidUTF8Error) Error() string
type InvalidUnmarshalError
    func (e *InvalidUnmarshalError) Error() string
type Marshaler
type MarshalerError
    func (e *MarshalerError) Error() string
    func (e *MarshalerError) Unwrap() error
type Number
    func (n Number) Float64() (float64, error)
    func (n Number) Int64() (int64, error)
    func (n Number) String() string
type RawMessage
    func (m RawMessage) MarshalJSON() ([]byte, error)
    func (m *RawMessage) UnmarshalJSON(data []byte) error
type SyntaxError
    func (e *SyntaxError) Error() string
type Token
type UnmarshalFieldError
    func (e *UnmarshalFieldError) Error() string
type UnmarshalTypeError
    func (e *UnmarshalTypeError) Error() string
type Unmarshaler
type UnsupportedTypeError
    func (e *UnsupportedTypeError) Error() string
type UnsupportedValueError
    func (e *UnsupportedValueError) Error() string

Package files

decode.go encode.go fold.go indent.go scanner.go stream.go tables.go tags.go

func Compact

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

Compact将dst附加到JSON编码的src,并省略了不重要的空格字符.

func HTMLEscape

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

HTMLEscape在字符串文字中将<,>,&,U + 2028和U + 2029字符附加到dst的JSON编码的src更改为\ u003c,\ u003e,\ u0026,\ u2028,\ u2029,以便JSON安全嵌入HTML <script>标记中. 由于历史原因,Web浏览器不支持<script>标记内的标准HTML转义,因此必须使用替代的JSON编码.

Example

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

func Indent

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

缩进将JSON编码的src的缩进形式附加到dst. JSON对象或数组中的每个元素都从一个新的缩进行开始,该行以前缀开头,然后根据缩进嵌套嵌套一个或多个缩进副本. 附加到dst的数据不以前缀或任何缩进开头,以便更轻松地嵌入其他格式化的JSON数据中. 尽管删除了src开头的前导空格字符(空格,制表符,回车符,换行符),但保留了src末尾的结尾空格字符并将其复制到dst. 例如,如果src没有尾随空格,则dst都不会; 如果src以结尾的换行符结尾,则dst也是如此.

Example

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

func Marshal

func Marshal(v interface{}) ([]byte, error)

元帅返回v的JSON编码.

Marshal traverses the value v recursively. If an encountered value implements the Marshaler interface and is not a nil pointer, Marshal calls its MarshalJSON method to produce JSON. If no MarshalJSON method is present but the value implements encoding.TextMarshaler instead, Marshal calls its MarshalText method and encodes the result as a JSON string. The nil pointer exception is not strictly necessary but mimics a similar, necessary exception in the behavior of UnmarshalJSON.

否则,元帅将使用以下类型相关的默认编码:

布尔值编码为JSON布尔值.

浮点数,整数和数字值编码为JSON数字.

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

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

结构值编码为JSON对象. 每个导出的struct字段都将使用字段名称作为对象关键字,成为对象的成员,除非出于以下原因之一省略了该字段.

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

" omitempty"选项指定如果字段具有空值(定义为false,0,nil指针,nil接口值以及任何空数组,切片,映射或字符串),则应将该字段从编码中省略.

作为特殊情况,如果字段标记为"-",则始终会省略该字段. 请注意,仍可以使用标签"-"来生成名称为"-"的字段.

struct字段标签及其含义的示例:

// Field appears in JSON as key "myName".
Field int `json:"myName"`

// Field appears in JSON as key "myName" and
// the field is omitted from the object if its value is empty,
// as defined above.
Field int `json:"myName,omitempty"`

// Field appears in JSON as key "Field" (the default), but
// the field is skipped if empty.
// Note the leading comma.
Field int `json:",omitempty"`

// Field is ignored by this package.
Field int `json:"-"`

// Field appears in JSON as key "-".
Field int `json:"-,"`

"字符串"选项表示字段在JSON编码的字符串中存储为JSON. 它仅适用于字符串,浮点,整数或布尔类型的字段. 与JavaScript程序进行通信时,有时会使用这种额外的编码级别:

Int64String int64 `json:",string"`

如果密钥名称是一个非空字符串,仅包含Unicode字母,数字和ASCII标点(引号,反斜杠和逗号除外),则将使用该密钥名.

匿名结构域通常被封送起来,就像它们的内部导出域是外部结构中的域一样,但要遵守下一段所述的通常Go可见性规则的修订. 在其JSON标记中具有名称的匿名struct字段被视为具有该名称,而不是匿名的. 接口类型的匿名struct字段被视为与该类型的名称相同,而不是匿名的.

The Go visibility rules for struct fields are amended for JSON when deciding which field to marshal or unmarshal. If there are multiple fields at the same level, and that level is the least nested (and would therefore be the nesting level selected by the usual Go rules), the following extra rules apply:

1)在这些字段中,如果有任何字段带有JSON标记,则即使存在多个否则会发生冲突的未标记字段,也仅考虑标记的字段.

2)如果正好有一个字段(根据第一条规则标记或未标记),则将其选中.

3)否则存在多个字段,所有字段都将被忽略; 没有错误发生.

Go 1.1中新增了处理匿名结构字段的功能. 在Go 1.1之前,匿名结构字段被忽略. 要在当前版本和早期版本中强制忽略匿名struct字段,请为该字段指定JSON标签"-".

映射值编码为JSON对象. 映射的键类型必须是字符串,整数类型或实现encoding.TextMarshaler. 通过应用以下规则对映射键进行排序并用作JSON对象键,但要遵守上述针对字符串值描述的UTF-8强制:

- keys of any string type are used directly
- encoding.TextMarshalers are marshaled
- integer keys are converted to strings

指针值编码为指向的值. nil指针编码为空JSON值.

接口值编码为接口中包含的值. nil接口值编码为空JSON值.

通道,复杂和函数值不能用JSON编码. 尝试对这样的值进行编码会导致Marshal返回UnsupportedTypeError.

JSON cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures to Marshal will result in an infinite recursion.

Example

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

func MarshalIndent

func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)

MarshalIndent类似于Marshal,但应用Indent格式化输出. 输出中的每个JSON元素都将从换行符开始,以前缀开头,后跟缩进嵌套的一个或多个缩进副本.

Example

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

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

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

Unmarshal使用Marshal使用的编码的倒数,根据需要分配映射,切片和指针,并具有以下附加规则:

为了将JSON解组为一个指针,Unmarshal首先处理JSON为JSON常量null的情况. 在这种情况下,Unmarshal会将指针设置为nil. 否则,Unmarshal会将JSON解组为指针所指向的值. 如果指针为nil,则Unmarshal为其分配一个新值以使其指向.

为了将JSON解组为实现Unmarshaler接口的值,Unmarshal调用该值的UnmarshalJSON方法,包括当输入为JSON null时. 否则,如果该值实现encoding.TextUnmarshaler且输入是带引号的JSON字符串,则Unmarshal会使用该字符串的未引号形式来调用该值的UnmarshalText方法.

为了将JSON解组到结构中,Unmarshal将传入的对象键与Marshal使用的键(结构字段名称或其标记)进行匹配,希望使用精确匹配,但还要接受不区分大小写的匹配. 默认情况下,没有相应结构字段的对象键将被忽略(有关替代方法,请参见Decoder.DisallowUnknownFields).

要将JSON解组为接口值,Unmarshal将其中之一存储在接口值中:

bool, for JSON booleans
float64, for JSON numbers
string, for JSON strings
[]interface{}, for JSON arrays
map[string]interface{}, for JSON objects
nil for JSON null

若要将JSON数组解组为切片,则解组会将切片长度重置为零,然后将每个元素附加到切片. 作为一种特殊情况,要将一个空的JSON数组解组到一个切片中,Unmarshal会用一个新的空切片替换该切片.

为了将JSON数组解组为Go数组,Unmarshal将JSON数组元素解码为对应的Go数组元素. 如果Go数组小于JSON数组,则将丢弃其他JSON数组元素. 如果JSON数组小于Go数组,则将其他Go数组元素设置为零值.

要将JSON对象解组到映射中,解组首先要建立要使用的映射. 如果地图为零,Unmarshal将分配一个新地图. 否则,Unmarshal会重用现有地图,保留现有条目. 然后,解组将来自JSON对象的键/值对存储到映射中. 地图的键类型必须是字符串,整数或实现encoding.TextUnmarshaler.

如果JSON值不适用于给定的目标类型,或者JSON数字溢出目标类型,则Unmarshal会跳过该字段并尽最大可能完成解组. 如果没有遇到更多的严重错误,则Unmarshal返回一个UnmarshalTypeError来描述最早的此类错误. 无论如何,不​​能保证有问题的字段之后的所有其余字段都将被编组到目标对象中.

通过将该Go值设置为nil,JSON空值可解组到接口,映射,指针或切片中. 由于在JSON中通常使用null来表示"不存在",因此将JSON null编组为任何其他Go类型不会影响该值,也不会产生任何错误.

解组带引号的字符串时,无效的UTF-8或无效的UTF-16代理对不会被视为错误. 而是将它们替换为Unicode替换字符U + FFFD.

Example

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

func Valid 1.9

func Valid(data []byte) bool

有效报告数据是否是有效的JSON编码.

Example

true false

type Decoder

解码器从输入流读取和解码JSON值.

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

Example

本示例使用Decoder解码不同JSON值的流.

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 1.1

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

Buffered返回解码器缓冲区中剩余数据的读取器. 读取器在下一次调用Decode之前一直有效.

func (*Decoder) Decode

func (dec *Decoder) Decode(v interface{}) error

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

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

示例(流)

本示例使用Decoder解码JSON对象的流数组.

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 1.10

func (dec *Decoder) DisallowUnknownFields()

当目标是结构并且输入包含与目标中任何未忽略的导出字段都不匹配的对象键时,DisallowUnknownFields会导致解码器返回错误.

func (*Decoder) More 1.5

func (dec *Decoder) More() bool

"更多"报告当前数组或对象中是否存在另一个要解析的元素.

func (*Decoder) Token 1.5

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

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

令牌保证返回的定界符[] {}正确嵌套和匹配:如果令牌在输入中遇到意外的定界符,它将返回错误.

输入流由基本JSON值(布尔,字符串,数字和null)以及Delim类型的定界符[] {}组成,以标记数组和对象的开始和结束. 逗号和冒号被删除.

Example

本示例使用Decoder解码不同JSON值的流.

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 1.1

func (dec *Decoder) UseNumber()

UseNumber使解码器将数字解组到接口{}中,作为数字而不是float64.

type Delim 1.5

Delim是JSON数组或对象定界符,是[] {或}之一.

type Delim rune

func (Delim) String 1.5

func (d Delim) String() string

type Encoder

编码器将JSON值写入输出流.

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

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

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

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode将v的JSON编码写入流,后跟换行符.

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

func (*Encoder) SetEscapeHTML 1.7

func (enc *Encoder) SetEscapeHTML(on bool)

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

在非HTML设置中,转义会干扰输出的可读性,SetEscapeHTML(false)会禁用此行为.

func (*Encoder) SetIndent 1.7

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

SetIndent instructs the encoder to format each subsequent encoded value as if indented by the package-level function Indent(dst, src, prefix, indent). SetIndent指示编码器格式化每个后续编码值,就好像由包级函数Indent(dst,src,prefix,indent)缩进一样. Calling SetIndent("", "") disables indentation. 调用SetIndent("","")禁用缩进.

type InvalidUTF8Error

在Go 1.2之前,Marshal在尝试使用无效的UTF-8序列编码字符串值时返回了InvalidUTF8Error. 从Go 1.2开始,Marshal通过将无效字节替换为Unicode替换符文U + FFFD,将字符串强制为有效UTF-8.

不推荐使用:不再使用; 保持兼容性.

type InvalidUTF8Error struct {
    S string // the whole string value that caused the error
}

func (*InvalidUTF8Error) Error

func (e *InvalidUTF8Error) Error() string

type InvalidUnmarshalError

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

type InvalidUnmarshalError struct {
    Type reflect.Type
}

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type Marshaler

Marshaler是由可以将自己编组为有效JSON的类型实现的接口.

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

type MarshalerError

MarshalerError表示调用MarshalJSON或MarshalText方法导致的错误.

type MarshalerError struct {
    Type reflect.Type
    Err  error
}

func (*MarshalerError) Error

func (e *MarshalerError) Error() string

func (*MarshalerError) Unwrap 1.13

func (e *MarshalerError) Unwrap() error

type Number 1.1

Number表示JSON数字文字.

type Number string

func (Number) Float64 1.1

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

Float64 returns the number as a float64.

func (Number) Int64 1.1

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

Int64将数字返回为int64.

func (Number) String 1.1

func (n Number) String() string

字符串返回数字的文字文本.

type RawMessage

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

type RawMessage []byte

例子(元帅)

本示例在编组期间使用RawMessage来使用预先计算的JSON.

{
	"header": {
		"precomputed": true
	},
	"body": "Hello Gophers!"
}

示例(解组)

本示例使用RawMessage延迟解析JSON消息的一部分.

YCbCr &{255 0 -10}
RGB &{98 218 255}

func (RawMessage) MarshalJSON 1.8

func (m RawMessage) MarshalJSON() ([]byte, error)

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

func (*RawMessage) UnmarshalJSON

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

UnmarshalJSON将* m设置为数据副本.

type SyntaxError

SyntaxError是JSON语法错误的描述.

type SyntaxError struct {
    Offset int64 // error occurred after reading Offset bytes
    // contains filtered or unexported fields
}

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Token 1.5

令牌持有以下类型之一的值:

Delim, for the four JSON delimiters [ ] { }
bool, for JSON booleans
float64, for JSON numbers
Number, for JSON numbers
string, for JSON string literals
nil, for JSON null
type Token interface{}

type UnmarshalFieldError

UnmarshalFieldError描述了导致未导出(因此不可写)结构字段的JSON对象密钥.

不推荐使用:不再使用; 保持兼容性.

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

func (*UnmarshalFieldError) Error

func (e *UnmarshalFieldError) Error() string

type UnmarshalTypeError

UnmarshalTypeError描述了不适用于特定Go类型值的JSON值.

type UnmarshalTypeError struct {
    Value  string       // description of JSON value - "bool", "array", "number -5"
    Type   reflect.Type // type of Go value it could not be assigned to
    Offset int64        // error occurred after reading Offset bytes; added in Go 1.5
    Struct string       // name of the struct type containing the field; added in Go 1.8
    Field  string       // the full path from root node to the field; added in Go 1.8
}

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type Unmarshaler

Unmarshaler是由可以解组自己的JSON描述的类型实现的接口. 可以假定输入是JSON值的有效编码. 如果UnmarshalJSON希望在返回后保留数据,则必须复制JSON数据.

按照约定,为了近似Unmarshal本身的行为,Unmarshalers将UnmarshalJSON([] byte(" null"))实现为无操作.

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

type UnsupportedTypeError

尝试对不支持的值类型进行编码时,元帅将返回UnsupportedTypeError.

type UnsupportedTypeError struct {
    Type reflect.Type
}

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError

type UnsupportedValueError struct {
    Value reflect.Value
    Str   string
}

func (*UnsupportedValueError) Error

func (e *UnsupportedValueError) Error() string

by  ICOPY.SITE