Пакет json
Обзор
Пакет json реализует кодирование и декодирование JSON, как определено в RFC 7159. Сопоставление между JSON и значениями Go описано в документации для функций Marshal и Unmarshal.
См. «JSON и Go» для введения в этот пакет: https://golang.org/doc/articles/json_and_go.html
Пример (CustomMarshalJSON)
Код:
package json_test
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 Example_customMarshalJSON() {
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
}
Пример (TextMarshalJSON)
Код:
package json_test
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 Example_textMarshalJSON() {
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
}
Индекс
Примеры
Файлы пакета
decode.go encode.go fold.go indent.go scanner.go stream.go tables.go tags.go
Функция Compact
func Compact(dst *bytes.Buffer, src []byte) error
Compact добавляет в dst закодированный в JSON src с удаленными несущественными символами пробела.
Функция HTMLEscape
func HTMLEscape(dst *bytes.Buffer, src []byte)
HTMLEscape добавляет в dst закодированный в JSON src, заменяя символы «<», «>», «&», U+2028 и U+2029 внутри строковых литералов на \u003c, \u003e, \u0026, \u2028, \u2029 соответственно, чтобы JSON можно было безопасно встраивать в теги HTML <script>. По историческим причинам веб-браузеры не поддерживают стандартную HTML-экранировку в тегах <script>, поэтому необходимо использовать альтернативное кодирование JSON.
Пример
Код:
var out bytes.Buffer
json.HTMLEscape(&out, []byte(`{"Name":"<b>HTML content</b>"}`))
out.WriteTo(os.Stdout)
Вывод:
{"Name":"\u003cb\u003eHTML content\u003c/b\u003e"}
Функция Indent
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
Indent добавляет в dst отформатированную с отступами версию закодированного в JSON src. Каждый элемент в JSON-объекте или массиве начинается с новой строки, имеющей отступ, начинающийся с prefix и последующим одним или несколькими повторениями indent в соответствии с уровнем вложенности. Данные, добавленные в dst, не начинаются с prefix и никакого отступа, чтобы упростить их встраивание в другие отформатированные JSON-данные. Несмотря на то, что начальные символы пробела (пробел, табуляция, возврат каретки, перевод строки) в начале src удаляются, заключительные пробелы в конце src сохраняются и копируются в dst. Например, если src не содержит заключительных пробелов, их не будет и в dst; если src заканчивается заключительной новой строкой, то dst также будет заканчиваться новой строкой.
Пример
Код:
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)
Вывод:
[
= {
= "Name": "Diamond Fork",
= "Number": 29
= },
= {
= "Name": "Sheep Creek",
= "Number": 51
= }
=]
Функция Marshal
func Marshal(v any) ([]byte, error)
Marshal возвращает JSON-кодирование v.
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.
Строковые значения кодируются как JSON-строки, преобразованные в допустимые UTF-8, заменяя недопустимые байты замещающим символом Юникода. Для того чтобы JSON было безопасно встраивать в HTML <script> теги, строка кодируется с помощью HTMLEscape, который заменяет «<», «>», «&», U+2028 и U+2029 на «\u003c», «\u003e», «\u0026», «\u2028» и «\u2029» соответственно. Эту замену можно отключить, используя Encoder, вызвав Encoder.SetEscapeHTML(false).
Массивы и срезы значений кодируются как JSON-массивы, за исключением того, что []byte кодируется как base64-строка, а пустой срез кодируется как null-значение JSON.
Значения структур кодируются как JSON-объекты. Каждый экспортированный поле структуры становится членом объекта, используя имя поля в качестве ключа объекта, если поле не опущено по одной из нижеприведенных причин.
Кодирование каждого поля структуры может быть настраиваемым с помощью строкового формата, хранящегося под ключом «json» в тэге поля структуры. Строка формата указывает имя поля, возможно, за которым следуют перечисленные через запятую опции. Имя может быть пустым, чтобы указать опции, не переопределяя имя поля по умолчанию.
Опция «omitempty» указывает, что поле должно быть опущено из кодирования, если поле имеет пустое значение, определяемое как false, 0, nil-указатель, nil-интерфейсное значение и любой пустой массив, срез, карта или строка.
В качестве специального случая, если тег поля «-», поле всегда опущено. Обратите внимание, что поле с именем «-» все же может быть сгенерировано с помощью тега «-,».
Примеры тегов полей структур и их значений:
// 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:"-,"`
Опция «string» указывает, что поле хранится как JSON внутри JSON-кодированной строки. Это применяется только к полям типа string, с плавающей точкой, целым числом или boolean. Этот дополнительный уровень кодирования иногда используется при общении с JavaScript-программами:
Int64String int64 `json:",string"`
Имя ключа будет использоваться, если это непустая строка, состоящая только из букв, цифр и ASCII-знаков пунктуации, кроме кавычек, обратной косой черты и запятой.
Встроенные поля структур обычно кодируются так, как будто их внутренние экспортируемые поля были полями во внешней структуре, с учетом обычных правил видимости Go, дополненных как описано в следующем абзаце.
Анонимное поле структуры с именем, заданным в его теге JSON, рассматривается как имеющее это имя, а не являющееся анонимным. Анонимное поле структуры типа interface обрабатывается так же, как если бы у него было это имя типа, а не являлось анонимным.
Правила видимости Go для полей структур дополняются для JSON, когда определяется, какое поле кодировать или декодировать.
Если на одном уровне есть несколько полей и этот уровень является наименее вложенным (и, следовательно, это уровень вложенности, выбранный обычными правилами Go), применяются следующие дополнительные правила:
1) Из этих полей, если какие-либо помечены тегами JSON, учитываются только помеченные поля, даже если есть несколько непомеченных полей, которые в противном случае конфликтуют.
2) Если ровно одно поле (помеченное или нет в соответствии с первым правилом), оно выбирается.
3) В противном случае присутствует несколько полей, и все они игнорируются; ошибка не возникает.
Обработка анонимных полей структуры — нововведение в Go 1.1. До Go 1.1 анонимные поля структуры игнорировались. Чтобы заставить игнорировать анонимное поле структуры как в текущих, так и в более ранних версиях, присвойте полю тег JSON «-».
Значения словарей кодируются как JSON-объекты. Тип ключа словаря должен быть либо строкой, либо целочисленным типом, либо реализовывать encoding.TextMarshaler. Ключи словаря сортируются и используются в качестве ключей JSON-объектов, применяя следующие правила, с учётом преобразования в UTF-8, описанного выше для строковых значений:
- ключи любого типа строки используются напрямую
- ключи, реализующие encoding.TextMarshaler, сериализуются
- целочисленные ключи преобразуются в строки
Значения указателей кодируются как значения, на которые указывают указатели. Нулевой указатель кодируется как нулевое значение JSON.
Значения интерфейсов кодируются как значения, содержащиеся в интерфейсе. Нулевое значение интерфейса кодируется как нулевое значение JSON.
Значения каналов, комплексных чисел и функций не могут быть закодированы в JSON. Попытка закодировать такое значение приводит к возврату Marshal ошибки UnsupportedTypeError.
JSON не может представлять циклические структуры данных, и Marshal не обрабатывает их. Передача циклических структур в Marshal приведёт к ошибке.
Пример
Код:
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)
Вывод:
{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}
func MarshalIndent
func MarshalIndent(v any, prefix, indent string) ([]byte, error)
MarshalIndent похож на Marshal, но применяет Indent для форматирования вывода. Каждый элемент JSON в выводе начинается с новой строки, начинающейся с префикса, за которым следует один или несколько экземпляров отступа, в соответствии с уровнем вложенности.
Пример
Код:
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))
Вывод:
{
<prefix><indent>"a": 1,
<prefix><indent>"b": 2
<prefix>}
func Unmarshal
func Unmarshal(data []byte, v any) error
Unmarshal анализирует данные в формате JSON и сохраняет результат в значение, на которое указывает v. Если v равно null или не является указателем, Unmarshal возвращает InvalidUnmarshalError.
Unmarshal использует обратные преобразования, которые использует Marshal, выделяя словари, срезы и указатели по мере необходимости, со следующими дополнительными правилами:
Для разбора JSON в указатель Unmarshal сначала обрабатывает случай, когда JSON представляет собой JSON-литерал null. В этом случае Unmarshal устанавливает указатель в null. В противном случае Unmarshal разбор JSON в значение, на которое указывает указатель. Если указатель равен null, Unmarshal выделяет новое значение для него.
Для разбора JSON в значение, реализующее Unmarshaler, Unmarshal вызывает метод [Unmarshaler.UnmarshalJSON] этого значения, включая случай, когда входные данные — JSON null. В противном случае, если значение реализует encoding.TextUnmarshaler и входные данные — JSON строка в кавычках, Unmarshal вызывает encoding.TextUnmarshaler.UnmarshalText с необрамлённой формой строки.
Для разбора JSON в структуру Unmarshal сопоставляет ключи входящего объекта с ключами, используемыми Marshal (либо имя поля структуры, либо его тег), отдавая предпочтение точному совпадению, но принимая также совпадение с учётом регистра. По умолчанию объекты, не имеющие соответствующего поля структуры, игнорируются (см. Decoder.DisallowUnknownFields для альтернативы).
Для разбора JSON в значение интерфейса Unmarshal сохраняет одно из следующих значений в значении интерфейса:
- bool, для JSON булевых значений
- float64, для JSON чисел
- string, для JSON строк
- []interface{}, для JSON массивов
- map[string]interface{}, для JSON объектов
- null для JSON null
Для разбора JSON массива в срез, Unmarshal сбрасывает длину среза на ноль, а затем добавляет каждый элемент в срез. В качестве специального случая, чтобы разобрать пустой JSON массив в срез, Unmarshal заменяет срез новым пустым срезом.
Для разбора JSON массива в массив Go, Unmarshal декодирует элементы JSON массива в соответствующие элементы массива Go. Если массив Go меньше JSON массива, дополнительные элементы JSON массива отбрасываются. Если JSON массив меньше массива Go, дополнительные элементы массива Go устанавливаются в нулевые значения.
Для разбора JSON объекта в словарь, Unmarshal сначала создаёт словарь для использования. Если словарь равен null, Unmarshal выделяет новый словарь. В противном случае Unmarshal использует существующий словарь, сохраняя существующие записи. Затем Unmarshal сохраняет пары ключ-значение из JSON объекта в словарь. Тип ключа словаря должен быть либо любой строкой, либо целым числом, либо реализовывать encoding.TextUnmarshaler.
Если кодированные JSON данные содержат синтаксическую ошибку, Unmarshal возвращает SyntaxError.
Если JSON значение не подходит для данного целевого типа или если JSON число переполняет целевой тип, Unmarshal пропускает это поле и завершает разбор наилучшим образом. Если больше нет серьёзных ошибок, Unmarshal возвращает UnmarshalTypeError, описывающий самую раннюю такую ошибку. В любом случае, не гарантируется, что все оставшиеся поля, следующие за проблематичным, будут обработаны в целевом объекте.
Значение JSON null преобразуется в интерфейс, массив, указатель или срез, установив это значение Go в null. Поскольку null часто используется в JSON для обозначения «отсутствия», разбор JSON null в любой другой тип Go не оказывает никакого влияния на значение и не приводит к ошибке.
При разборе строк в кавычках неверный UTF-8 или неверные суррогатные пары UTF-16 не обрабатываются как ошибка. Вместо этого они заменяются символом замены Юникода U+FFFD.
Пример
Код:
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)
Вывод:
[{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
func Valid 1.9
func Valid(data []byte) bool
Valid проверяет, является ли data корректным кодированием JSON.
Пример
Код:
goodJSON := `{"example": 1}`
badJSON := `{"example":2:]}}`
fmt.Println(json.Valid([]byte(goodJSON)), json.Valid([]byte(badJSON)))
Вывод:
true false
тип Decoder
Decoder считывает и декодирует JSON значения из входного потока.
type Decoder struct {
// contains filtered or unexported fields
}
Пример
В этом примере Decoder используется для декодирования потока различных JSON значений.
Код:
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)
}
Вывод:
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 возвращает читатель данных, оставшихся в буфере Decoder. Читатель действителен до следующего вызова Decoder.Decode.
func (*Decoder) Decode
func (dec *Decoder) Decode(v any) error
Decode считывает следующее кодированное JSON значение из своего входа и сохраняет его в значение, на которое указывает v.
См. документацию для Unmarshal для получения подробностей о преобразовании JSON в значение Go.
Пример (Поток)
В этом примере Decoder используется для декодирования потока массива JSON объектов.
Код:
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)
Вывод:
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 заставляет Decoder возвращать ошибку, когда целевое значение — структура, а вход содержит ключи объекта, которые не соответствуют ни одному неигнорируемому, экспортируемому полю в целевом значении.
func (*Decoder) InputOffset 1.14
func (dec *Decoder) InputOffset() int64
InputOffset возвращает смещение байта входного потока текущего положения декодера. Смещение задаёт местоположение конца последнего возвращённого токена и начала следующего токена.
func (*Decoder) More 1.5
func (dec *Decoder) More() bool
More сообщает, существует ли ещё один элемент в текущем массиве или объекте, обрабатываемом для разбора.
func (*Decoder) Token 1.5
func (dec *Decoder) Token() (Token, error)
Token возвращает следующий токен JSON в входном потоке. В конце входного потока Token возвращает null, io.EOF.
Token гарантирует, что разделители [ ] { } которые он возвращает, корректно вложены и согласованы: если Token встречает неожиданный разделитель во входных данных, он вернёт ошибку.
Входной поток состоит из основных JSON значений — bool, string, number и null — вместе с разделителями [ ] { } типа Delim для обозначения начала и конца массивов и объектов. Запятые и двоеточия опущены.
Пример
В этом примере Decoder используется для декодирования потока различных JSON значений.
Код:
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")
}
Вывод:
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 заставляет Decoder разбор числа в интерфейс{} как Number, вместо float64.
тип Delim 1.5
Delim — это разделитель JSON массива или объекта, один из [ ] { или }.
type Delim rune
func (Delim) String 1.5
func (d Delim) String() string
тип Encoder
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 any) error
Encode записывает JSON кодирование v в поток, без несущественных пробелов, за которым следует символ новой строки.
См. документацию для Marshal для получения подробностей о преобразовании значений Go в JSON.
func (*Encoder) SetEscapeHTML 1.7
func (enc *Encoder) SetEscapeHTML(on bool)
SetEscapeHTML указывает, нужно ли экранировать проблемные HTML символы внутри JSON строк в кавычках. По умолчанию &, < и > экранируются до \u0026, \u003c и \u003e для предотвращения некоторых проблем безопасности, которые могут возникнуть при встраивании JSON в HTML.
В не-HTML средах, где экранирование мешает читаемости вывода, SetEscapeHTML(false) отключает это поведение.
func (*Encoder) SetIndent 1.7
func (enc *Encoder) SetIndent(prefix, indent string)
SetIndent инструктирует кодировщик форматировать каждое последующее кодируемое значение так, как если бы оно было отступом функцией Indent(dst, src, prefix, indent) на уровне пакета. Вызов SetIndent("", "") отключает отступы.
тип InvalidUTF8Error
До версии Go 1.2, InvalidUTF8Error возвращался методом Marshal при попытке закодировать строковое значение с неверными последовательностями UTF-8. Начиная с Go 1.2, Marshal вместо этого преобразует строку в корректные данные UTF-8, заменяя неверные байты на символ Unicode замены U+FFFD.
Устаревшее: больше не используется; сохраняется для совместимости.
type InvalidUTF8Error struct {
S string // the whole string value that caused the error
}
func (*InvalidUTF8Error) Error
func (e *InvalidUTF8Error) Error() string
тип InvalidUnmarshalError
InvalidUnmarshalError описывает некорректный аргумент, переданный методу Unmarshal. (Аргумент метода Unmarshal должен быть указателем на не-nil значение.)
type InvalidUnmarshalError struct {
Type reflect.Type
}
func (*InvalidUnmarshalError) Error
func (e *InvalidUnmarshalError) Error() string
тип Marshaler
Marshaler — это интерфейс, реализуемый типами, которые могут сериализовать себя в корректный JSON.
type Marshaler interface {
MarshalJSON() ([]byte, error)
} тип MarshalerError
MarshalerError представляет ошибку при вызове метода [Marshaler.MarshalJSON] или encoding.TextMarshaler.MarshalText.
type MarshalerError struct {
Type reflect.Type
Err error
// contains filtered or unexported fields
}
func (*MarshalerError) Error
func (e *MarshalerError) Error() string
func (*MarshalerError) Unwrap 1.13
func (e *MarshalerError) Unwrap() error
Unwrap возвращает базовую ошибку.
тип Number 1.1
Number представляет собой числовую литерал JSON.
type Number string
func (Number) Float64 1.1
func (n Number) Float64() (float64, error)
Float64 возвращает число как float64.
func (Number) Int64 1.1
func (n Number) Int64() (int64, error)
Int64 возвращает число как int64.
func (Number) String 1.1
func (n Number) String() string
String возвращает текстовое представление числа.
тип RawMessage
RawMessage — это сырое закодированное значение JSON. Оно реализует Marshaler и Unmarshaler и может использоваться для отложенного декодирования JSON или предварительного вычисления кодирования JSON.
type RawMessage []byte
Пример (Marshal)
В этом примере RawMessage используется для использования предварительно вычисленного JSON при сериализации.
Код:
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)
Вывод:
{
"header": {
"precomputed": true
},
"body": "Hello Gophers!"
}
Пример (Unmarshal)
В этом примере RawMessage используется для отложенного разбора части сообщения JSON.
Код:
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)
}
Вывод:
YCbCr &{255 0 -10}
RGB &{98 218 255}
func (RawMessage) MarshalJSON 1.8
func (m RawMessage) MarshalJSON() ([]byte, error)
MarshalJSON возвращает m как JSON-кодирование m.
func (*RawMessage) UnmarshalJSON
func (m *RawMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON устанавливает *m в копию данных.
тип SyntaxError
SyntaxError — это описание синтаксической ошибки JSON. Unmarshal вернёт 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
тип Token 1.5
Token содержит значение одного из следующих типов:
- Delim, для четырёх разделителей JSON [ ] { }
- bool, для JSON булевых значений
- float64, для JSON чисел
- Number, для JSON чисел
- string, для JSON строковых литералов
- nil, для JSON null
type Token any
тип UnmarshalFieldError
UnmarshalFieldError описывает ключ объекта JSON, который привёл к неэкспортированному (и поэтому неперезаписываемому) полю структуры.
Устаревшее: больше не используется; сохраняется для совместимости.
type UnmarshalFieldError struct {
Key string
Type reflect.Type
Field reflect.StructField
}
func (*UnmarshalFieldError) Error
func (e *UnmarshalFieldError) Error() string
тип UnmarshalTypeError
UnmarshalTypeError описывает значение JSON, которое не подходит для значения определённого типа Go.
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
тип Unmarshaler
Unmarshaler — это интерфейс, реализуемый типами, которые могут десериализовать описание себя в формате JSON. Можно предполагать, что вход представляет собой корректное кодирование значения JSON. UnmarshalJSON должен копировать данные JSON, если он хочет сохранить данные после возврата.
По соглашению, для приближения поведения метода Unmarshal, Unmarshaler реализует UnmarshalJSON([]byte("null")) как бездействующую операцию.
type Unmarshaler interface {
UnmarshalJSON([]byte) error
} тип UnsupportedTypeError
UnsupportedTypeError возвращается методом Marshal при попытке закодировать тип значения, который не поддерживается.
type UnsupportedTypeError struct {
Type reflect.Type
}
func (*UnsupportedTypeError) Error
func (e *UnsupportedTypeError) Error() string
тип UnsupportedValueError
UnsupportedValueError возвращается методом Marshal при попытке закодировать значение, которое не поддерживается.
type UnsupportedValueError struct {
Value reflect.Value
Str string
}
func (*UnsupportedValueError) Error
func (e *UnsupportedValueError) Error() string
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/encoding/json/
