Nuevos paquetes experimentales de Go: lo que debes saber

Introducción es un formato de intercambio de datos simple.Hace casi 15 años, escribimos sobre , que introdujo la capacidad de serializar y deserializar los tipos de Go a y desde los datos de JSON. Desde entonces, JSON se ha convertido en el formato de datos más popular utilizado en Internet. Es ampliamente leído y escrito por los programas de Go, y la codificación/json ahora se ubica como el quinto paquete de Go más importado. JavaScript Object Notation (JSON) Soporte para JSON en Go Con el tiempo, los paquetes evolucionan con las necesidades de sus usuarios, y Este blog trata sobre el nuevo experimento de Go 1.25 y Este post argumenta por una nueva versión importante de la API, proporciona una visión general de los nuevos paquetes y explica cómo puede hacer uso de ellos.Los paquetes experimentales no son visibles por defecto y pueden sufrir futuras modificaciones de la API. encoding/json encoding/json/v2 encoding/json/jsontext Problemas con encoding/json Codificación / JSON En general, La idea de marshaling y desmarshaling de tipos arbitrarios de Go con alguna representación predeterminada en JSON, combinada con la capacidad de personalizar la representación, ha demostrado ser altamente flexible. Sin embargo, en los años desde su introducción, varios usuarios han identificado numerosas deficiencias. encoding/json Errores de comportamiento Existen varios errores de comportamiento en : 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 Leaking nilness of slices and maps: JSON se utiliza a menudo para comunicarse con programas utilizando implementaciones JSON que no permiten que null sea desmarchado en un tipo de datos esperado para ser un array o objeto JSON. Dado que la codificación/json marshals un nil slice o mapa como un JSON null, esto puede conducir a errores cuando desmarchado por otras implementaciones. Una encuesta indicó que la mayoría de los usuarios de Go prefieren que los nil slices y mapas se marshalen como un array o objeto JSON vacío por defecto. Unmarshaling no sensible al caso: Cuando unmarshaling, un nombre de miembro de un objeto JSON se resuelve en un nombre de campo Go struct usando un encuentro no sensible al caso. Llamamiento inconsistente de métodos: Debido a un detalle de implementación, los métodos MarshalJSON declarados en un receptor de puntaje son incoherentemente llamados por codificación/json. Falta de fuego El fuego de Puede ser complicado o restrictivo: encoding/json It is difficult to correctly unmarshal from an . Users often write , which fails to reject trailing junk at the end of the input. io.Reader json.NewDecoder(r).Decode(v) 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 Las funciones Compact, Indent y HTMLEscape escriben a un bytes.Buffer en lugar de algo más flexible como un []byte o io.Writer. Esto limita la usabilidad de esas funciones. Limitaciones de rendimiento Poniendo de lado los detalles de la implementación interna, la API pública se compromete a ciertas limitaciones de rendimiento: : 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 Además, si la implementación de un o El método recursivo llama la o función, entonces el rendimiento se convierte en cuadrático. MarshalJSON UnmarshalJSON Marshal Unmarshal Tratando de arreglar directamente Codificación / JSON Codificación / JSON Introducir una nueva versión principal de un paquete incompatible es una consideración pesada.Si es posible, debemos tratar de corregir el paquete existente. 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 Compatibilidad promesa En principio, podríamos declarar nombres separados, como o , pero eso equivale a crear un espacio de nombres paralelo dentro del mismo paquete. (de ahora en adelante llamado ), donde podemos hacer estos cambios dentro de un El espacio en contraste con el (de ahora en adelante llamado ) de MarshalV2 UnmarshalV2 encoding/json/v2 v2 v2 encoding/json v1 Planificación para Codificación / JSON / V2 Codificación / JSON / V2 The planning for a new major version of A finales de 2020, impulsado por la incapacidad de corregir problemas en el paquete actual, Daniel Martí (uno de los En primer lugar escribió sus pensamientos sobre el paquete debe parecer. por separado, después de un trabajo anterior en el Joe Tsai se decepcionó. el paquete necesario para utilizar una implementación de JSON personalizada porque was neither capable of adhering to the stricter JSON standard that the Protocol Buffer specification required, nor of efficiently serializing JSON in a streaming manner. encoding/json encoding/json ¿Qué hipótesis v2 Go API para Protocol Buffers El protojson encoding/json Creyendo que un futuro más brillante para JSON era beneficioso y alcanzable, Daniel y Joe unieron fuerzas para hacer un brainstorm en el futuro. y (con el código inicial siendo una versión pulida de la lógica de serialización de JSON del módulo protobuf Go). Con el tiempo, algunos otros (Roger Peppe, Chris Hines, Johan Brandhorst-Satzkorn, y Damien Neil) se unieron al esfuerzo proporcionando revisión de diseño, revisión de código y pruebas de regresión. y . v2 Comienza la construcción de un prototipo Encuentros registrados Notas de reunión Este trabajo ha sido público desde el comienzo, y cada vez involucramos más a la comunidad Go, primero con una y , de Y más recientemente como un experimento de Go (disponible en Go 1.25) para pruebas a mayor escala por todos los usuarios de Go. Gophercon habla Discusión publicada a finales de 2023 Propuesta formal publicada a principios de 2025 Adopción encoding/json/v2 El El esfuerzo ha estado en curso durante 5 años, incorporando el feedback de muchos contribuyentes y también obteniendo valiosa experiencia empírica del uso en los entornos de producción. v2 Vale la pena señalar que ha sido desarrollado y promovido en gran medida por personas no empleadas por Google, demostrando que el proyecto Go es un esfuerzo colaborativo con una próspera comunidad global dedicada a mejorar el ecosistema de Go. La construcción en encoding/json/jsontext Codificación / JSON / JSONTEXT Before discussing the En primer lugar, vamos a introducir el experimento paquete que pone las bases para futuras mejoras a JSON en Go. v2 encoding/json/jsontext La serialización de JSON en Go se puede dividir en dos componentes primarios: funcionalidad sintáctica que se ocupa del procesamiento de JSON basado en su gramática, y Funcionalidad semántica que define la relación entre los valores JSON y los valores Go. Utilizamos los términos “código” y “decodificación” para describir la funcionalidad sintáctica y los términos “marshal” y “unmarshal” para describir la funcionalidad semántica. 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 el paquete, contiene funcionalidad que sólo se refiere a la sintaxis, mientras que la mitad superior, implementada por la package, contains functionality that assigns semantic meaning to syntactic data handled by the bottom half. jsontext json/v2 El fuego básico de Es lo siguiente: 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 El El paquete proporciona funcionalidad para interactuar con JSON a nivel sintáctico y deriva su nombre de donde la gramática de los datos JSON se llama literalmente Dado que sólo interactúa con JSON a nivel sintáctico, no depende de la reflexión de Go. jsontext RFC 8259, sección 2 JSON-text El y proporcionar soporte para la codificación y decodificación de valores y tokens JSON. que afectan al comportamiento particular de la codificación y la decodificación. y types declared in Los nuevos tipos en Evitar confundir la distinción entre la sintaxis y la semántica y operar de una manera verdaderamente streaming. Encoder Decoder accept variadic options Encoder Decoder v1 jsontext Un valor JSON es una unidad completa de datos y se representa en Go como Es idéntico a en Un valor JSON está compuesto sintácticamente de uno o más tokens JSON. tipo con constructores y métodos accesorios. es análogo a en pero está diseñado para representar tokens JSON arbitrarios sin asignación. El Nombre []byte RawMessage v1 Opacidad Token Token v1 Para resolver los problemas fundamentales de desempeño con la y Los métodos de interfaz, necesitamos una manera eficiente de codificar y decodificar JSON como una secuencia de streaming de tokens y valores. Introducimos el y Los métodos de interfaz que operan en un o , permitiendo que las implementaciones de los métodos procesen JSON de una manera puramente streaming. MarshalJSON UnmarshalJSON v2 MarshalJSONTo UnmarshalJSONFrom Encoder Decoder Así, el package need not be responsible for validating or formatting a JSON value returned by , nor would it need to be responsible for determining the boundaries of a JSON value provided to Estas responsabilidades pertenecen a la y . json MarshalJSON UnmarshalJSON Encoder Decoder Introducción encoding/json/v2 Codificación / JSON / V2 La construcción en la package, we now introduce the experimental está diseñado para corregir los problemas antes mencionados, mientras que permanece familiar a los usuarios del El objetivo es que los usos de Se operará En el caso de migrar directamente a . jsontext encoding/json/v2 v1 v1 mostly v2 En este artículo, abordaremos principalmente la API de alto nivel de Para ejemplos de cómo usarlo, animamos a los lectores a estudiar package or read . v2 Los ejemplos en la v2 Anton Zhiyanov’s blog covering the topic El fuego básico de Es lo siguiente: 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 y las funciones tienen una firma similar a , but accept options to configure their behavior. The y Funciones que operan en un o para evitar la necesidad de construir temporalmente un o Escribir o leer de este tipo de personas. Marshal Unmarshal v1 MarshalWrite UnmarshalRead io.Writer io.Reader Encoder Decoder El y Funciones que operan en A y y es en realidad la implementación subyacente de las funciones antes mencionadas. , options are a first-class argument to each of the marshal and unmarshal functions, greatly extending the flexibility and configurability of . There are en que no están cubiertas por este artículo. MarshalEncode UnmarshalDecode jsontext.Encoder jsontext.Decoder v1 v2 Varias opciones disponibles v2 Tipo de customización especificado similares a , de Permite a los tipos definir su propia representación JSON satisfaciendo interfaces particulares. 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 } El y Las interfaces son idénticas a las de El Nuevo y interfaces permiten que un tipo se represente como JSON utilizando un o Esto permite que las opciones se redireccionen hacia abajo en la pila de llamadas, ya que las opciones se pueden recuperar a través de la El método de accesibilidad en la o . Marshaler Unmarshaler v1 MarshalerTo UnmarshalerFrom jsontext.Encoder jsontext.Decoder Options Encoder Decoder este example for how to implement a custom type that maintains the ordering of JSON object members. El OrderedObject Customización especificada por Caller In El llamado de y También puede especificar una representación JSON personalizada para cualquier tipo arbitrario, donde las funciones especificadas por el llamador tienen prioridad sobre los métodos definidos por el tipo o la representación predeterminada para un tipo particular. 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 y construye un custom marshaler que puede ser transmitido a un Llamar a usar para despejar el marshalling de los tipos particulares. y support similar customization for . MarshalFunc MarshalToFunc Marshal WithMarshalers UnmarshalFunc UnmarshalFromFunc Unmarshal ejemplo demuestra cómo esta característica permite la serialización de todos los tipos a tratar por los El paquete. El ProtoJSON proto.Message protojson Diferencias de comportamiento Mientras El objetivo es comportarse the same as Su comportamiento ha cambiado Para abordar los problemas en Y más notablemente: v2 La mayoría v1 De alguna manera 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 la mayoría de los cambios de comportamiento, hay una opción de etiqueta estruct o una opción especificada por el llamador que puede configurar el comportamiento para operar bajo o semántica, o incluso otro comportamiento determinado por el llamador. Para más información. v1 v2 “Migración a V2” Optimización de rendimiento The Desempeño de is roughly at parity with A veces es un poco más rápido, pero otras veces es un poco más lento. Desempeño de Es mucho más rápido que , con índices de referencia que demuestran mejoras de hasta 10x. Marshal v2 v1 Unmarshal v2 v1 Para lograr un mayor rendimiento, las implementaciones existentes de y La migración también debe implementarse y , para que puedan beneficiarse del procesamiento de JSON de una manera puramente streaming. Por ejemplo, el análisis recursivo de las especificaciones de OpenAPI en methods significantly hurt performance in a particular service of Kubernetes (see ), mientras se cambia de Mejora de rendimiento por orden de magnitud. Marshaler Unmarshaler MarshalerTo UnmarshalerFrom UnmarshalJSON cubernetes/cube-openapi#315 UnmarshalJSONFrom Para más información, ver el El repositorio. go-json-experiment/jsonbench Retroactively improving encoding/json Codificación / JSON Queremos evitar dos implementaciones separadas de JSON en la biblioteca estándar de Go, por lo que es crítico que, bajo el capó, Se realiza en términos de . v1 v2 There are several benefits to this approach: Migración gradual: Las funciones Marshal y Unmarshal en v1 o v2 representan un conjunto de comportamientos predeterminados que operan de acuerdo con la semántica v1 o v2. Se pueden especificar opciones que configure Marshal o Unmarshal para operar con totalmente v1, principalmente v1 con algo v2, una mezcla de v1 o v2, principalmente v2 con algo v1, o completamente v2 semántica. Esto permite la migración gradual entre los comportamientos predeterminados de las dos versiones. Herencia de características: A medida que se añaden características compatibles con el retroceso a v2, en su naturaleza se harán disponibles en v1. Por ejemplo, v2 añade soporte para varias nuevas opciones de etiquetas de estructura como inline o formato y también soporte para los métodos de interfaz MarshalJSONTo y UnmarshalJSONFrom, que son tanto más potentes como flexibles. Cuando v1 se implementa en términos de v2, heredará soporte para estas características. Reducido mantenimiento: el mantenimiento de un paquete ampliamente utilizado requiere un esfuerzo significativo. Al tener v1 y v2 usando la misma implementación, la carga de mantenimiento se reduce. En general, un solo cambio corregirá errores, mejorará el rendimiento o añadirá funcionalidad a ambas versiones. No hay necesidad de backportar un cambio v2 con un cambio equivalente v1. Al seleccionar partes de puede ser depreciado con el tiempo (suponiendo graduados de ser un experimento), el paquete en su conjunto nunca será depreciado. se fomentará, pero no se requiere.El proyecto Go no dejará de apoyar . v1 v2 v2 v1 Experimentando con jsonv2 Siguiente V2 El nuevo fuego en la y los paquetes no son visibles por defecto. Para usarlos, construya su código con set in your environment or with the 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 El hecho de que is implemented in terms of Esto significa que la aplicación subyacente de is completely different when building under the Sin cambiar ningún código, usted debe ser capaz de ejecutar sus pruebas bajo Teóricamente, no hay nada nuevo: v1 v2 v1 jsonv2 jsonv2 GOEXPERIMENT=jsonv2 go test ./... The re-implementation of En términos de El objetivo es proporcionar un comportamiento idéntico dentro de los límites de la , aunque algunas diferencias pueden ser observables, como la formulación exacta de los mensajes de error. le animamos a ejecutar sus pruebas bajo and report any regressions . v1 v2 Go 1 Compatibilidad promesa jsonv2 Sobre el tema Tracker Convertirse en un experimento en Go 1.25 es un hito importante en el camino hacia la adopción formal. y de la biblioteca, pero el propósito de la Su feedback determinará nuestros próximos pasos, y el resultado de este experimento, que puede resultar en cualquier cosa desde el abandono del esfuerzo, a la adopción como paquetes estables de Go 1.26. , and help determine the future of Go. encoding/json/jsontext encoding/json/v2 jsonv2 go.dev/encuentro 71497 Joe Tsai, Daniel Martí, Johan Brandhorst-Satzkorn, Roger Peppe, Chris Hines y Damien Neil Este artículo está disponible en The Go Blog bajo una licencia CC BY 4.0 DEED. El blog de Go El blog de Go Imagen de Jr Korpa en Unsplash JR Corpa Unosplash