package json · Go 標準庫中文參考

# package json `import "encoding/json"` json包實現了json對象的編解碼，參見[RFC 4627](http://tools.ietf.org/html/rfc4627)。Json對象和go類型的映射關系請參見Marshal和Unmarshal函數的文檔。參見"JSON and Go"獲取本包的一個介紹：[http://golang.org/doc/articles/json_and_go.html](http://golang.org/doc/articles/json_and_go.html) ## Index * [type InvalidUTF8Error](#InvalidUTF8Error) * [func (e \*InvalidUTF8Error) Error() string](#InvalidUTF8Error.Error) * [type InvalidUnmarshalError](#InvalidUnmarshalError) * [func (e \*InvalidUnmarshalError) Error() string](#InvalidUnmarshalError.Error) * [type SyntaxError](#SyntaxError) * [func (e \*SyntaxError) Error() string](#SyntaxError.Error) * [type UnmarshalFieldError](#UnmarshalFieldError) * [func (e \*UnmarshalFieldError) Error() string](#UnmarshalFieldError.Error) * [type UnmarshalTypeError](#UnmarshalTypeError) * [func (e \*UnmarshalTypeError) Error() string](#UnmarshalTypeError.Error) * [type UnsupportedTypeError](#UnsupportedTypeError) * [func (e \*UnsupportedTypeError) Error() string](#UnsupportedTypeError.Error) * [type UnsupportedValueError](#UnsupportedValueError) * [func (e \*UnsupportedValueError) Error() string](#UnsupportedValueError.Error) * [type MarshalerError](#MarshalerError) * [func (e \*MarshalerError) Error() string](#MarshalerError.Error) * [type Number](#Number) * [func (n Number) Int64() (int64, error)](#Number.Int64) * [func (n Number) Float64() (float64, error)](#Number.Float64) * [func (n Number) String() string](#Number.String) * [type RawMessage](#RawMessage) * [func (m \*RawMessage) MarshalJSON() ([]byte, error)](#RawMessage.MarshalJSON) * [func (m \*RawMessage) UnmarshalJSON(data []byte) error](#RawMessage.UnmarshalJSON) * [type Marshaler](#Marshaler) * [type Unmarshaler](#Unmarshaler) * [func Compact(dst \*bytes.Buffer, src []byte) error](#Compact) * [func HTMLEscape(dst \*bytes.Buffer, src []byte)](#HTMLEscape) * [func Indent(dst \*bytes.Buffer, src []byte, prefix, indent string) error](#Indent) * [func Marshal(v interface{}) ([]byte, error)](#Marshal) * [func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)](#MarshalIndent) * [func Unmarshal(data []byte, v interface{}) error](#Unmarshal) * [type Decoder](#Decoder) * [func NewDecoder(r io.Reader) \*Decoder](#NewDecoder) * [func (dec \*Decoder) Buffered() io.Reader](#Decoder.Buffered) * [func (dec \*Decoder) UseNumber()](#Decoder.UseNumber) * [func (dec \*Decoder) Decode(v interface{}) error](#Decoder.Decode) * [type Encoder](#Encoder) * [func NewEncoder(w io.Writer) \*Encoder](#NewEncoder) * [func (enc \*Encoder) Encode(v interface{}) error](#Encoder.Encode) ### Examples * [Decoder](#example-Decoder) * [Indent](#example-Indent) * [Marshal](#example-Marshal) * [RawMessage](#example-RawMessage) * [Unmarshal](#example-Unmarshal) ## type [InvalidUTF8Error](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L220 "View Source") ``` type InvalidUTF8Error struct { S string // 引發錯誤的完整字符串 } ``` Go 1.2之前版本，當試圖編碼一個包含非法utf-8序列的字符串時會返回本錯誤。Go 1.2及之后版本，編碼器會強行將非法字節替換為unicode字符U+FFFD來使字符串合法。本錯誤已不會再出現，但出于向后兼容考慮而保留。 ### func (\*InvalidUTF8Error) [Error](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L224 "View Source") ``` func (e *InvalidUTF8Error) Error() string ``` ## type [InvalidUnmarshalError](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L116 "View Source") ``` type InvalidUnmarshalError struct { Type reflect.Type } ``` InvalidUnmarshalError用于描述一個傳遞給解碼器的非法參數。（解碼器的參數必須是非nil指針） ### func (\*InvalidUnmarshalError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L120 "View Source") ``` func (e *InvalidUnmarshalError) Error() string ``` ## type [SyntaxError](https://github.com/golang/go/blob/master/src/encoding/json/scanner.go#L57 "View Source") ``` type SyntaxError struct { Offset int64 // 在讀取Offset個字節后出現錯誤 // 內含隱藏或非導出字段 } ``` SyntaxError表示一個json語法錯誤。 ### func (\*SyntaxError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/scanner.go#L62 "View Source") ``` func (e *SyntaxError) Error() string ``` ## type [UnmarshalFieldError](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L104 "View Source") ``` type UnmarshalFieldError struct { Key string Type reflect.Type Field reflect.StructField } ``` UnmarshalFieldError表示一個json對象的鍵指向一個非導出字段。（因此不能寫入；已不再使用，出于兼容保留） ### func (\*UnmarshalFieldError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L110 "View Source") ``` func (e *UnmarshalFieldError) Error() string ``` ## type [UnmarshalTypeError](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L92 "View Source") ``` type UnmarshalTypeError struct { Value string // 描述json值："bool", "array", "number -5" Type reflect.Type // 不能轉化為的go類型 } ``` UnmarshalTypeError表示一個json值不能轉化為特定的go類型的值。 ### func (\*UnmarshalTypeError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L97 "View Source") ``` func (e *UnmarshalTypeError) Error() string ``` ## type [UnsupportedTypeError](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L197 "View Source") ``` type UnsupportedTypeError struct { Type reflect.Type } ``` UnsupportedTypeError表示試圖編碼一個不支持類型的值。 ### func (\*UnsupportedTypeError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L201 "View Source") ``` func (e *UnsupportedTypeError) Error() string ``` ## type [UnsupportedValueError](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L205 "View Source") ``` type UnsupportedValueError struct { Value reflect.Value Str string } ``` ### func (\*UnsupportedValueError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L210 "View Source") ``` func (e *UnsupportedValueError) Error() string ``` ## type [MarshalerError](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L228 "View Source") ``` type MarshalerError struct { Type reflect.Type Err error } ``` ### func (\*MarshalerError) [Error](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L233 "View Source") ``` func (e *MarshalerError) Error() string ``` ## type [Number](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L154 "View Source") ``` type Number string ``` Number類型代表一個json數字字面量。 ### func (Number) [Int64](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L165 "View Source") ``` func (n Number) Int64() (int64, error) ``` 將該數字作為int64類型返回。 ### func (Number) [Float64](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L160 "View Source") ``` func (n Number) Float64() (float64, error) ``` 將該數字作為float64類型返回。 ### func (Number) [String](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L157 "View Source") ``` func (n Number) String() string ``` 返回該數字的字面值文本表示。 ## type [RawMessage](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L184 "View Source") ``` type RawMessage []byte ``` RawMessage類型是一個保持原本編碼的json對象。本類型實現了Marshaler和Unmarshaler接口，用于延遲json的解碼或者預計算json的編碼。 Example ``` 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 interface{} 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](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L187 "View Source") ``` func (m *RawMessage) MarshalJSON() ([]byte, error) ``` MarshalJSON返回\*m的json編碼。 ### func (\*RawMessage) [UnmarshalJSON](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L192 "View Source") ``` func (m *RawMessage) UnmarshalJSON(data []byte) error ``` UnmarshalJSON將\*m設為data的一個拷貝。 ## type [Marshaler](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L191 "View Source") ``` type Marshaler interface { MarshalJSON() ([]byte, error) } ``` 實現了Marshaler接口的類型可以將自身序列化為合法的json描述。 ## type [Unmarshaler](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L86 "View Source") ``` type Unmarshaler interface { UnmarshalJSON([]byte) error } ``` 實現了Unmarshaler接口的對象可以將自身的json描述反序列化。該方法可以認為輸入是合法的json字符串。如果要在方法返回后保存自身的json數據，必須進行拷貝。 ## func [Compact](https://github.com/golang/go/blob/master/src/encoding/json/indent.go#L11 "View Source") ``` func Compact(dst *bytes.Buffer, src []byte) error ``` Compact函數將json編碼的src中無用的空白字符剔除后寫入dst。 ## func [HTMLEscape](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L160 "View Source") ``` func HTMLEscape(dst *bytes.Buffer, src []byte) ``` HTMLEscape?函數將json編碼的src中的<、>、&、U+2028?和U+2029字符替換為\u003c、\u003e、\u0026、\u2028、\u2029?轉義字符串，以便json編碼可以安全的嵌入HTML的<script>標簽里。因為歷史原因，網絡瀏覽器不支持在<script>標簽中使用標準HTML轉義，?因此必須使用另一種json編碼方案。 ## func [Indent](https://github.com/golang/go/blob/master/src/encoding/json/indent.go#L75 "View Source") ``` func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error ``` Indent函數將json編碼的調整縮進之后寫入dst。每一個json元素/數組都另起一行開始，以prefix為起始，一或多個indent縮進（數目看嵌套層數）。寫入dst的數據起始沒有prefix字符，也沒有indent字符，最后也不換行，因此可以更好的嵌入其他格式化后的json數據里。 Example ``` 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](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L131 "View Source") ``` func Marshal(v interface{}) ([]byte, error) ``` Marshal函數返回v的json編碼。 Marshal函數會遞歸的處理值。如果一個值實現了Marshaler接口切非nil指針，會調用其MarshalJSON方法來生成json編碼。nil指針異常并不是嚴格必需的，但會模擬與UnmarshalJSON的行為類似的必需的異常。否則，Marshal函數使用下面的基于類型的默認編碼格式：布爾類型編碼為json布爾類型。浮點數、整數和Number類型的值編碼為json數字類型。字符串編碼為json字符串。角括號"<"和">"會轉義為"\u003c"和"\u003e"以避免某些瀏覽器吧json輸出錯誤理解為HTML。基于同樣的原因，"&"轉義為"\u0026"。數組和切片類型的值編碼為json數組，但[]byte編碼為base64編碼字符串，nil切片編碼為null。結構體的值編碼為json對象。每一個導出字段變成該對象的一個成員，除非： ``` - 字段的標簽是"-" - 字段是空值，而其標簽指定了omitempty選項 ``` 空值是false、0、""、nil指針、nil接口、長度為0的數組、切片、映射。對象默認鍵字符串是結構體的字段名，但可以在結構體字段的標簽里指定。結構體標簽值里的"json"鍵為鍵名，后跟可選的逗號和選項，舉例如下： ``` // 字段被本包忽略 Field int `json:"-"` // 字段在json里的鍵為"myName" Field int `json:"myName"` // 字段在json里的鍵為"myName"且如果字段為空值將在對象中省略掉 Field int `json:"myName,omitempty"` // 字段在json里的鍵為"Field"（默認值），但如果字段為空值會跳過；注意前導的逗號 Field int `json:",omitempty"` ``` "string"選項標記一個字段在編碼json時應編碼為字符串。它只適用于字符串、浮點數、整數類型的字段。這個額外水平的編碼選項有時候會用于和javascript程序交互： ``` Int64String int64 `json:",string"` ``` 如果鍵名是只含有unicode字符、數字、美元符號、百分號、連字符、下劃線和斜杠的非空字符串，將使用它代替字段名。匿名的結構體字段一般序列化為他們內部的導出字段就好像位于外層結構體中一樣。如果一個匿名結構體字段的標簽給其提供了鍵名，則會使用鍵名代替字段名，而不視為匿名。 Go結構體字段的可視性規則用于供json決定那個字段應該序列化或反序列化時是經過修正了的。如果同一層次有多個（匿名）字段且該層次是最小嵌套的（嵌套層次則使用默認go規則），會應用如下額外規則： 1）json標簽為"-"的匿名字段強行忽略，不作考慮； 2）json標簽提供了鍵名的匿名字段，視為非匿名字段； 3）其余字段中如果只有一個匿名字段，則使用該字段； 4）其余字段中如果有多個匿名字段，但壓平后不會出現沖突，所有匿名字段壓平； 5）其余字段中如果有多個匿名字段，但壓平后出現沖突，全部忽略，不產生錯誤。對匿名結構體字段的管理是從go1.1開始的，在之前的版本，匿名字段會直接忽略掉。映射類型的值編碼為json對象。映射的鍵必須是字符串，對象的鍵直接使用映射的鍵。指針類型的值編碼為其指向的值（的json編碼）。nil指針編碼為null。接口類型的值編碼為接口內保持的具體類型的值（的json編碼）。nil接口編碼為null。通道、復數、函數類型的值不能編碼進json。嘗試編碼它們會導致Marshal函數返回UnsupportedTypeError。 Json不能表示循環的數據結構，將一個循環的結構提供給Marshal函數會導致無休止的循環。 Example ``` 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](https://github.com/golang/go/blob/master/src/encoding/json/encode.go#L141 "View Source") ``` func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error) ``` MarshalIndent類似Marshal但會使用縮進將輸出格式化。 ## func [Unmarshal](https://github.com/golang/go/blob/master/src/encoding/json/decode.go#L67 "View Source") ``` func Unmarshal(data []byte, v interface{}) error ``` Unmarshal函數解析json編碼的數據并將結果存入v指向的值。 Unmarshal和Marshal做相反的操作，必要時申請映射、切片或指針，有如下的附加規則：要將json數據解碼寫入一個指針，Unmarshal函數首先處理json數據是json字面值null的情況。此時，函數將指針設為nil；否則，函數將json數據解碼寫入指針指向的值；如果指針本身是nil，函數會先申請一個值并使指針指向它。要將json數據解碼寫入一個結構體，函數會匹配輸入對象的鍵和Marshal使用的鍵（結構體字段名或者它的標簽指定的鍵名），優先選擇精確的匹配，但也接受大小寫不敏感的匹配。要將json數據解碼寫入一個接口類型值，函數會將數據解碼為如下類型寫入接口： ``` Bool 對應JSON布爾類型 float64 對應JSON數字類型 string 對應JSON字符串類型 []interface{} 對應JSON數組 map[string]interface{} 對應JSON對象 nil 對應JSON的null ``` 如果一個JSON值不匹配給出的目標類型，或者如果一個json數字寫入目標類型時溢出，Unmarshal函數會跳過該字段并盡量完成其余的解碼操作。如果沒有出現更加嚴重的錯誤，本函數會返回一個描述第一個此類錯誤的詳細信息的UnmarshalTypeError。 JSON的null值解碼為go的接口、指針、切片時會將它們設為nil，因為null在json里一般表示“不存在”。?解碼json的null值到其他go類型時，不會造成任何改變，也不會產生錯誤。當解碼字符串時，不合法的utf-8或utf-16代理（字符）對不視為錯誤，而是將非法字符替換為unicode字符U+FFFD。 Example ``` 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}] ``` ## type [Decoder](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L14 "View Source") ``` type Decoder struct { // 內含隱藏或非導出字段 } ``` Decoder從輸入流解碼json對象 Example ``` 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](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L26 "View Source") ``` func NewDecoder(r io.Reader) *Decoder ``` NewDecoder創建一個從r讀取并解碼json對象的\*Decoder，解碼器有自己的緩沖，并可能超前讀取部分json數據。 ### func (\*Decoder) [Buffered](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L64 "View Source") ``` func (dec *Decoder) Buffered() io.Reader ``` Buffered方法返回保存在dec緩存里數據的讀取器，該返回值在下次調用Decode方法之前有效。 ### func (\*Decoder) [UseNumber](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L32 "View Source") ``` func (dec *Decoder) UseNumber() ``` UseNumber方法將dec設置為當接收端是interface{}接口時將json數字解碼為Number類型而不是float64類型 ### func (\*Decoder) [Decode](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L39 "View Source") ``` func (dec *Decoder) Decode(v interface{}) error ``` Decode從輸入流讀取下一個json編碼值并保存在v指向的值里，參見Unmarshal函數的文檔獲取細節信息。 ## type [Encoder](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L140 "View Source") ``` type Encoder struct { // 內含隱藏或非導出字段 } ``` Encoder將json對象寫入輸出流。 ### func [NewEncoder](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L147 "View Source") ``` func NewEncoder(w io.Writer) *Encoder ``` NewEncoder創建一個將數據寫入w的\*Encoder。 ### func (\*Encoder) [Encode](https://github.com/golang/go/blob/master/src/encoding/json/stream.go#L156 "View Source") ``` func (enc *Encoder) Encode(v interface{}) error ``` Encode將v的json編碼寫入輸出流，并會寫入一個換行符，參見Marshal函數的文檔獲取細節信息。