json

Documentation

Overview

Package json generates methods for encoding/decoding types to/from JSON.

When used correctly, these methods can easily give a ~200-300% performance increase when serializing objects to JSON while also reducing memory usage by ~95-99%. For taking advantage of these gains, you must use gnd.la/app/serialize or Context.WriteJSON to encode to JSON, since json.Marshal won't use these methods correctly and might even have worse performance when these methods are implemented.

This is a small benchmark comparing the performance of these JSON encoding methods. JSONDirect uses WriteJSON(), JSONSerialize uses gnd.la/app/serialize (which adds some overhead because it also sets the Content-Length and Content-Encoding headers and thus must encode into an intermediate buffer first), while JSON uses json.Marshal(). All three benchmarks write the result to ioutil.Discard.

BenchmarkJSONDirect	    1000000 1248 ns/op	117.73 MB/s 16 B/op	2 allocs/op
BenchmarkJSONSerialize  1000000 1587 ns/op	92.62 MB/s  16 B/op	2 allocs/op
BenchmarkJSON	    500000  4583 ns/op	32.07 MB/s  620 B/op	4 allocs/op

Code generated by this package respects json related struct tags except omitempty and and encodes time.Time UTC as a Unix time (encoding/json uses time.Format).

If you want to specify a different serialization when using encoding/json than when using this package, you can use the "genjson" field tag. Fields with a genjson tag will use it and ignore the "json" tag.

The recommended way use to generate JSON methods for a given package is using the gondola command rather than using this package directly.

Index

• func Gen(pkgName string, opts *Options) error
• type Field
• type Options

Functions

func Gen

func Gen(pkgName string, opts *Options) error

Gen generates a WriteJSON method and, optionally, MarshalJSON for every selected type in the given package. The package might be either an absolute path or an import path. See Options to learn how to select types and specify type options

Types

type Field

type Field struct {
	Key       string
	Name      string
	OmitEmpty bool
}

Field indicates a JSON field to be included in the output. Key indicates the key used in the JSON, while name indicate the field or method (in that case, it should receive no arguments) name.

type Options

type Options struct {
	// Wheter to generate a MarshalJSON method. This is false by default
	// because in most cases will result in lower performance when using
	// json.Marshal, since the encoder from encoding/json will revalidate
	// the returned JSON, resulting in a performance loss. Turn this on
	// only if you're using the Methods feature (otherwise you'll get
	// different results when serializing with json.Marshal).
	MarshalJSON bool
	// The size of the allocated buffers for serializing to JSON. If zero,
	// the default size of 8192 is used (8K).
	BufferSize int
	// The maximum buffer size. Buffers which grow past this size won't
	// be reused. If zero, it takes the same value os BufferSize.
	MaxBufferSize int
	// The number of buffers to be kept for reusing. If zero, it defaults
	// to GOMAXPROCS. Set it to a negative number to disable buffering.
	BufferCount int
	// If not zero, this takes precedence over BufferCount. The number of
	// maximum buffers will be GOMAXPROCS * BuffersPerProc.
	BuffersPerProc int
	// TypeFields contains the per-type fields. The key in the map is the
	// type name in the package (e.g. MyStruct not mypackage.MyStruct).
	// Field tags are ignored for types that explicitely specify their
	// fields. Additionally, specific fields for contains might be
	// specified using the container.type syntax (e.g. MyOtherStruct.MyStruct
	// or MySliceType.MyStruct will set the fields for MyStruct only when
	// it's contained in MyOtherStruct or MySliceType respectively).
	// Any type in this map is included regardless of Include and Exclude.
	TypeFields map[string][]*Field
	// If not nil, only types matching this regexp will be included.
	Include *regexp.Regexp
	// If not nil, types matching this regexp will be excluded.
	Exclude *regexp.Regexp
}

Options specify the options used when generating JSON related methods.