Go's Neue Experimentelle Pakete: Was zu wissen ist

Einführung ist ein einfaches Datenaustauschformat.Vor fast 15 Jahren schrieben wir über , die die Fähigkeit zur Serialisierung und Deserialisierung von Go-Typen zu und von JSON-Daten eingeführt hat.Seitdem ist JSON das beliebteste Datenformat im Internet geworden.Es wird weit verbreitet von Go-Programmen gelesen und geschrieben, und Coding/json rangiert jetzt als das fünftgrößte importierte Go-Paket. Die JavaScript Object Notation (JSON) Unterstützung für JSON in Go Im Laufe der Zeit entwickeln sich die Pakete mit den Bedürfnissen ihrer Nutzer und ist keine Ausnahme. Dieser Blogbeitrag handelt von Go 1.25s neuem Experimental und Dieser Beitrag argumentiert für eine neue große API-Version, bietet einen Überblick über die neuen Pakete und erklärt, wie Sie sie nutzen können. encoding/json encoding/json/v2 encoding/json/jsontext Probleme mit Codierung / Jason Codierung / Jason im Allgemeinen, Die Idee von marshaling und unmarshaling willkürlichen Go-Typen mit einer gewissen Standarddarstellung in JSON, kombiniert mit der Fähigkeit, die Darstellung anzupassen, hat sich als sehr flexibel erwiesen. encoding/json Verhaltensfehler Es gibt verschiedene Verhaltensfehler in : 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: Beim Unmarshaling wird ein JSON-Objekt-Mitgliedenname mit einem Case-insensitive Match zu einem Go-Struct-Feldname gelöst. Inkonsistentes Anrufen von Methoden: Aufgrund eines Implementierungsdetails werden MarshalJSON-Methoden, die auf einem Zeigerempfänger deklariert werden, durch Codierung/json inkonsistent genannt. Feuermangel Das Feuer des Es kann schwierig oder einschränkend sein: encoding/json Benutzer schreiben oft json.NewDecoder(r).Decode(v), die den nachfolgenden Müll am Ende der Eingabe nicht ablehnt. Optionen können auf den Encoder- und Decoder-Typen eingestellt werden, können aber nicht mit den Marshal- und Unmarshal-Funktionen verwendet werden. Ähnlich können Typen, die die Marshaler- und Unmarshaler-Schnittstellen implementieren, die Optionen nicht nutzen und es gibt keine Möglichkeit, Optionen in den Anrufstapel zu verdrängen. Zum Beispiel verliert die Option Decoder.DisallowUnknownFields ihre Wirkung, wenn Sie eine benutzerdefinierte UnmarshalJSON-Methode anrufen. The , , and functions write to a instead of something more flexible like a or . This limits the usability of those functions. Compact Indent HTMLEscape bytes.Buffer []byte io.Writer Leistungsbegrenzungen Indem die interne Implementierungsdetails beiseite gestellt werden, verpflichtet sich die öffentliche API zu bestimmten Leistungsbegrenzungen: : 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 Auch wenn die Umsetzung einer oder method recursively calls the oder Funktion, dann wird die Leistung quadratisch. MarshalJSON UnmarshalJSON Marshal Unmarshal Versuchen zu reparieren direkt encoding/json encoding/json Die Einführung einer neuen, nicht kompatiblen Hauptversion eines Pakets ist eine schwere Überlegung. Obwohl es relativ einfach ist, neue Features hinzuzufügen, ist es schwierig, bestehende Features zu ändern. Leider sind diese Probleme inhärente Folgen der bestehenden API, was sie praktisch unmöglich macht, innerhalb der . Go 1 Kompatibilitätsversprechen Wir könnten grundsätzlich getrennte Namen erklären, wie oder , aber das ist gleichbedeutend mit der Erstellung eines parallelen Namespaces innerhalb desselben Pakets. (henceforth called , wo wir diese Änderungen in einem separaten namespace in contrast to (von nun an heißt es der ) MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Planung für encoding/json/v2 Codierung / JSON / V2 Vorbereitung auf eine neue Version von Ende 2020, angetrieben von der Unfähigkeit, Probleme im aktuellen Paket zu beheben, Daniel Martí (einer der Er schrieb zuerst seine Gedanken über Verpackung sollte aussehen. getrennt, nach vorheriger Arbeit an der Joe Tsai war enttäuscht. Paket benötigt, um eine benutzerdefinierte JSON-Implementierung zu verwenden, weil war weder in der Lage, sich an den strengeren JSON-Standard zu halten, den die Protocol Buffer-Spezifikation erfordert, noch in der Lage, JSON effizient in einer Streaming-Methode zu serialisieren. encoding/json encoding/json Was für eine Hypothese v2 Go API für Protocol Buffers Die protojson encoding/json In der Überzeugung, dass eine bessere Zukunft für JSON sowohl vorteilhaft als auch erreichbar war, schlossen sich Daniel und Joe zusammen, um auf und (der ursprüngliche Code ist eine polierte Version der JSON-Serialisierungs-Logik aus dem Go-Protobuf-Modul). Im Laufe der Zeit haben sich einige andere (Roger Peppe, Chris Hines, Johan Brandhorst-Satzkorn und Damien Neil) der Anstrengung angeschlossen, indem sie Designüberprüfung, Codeüberprüfung und Regressionstests bereitgestellt haben. und . v2 Beginn der Konstruktion eines Prototyps Aufgezeichnete Treffen Treffen Notizen Diese Arbeit ist von Anfang an öffentlich, und wir haben die breitere Go-Community zunehmend involviert, zuerst mit einer und , der Und vor kurzem als Go-Experiment (in Go 1.25 verfügbar) für größere Tests durch alle Go-Nutzer. Gophercon spricht discussion posted in late 2023 formal proposal posted in early 2025 Adoptieren encoding/json/v2 The effort has been going on for 5 years, incorporating feedback from many contributors and also gaining valuable empirical experience from use in production settings. v2 Es ist erwähnenswert, dass es weitgehend von Menschen entwickelt und gefördert wurde, die nicht von Google beschäftigt sind, was zeigt, dass das Go-Projekt eine kollaborative Anstrengung mit einer blühenden globalen Gemeinschaft ist, die sich der Verbesserung des Go-Ökosystems verschrieben hat. Gebäude auf Codierung / JSON / JSONTEXT Codierung / JSON / JSONTEXT Bevor wir über die API, wir stellen zunächst die experimentelle Paket, das die Grundlagen für zukünftige Verbesserungen von JSON in Go legt. v2 encoding/json/jsontext JSON-Serialisierung in Go kann in zwei Hauptkomponenten unterteilt werden: syntaktische Funktionalität, die sich mit der Verarbeitung von JSON auf der Grundlage seiner Grammatik befasst, und Semantische Funktionalität, die die Beziehung zwischen JSON-Werten und Go-Werten definiert. Wir verwenden die Begriffe „codieren“ und „decodieren“, um syntaktische Funktionalität zu beschreiben, und die Begriffe „marshal“ und „unmarshal“ um semantische Funktionalität zu beschreiben. Dieses Diagramm bietet einen Überblick über diese Trennung. Purpurblöcke repräsentieren Typen, während blaue Blöcke Funktionen oder Methoden repräsentieren. Die Richtung der Pfeile repräsentiert ungefähr den Datenfluss. package, contains functionality that is only concerned with syntax, while the upper half, implemented by the package, contains functionality that assigns semantic meaning to syntactic data handled by the bottom half. jsontext json/v2 Das grundlegende Feuer der Es ist folgendes: 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 Die package provides functionality for interacting with JSON at a syntactic level and derives its name from wo die Grammatik für JSON-Daten buchstäblich genannt wird Da es nur auf einer syntaktischen Ebene mit JSON interagiert, ist es nicht von Go-Reflection abhängig. jsontext RFC 8259, Abschnitt 2 JSON-text Die und provide support for encoding and decoding JSON values and tokens. The constructors die das besondere Verhalten der Kodierung und Dekodierung beeinflussen. im Gegensatz zu and Typen, die in Die neuen Typen in Vermeiden Sie die Verwirrung der Unterscheidung zwischen Syntax und Semantik und arbeiten Sie in einer wirklich Streaming-Methode. Encoder Decoder Variable Optionen akzeptieren Encoder Decoder v1 jsontext Ein JSON-Wert ist eine komplette Einheit von Daten und wird in Go als . It is identical to in Ein JSON-Wert besteht syntaktisch aus einem oder mehreren JSON-Token. Ein JSON-Token wird in Go als Typ mit Konstruktoren und Zubehörmethoden. Es ist ähnlich wie in aber ist entworfen, um willkürliche JSON-Token ohne Allokation darzustellen. Ein Name []byte RawMessage v1 opaque Token Token v1 To resolve the fundamental performance problems with the und interface methods, we need an efficient way of encoding and decoding JSON as a streaming sequence of tokens and values. In , we introduce the und interface methods that operate on an oder , so dass die Implementierungen der Methoden JSON in einer rein Streaming-Methode verarbeiten können. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder So wird die Das Paket muss nicht für die Validierung oder Formatierung eines JSON-Werts verantwortlich sein, der Es muss auch nicht für die Bestimmung der Grenzen eines JSON-Werts verantwortlich sein. Diese Verantwortung gehört zu den und . json MarshalJSON UnmarshalJSON Encoder Decoder Einführung Codierung / JSON / V2 Codierung / JSON / V2 Building on the In diesem Zusammenhang stellen wir nun die experimentelle Es wurde entwickelt, um die oben genannten Probleme zu beheben, während es den Benutzern des Unser Ziel ist es, dass die Verwendung von Wir operieren the same if directly migrated to . jsontext encoding/json/v2 v1 v1 mostly v2 In this article, we will primarily cover the high-level API of Für Beispiele, wie man es benutzt, ermutigen wir die Leser zu studieren Paket oder Lesen . v2 Die Beispiele in der v2 Anton Zhiyanovs Blog, der das Thema abdeckt The basic API of Es ist folgendes: 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 Die und functions have a signature similar to , aber akzeptieren Optionen, um ihr Verhalten zu konfigurieren. and Funktionen funktionieren direkt auf einer oder Vermeiden Sie die Notwendigkeit, vorübergehend eine oder Nur zu schreiben oder von solchen Typen zu lesen. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder Die und Funktionen funktionieren auf a and und ist tatsächlich die zugrunde liegende Implementierung der zuvor erwähnten Funktionen. , Optionen sind ein erstklassiges Argument für jede der Marshal- und Unmarshal-Funktionen, was die Flexibilität und Konfigurierbarkeit von • Es gibt in die nicht durch diesen Artikel abgedeckt sind. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 Mehrere Optionen zur Verfügung v2 Typspezifische Customisierung Similar to , der 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 } Die und interfaces are identical to those in Die neue und Schnittstellen ermöglichen es einem Typ, sich als JSON mit einem or Dadurch können Optionen auf den Call Stack weitergeleitet werden, da Optionen über die accessor method on the oder . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder Siehe Beispiel für die Implementierung eines benutzerdefinierten Typs, der die Sortierung von JSON-Objektmitgliedern aufrechterhält. the OrderedObject Caller-spezifizierte Customisierung in , the caller of and kann auch eine benutzerdefinierte JSON-Repräsentation für jeden willkürlichen Typ angeben, bei dem Caller-spezifizierte Funktionen Vorrang vor typdefinierten Methoden oder der Standardrepräsentation für einen bestimmten Typ haben. 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 und Bauen Sie einen custom marshaler, der an eine call using to override the marshaling of particular types. Similarly, und Unterstützung ähnlicher Anpassungen für . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal example demonstrates how this feature allows serialization of all types to be handled by the package. The ProtoJSON proto.Message protojson Verhaltensunterschiede Während Ziel ist das Verhalten Das gleiche wie Sein Verhalten hat sich verändert Um Probleme in Und vor allem: v2 meistens v1 In mancher Hinsicht 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 Für die meisten Verhaltensänderungen gibt es eine Struct-Tag-Option oder eine Caller-spezifizierte Option, die das Verhalten so konfigurieren kann, dass es unter or Semantik oder sogar anderes anruferbestimmtes Verhalten. siehe for more information. v1 v2 „Migration nach V2“ Performance optimizations Die performance of ist ungefähr auf Parität mit . Sometimes it is slightly faster, but other times it is slightly slower. The Leistung von ist wesentlich schneller als , mit Benchmarks, die Verbesserungen von bis zu 10x zeigen. Marshal v2 v1 Unmarshal v2 v1 Um größere Leistungsgewinne zu erzielen, bestehende Implementierungen von and Migration muss auch umgesetzt werden and , so that they can benefit from processing JSON in a purely streaming manner. For example, recursive parsing of OpenAPI specifications in die Leistung in einem bestimmten Dienst von Kubernetes erheblich beeinträchtigt (siehe (Während der Umstellung auf Verbesserung der Leistung durch Größenordnungen. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON Kubernetes/Kube-Openapi #315 UnmarshalJSONFrom Für weitere Informationen, siehe die repository. go-json-experiment/jsonbench Retroactively improving encoding/json Codierung / Jason Wir möchten zwei getrennte JSON-Implementierungen in der Go-Standardbibliothek vermeiden, daher ist es von entscheidender Bedeutung, dass is implemented in terms of . v1 v2 Es gibt mehrere Vorteile für diesen Ansatz: Die Marshal- und Unmarshal-Funktionen in v1 oder v2 repräsentieren eine Reihe von Standardverhaltensweisen, die nach v1- oder v2-Semantik funktionieren. Optionen können angegeben werden, die Marshal oder Unmarshal so konfigurieren, dass sie vollständig mit v1, meistens v1 mit etwas v2, einer Mischung aus v1 oder v2, meistens v2 mit etwas v1, oder vollständig v2-Semantik funktionieren. Feature-Erbe: Wenn rückwärts kompatible Features zu v2 hinzugefügt werden, werden sie inhärent in v1 verfügbar gemacht. z. B. v2 fügt Unterstützung für mehrere neue strukturelle Tag-Optionen wie inline oder format hinzu und unterstützt auch die MarshalJSONTo- und UnmarshalJSONFrom-Schnittstellenmethoden, die sowohl leistungsfähiger als auch flexibler sind. Reduzierte Wartung: Die Wartung eines weit verbreiteten Pakets erfordert erhebliche Anstrengungen.Wenn v1 und v2 die gleiche Implementierung verwenden, wird die Wartungslast reduziert.Im Allgemeinen wird eine einzelne Änderung Fehler beheben, die Leistung verbessern oder Funktionalität zu beiden Versionen hinzufügen.Es gibt keine Notwendigkeit, eine v2-Änderung mit einer gleichwertigen v1-Änderung zu backport. Während ausgewählte Teile der may be deprecated over time (supposing Absolventen von einem Experiment), wird das Paket als Ganzes niemals entwertet werden. will be encouraged, but not required. The Go project will not drop support for . v1 v2 v2 v1 Experimentieren mit JSONV2 JSONV2 Das neue Feuer in der and Pakete sind standardmäßig nicht sichtbar. Um sie zu verwenden, erstellen Sie Ihren Code mit in Ihrer Umgebung oder mit der build tag. The nature of an experiment is that the API is unstable and may change in the future. Though the API is unstable, the implementation is of a high quality and has been successfully used in production by several major projects. encoding/json/jsontext encoding/json/v2 GOEXPERIMENT=jsonv2 goexperiment.jsonv2 Die Tatsache, dass is implemented in terms of Dies bedeutet, dass die zugrunde liegende Umsetzung der is completely different when building under the Experiment. Ohne jeden Code zu ändern, sollten Sie in der Lage sein, Ihre Tests unter und theoretisch nichts Neues sollte scheitern: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... Die Wiedereinführung der In Bezug auf Ziel ist es, innerhalb der Grenzen des , though some differences might be observable such as the exact wording of error messages. We encourage you to run your tests under Melden Sie alle Regressionen . v1 v2 Go 1 Kompatibilitätsversprechen jsonv2 Zum Thema Tracker Ein Experiment in Go 1.25 zu werden, ist ein bedeutender Meilenstein auf dem Weg zur formellen Annahme. und into the standard library. However, the purpose of the experiment is to gain broader experience. Your feedback will determine our next steps, and the outcome of this experiment, which may result in anything from abandonment of the effort, to adoption as stable packages of Go 1.26. Please share your experience on , und helfen, die Zukunft von Go zu bestimmen. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/ausgabe 71497 Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines und Damien Neil Dieser Artikel ist auf The Go Blog unter einer CC BY 4.0 DEED Lizenz verfügbar. Der Go Blog Der Go Blog Foto von Jr Korpa auf Unsplash Jr Korpa Unsplash