DOCSEARCHbyAlgolia
Submit Docs

easyjson

repository·master·Indexed 26 days ago

https://github.com/mailru/easyjson

A high-performance JSON marshaling/unmarshaling library for Go that avoids reflection by generating specialized code for structs. It typically outperforms the standard encoding/json package by 4-5x. The library includes a CLI tool for code generation, support for advanced JSON tags like nocopy and intern, and interfaces for custom marshaling, unmarshaling, and handling unknown fields.

Tokens
3.1K
Snippets
15
Records
29
Agent score
89%

What's inside easyjson

  1. Run easyjson benchmarks

    master
    You can run the performance benchmarks included in the repository by using the make command. These benchmarks compare easyjson against encoding/json, ffjson, go/codec, and Python's ujson across various scenarios including unmarshaling, single-goroutine marshaling, and concurrent marshaling.
    make

  2. Use advanced JSON tag options

    master

    In addition to standard encoding/json tags, easyjson supports the following specialized tags for performance optimization:

    • nocopy: Disables allocation and copying of string values, making them refer to the original JSON buffer memory. This is ideal for short-lived objects. Note that strings requiring unescaping will still be processed normally.
    • intern: Enables string interning (deduplication) during unmarshaling. This reduces memory usage when the same string values appear frequently across the structure, at the cost of slightly higher CPU usage.

    Example of intern usage:

    type Foo struct {
  UUID  string `json:"uuid"`         // will not be interned
  State string `json:"state,intern"` // will be interned during unmarshaling
}
    type Foo struct {
  UUID  string `json:"uuid"`         // will not be interned during unmarshaling
  State string `json:"state,intern"` // will be interned during unmarshaling
}

  3. Generate easyjson marshaler/unmarshaler code

    master

    Use the easyjson CLI to generate _easyjson.go files for your structs. This avoids reflection and provides high-performance JSON processing.

    To generate code for all structs in a file:

    easyjson -all <file>.go

    Behavioral Notes:

    • Using -all generates code for all structs in the file except those preceded by the comment //easyjson:skip.
    • If -all is not provided, only structs preceded by //easyjson:json will have code generated.
    • The generated file will be named <file>_easyjson.go.
    easyjson -all <file>.go

  4. Install easyjson

    master

    Install the easyjson tool and package based on your Go version.

    For Go < 1.17:

    go get -u github.com/mailru/easyjson/...

    For Go >= 1.17:

    go get github.com/mailru/easyjson && go install github.com/mailru/easyjson/...@latest

    Note: easyjson requires a full Go build environment and the GOPATH environment variable to be set because the code generation process invokes go run on temporary files.

    # for Go < 1.17
go get -u github.com/mailru/easyjson/...

# for Go >= 1.17
go get github.com/mailru/easyjson && go install github.com/mailru/easyjson/...@latest

  5. Use the easyjson CLI to generate marshaler/unmarshaler code

    master

    The easyjson CLI tool generates high-performance JSON marshaling and unmarshaling code for Go structs. You can run it against specific .go files or entire packages.

    Usage Patterns:

    • Single File: Provide the path to a .go file. The tool will create a file named <filename>_easyjson.go.
    • Whole Package: Use the -pkg flag. If -pkg is used, the tool looks for the GOFILE environment variable to determine the package directory.
    • Custom Output Name: Use the -output_filename flag to specify a specific name for the generated file.

    Requirements:

    • Input files must have a .go extension.

  6. Serialize and Deserialize with easyjson

    master

    Use the easyjson package functions for high-performance marshaling and unmarshaling. These functions utilize the generated MarshalEasyJSON and UnmarshalEasyJSON methods to avoid reflection.

    Serialization:

    someStruct := &SomeStruct{Field1: "val1", Field2: "val2"}
rawBytes, err := easyjson.Marshal(someStruct)

    Deserialization:

    someStruct := &SomeStruct{}
err := easyjson.Unmarshal(rawBytes, someStruct)
    someStruct := &SomeStruct{Field1: "val1", Field2: "val2"}
rawBytes, err := easyjson.Marshal(someStruct)

someStruct := &SomeStruct{}
err := easyjson.Unmarshal(rawBytes, someStruct)

  7. Reference easyjson CLI options

    master

    The following flags are available when running the easyjson command-line tool:

    FlagDescription
    -allgenerate marshaler/unmarshalers for all structs in a file
    -build_tags stringbuild tags to add to generated file
    -gen_build_flags stringbuild flags when running the generator while bootstrapping
    -byteuse simple bytes instead of Base64Bytes for slice of bytes
    -leave_tempsdo not delete temporary files
    -no_std_marshalersdon't generate MarshalJSON/UnmarshalJSON funcs
    -noformatdo not run 'gofmt -w' on output file
    -omit_emptyomit empty fields by default
    -output_filename stringspecify the filename of the output
    -pkgprocess the whole package instead of just the given file
    -snake_caseuse snake_case names instead of CamelCase by default
    -lower_camel_caseuse lowerCamelCase instead of CamelCase by default
    -stubsonly generate stubs for marshaler/unmarshaler funcs
    -disallow_unknown_fieldsreturn error if some unknown field in json appeared
    -disable_members_unescapedisable unescaping of \uXXXX string sequences in member names

  8. Compile easyjson without unsafe

    master
    By default, easyjson uses the unsafe package to provide significant performance benefits (such as no-copy conversion from []byte to string). If your environment requires it, you can compile without unsafe by setting the build tag easyjson_nounsafe.

  9. Marshal a Marshaler to a byte slice

    master
    Use Marshal(v Marshaler) to convert a type implementing the Marshaler interface into a single byte slice. Note that this method may be suboptimal for very large data sets due to potential memory copying.

  10. Marshal a Marshaler to an http.ResponseWriter

    master
    Use MarshalToHTTPResponseWriter(v Marshaler, w http.ResponseWriter) to send JSON directly in an HTTP response. This helper automatically sets the Content-Type: application/json and Content-Length headers.