JSON Marshal Library

By default, Hertz integrates with and uses Sonic for serializing ctx.JSON interface and deserialization requests as defined in the binding package. Sonic is an ultra-high performance golang json library, also see Sonic README for details.

The following are requirements to enable Sonic:

• Go 1.15/1.16/1.17/1.18
• Linux / darwin OS / Windows
• Amd64 CPU with AVX instruction set

Sonic automatically fallback to golang’s encoding/json library when the above requirements have not been satisfied.

Compatibility With encoding/json

Currently, Hertz uses the default configuration for Sonic (i.e.sonic.ConfigDefault), which behaves different from JSON encoding/json. Specifically, by default, Sonic are configured to:

• disable html escape: Sonic will not escape HTML’s special characters
• disable key-sort by default: Sonic will not sort json in lexicographical order

To find more about the compatibility with encoding/json, you may want to see sonic#Compatibility. You may change Sonic’s behavior (e.g. behaving exactly the same way as encoding/json) by calling ResetJSONMarshaler for render.

render.ResetJSONMarshaler(sonic.ConfigStd.Marshal)

Bringing Your Own JSON Marshal Library

If Sonic does not meet your needs, you may provide your own implementation by calling ResetJSONMarshal for render and ResetJSONUnmarshaler for binding.

import (
    "encoding/json"

    "github.com/bytedance/go-tagexpr/v2/binding"
    "github.com/cloudwego/hertz/pkg/app/server/render"
)

func main() {
    // Render
    render.ResetJSONMarshal(json.Marshal)

    // Binding
    binding.ResetJSONUnmarshaler(json.Unmarshal)
}

Conditional Compilation

Hertz supports conditional compilation to control the actual json library used, you can use -tags stdjson to choose to use the standard library.

go build -tags stdjson .

Common FAQs

Error when using Sonic on M1

Build constraints exclude all Go files in xxx

Usually because the Go version or environment parameters do not meet Sonic requirements.

• Go version: go1.15 or above, recommend go1.17 or above. For the currently supported versions of Sonic, please see Sonic#Requirement

• Go environment parameters: set GOARCH=amd64. Because Sonic already supports the binary translation software Rosetta, with Rosetta, the programs compiled under the x86 environment can be run on the M1.

Unable to Debug

If you want to debug, you can set GOARCH=arm64. Because the Rosetta will cause the binary of Sonic to fail to debug.

Note that the performance of Sonic will be hurt, because Sonic will fallback to the standard library in this environment.