Go's New Experimental Packages: Ano ang Kaalaman

Introduction ang Ito ay isang simpleng format ng data interchange. Halos 15 taon na ang nakalipas, kami ay nag-ulat tungkol sa Ang JSON ay naging ang pinaka-popular na format ng data na ginagamit sa Internet. Ito ay karaniwang nabasa at nabasa sa pamamagitan ng mga programa ng Go, at ang coding/json ngayon ay matatagpuan bilang ang 5th most imported Go package. Mga pahinang tumuturo sa JavaScript Object Notation (JSON) support for JSON in Go Over time, packages evolve with the needs of their users, and Ang blog na ito ay tungkol sa Go 1.25's bagong eksperimental at ang packages, which bring long-awaited improvements and fixes. This post argues for a new major API version, provides an overview of the new packages, and explains how you can make use of it. The experimental packages are not visible by default and may undergo future API changes. encoding/json encoding/json/v2 encoding/json/jsontext Problema sa encoding/json ang napili ng mga taga-hanga: Jason sa lahat, 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 Mga defect sa behavior Maraming mga error sa behavior : 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 Ang JSON ay karaniwang ginagamit upang makipag-ugnayan sa mga programa gamit ang mga implementasyon ng JSON na hindi nagbibigay ng null na unmarshalled sa isang uri ng data na inaasahan na maging isang JSON array o object. Dahil ang coding/json marshalls isang nil slice o mapa bilang isang JSON null, ito ay maaaring humantong sa mga error kapag unmarshalled sa pamamagitan ng iba pang mga implementasyon. Ang isang survey ay nagpapakita na ang karamihan ng mga gumagamit ng Go ay mas gusto na nil slices at mga mapa ay marshalled bilang isang empty JSON array o object sa default. Case-insensitive unmarshaling: Kapag unmarshaling, ang isang JSON object member name ay resolved sa isang Go struct field name gamit ang isang case-insensitive match. Incoherent calling of methods: Dahil sa isang detalye ng implementation, MarshalJSON methods declared sa isang pointer receiver ay incoherently naulat sa pamamagitan ng encoding/json. Habang tinatanggap bilang isang bug, ito ay hindi maaaring i-fixed dahil maraming mga application depende sa kasalukuyang behavior. Ang mga deficiency Ang mga fire of Ang mga ito ay maaaring maging mababang o mababang: encoding/json Ang mga gumagamit ay karaniwang i-unmarshal mula sa isang io.Reader. Ang mga gumagamit ay karaniwang i-writing json.NewDecoder(r).Decode(v), na hindi nagpapahiwatig ng trailing junk sa katapusan ng input. Options can be set on the and types, but cannot be used with the and functions. Similarly, types implementing the and interfaces cannot make use of the options and there is no way to plumb options down the call stack. For example, the option loses its effect when calling a custom method. Encoder Decoder Marshal Unmarshal Marshaler Unmarshaler Decoder.DisallowUnknownFields UnmarshalJSON Ang mga function ng Compact, Indent, at HTMLEscape ay mag-script sa isang bytes.Buffer sa halip ng isang bagay na mas fleksibong tulad ng isang []byte o io.Writer. Ito limitasyon ang usability ng mga function na ito. Mga limitasyon sa performance Upang ilagay ang mga detalye ng internal implementation, ang public API ay nag-iisa sa anumang limitasyon ng pagganap: : 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 Dahil dito, ang implementasyon ng a o sa Ang metriko para sa espasyo-panahong Schwarzschild na may sistemang koordinatong ( or ang function, pagkatapos ay ang performance ay maging quadratic. MarshalJSON UnmarshalJSON Marshal Unmarshal nagtatrabaho sa fix sa direktang ang napili ng mga taga-hanga: Jason ang napili ng mga taga-hanga: Jason Ang pag-introduction ng isang bagong, incompatible pangunahing bersyon ng isang pakete ay isang mahigpit na pag-aaral. Kung posible, dapat nating subukan upang i-fix ang kasalukuyang pakete. Habang ito ay relatibong madaling magdagdag ng mga bagong mga tampok, ito ay mahirap upang baguhin ang mga kasalukuyang tampok. Malamang, ang mga problema na ito ay mga pangkaraniwang pangangasiwa ng mga kasalukuyang API, na kung saan sila ay karaniwang hindi maaaring i-fix sa loob ng . Go 1 compatibility promise May mga pagkakataon na may mga pangalan, tulad ng o sa , ngunit ito ay katumbas na lumikha ng isang parallel namespace sa loob ng parehong pakete. Ito ay nagdadala sa amin (Ito ang ibig sabihin Kung paano gumawa ng mga pagbabago sa anumang lugar sa pamamagitan ng namespace (Ito ang ibig sabihin ang mga ito) MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Planning para sa ang napili ng mga taga-hanga: JSON/V2 ang napili ng mga taga-hanga: JSON/V2 Ang paggawa ng isang bagong major version ng spanned years. In late 2020, spurred on by the inability to fix issues in the current package, Daniel Martí (one of the maintainers of (Pinatawag na ang kanyang mga ideya tungkol sa at malapit na ding maging isang trahedya Si Joe Tsai ay napaka-disappointed sa ang pakete na kailangan upang gamitin ang isang custom JSON implementation dahil Hindi na maaaring humantong sa mas karaniwang JSON standard na kinakailangan ng Protocol Buffer specification, at hindi na mahigpit na serializing JSON sa isang streaming na paraan. encoding/json encoding/json Ano ang hypothetical v2 Go API for Protocol Buffers the protojson encoding/json Sa pananampalataya ng isang mas mataas na bukas para sa JSON ay ganap na ganap at makukuha, si Daniel at Joe ay sumali sa mga kapangyarihan upang brainstorm sa at ang (na may unang code na isang polished bersyon ng JSON serialization logic mula sa Go protobuf module). Sa paglipas ng panahon, ang ilang iba (Roger Peppe, Chris Hines, Johan Brandhorst-Satzkorn, at Damien Neil) sumali sa pag-aalok ng design review, code review, at regression testing. at ang . v2 Nagsimula ang paggawa ng isang prototype recorded meetings meeting notes Ang trabaho na ito ay publikong mula sa unang pagkakataon, at kami ay higit pa sumali sa mas mataas na komunidad ng Go, unang kasama ang isang at ang na ang , and most recently bilang isang eksperimento ng Go (mga magagamit sa Go 1.25) para sa mas malalaking pagsubok sa pamamagitan ng lahat ng mga gumagamit ng Go. GopherCon talk Diskusiya Posted sa katapusan ng 2023 Formal na proposal na inilabas sa simula ng 2025 adopting encoding/json/v2 ang Ang pag-aaral ay nangangailangan para sa 5 taon, na naglalaman ng feedback mula sa maraming contributors at din makakuha ng mahalagang empirical na karanasan mula sa paggamit sa produksyon setting. v2 It’s worth noting that it’s largely been developed and promoted by people not employed by Google, demonstrating that the Go project is a collaborative endeavor with a thriving global community dedicated to improving the Go ecosystem. Pagbutihin ang Mga pahinang tumuturo sa JSON / JSON Mga pahinang tumuturo sa JSON / JSON Before discussing the API, we first introduce the experimental isang pakete na nagtatag ng mga pangunahing base para sa mga future improvements sa JSON sa Go. v2 encoding/json/jsontext JSON serialization in Go can be broken down into two primary components: sintactic functionality na nagtatrabaho sa pagproseso ng JSON batay sa kanyang grammatics, at Semantic functionality na nagpapakita ng relasyon sa pagitan ng mga halaga ng JSON at mga halaga ng Go. Ginagamit namin ang mga termino "coding" at "decoding" upang ilarawan ang sintactic functionality at ang mga termino "marshal" at "unmarshal" upang ilarawan ang semantic functionality. Ang diagram na ito ay nagbibigay ng isang pakikipagsapalaran ng separation na ito. Purple blocks ay nagpapakita ng mga uri, habang blue blocks ay nagpapakita ng mga function o mga paraan. Ang direksyon ng mga arrow ay halos nagpapakita ng flow ng data. Ang pangunahing bahagi ng diagram, na itinatag sa pamamagitan ng package, contains functionality that is only concerned with syntax, while the upper half, implemented by the Ang pakete, ay naglalaman ng functionality na ibinigay ng semantic meaning sa syntactic data na ginagamit ng pangunahing halimbawa. jsontext json/v2 The basic API of Ito ang mga sumusunod: 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 ang Ang pakete ay nagbibigay ng functionality para sa pag-interact sa JSON sa isang syntactic level at binubuo ang kanyang pangalan mula sa kung saan ang grammatics para sa JSON data ay literal na tinatawag Dahil ito ay mag-interact sa JSON lamang sa isang syntactic level, ito ay hindi depende sa Go reflection. jsontext RFC 8259, seksyon 2 JSON-text ang at ang magbibigay ng suporta para sa pag-encode at pag-decode ng mga halaga at token ng JSON. ang mga constructors that affect the particular behavior of encoding and decoding. Unlike the at ang types declared in Ang mga bagong mga tao sa Huwag mag-imbak ang pagitan sa pagitan ng syntax at semantics at mag-operate sa isang tunay na streaming na paraan. Encoder Decoder I-accept ang variable options Encoder Decoder v1 jsontext A JSON value is a complete unit of data and is represented in Go as Ito ay identical sa in Ang isang JSON value ay sintactically binubuo ng isa o higit sa isang JSON token. Ang isang JSON token ay ibinibigay sa Go bilang ang Ang mga sumusunod na mga materyales at mga aksesorya ay tulad ng mga in But is designed to represent arbitrary JSON tokens without allocation. a named []byte RawMessage v1 opaque Token Token v1 Upang i-solve ang mga pangunahing problema ng performance sa pamamagitan ng at ang interface methods, we need an efficient way of encoding and decoding JSON as a streaming sequence of tokens and values. In Ipinapakita natin ang at ang Ang mga interfaces na gumagana sa isang o sa , na nagpapahintulot ng mga implementasyon ng mga methods sa pagproseso ng JSON sa isang purong streaming na paraan. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder Dahil dito, ang Ang pakete ay hindi kailangang maging responsable para sa pag-validate o format ng isang halaga ng JSON na bumalik sa pamamagitan ng , hindi kailangang maging responsable para sa pagkuha ng mga limitasyon ng isang halaga ng JSON na ibinigay sa Ang responsibilidad na ito ay sa mga at ang . json MarshalJSON UnmarshalJSON Encoder Decoder Introducing encoding/json/v2 encoding/json/v2 Building on the Pagkatapos ng eksperimento, inilagay namin ang Nagtataka kung ano ito ay tungkol sa ako nagpasya, inexplicably, na ang pinakamahusay na bagay na gawin ay, hindi upang tumakbo sa banyo, ngunit upang pumunta sa isang pagmumuni-muni. package. Our goal is that usages of Mag-operate ang the same if directly migrated to . jsontext encoding/json/v2 v1 v1 sa karamihan v2 Sa artikulong ito, i-cover ang high-level API ng Para sa mga halimbawa tungkol sa kung paano gamitin ito, kami ay nag-iisip ng mga readers upang pananaliksik package or read . v2 Ang mga halimbawa sa v2 Ang blog ni Anton Zhiyanov na naglalaman ng tema Ang mga pangunahing API Ito ang mga sumusunod: 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 functions have a signature similar to , but accept options to configure their behavior. The and functions directly operate on an o sa , avoiding the need to temporarily construct an o sa I-read or write sa mga bagay na ito. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder The at ang Ang function ay nagtatrabaho sa a at ang Ito ay dahil ang mga termino at kontekstong ginagagamit ay mas malinaw at madali maintindihan. , ang mga opsyon ay isang first-class argument sa bawat ng mga function ng marshal at non-marshal, na mas mataas ang flexibility at configurability ng May mga in Ang mga ito ay hindi tinutukoy sa artikulong ito. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 several options available v2 Tipo-specific ang customization Similar to , ay nagbibigay-daan sa mga uri upang i-definite ang kanilang sarili na JSON representation sa pamamagitan ng pagkuha ng anumang mga interface. 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 } ang at ang Ang mga interfaces ay identical sa mga ang new at ang Ang mga interface ay nagbibigay-daan ng isang type na mag-represento bilang JSON gamit ang isang or Ito ay nagbibigay-daan sa mga opsyon na mag-post sa ilalim ng call stack, dahil ang mga opsyon ay maaaring i-download sa pamamagitan ng accessor method on the o sa . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder ang isang halimbawa para sa kung paano i-implementate ang isang custom type na nagbibigay-daan sa pag-order ng mga miyembro ng JSON object. ang OrderedObject Caller-specified customization In At ang caller ng at ang Maaari rin na itakda ang isang custom JSON representation para sa anumang arbitrary na uri, kung saan ang caller-specified function ay may kapangyarihan sa type-defined methods o ang default representation para sa isang particular na uri. 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 at ang Ipinanganak ang isang marshaler na maaaring magpasalamat sa isang Paggamit ng paggamit sa pamamagitan ng pag-aayos ng mga marshalling ng anumang uri. tulad ng, at ang Subukan ang similar customization para sa . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal Ang isang halimbawa ay nagpapakita kung paano ang feature na ito ay nagbibigay ng seryalization ng lahat ng Mga bagay na dapat gawin sa pamamagitan ng ang pakete. The ProtoJSON proto.Message protojson Mga Differential ng Behavior habang Tapos na ang behavior Ang parehong Ang kanyang behavior ay nagbabago Para sa pag-aayos ng mga problema sa , most notably: v2 sa karamihan v1 Sa ilang paraan 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 Para sa karamihan ng mga pagbabago ng behavior, mayroong isang struct tag option o caller-specified option na maaaring i-configure ang behavior upang gumagana sa ilalim ng o sa Magbigay ng inspirasyon sa kontemporaryong designer ay maaaring gumawa ng kahit ano, kahit ano, at ang New Year - ay walang exception. for more information. v1 v2 “Migrating to v2” Performance optimizations The performance of is roughly at parity with . Sometimes it is slightly faster, but other times it is slightly slower. The ang performance Ito ay mas mabilis kaysa sa , with benchmarks demonstrating improvements of up to 10x. Marshal v2 v1 Unmarshal v2 v1 In order to obtain greater performance gains, existing implementations of at ang Kailangan ng migration para sa implementasyon and , so that they can benefit from processing JSON in a purely streaming manner. For example, recursive parsing of OpenAPI specifications in Ang mga metodo ay nangangahulugan na nakakaapekto sa pagganap sa isang anumang serbisyo ng Kubernetes (tingnan (Kapag bumalik na ako sa Pagbabago ng performance sa pamamagitan ng mga order ng magnitude. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON ang napili ng mga taga-hanga: kubernetes/kube-openapi#315 UnmarshalJSONFrom Para sa karagdagang impormasyon, tingnan ang ang repository. go-json-experiment/jsonbench Pagbabago ng retroactive ang napili ng mga taga-hanga: Jason ang napili ng mga taga-hanga: Jason Gusto naming i-evite ang dalawang patuloy na implementasyon ng JSON sa Go standard library, kaya ito ay kritikal na, sa ilalim ng kape, is implemented in terms of . v1 v2 There are several benefits to this approach: Gradual migration: Ang mga function ng Marshal at Unmarshal sa v1 o v2 ay nagpapakita ng isang set ng default behaviors na gumagana ayon sa v1 o v2 semantics. Ang mga opsyon ay maaaring na-specify na mag-configure ng Marshal o Unmarshal upang gumagana sa ganap na v1, karamihan ng v1 na may ilang v2, isang mix ng v1 o v2, karamihan ng v2 na may ilang v1, o ganap na v2 semantics. Ito ay nagbibigay ng gradual na migration sa pagitan ng mga default behaviors ng dalawang bersyon. : As backward-compatible features are added to , they will inherently be made available in . For example, adds support for several new struct tag options such as or and also support for the and interface methods, which are both more performant and flexible. When is implemented in terms of , it will inherit support for these features. Feature inheritance v2 v1 v2 inline format MarshalJSONTo UnmarshalJSONFrom v1 v2 Reduced maintenance: Ang paghahatid ng isang karaniwang ginagamit na pakete ay nangangailangan ng karaniwang pag-uugali. Sa pamamagitan ng magkaroon ng v1 at v2 na gamitin ang parehong pag-implementasyon, ang pag-uugali ng pag-uugali ay na-reduced. Sa pangkalahatan, isang single pagbabago ay i-fix bugs, i-improve performance, o i-add functionality sa parehong bersyon. Walang kailangang backport ang isang v2 pagbabago sa isang katumbas na v1 pagbabago. While select parts of Ang mga ito ay maaaring magkaroon ng isang panahon (suppose sa pamamagitan ng mga graduates mula sa pagiging isang eksperimento), ang pakete bilang isang buong ay hindi mai-deprecate. will be encouraged, but not required. The Go project will not drop support for . v1 v2 v2 v1 Experimenting with jsonv2 Mga pahinang Ang mga bagong API sa and packages are not visible by default. To use them, build your code with sa pamamagitan ng iyong environment o sa pamamagitan ng iyong Build tag. Ang katotohanan ng isang eksperimento ay na ang API ay hindi napaka-stable at maaaring magbabago sa hinaharap. Habang ang API ay hindi napaka-stable, ang pag-implementasyon ay ng mataas na kalidad at ay na-usapan sa produksyon ng ilang mga pangunahing proyekto. encoding/json/jsontext encoding/json/v2 GOEXPERIMENT=jsonv2 goexperiment.jsonv2 The fact that Ito ay ginagamit sa pamamagitan ng Dahil dito, ang pangunahing implementasyon ng is completely different when building under the Kung hindi mo i-modify ang anumang code, maaari mong i-execute ang iyong mga test sa ilalim ng and theoretically nothing new should fail: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... Ang re-implementasyon ng Dahil sa Ito ay nagbibigay ng mga patakaran sa pagitan ng limitasyon ng Ang maliliit na negosyo sa mga sumusunod na sektor ay kinakailangan: pagproseso ng produktong agrikultural ( I-report ang lahat ng regressions . v1 v2 Go 1 compatibility promise jsonv2 Tungkol sa Tracker Kung maging isang eksperimento sa Go 1.25 ay isang mahalagang milestone sa lalong sa formally adopting at ang sa isang library, ngunit ang mga ito ay Ang iyong mga feedback ay itinuturing ang aming mga susunod na mga patakaran, at ang resulta ng eksperimento na ito, na maaaring magdadala sa anumang bagay mula sa pag-abandon ng pagsasanay, sa pag-adoptasyon bilang stable packages ng Go 1.26. Mangyaring ibahagi ang iyong karanasan sa , and help determine the future of Go. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/sa mga problema 71497 Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines, and Damien Neil Ang artikulong ito ay magagamit sa The Go Blog sa ilalim ng lisensya ng CC BY 4.0 DEED. ang blog ay ang blog ay Foto sa pamamagitan ng Jr Korpa sa Unsplash ang jr corpa Mga Unsplash