go-json

Fast JSON encoder/decoder compatible with encoding/json for Go

Features

• Drop-in replacement of encoding/json. Values are decoded, and their errors are reported, as encoding/json of Go 1.27 (built on encoding/json/v2) does, on every Go version. Only the syntax errors of decoding and the reading of a stream token by token (Token, More, InputOffset, and Decode between calls of Token) follow the encoding/json the program is built with. Values are encoded as the encoding/json the program is built with encodes them, except for some behaviors of Go 1.27 that apply on every version, such as the limit of 10000 nested levels, map keys of pointer types, and the syntax errors of MarshalJSON output, Compact and Indent. The MarshalJSONTo and UnmarshalJSONFrom methods are called before MarshalJSON and UnmarshalJSON, as encoding/json of Go 1.27 calls them: the ones which take the Encoder and the Decoder of github.com/goccy/go-json/jsontext first, on every Go version, and the ones which take those of encoding/json/jsontext where the program is built with Go 1.27. As encoding/json does, they are given an encoder and a decoder with the options of encoding/json (DefaultOptionsV1), and the decoder with the ones of DisallowUnknownFields and UseNumber of a Decoder, so that MarshalEncode and UnmarshalDecode within the methods encode and decode as this package does; UseNumber is given only to the methods of github.com/goccy/go-json/jsontext, as encoding/json exports no option of it.
• Drop-in replacement of encoding/json/v2 and encoding/json/jsontext by github.com/goccy/go-json/v2 and github.com/goccy/go-json/jsontext, with the API and behavior of those packages of Go 1.27 on Go 1.23 and later, with no need of GOEXPERIMENT=jsonv2. Their types are their own, not aliases of the ones of the standard library: replace both imports together, and declare MarshalJSONTo and UnmarshalJSONFrom methods with the Encoder and Decoder of github.com/goccy/go-json/jsontext, since methods taking the ones of encoding/json/jsontext are not called.
• Fast ( See Benchmark section )
• MarshalOf and UnmarshalOf, which take the value by its type and save the allocations Marshal and Unmarshal need for an interface{} argument
• Flexible customization with options
• Coloring the encoded string
• Can propagate context.Context to MarshalJSON or UnmarshalJSON
• Can dynamically filter the fields of the structure type-safely

Installation

go get github.com/goccy/go-json

How to use

Replace import statement from encoding/json to github.com/goccy/go-json

-import "encoding/json"
+import "github.com/goccy/go-json"

Code which uses encoding/json/v2 or encoding/json/jsontext replaces them likewise

-import "encoding/json/v2"
+import "github.com/goccy/go-json/v2"
-import "encoding/json/jsontext"
+import "github.com/goccy/go-json/jsontext"

JSON library comparison

name	encoder	decoder	compatible with encoding/json
encoding/json	yes	yes	N/A
json-iterator/go	yes	yes	partial
easyjson	yes	yes	no
gojay	yes	yes	no
segmentio/encoding/json	yes	yes	partial
jettison	yes	no	no
simdjson-go	no	yes	no
bytedance/sonic	yes	yes	partial
goccy/go-json	yes	yes	yes

• json-iterator/go isn't compatible with encoding/json in many ways (e.g. https://github.com/json-iterator/go/issues/229 ), but it hasn't been supported for a long time.
• segmentio/encoding/json is well supported for encoders, but some are not supported for decoder APIs such as Token ( streaming decode )
• bytedance/sonic is compatible with encoding/json in its ConfigStd configuration; by default it doesn't escape HTML, sort the keys of maps or validate strings. It decodes and encodes by native code: SIMD code and, on amd64, code generated at run time. The benchmarks of this repository compare go-json with sonic in both configurations ( see below ).

Other libraries

• jingo

I tried the benchmark but it didn't work. Also, it seems to panic when it receives an unexpected value because there is no error handling...

• ffjson

Benchmarking gave very slow results. It seems that it is assumed that the user will use the buffer pool properly. Also, development seems to have already stopped

Benchmarks

The JSON libraries of Go are measured doing the same work on GitHub Actions, on amd64 and arm64, and the results are published at https://goccy.github.io/go-json/, measured again whenever go-json, the version of a library or the report changes. The page has every payload, the encode and decode of each library, the allocations, and the results without a live heap.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗