mailru / easyjson

easyjson Package easyjson provides a fast and easy way to marshal/unmarshal Go structs to/from JSON without the use of reflection. In performance tests, easyjson outperforms the standard package by a factor of 4-5x, and other JSON encoding packages by a factor of 2-3x. easyjson aims to keep generated Go code simple enough so that it can be easily optimized or fixed. Another goal is to provide users with the ability to customize the generated code by providing options not available with the standard package, such as generating "snake_case" names or enabling behavior by default. Usage Install: or Run: The above will generate containing the appropriate marshaler and unmarshaler funcs for all structs contained in . Please note that easyjson requires a full Go build environment and the environment variable to be set. This is because easyjson code generation invokes on a temporary file (an approach to code generation borrowed from ffjson). Serialize Deserialize Please see the GoDoc for more information and features. Options Using will generate marshalers/unmarshalers for all Go structs in the file excluding those structs whose preceding comment starts with . For example: If is not provided, then only those structs whose preceding comment starts with will have marshalers/unmarshalers generated. For example: Additional option notes: • tells easyjson to generate snake\_case field names by default (unless overridden by a field tag). The CamelCase to snake\_case conversion algorithm should work in most cases (ie, HTTPVersion will be converted to "http_version"). • will add the specified build tags to generated Go sources. • will execute the easyjson bootstapping code to launch the actual generator command with provided flags. Multiple arguments should be separated by space e.g. . Structure json tag options Besides standard json tag options like 'omitempty' the following are supported: • 'nocopy' - disables allocation and copying of string values, making them refer to original json buffer memory. This works great for short lived objects which are not hold in memory after decoding and immediate usage. Note if string requires unescaping it will be processed as normally. • 'intern' - string "interning" (deduplication) to save memory when the very same string dictionary values are often met all over the structure. See below for more details. Generated Marshaler/Unmarshaler Funcs For Go struct types, easyjson generates the funcs / for marshaling/unmarshaling JSON. In turn, these satisfy the and interfaces and when used in conjunction with / avoid unnecessary reflection / type assertions during marshaling/unmarshaling to/from JSON for Go structs. easyjson also generates and funcs for Go struct types compatible with the standard and interfaces. Please be aware that using the standard / for marshaling/unmarshaling will incur a significant performance penalty when compared to using / . Additionally, easyjson exposes utility funcs that use the and for marshaling/unmarshaling to and from standard readers and writers. For example, easyjson provides which marshals to the standard . Please see the GoDoc listing for the full listing of utility funcs that are available. Controlling easyjson Marshaling and Unmarshaling Behavior Go types can provide their own and funcs that satisfy the / interfaces. These will be used by and when defined for a Go type. Go types can also satisfy the interface, which allows the type to define its own logic. Type Wrappers easyjson provides additional type wrappers defined in the package. These wrap the standard Go primitives and in turn satisfy the easyjson interfaces. The type wrappers are useful when needing to distinguish between a missing value and/or when needing to specifying a default value. Type wrappers allow easyjson to avoid additional pointers and heap allocations and can significantly increase performance when used properly. Memory Pooling easyjson uses a buffer pool that allocates data in increasing chunks from 128 to 32768 bytes. Chunks of 512 bytes and larger will be reused with the help of . The maximum size of a chunk is bounded to reduce redundant memory allocation and to allow larger reusable buffers. easyjson's custom allocation buffer pool is defined in the package, and the default behavior pool behavior can be modified (if necessary) through a call to prior to any marshaling or unmarshaling. Please see the GoDoc listing for more information. String interning During unmarshaling, field values can be optionally interned to reduce memory allocations and usage by deduplicating strings in memory, at the expense of slightly increased CPU usage. This will work effectively only for fields being decoded that have frequently the same value (e.g. if you have a string field that can only assume a small number of possible values). To enable string interning, add the keyword tag to your tag on fields, e.g.: Issues, Notes, and Limitations • easyjson is still early in its development. As such, there are likely to be bugs and missing features when compared to . In the case of a missing feature or bug, please create a GitHub issue. Pull requests are welcome! • Unlike , object keys are case-sensitive. Case-insensitive matching is not currently provided due to the significant performance hit when doing case-insensitive key matching. In the future, case-insensitive object key matching may be provided via an option to the generator. • easyjson makes use of , which simplifies the code and provides significant performance benefits by allowing no-copy conversion from to . That said, is used only when unmarshaling and parsing JSON, and any operations / memory allocations done will be safely deallocated by easyjson. Set the build tag to compile it without . • easyjson is compatible with Google App Engine. The build tag (set by App Engine's environment) will automatically disable the use of , which is not allowed in App Engine's S…