Nové experimentální balíčky Go: Co je třeba vědět

Úvodní je jednoduchý formát výměny dat. Téměř před 15 lety jsme napsali o , který představil schopnost serializovat a deserializovat typy Go do a z dat JSON. Od té doby se JSON stal nejoblíbenějším datovým formátem používaným na internetu. Je široce čten a psán Go programy, a kódování/json nyní řadí jako 5. nejvíce importovaný Go balíček. Nastavení JavaScript Object Notation (JSON) Podpora JSON v Go Postupem času se balíčky vyvíjejí s potřebami svých uživatelů a Tento blogový příspěvek je o novém experimentálním Go 1.25 a Tento příspěvek argumentuje pro novou hlavní verzi API, poskytuje přehled nových balíčků a vysvětluje, jak je můžete využít. encoding/json encoding/json/v2 encoding/json/jsontext Problémy s encoding/json Kódování / JSON v celku , Myšlenka marshaling a unmarshaling arbitrážních typů Go s nějakým výchozím zastoupením v JSON, v kombinaci se schopností přizpůsobit zastoupení, se ukázala být vysoce flexibilní. encoding/json Chování chyb Existují různé poruchy chování : 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 Úniková nylost řezů a map: JSON se často používá k komunikaci s programy pomocí implementací JSON, které neumožňují null být unmarshed do datového typu očekávaného jako JSON array nebo objekt. Vzhledem k tomu, že kódování/json marshals nil řez nebo mapu jako JSON null, to může vést k chybám při unmarshalingu jinými implementacemi. Case-insensitive unmarshaling: Při unmarshalingu je jméno člena objektu JSON vyřešeno na jméno pole Go struct pomocí case-insensitive match. Nekonzistentní volání metod: Vzhledem k detailu implementace jsou metody MarshalJSON deklarované na přijímači ukazatele nekonzistentně nazývány kódováním/jsonem. Nedostatky ohně Oheň z Může být obtížné nebo omezující: encoding/json Uživatelé často píší json.NewDecoder(r).Decode(v), který na konci vstupu neodmítá sledující odpadky. Možnosti lze nastavit na typy Encoder a Decoder, ale nemohou být použity s funkcemi Marshal a Unmarshal. Podobně typy, které implementují rozhraní Marshaler a Unmarshaler, nemohou využít možnosti a není možné nastavit možnosti dolů do hovoru. Například možnost Decoder.DisallowUnknownFields ztrácí svůj účinek při volání vlastní metody UnmarshalJSON. Funkce Compact, Indent a HTMLEscape píší do bajtů.Buffer místo něčeho flexibilnějšího, jako je []byte nebo io.Writer. Omezení výkonu Setting aside internal implementation details, the public API commits it to certain performance limitations: : 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 Kromě toho, pokud je provádění a nebo Metoda recursivně nazývá nebo funkce, pak se výkon stává kvadratickým. MarshalJSON UnmarshalJSON Marshal Unmarshal Snažíme se opravit přímo Kódování / JSON Kódování / JSON Zavedení nové, neslučitelné hlavní verze balíčku je těžké úvahy. pokud je to možné, měli bychom se pokusit opravit stávající balíček. I když je relativně snadné přidat nové funkce, je obtížné změnit stávající funkce. Bohužel tyto problémy jsou důsledky stávajícího rozhraní API, takže je prakticky nemožné opravit v rámci rozhraní API. . Go 1 kompatibilita slib V zásadě bychom mohli deklarovat samostatná jména, jako jsou: nebo , ale to je stejné jako vytváření paralelního jmenového prostoru v rámci téhož balíčku. (od nynějška voláme , kde můžeme tyto změny provést v rámci samostatného Namespace na rozdíl od (od nynějška voláme ) se MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Plánování pro encoding/json/v2 Kódování / JSON / V2 Plánování nové hlavní verze spanned years. In late 2020, spurred on by the inability to fix issues in the current package, Daniel Martí (one of the maintainers of (Nejprve napsal své myšlenky na balíček by měl vypadat. samostatně, po předchozí práci na Joe Tsai byl zklamaný. balíček potřebný k použití vlastní implementace JSON, protože nebyl schopen dodržovat přísnější standard JSON, který specifikace Protocol Buffer vyžadovala, ani efektivně serializovat JSON streamovaným způsobem. encoding/json encoding/json Co je hypotetické v2 Go API pro protokolové buffery Ať protojson encoding/json Věřící, že světlejší budoucnost pro JSON byla prospěšná i dosažitelná, Daniel a Joe spojili své síly, aby přemýšleli. a (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 Začal stavět prototyp zaznamenané schůzky Setkání poznámek Tato práce byla od počátku veřejná a my jsme se stále více zapojili do širší komunity Go, nejprve s a , , a v poslední době jako Go experiment (k dispozici v Go 1.25) pro širší testování všemi Go uživateli. GopherCon mluví Diskuse zveřejněná koncem roku 2023 Formální návrh zveřejněný na začátku roku 2025 Adopce encoding/json/v2 Tyto úsilí probíhá již 5 let, zahrnuje zpětnou vazbu od mnoha přispěvatelů a také získává cenné empirické zkušenosti z použití ve výrobních prostředích. v2 Stojí za zmínku, že byl do značné míry vyvinut a propagován lidmi, kteří nejsou zaměstnáni společností Google, což dokazuje, že projekt Go je kolaborativním úsilím s prosperující globální komunitou věnovanou zlepšování ekosystému Go. Stavba na encoding/json/jsontext kódování/json /jsontext Before discussing the V první řadě uvádíme experimentální balíček, který položí základy pro budoucí vylepšení JSON v Go. v2 encoding/json/jsontext Serializace JSON v Go lze rozdělit na dvě hlavní složky: syntaxní funkce, která se zabývá zpracováním JSON na základě jeho gramatiky, a that defines the relationship between JSON values and Go values. semantic functionality Používáme termíny „kódovat“ a „dekódovat“ k popisu syntaktické funkčnosti a termíny „maršál“ a „unmaršál“ k popisu sémantické funkčnosti. Tento diagram poskytuje přehled tohoto oddělení. Purpurové bloky představují typy, zatímco modré bloky představují funkce nebo metody. Směr šipek přibližně představuje tok dat. Spodní polovina diagramu, implementovaná balíček, obsahuje funkčnost, která se týká pouze syntaxe, zatímco horní polovina, implementovaná package, contains functionality that assigns semantic meaning to syntactic data handled by the bottom half. jsontext json/v2 Základní API Je to následující: 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 Tyto balíček poskytuje funkčnost pro interakci s JSON na syntaktické úrovni a odvozuje jeho název od kde je gramatika pro data JSON doslova nazývána Vzhledem k tomu, že interaguje pouze s JSON na syntaktické úrovni, nezávisí na odrazu Go. jsontext RFC 8259, oddíl 2 JSON-text Tyto a poskytují podporu pro kódování a dekódování hodnot JSON a tokenů. které ovlivňují konkrétní chování kódování a dekódování. na rozdíl od a Typy deklarované v Nové typy v Vyhněte se rozlišování mezi syntaxí a semantikou a pracujte skutečně streamovaným způsobem. Encoder Decoder Přijmout variabilní možnosti Encoder Decoder v1 jsontext A JSON value is a complete unit of data and is represented in Go as Je to totožné s v Hodnota JSON se syntakticky skládá z jednoho nebo více JSON tokenů. s konstruktory a doplňkovými metodami. je podobné v ale je navržen tak, aby představoval libovolné JSON tokeny bez přidělení. Jmenuje se []byte RawMessage v1 Opatrný Token Token v1 Řešení základních výkonnostních problémů s a Metody rozhraní, potřebujeme efektivní způsob kódování a dekódování JSON jako streamovací sekvence tokenů a hodnot. Představíme tedy a Metody, které fungují na nebo , což umožňuje implementacím metod zpracovávat JSON čistě streamovaným způsobem. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder Tímto způsobem se balíček nemusí být zodpovědný za ověření nebo formátování hodnoty JSON vrácené , ani by neměla být zodpovědná za určení hranic hodnoty JSON poskytnuté Tyto povinnosti patří do a . json MarshalJSON UnmarshalJSON Encoder Decoder zavádění encoding/json/v2 Kódování / JSON / V2 Building on the Nyní přinášíme experimentální package. It is designed to fix the aforementioned problems, while remaining familiar to users of the package. Our goal is that usages of Bude operovat the same if directly migrated to . jsontext encoding/json/v2 v1 v1 Většinou v2 V tomto článku se zaměříme především na vysokou úroveň Pro příklady toho, jak jej používat, doporučujeme čtenářům studovat balíček nebo čtení . v2 Příklady v v2 Blog Anton Zhiyanov pokrývající toto téma Základní API is the following: 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 Tyto and funkce mají podobný podpis jako , but accept options to configure their behavior. The a Funkce působí přímo na or Aby se zabránilo nutnosti dočasně vytvořit nebo Číst nebo psát o takových lidech. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder Tyto a Funkce funguje na A a and is actually the underlying implementation of the previously mentioned functions. Unlike , možnosti jsou prvotřídním argumentem pro každou z maršálových a nemaršálových funkcí, což výrazně rozšiřuje flexibilitu a konfigurovatelnost . There are v které nejsou uvedeny v tomto článku. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 Několik dostupných možností v2 Typ specifické customizace Podobně jako , , Umožňuje typům definovat vlastní JSON reprezentaci uspokojováním konkrétních rozhraní. 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 a Rozhraní je totožné s těmi v • Nový a Tyto rozhraní umožňují, aby se typ představoval jako JSON pomocí nebo To umožňuje posílat možnosti dolů do hovoru, protože možnosti lze získat prostřednictvím Přístupová metoda na nebo . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder se Příklad, jak implementovat vlastní typ, který udržuje uspořádání členů objektů JSON. Ať OrderedObject Caller-specified customization In A volající z a 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 a vytvořit vlastní maršál, který může být předán na Volání pomocí to override the marshaling of particular types. Similarly, a Podpora podobné personalizace pro . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal example demonstrates how this feature allows serialization of all Typy, které mají být řízeny Z balíčku . The ProtoJSON proto.Message protojson Rozdíly v chování Zatímco aims to behave Stejně jako Jeho chování se změnilo to address problems in A nejvíce zejména: v2 Většinou v1 V některých ohledech 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 U většiny změn chování existuje možnost struktury značky nebo volající specifikovaná možnost, která může konfigurovat chování tak, aby fungovalo pod nebo Semantika, nebo dokonce jiné chování určené volatelem. viz Pro více informací. v1 v2 “Migrating to v2” Performance optimizations Tyto Výkonnost O Je přibližně na paritě s Někdy je to trochu rychlejší, ale jindy je to trochu pomalejší. Výkonnost O is significantly faster than , s referenčními hodnotami prokazujícími zlepšení až 10x. Marshal v2 v1 Unmarshal v2 v1 Aby bylo možné dosáhnout vyšších výkonnostních zisků, existující implementace a should migrate to also implement a , takže mohou těžit z zpracování JSON čistě streamovaným způsobem. Například recursivní analýza specifikací OpenAPI v metody výrazně narušily výkon v určité službě Kubernetes (viz a) při přechodu na Vylepšený výkon podle velikostních řádků. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON Kubernetes / Kube-openapi #315 UnmarshalJSONFrom Pro více informací viz a repozitáře. go-json-experiment/jsonbench Retroaktivní zlepšení encoding/json Kódování / JSON Chceme se vyhnout dvěma odděleným implementacím JSON ve standardní knihovně Go, takže je důležité, aby pod kapotou, Provádí se z hlediska . v1 v2 Existuje několik výhod tohoto přístupu: Postupná migrace: Funkce Marshal a Unmarshal v v1 nebo v2 představují soubor výchozích chování, které fungují podle sémantiky v1 nebo v2. Možnosti mohou být specifikovány tak, aby konfigurovaly funkce Marshal nebo Unmarshal tak, aby fungovaly zcela v1, většinou v1 s nějakým v2, směskou v1 nebo v2, většinou v2 s nějakým v1, nebo zcela v2 sémantiky. Dědičnost funkcí: Vzhledem k tomu, že jsou zpětně kompatibilní funkce přidány do v2, budou v podstatě k dispozici v v1. Například v2 přidává podporu pro několik nových možností struktury, jako je inline nebo formát, a také podporu pro metody rozhraní MarshalJSONTo a UnmarshalJSONFrom, které jsou výkonnější a flexibilnější. Snížená údržba: Údržba široce používaného balíčku vyžaduje značné úsilí. Tím, že v1 a v2 používají stejnou implementaci, je zátěž údržby snížena. Obecně platí, že jediná změna opraví chyby, zlepší výkon nebo přidá funkčnost do obou verzí. Není třeba backportovat změnu v2 s ekvivalentní změnou v1. While select parts of může být časově omezena (předpokládá se, že absolventů z bytí experiment), balíček jako celek nikdy nebude znehodnocen. bude podporováno, ale není vyžadováno. projekt Go neztratí podporu pro . v1 v2 v2 v1 Experimentování s jsonv2 JSONV2 Nejnovější ohňostroj v a balíčky nejsou ve výchozím nastavení viditelné. Chcete-li je použít, vytvořte svůj kód ve svém životním prostředí nebo s Přirozenost experimentu spočívá v tom, že rozhraní API je nestabilní a může se v budoucnu změnit.Ačkoli rozhraní API je nestabilní, implementace je vysoce kvalitní a bylo úspěšně použito ve výrobě několika hlavními projekty. encoding/json/jsontext encoding/json/v2 GOEXPERIMENT=jsonv2 goexperiment.jsonv2 Skutečnost, že is implemented in terms of Znamená to, že podkladová implementace is completely different when building under the Bez změny jakéhokoli kódu byste měli být schopni spustit testy pod a teoreticky by nic nového nemělo selhat: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... The re-implementation of Z hlediska Cílem je poskytnout stejné chování v mezích , ačkoli některé rozdíly mohou být pozorovatelné, jako je přesné znění chybových zpráv. and report any regressions . v1 v2 Go 1 kompatibilita slib jsonv2 Na téma Tracker Becoming an experiment in Go 1.25 is a significant milestone on the road to formally adopting and do standardní knihovny. nicméně účel Vaše zpětná vazba určí naše další kroky a výsledek tohoto experimentu, který může mít za následek cokoli od opuštění úsilí, až po přijetí jako stabilní balíčky Go 1.26. Pomozte rozhodnout o budoucnosti. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/výzva 71497 Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines a Damien Neil Tento článek je k dispozici na The Go Blog pod licencí CC BY 4.0 DEED. Blog Go Blog Go Photo by on Jr Korpa Unsplashová JR Korpa Unsplashová