Новите експериментални пакети на Go: какво да знаем

Въведение is a simple data interchange format. Almost 15 years ago, we wrote about Оттогава JSON се е превърнал в най-популярния формат на данни, използван в интернет. Той е широко прочетен и написан от програми на Go, а кодирането/json сега се нарежда като петият най-импортиран пакет на Go. JavaScript нотация на обекти (JSON) Поддръжка на JSON в Go С течение на времето пакетите се развиват с нуждите на своите потребители и Тази публикация в блога е за новата експериментална версия на Go 1.25 и Тази публикация поддържа нова основна версия на API, предоставя преглед на новите пакети и обяснява как можете да ги използвате. encoding/json encoding/json/v2 encoding/json/jsontext Проблеми с encoding/json Кодиране / JSON Като цяло , Идеята за маршалинг и демаршалинг на произволни типове Go с някакво подразбиращо се представяне в JSON, съчетана със способността за персонализиране на представянето, се оказа изключително гъвкава. encoding/json Дефекти в поведението Съществуват различни поведенчески дефекти в : encoding/json : Over the years, JSON has seen increased standardization in order for programs to properly communicate. Generally, decoders have become stricter at rejecting ambiguous inputs, to reduce the chance that two implementations will have different (successful) interpretations of a particular JSON value. Imprecise handling of JSON syntax currently accepts invalid UTF-8, whereas the latest Internet Standard (RFC 8259) requires valid UTF-8. The default behavior should report an error in the presence of invalid UTF-8, instead of introducing silent data corruption, which may cause problems downstream. encoding/json currently accepts objects with duplicate member names. RFC 8259 does not specify how to handle duplicate names, so an implementation is free to choose an arbitrary value, merge the values, discard the values, or report an error. The presence of a duplicate name results in a JSON value without a universally agreed upon meaning. This could be and has been exploited before (as in ). The default behavior should err on the side of safety and reject duplicate names. encoding/json exploited by attackers in security applications CVE-2017-12635 Изтичане на нивото на филийки и карти: JSON често се използва за комуникация с програми, използващи JSON внедрения, които не позволяват null да бъде демаршализиран в тип данни, който се очаква да бъде JSON матрица или обект. Тъй като кодирането/json маршализира нилово филийка или карта като JSON null, това може да доведе до грешки при демаршализиране от други внедрения. Случайно-нечувствително демаршалиране: При демаршалиране името на член на JSON обект се разрешава на име на поле Go struct с помощта на случайно-нечувствително съвпадение. Несъвместимо призоваване на методи: Поради детайли в изпълнението, методите MarshalJSON, декларирани на насочващ приемник, се наричат несъвместимо от кодиране/json. Недостатъци на огъня The API of can be tricky or restrictive: encoding/json Потребителите често пишат json.NewDecoder(r).Decode(v), което не отхвърля последващите боклуци в края на входа. Опциите могат да бъдат зададени на типовете Encoder и Decoder, но не могат да се използват с функциите Marshal и Unmarshal. По същия начин типовете, които изпълняват интерфейсите Marshaler и Unmarshaler, не могат да използват опциите и няма начин да се насочат опциите надолу по стека за обаждания. Например опцията Decoder.DisallowUnknownFields губи ефекта си, когато се обажда персонализиран метод UnmarshalJSON. Функциите Compact, Indent и HTMLEscape пишат на bytes.Buffer вместо на нещо по-гъвкаво като []byte или io.Writer. Performance limitations Отстранявайки подробностите за вътрешното изпълнение, публичният API го ангажира с определени ограничения на производителността: : The interface method forces the implementation to allocate the returned . Also, the semantics require that verify that the result is valid JSON and also to reformat it to match the specified indentation. MarshalJSON MarshalJSON []byte encoding/json : The interface method requires that a complete JSON value be provided (without any trailing data). This forces to parse the JSON value to be unmarshaled in its entirety to determine where it ends before it can call . Afterwards, the method itself must parse the provided JSON value again. UnmarshalJSON UnmarshalJSON encoding/json UnmarshalJSON UnmarshalJSON : Even though the and types operate on an or , they buffer the entire JSON value in memory. The method for reading individual tokens is allocation-heavy and there is no corresponding API for writing tokens. Lack of streaming Encoder Decoder io.Writer io.Reader Decoder.Token Освен това, ако прилагането на или Методът на рециклиране се нарича или След това функцията се превръща в квадратна. MarshalJSON UnmarshalJSON Marshal Unmarshal Опитвайки се да поправя Директно Кодиране / JSON Кодиране / JSON Introducing a new, incompatible major version of a package is a heavy consideration. If possible, we should try to fix the existing package. Въпреки че е сравнително лесно да се добавят нови функции, е трудно да се променят съществуващите функции. За съжаление, тези проблеми са присъщи последици от съществуващия API, което ги прави практически невъзможни за коригиране в рамките на . Go 1 съвместимост обещание По принцип можем да декларираме отделни имена, като or , но това е еквивалентно на създаването на паралелно именно пространство в рамките на един и същ пакет. (оттук нататък се нарича , където можем да направим тези промени в рамките на отделен namespace in contrast to (оттук нататък се нарича ) на MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Planning for encoding/json/v2 Кодиране / JSON / V2 Изготвяне на нова основна версия на В края на 2020 г., подтикнат от невъзможността да се поправят проблемите в сегашния пакет, Даниел Марти (един от поддържащите Първо изготви мислите си за трябва да изглежда като. Отделно, след предишна работа по , Joe Tsai was disapppointed that Пакетът е необходим за използване на персонализирана JSON реализация, защото не е в състояние нито да се придържа към по-строгия JSON стандарт, който изисква спецификацията на протокола Buffer, нито ефективно да сериализира JSON по стрийминг начин. encoding/json encoding/json Какво е хипотетично v2 Go API за протокол буфери на protojson encoding/json Вярвайки, че по-яркото бъдеще за JSON е както полезно, така и постижимо, Даниел и Джо се обединиха, за да направят мозъчна буря. и (като първоначалният код е полирана версия на логиката за сериализация на JSON от модула Go protobuf). С течение на времето, няколко други (Roger Peppe, Chris Hines, Johan Brandhorst-Satzkorn и Damien Neil) се присъединиха към усилията, като предоставиха преглед на дизайна, преглед на кода и регресионно тестване. и . v2 Започна изграждането на прототип Записани срещи Забележки за срещи Тази работа е публична от самото начало и ние все повече се ангажираме с по-широката общност на Go, първо с и , Напоследък и като Go експеримент (достъпно в Go 1.25) за по-широкомащабно тестване от всички потребители на Go. Гофър говори discussion posted in late 2023 Официално предложение, публикувано в началото на 2025 г. осиновяване encoding/json/v2 на усилията продължават в продължение на 5 години, като включват обратна връзка от много участници и също така придобиват ценен емпиричен опит от използването в производствените настройки. v2 Заслужава да се отбележи, че той е разработен и популяризиран до голяма степен от хора, които не са наети от Google, което показва, че проектът Go е съвместно усилие с процъфтяваща глобална общност, посветена на подобряването на екосистемата на Go. Изграждане на encoding/json/jsontext Кодиране / JSON / JSON Преди да обсъдим Първо ще представим експерименталния Пакет, който поставя основите за бъдещи подобрения на JSON в Go. v2 encoding/json/jsontext Сериализацията на JSON в Go може да бъде разделена на два основни компонента: синтактична функционалност, която се занимава с обработката на JSON въз основа на неговата граматика, и that defines the relationship between JSON values and Go values. semantic functionality Използваме термините „кодиране“ и „декодиране“, за да опишем синтактичната функционалност, а термините „маршал“ и „безмаршал“ да опишем семантичната функционалност. This diagram provides an overview of this separation. Purple blocks represent types, while blue blocks represent functions or methods. The direction of the arrows approximately represents the flow of data. The bottom half of the diagram, implemented by the пакета, съдържа функционалност, която се отнася само до синтаксиса, докато горната половина, изпълнена от package, contains functionality that assigns semantic meaning to syntactic data handled by the bottom half. jsontext json/v2 Основното огнище на is the following: jsontext package jsontext type Encoder struct { ... } func NewEncoder(io.Writer, ...Options) *Encoder func (*Encoder) WriteValue(Value) error func (*Encoder) WriteToken(Token) error type Decoder struct { ... } func NewDecoder(io.Reader, ...Options) *Decoder func (*Decoder) ReadValue() (Value, error) func (*Decoder) ReadToken() (Token, error) type Kind byte type Value []byte func (Value) Kind() Kind type Token struct { ... } func (Token) Kind() Kind на Пакетът осигурява функционалност за взаимодействие с JSON на синтактично ниво и получава името си от where the grammar for JSON data is literally called Тъй като тя взаимодейства само с JSON на синтактично ниво, тя не зависи от Go отражение. jsontext RFC 8259, section 2 JSON-text на и предоставяне на поддръжка за кодиране и декодиране на JSON стойности и токени. които засягат специфичното поведение на кодирането и декодирането. за разлика от и types declared in Новите типове в Избягвайте да обърквате разликата между синтаксиса и семантиката и да работите по истински поток. Encoder Decoder Приемане на вариативни опции Encoder Decoder v1 jsontext JSON стойност е пълна единица от данни и е представена в Go като . It is identical to в . A JSON value is syntactically composed of one or more JSON tokens. A JSON token is represented in Go as the Създаване на конструктори и аксесоари, които са подобни на в но е предназначен да представлява произволни JSON токени без разпределение. на име []byte RawMessage v1 непрозрачен Token Token v1 за решаване на основните проблеми с изпълнението на и интерфейсните методи, ние се нуждаем от ефективен начин за кодиране и декодиране на JSON като поточна последователност от токени и стойности. Ние въвеждаме and интерфейси, които работят върху or , което позволява на реализациите на методите да обработват JSON по чисто стрийминг начин. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder По този начин, на Пакетът не трябва да отговаря за валидирането или форматирането на стойност JSON, върната от , nor would it need to be responsible for determining the boundaries of a JSON value provided to . These responsibilities belong to the и . json MarshalJSON UnmarshalJSON Encoder Decoder въвеждане encoding/json/v2 Кодиране / JSON / V2 Изграждане на на В този случай, ние въвеждаме експерименталната Пакетът е предназначен за решаване на гореспоменатите проблеми, като същевременно остава познат на потребителите на Нашата цел е използването на ще оперира Същото се отнася и за миграцията на . jsontext encoding/json/v2 v1 v1 Повечето v2 В тази статия ще обхванем предимно високо ниво на API на За примери за това как да го използваме, насърчаваме читателите да изучават package or read . v2 Примерите в v2 Блогът на Антон Жиянов, обхващащ темата Основното огнище на Това е следното: v2 package json func Marshal(in any, opts ...Options) (out []byte, err error) func MarshalWrite(out io.Writer, in any, opts ...Options) error func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) error func Unmarshal(in []byte, out any, opts ...Options) error func UnmarshalRead(in io.Reader, out any, opts ...Options) error func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) error на и функциите имат подпис, подобен на , но приемат опции за конфигуриране на тяхното поведение. and Функциите се изпълняват директно върху или , avoiding the need to temporarily construct an или Пишете или четете от такива хора. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder на и Функциите се изпълняват на и и всъщност е основната реализация на гореспоменатите функции. , опциите са първокласен аргумент към всяка от маршаловите и немаршаловите функции, което значително разширява гъвкавостта и конфигурирането на . There are в които не са обхванати от тази статия. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 several options available v2 Type-specified customization Подобни на , позволява на типовете да определят собственото си JSON представяне чрез задоволяване на конкретни интерфейси. v1 v2 type Marshaler interface { MarshalJSON() ([]byte, error) } type MarshalerTo interface { MarshalJSONTo(*jsontext.Encoder) error } type Unmarshaler interface { UnmarshalJSON([]byte) error } type UnmarshalerFrom interface { UnmarshalJSONFrom(*jsontext.Decoder) error } The и Интерфейсите са идентични с тези в Новата and интерфейси позволяват на тип да се представя като JSON с помощта на или Това позволява опциите да бъдат пренасочени надолу по стека за обаждания, тъй като опциите могат да бъдат изтеглени чрез accessor method on the or . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder See example for how to implement a custom type that maintains the ordering of JSON object members. на OrderedObject Caller-specified customization в Извадител на and can also specify a custom JSON representation for any arbitrary type, where caller-specified functions take precedence over type-defined methods or the default representation for a particular type. v2 Marshal Unmarshal func WithMarshalers(*Marshalers) Options type Marshalers struct { ... } func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers func WithUnmarshalers(*Unmarshalers) Options type Unmarshalers struct { ... } func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers и създаване на маршал, който може да бъде прехвърлен на Използване на повикване to override the marshaling of particular types. Similarly, и подпомагане на подобна персонализация за . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal example demonstrates how this feature allows serialization of all types to be handled by the на пакета. на ProtoJSON proto.Message protojson Разлики в поведението Докато Целта е да се държи the same as Поведението му се е променило to address problems in По-специално и най особено: v2 mostly v1 По някакъв начин v1 reports an error in the presence of invalid UTF-8. v2 reports an error if a JSON object contains a duplicate name. v2 marshals a nil Go slice or Go map as an empty JSON array or JSON object, respectively. v2 unmarshals a JSON object into a Go struct using a case-sensitive match from the JSON member name to the Go field name. v2 redefines the tag option to omit a field if it would have encoded as an “empty” JSON value (which are , , , and ). v2 omitempty null "" [] {} reports an error when trying to serialize a , which currently has , but provides options to let the caller decide. v2 time.Duration no default representation За повечето промени в поведението има опция struct tag или опция, посочена от повиквателя, която може да конфигурира поведението да работи под or семантика, или дори друго поведение, определено от обаждащия. виж За повече информация. v1 v2 Миграция към V2 Performance optimizations на performance of Тя е почти на равнище с . Sometimes it is slightly faster, but other times it is slightly slower. The performance of is significantly faster than , with benchmarks demonstrating improvements of up to 10x. Marshal v2 v1 Unmarshal v2 v1 За да се постигне по-голяма ефективност, съществуващите и should migrate to also implement и , така че те да могат да се възползват от обработката на JSON по чисто стрийминг начин. например, рекурсивно анализиране на спецификациите на OpenAPI в methods significantly hurt performance in a particular service of Kubernetes (see ), while switching to improved performance by orders of magnitude. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON kubernetes/kube-openapi#315 UnmarshalJSONFrom За повече информация вижте Репозиторията е go-json-experiment/jsonbench Ретроактивно подобрение Кодиране / JSON Кодиране / JSON Искаме да избегнем две отделни JSON реализации в стандартната библиотека на Go, така че е от решаващо значение, че под капака, is implemented in terms of . v1 v2 There are several benefits to this approach: : The and functions in or represent a set of default behaviors that operate according to or semantics. Options can be specified that configure or to operate with entirely , mostly with a some , a mix of or , mostly with some , or entirely semantics. This allows for gradual migration between the default behaviors of the two versions. Gradual migration Marshal Unmarshal v1 v2 v1 v2 Marshal Unmarshal v1 v1 v2 v1 v2 v2 v1 v2 Наследственост на функциите: Тъй като функциите, съвместими с обратната линия, се добавят към v2, те по своята същност ще бъдат достъпни в v1. Например v2 добавя поддръжка за няколко нови структурирани опции като inline или формат и също така поддръжка за методите за интерфейс MarshalJSONTo и UnmarshalJSONFrom, които са по-ефективни и гъвкави. Намалена поддръжка: Поддръжката на широко използван пакет изисква значителни усилия. Като v1 и v2 използват едно и също изпълнение, тежестта на поддръжката се намалява. Като цяло, една промяна ще поправи грешки, ще подобри производителността или ще добави функционалност към двете версии. While select parts of може да бъде отслабена с течение на времето (предполага се, че след завършване на експеримент), пакетът като цяло никога няма да бъде обезценен. will be encouraged, but not required. The Go project will not drop support for . v1 v2 v2 v1 Експериментирайте с Джейсън2 Джейсън2 The newer API in the и пакетите не са видими по подразбиране. За да ги използвате, създайте set in your environment or with the Естеството на експеримента е, че API е нестабилен и може да се промени в бъдеще.Въпреки че API е нестабилен, изпълнението е с високо качество и е успешно използвано в производството от няколко големи проекта. encoding/json/jsontext encoding/json/v2 GOEXPERIMENT=jsonv2 goexperiment.jsonv2 The fact that Тя се прилага по отношение на Това означава, че основното прилагане на Това е съвсем различно, когато става дума за изграждане на Без да променяте кода, трябва да можете да изпълнявате тестовете си под and theoretically nothing new should fail: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... Възстановяването на По отношение на Целта е да се осигури еднакво поведение в рамките на , въпреки че някои различия могат да бъдат наблюдавани, като например точната формулировка на съобщенията за грешки. Докладвайте за всякакви регресии . v1 v2 Go 1 compatibility promise jsonv2 По темата Tracker Ставането на експеримент в Go 1.25 е значителен етап по пътя към официалното приемане и в стандартната библиотека. Въпреки това, целта на Вашите отзиви ще определят следващите ни стъпки и резултата от този експеримент, който може да доведе до всичко, от изоставянето на усилията, до приемането като стабилни пакети на Go 1.26. Помогнете им да определят бъдещето. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/проблем / 71497 Джо Цай, Даниел Марти, Йохан Брандхорст-Сацкорн, Роджър Пеппе, Крис Хайнс и Деймиън Нийл Тази статия е достъпна на The Go Blog под лиценз CC BY 4.0 DEED. Блогът Go Блогът Go Photo by on Jr Korpa Непълен Джордж Корпа Непълен