Нови експериментални пакети Гоо-а: Шта знати

Увод је једноставан формат за размену података. Пре скоро 15 година, писали смо о , који је увео могућност сериализације и десериализације Го типова у и из ЈСОН података. Од тада, ЈСОН је постао најпопуларнији формат података који се користи на Интернету. JavaScript Object Notation (JSON) support for JSON in Go Временом, пакети се развијају са потребама својих корисника, и is no exception. This blog post is about Go 1.25’s new experimental и Пакети, који доносе дуго очекивана побољшања и поправке. Овај пост тврди за нову главну АПИ верзију, пружа преглед нових пакета, и објашњава како можете да га користите. encoding/json encoding/json/v2 encoding/json/jsontext Проблеми са Кодирање / Џон Кодирање / Џон Све у свему, has held up well. The idea of marshaling and unmarshaling arbitrary Go types with some default representation in JSON, combined with the ability to customize the representation, has proven to be highly flexible. However, in the years since its introduction, various users have identified numerous shortcomings. 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 is often used to communicate with programs using JSON implementations that do not allow to be unmarshaled into a data type expected to be a JSON array or object. Since marshals a nil slice or map as a JSON , this may lead to errors when unmarshaling by other implementations. indicated that most Go users prefer that nil slices and maps are marshaled as an empty JSON array or object by default. Leaking nilness of slices and maps null encoding/json null A survey Case-insensitive unmarshaling: Kada se unmarshalate, ime JSON objekta se reši na ime Go struktur polja koristeći slučaj-insensitive match.To je iznenađujuće podrazumevano, potencijalna bezbednosna ranjivost i ograničenje performansi. Неконзистентно позивање метода: Због детаља имплементације, МарсхалЈСОН методе декларисане на пријемнику показивача неконзистентно се називају кодирањем/јсон. Недостаци пожара Огњеница о can be tricky or restrictive: encoding/json Корисници често пишу json.NewDecoder(r).Decode(v), који не одбацује траилинг смеће на крају уноса. Opcije se mogu postaviti na tipove Encoder i Decoder, ali se ne mogu koristiti sa funkcijama Marshal i Unmarshal. Slično tome, tipovi koji implementiraju interfejse Marshaler i Unmarshaler ne mogu da iskoriste opcije i nema načina da se opcije potkopaju u pozivu. Na primer, opcija Decoder.DisallowUnknownFields gubi svoj efekat kada se pozove prilagođena metoda UnmarshalJSON. Funkcije Compact, Indent i HTMLEscape pišu u bajt.Buffer umesto nečeg fleksibilnijeg kao što je []byte ili io.Writer. Ограничења перформанси Одбацујући интерне детаље имплементације, јавни АПИ га обавезује на одређена ограничења у перформансама: : 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 Поред тога, ако се спровођење а or Метод рекурзивно назива или функција, онда перформансе постају квадратне. MarshalJSON UnmarshalJSON Marshal Unmarshal Trying to fix directly encoding/json Кодирање / Џон Увођење нове, некомпатибилне главне верзије пакета је тешка размишљања. While it is relatively easy to add new features, it is difficult to change existing features. Unfortunately, these problems are inherent consequences of the existing API, making them practically impossible to fix within the . Go 1 compatibility promise У принципу можемо прогласити одвојена имена, као што су или , али то је еквивалентно стварању паралелног именовног простора унутар истог пакета. (Од сада се зове ), где можемо направити ове промене у посебном namespace in contrast to (Од сада се зове ). MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Планирање за Кодирање / JSON / V2 Кодирање / JSON / V2 Планирање нове велике верзије Крајем 2020. године, подстакнут немогућношћу поправљања проблема у садашњем пакету, Даниел Марти (један од одржавача Прво је написао своје мисли о пакет треба да изгледа као. одвојено, након претходног рада на Joe Tsai je bio razočaran Пакет је потребан за коришћење прилагођене имплементације ЈСОН-а јер није био у стању да се придржава строжег ЈСОН стандарда који захтева спецификација Протокола Бафер, нити да ефикасно сериализује ЈСОН на стриминг начин. encoding/json encoding/json what a hypothetical v2 Иди API за протокол Буффери the protojson encoding/json Верујући да је светлија будућност за ЈСОН била и корисна и остварива, Даниел и Јое су се удружили да би размишљали о томе. и (with the initial code being a polished version of the JSON serialization logic from the Go protobuf module). Over time, a few others (Roger Peppe, Chris Hines, Johan Brandhorst-Satzkorn, and Damien Neil) joined the effort by providing design review, code review, and regression testing. Many of the early discussions are publicly available in our and . v2 Počeli smo da pravimo prototip Zabeleženi sastanci Ноте за састанак Овај рад је био јаван од почетка, а ми смо све више укључивали ширу Go заједницу, прво са и , i poslednje vreme као Го експеримент (доступан у Го 1.25) за шире тестирање од стране свих Го корисника. Гоферов говор дискусија објављена крајем 2023. године Formalni predlog objavljen početkom 2025. godine usvajanje encoding/json/v2 The напор се наставља већ 5 година, укључујући повратне информације од многих доприносилаца и такође добијају драгоцено емпиријско искуство из употребе у производним поставкама. v2 Вреди напоменути да је углавном развијен и промовисан од стране људи који нису запослени у Гоогу, демонстрирајући да је Го пројекат заједнички напор са просперитетном глобалном заједницом посвећеном побољшању Го екосистема. Изградња на encoding/json/jsontext encoding/json/jsontext Before discussing the API, we first introduce the experimental package that lays the foundation for future improvements to JSON in Go. v2 encoding/json/jsontext JSON serialization in Go can be broken down into two primary components: синтактичка функционалност која се бави обрадом ЈСОН-а на основу његове граматике, и Семантичка функционалност која дефинише однос између JSON вредности и Go вредности. Mi koristimo pojmove „kode“ i „dekode“ da bismo opisali sintaktičku funkcionalnost, a pojmove „maršal“ i „unmarshal“ da bismo opisali semantičku funkcionalnost. Овај дијаграм пружа преглед овог раздвајања. Пурпурни блокови представљају типове, док плави блокови представљају функције или методе. Смер стрелица приближно представља проток података. пакет, садржи функционалност која се тиче само синтаксе, док је горња половина, имплементирана од стране 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 Тхе пакет пружа функционалност за интеракцију са ЈСОН-ом на синтактичком нивоу и добија своје име од где се граматика за ЈСОН податке буквално назива Пошто само комуницира са ЈСОН-ом на синтактичком нивоу, не зависи од Го рефлексије. jsontext РФЦ 8259, одељак 2 JSON-text Тхе и provide support for encoding and decoding JSON values and tokens. The constructors који утичу на специфично понашање кодирања и декодирања. за разлику од and Типови објављени у , the new types in Избегавајте замагљивање разлике између синтаксиса и семантике и радите на истински стриминг начин. Encoder Decoder Prihvatite varijable opcije Encoder Decoder v1 jsontext ЈСОН вредност је комплетна јединица података и представља се у Го као То је идентично са in JSON vrednost je sintaktički sastavljena od jednog ili više JSON žetona. тип са конструкторима и методама прибора. То је аналогно на in али је дизајниран да представља произвољне ЈСОН токене без алокације. Именује []byte RawMessage v1 непрозирно Token Token v1 To resolve the fundamental performance problems with the и interface methods, we need an efficient way of encoding and decoding JSON as a streaming sequence of tokens and values. In Mi predstavljamo и интерфејс методе које раде на или , омогућавајући имплементацијама метода да обрађују ЈСОН на чисто стриминг начин. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder Thus, the package need not be responsible for validating or formatting a JSON value returned by , нити би требало да буде одговоран за одређивање граница ЈСОН вредности обезбеђене Te odgovornosti pripadaju и . json MarshalJSON UnmarshalJSON Encoder Decoder Увођење encoding/json/v2 encoding/json/v2 Building on the package, we now introduce the experimental package. It is designed to fix the aforementioned problems, while remaining familiar to users of the Наш циљ је да се коришћење will operate the same if directly migrated to . jsontext encoding/json/v2 v1 v1 mostly v2 У овом чланку ћемо првенствено покрити високог нивоа АПИ . For examples on how to use it, we encourage readers to study package or read . v2 Примери у v2 Блог Антона Жијанова који покрива тему The basic API of To je sledeće: 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 The и функције имају потпис сличан , али прихватите опције за конфигурисање њиховог понашања. and функције директно раде на or , avoiding the need to temporarily construct an or just to write or read from such types. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder The и функције раде на а and and is actually the underlying implementation of the previously mentioned functions. Unlike , опције су првокласни аргумент за сваку од маршалских и немаршалских функција, што значајно проширује флексибилност и конфигурираност . There are in which are not covered by this article. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 nekoliko opcija dostupnih v2 Тип-специфична персонализација Similar to , allows types to define their own JSON representation by satisfying particular interfaces. 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 interfaces are identical to those in • Нови и interfaces allow a type to represent itself as JSON using a или Ово омогућава да се опције преусмеравају на позив, јер се опције могу преузети преко Додатни метод на или . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder ovo пример како да имплементирате прилагођени тип који одржава организовање чланова ЈСОН објекта. о OrderedObject Цаллер-спецификована персонализација In Pozivnik za и 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 and изградити уобичајени маршал који се може пренијети на Позивање Коришћење to override the marshaling of particular types. Similarly, and подржава сличну персонализацију за . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal пример показује како ова функција омогућава сериализацију свих types to be handled by the package. Тхе ProtoJSON proto.Message protojson Behavior differences While Cilj je da se ponaša Исто као Njegovo ponašanje se promenilo Da bi se rešili problemi u , most notably: v2 Углавном v1 in some ways 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 For most behavior changes, there is a struct tag option or caller-specified option that can configure the behavior to operate under or семантике, или чак и друго понашање одређено позивачем. види for more information. v1 v2 “Migrating to v2” Performance optimizations The performance of То је приближно у паралелу са Понекад је мало брже, али други пут је мало спорије. performance of Značajno je brže nego , with benchmarks demonstrating improvements of up to 10x. Marshal v2 v1 Unmarshal v2 v1 In order to obtain greater performance gains, existing implementations of и should migrate to also implement и , тако да могу имати користи од обраде ЈСОН-а на чисто стриминг начин. На пример, рекурзивно анализирање ОпенАПИ спецификација у methods significantly hurt performance in a particular service of Kubernetes (see ), while switching to побољшана перформансе по величини реда. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON kubernetes/kube-openapi#315 UnmarshalJSONFrom For more information, see the repository. go-json-experiment/jsonbench retroaktivno poboljšanje encoding/json encoding/json We want to avoid two separate JSON implementations in the Go standard library, so it is critical that, under the hood, 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 додаје подршку за неколико нових опција структуре, као што су инлине или формат, као и подршку за методе интерфејса MarshalJSONTo и UnmarshalJSONFrom, који су оба ефикаснији и флексибилнији. : Maintenance of a widely used package demands significant effort. By having and use the same implementation, the maintenance burden is reduced. In general, a single change will fix bugs, improve performance, or add functionality to both versions. There is no need to backport a change with an equivalent change. Reduced maintenance v1 v2 v2 v1 While select parts of може бити депресиван током времена (претпостављајући дипломирани да буде експеримент), пакет у целини никада неће бити депресиван. će biti ohrabreni, ali ne i potrebni. Projekat Go neće odustati od podrške za . v1 v2 v2 v1 Експериментисање са jsonv2 ЈСОНВ2 The newer API in the и packages are not visible by default. To use them, build your code with set in your environment or with the Природа експеримента је да је АПИ нестабилан и може се променити у будућности.Иако је АПИ нестабилан, имплементација је високог квалитета и успешно се користи у производњи неколико великих пројеката. encoding/json/jsontext encoding/json/v2 GOEXPERIMENT=jsonv2 goexperiment.jsonv2 The fact that is implemented in terms of means that the underlying implementation of потпуно другачије када се гради под без промене било ког кода, требало би да можете да покренете своје тестове под and theoretically nothing new should fail: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... Поновна имплементација in terms of има за циљ да обезбеди идентично понашање у границама , иако неке разлике могу бити примећене, као што је тачно формулисање порука о грешци. and report any regressions . v1 v2 Go 1 компатибилност обећање jsonv2 На тему Трацкер Постати експеримент у Го 1.25 је значајан прекретница на путу формалног усвајања и у стандардној библиотеци. међутим, сврха Ваше повратне информације ће одредити наше следеће кораке и исход овог експеримента, који може резултирати било чим од напуштања напора, до усвајања као стабилних пакета Го 1.26. , and help determine the future of Go. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/izveštaj 71497 Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines i Damien Neil This article is available on under a CC BY 4.0 DEED license. The Go Blog The Go Blog The Go Blog Photo by on Jr Korpa Unsplash Jr Korpa Unsplash