docs: add comments informing that global variable JSONAPI should not …

…be modified (trpc-group#157)

codec/serialization_json.go

@@ -17,8 +17,15 @@ import (
 	jsoniter "github.com/json-iterator/go"
 )
 
-// JSONAPI is json packing and unpacking object, users can change
-// the internal parameter.
+// Deprecated: JSONAPI is used by tRPC JSON serialization when the object does
+// not conform to protobuf proto.Message interface.
+//
+// This global variable is exportable due to backward comparability issue but
+// should not be modified. If users want to change the default behavior of
+// internal JSON serialization, please use register your customized serializer
+// function like:
+//
+//	codec.RegisterSerializer(codec.SerializationTypeJSON, yourOwnJSONSerializer)
 var JSONAPI = jsoniter.ConfigCompatibleWithStandardLibrary
 
 // JSONSerialization provides json serialization mode.

codec/serialization_jsonpb.go

@@ -29,7 +29,9 @@ var Marshaler = protojson.MarshalOptions{EmitUnpopulated: true, UseProtoNames: t
 var Unmarshaler = protojson.UnmarshalOptions{DiscardUnknown: false}
 
 // JSONPBSerialization provides jsonpb serialization mode. It is based on
-// protobuf/jsonpb.
+// protobuf/jsonpb. This serializer will firstly try jsonpb's serialization. If
+// object does not conform to protobuf proto.Message interface, json-iterator
+// will be used.
 type JSONPBSerialization struct{}
 
 // Unmarshal deserialize the in bytes into body.

restful/serialize_jsonpb.go

@@ -31,12 +31,23 @@ func init() {
 
 // JSONPBSerializer is used for content-Type: application/json.
 // It's based on google.golang.org/protobuf/encoding/protojson.
+//
+// This serializer will firstly try jsonpb's serialization. If object does not
+// conform to protobuf proto.Message interface, the serialization will switch to
+// json-iterator.
 type JSONPBSerializer struct {
 	AllowUnmarshalNil bool // allow unmarshalling nil body
 }
 
-// JSONAPI is a copy of jsoniter.ConfigCompatibleWithStandardLibrary.
+// Deprecated: JSONAPI is a copy of jsoniter.ConfigCompatibleWithStandardLibrary.
 // github.com/json-iterator/go is faster than Go's standard json library.
+//
+// This global variable is exportable due to backward comparability issue but
+// should not be modified. If users want to change the default behavior of
+// internal JSON serialization, please use register your customized serializer
+// function like:
+//
+//	restful.RegisterSerializer(yourOwnJSONSerializer)
 var JSONAPI = jsoniter.ConfigCompatibleWithStandardLibrary
 
 // Marshaller is a configurable protojson marshaler.