feat: support custom json codec at runtime (#3391)

* refactor(json): export json codec

* feat(json): support custom json codec at runtime

* chore(copyright): update copyright to 2025 gin core team

* docs(gin): add custom json codec examples in doc file

codec/json/api.go

@@ -0,0 +1,57 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+package json
+
+import "io"
+
+// API the json codec in use.
+var API Core
+
+// Core the api for json codec.
+type Core interface {
+	Marshal(v any) ([]byte, error)
+	Unmarshal(data []byte, v any) error
+	MarshalIndent(v any, prefix, indent string) ([]byte, error)
+	NewEncoder(writer io.Writer) Encoder
+	NewDecoder(reader io.Reader) Decoder
+}
+
+// Encoder an interface writes JSON values to an output stream.
+type Encoder interface {
+	// SetEscapeHTML specifies whether problematic HTML characters
+	// should be escaped inside JSON quoted strings.
+	// The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e
+	// to avoid certain safety problems that can arise when embedding JSON in HTML.
+	//
+	// In non-HTML settings where the escaping interferes with the readability
+	// of the output, SetEscapeHTML(false) disables this behavior.
+	SetEscapeHTML(on bool)
+
+	// Encode writes the JSON encoding of v to the stream,
+	// followed by a newline character.
+	//
+	// See the documentation for Marshal for details about the
+	// conversion of Go values to JSON.
+	Encode(v any) error
+}
+
+// Decoder an interface reads and decodes JSON values from an input stream.
+type Decoder interface {
+	// UseNumber causes the Decoder to unmarshal a number into an any as a
+	// Number instead of as a float64.
+	UseNumber()
+
+	// DisallowUnknownFields causes the Decoder to return an error when the destination
+	// is a struct and the input contains object keys which do not match any
+	// non-ignored, exported fields in the destination.
+	DisallowUnknownFields()
+
+	// Decode reads the next JSON-encoded value from its
+	// input and stores it in the value pointed to by v.
+	//
+	// See the documentation for Unmarshal for details about
+	// the conversion of JSON into a Go value.
+	Decode(v any) error
+}

codec/json/go_json.go

@@ -0,0 +1,42 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+//go:build go_json
+
+package json
+
+import (
+	"io"
+
+	"github.com/goccy/go-json"
+)
+
+// Package indicates what library is being used for JSON encoding.
+const Package = "github.com/goccy/go-json"
+
+func init() {
+	API = gojsonApi{}
+}
+
+type gojsonApi struct{}
+
+func (j gojsonApi) Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+func (j gojsonApi) Unmarshal(data []byte, v any) error {
+	return json.Unmarshal(data, v)
+}
+
+func (j gojsonApi) MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+	return json.MarshalIndent(v, prefix, indent)
+}
+
+func (j gojsonApi) NewEncoder(writer io.Writer) Encoder {
+	return json.NewEncoder(writer)
+}
+
+func (j gojsonApi) NewDecoder(reader io.Reader) Decoder {
+	return json.NewDecoder(reader)
+}

codec/json/json.go

@@ -0,0 +1,41 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+//go:build !jsoniter && !go_json && !(sonic && (linux || windows || darwin))
+
+package json
+
+import (
+	"encoding/json"
+	"io"
+)
+
+// Package indicates what library is being used for JSON encoding.
+const Package = "encoding/json"
+
+func init() {
+	API = jsonApi{}
+}
+
+type jsonApi struct{}
+
+func (j jsonApi) Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+func (j jsonApi) Unmarshal(data []byte, v any) error {
+	return json.Unmarshal(data, v)
+}
+
+func (j jsonApi) MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+	return json.MarshalIndent(v, prefix, indent)
+}
+
+func (j jsonApi) NewEncoder(writer io.Writer) Encoder {
+	return json.NewEncoder(writer)
+}
+
+func (j jsonApi) NewDecoder(reader io.Reader) Decoder {
+	return json.NewDecoder(reader)
+}

codec/json/jsoniter.go

@@ -0,0 +1,44 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+//go:build jsoniter
+
+package json
+
+import (
+	"io"
+
+	jsoniter "github.com/json-iterator/go"
+)
+
+// Package indicates what library is being used for JSON encoding.
+const Package = "github.com/json-iterator/go"
+
+func init() {
+	API = jsoniterApi{}
+}
+
+var json = jsoniter.ConfigCompatibleWithStandardLibrary
+
+type jsoniterApi struct{}
+
+func (j jsoniterApi) Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+func (j jsoniterApi) Unmarshal(data []byte, v any) error {
+	return json.Unmarshal(data, v)
+}
+
+func (j jsoniterApi) MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+	return json.MarshalIndent(v, prefix, indent)
+}
+
+func (j jsoniterApi) NewEncoder(writer io.Writer) Encoder {
+	return json.NewEncoder(writer)
+}
+
+func (j jsoniterApi) NewDecoder(reader io.Reader) Decoder {
+	return json.NewDecoder(reader)
+}

codec/json/sonic.go

@@ -0,0 +1,44 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+//go:build sonic && (linux || windows || darwin)
+
+package json
+
+import (
+	"io"
+
+	"github.com/bytedance/sonic"
+)
+
+// Package indicates what library is being used for JSON encoding.
+const Package = "github.com/bytedance/sonic"
+
+func init() {
+	API = sonicApi{}
+}
+
+var json = sonic.ConfigStd
+
+type sonicApi struct{}
+
+func (j sonicApi) Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+func (j sonicApi) Unmarshal(data []byte, v any) error {
+	return json.Unmarshal(data, v)
+}
+
+func (j sonicApi) MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+	return json.MarshalIndent(v, prefix, indent)
+}
+
+func (j sonicApi) NewEncoder(writer io.Writer) Encoder {
+	return json.NewEncoder(writer)
+}
+
+func (j sonicApi) NewDecoder(reader io.Reader) Decoder {
+	return json.NewDecoder(reader)
+}