github.com/json-iterator/go 详细教程

最近接触到了 github.com/json-iterator/go , 是由滴滴开源的第三方json编码库，它同时提供Go和Java两个版本。

文中大量内容来自 github 上的 wiki 文档，有兴趣的朋友可以直接点击 Home 跳转到官方文档查阅。
本文加了些自己的思考以及相关的详细学习例子，废话不多说了，冲！！！

1、基础介绍

json-iterator提供简洁的API，可以让你很方便地进行json序列化/反序列化；与encoding/json完全兼容，使用者可以快速、方便地迁移到json-iterator上来。此外，json-iterator还提供了很多其他方便的功能，如开放的序列化/反序列化配置、Extension、FieldEncoder/FieldDecoder、懒解析Any对象等等增强功能，应对不同使用场景下的json编码和解析，满足各种复杂的需求
1.1、简单的API

• 序列化
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. b, err := jsoniter.Marshal(Student{"Allen", 18, 180.43})

  复制代码
• 反序列化
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. var std Student
  8. err := jsoniter.Unmarshal([]byte(`{"Name":"Allen","Age":18,"Height":180.43}`), &std)

  复制代码

1.2、替代encoding/json

encoding/json可以很方便地迁移到json-iterator，并且迁移前后代码行为保持一致。不管你是使用基本的Marshal/Unmarshal接口，或是使用Encoder/Decoder，或是你已有的Marshaler/Unmarshaler实现，都能正常地工作。

这一点还是挺重要的，尤其是对于替换成该 json 库的项目。

1. // import "encoding/json"
2. //
3. // json.Marshal(data)
5. import "github.com/json-iterator/go"
7. jsoniter.Marshal(data)

复制代码

只需要把import的package替换成"github.com/json-iterator/go"，包名从"json"，替换成"jsoniter"即可
1.3、序列化/反序列化配置

json-iterator提供了几种序列化/反序列化配置，供不同的场景下的使用

1. api := jsoniter.Config{SortMapKeys:true}.Froze()
2. b, err := api.Marshal(map[string]string{"C":"c", "A":"a", "B":"b"})

复制代码

上面的例子中，我们开启了SortMapKeys配置选项，让map序列化输出时字段进行排序输出。更多的选项说明，请参考Config章节
1.4、控制编解码行为

json-iterator提供了Extension机制，我们可以通过注册自己的Extension，来更精确地控制我们的序列化/反序列化行为

1. type sampleExtension struct {
2.     jsoniter.DummyExtension
3. }
5. func (e *sampleExtension) UpdateStructDescriptor(structDescriptor *jsoniter.StructDescriptor) {
6.     if structDescriptor.Type.String() != "main.testStruct" {
7.         return
8.     }
10.     binding := structDescriptor.GetField("TestField")
11.     binding.FromNames = []string{"TestField", "Test_Field", "Test-Field"}
12. }
14. type testStruct struct {
15.     TestField string
16. }
18. var t testStruct
19. jsoniter.RegisterExtension(&sampleExtension{})
20. err := jsoniter.Unmarshal([]byte(`{"TestField":"aaa"}`), &t)
21. err = jsoniter.Unmarshal([]byte(`{"Test_Field":"bbb"}`), &t)
22. err = jsoniter.Unmarshal([]byte(`{"Test-Field":"ccc"}`), &t)

复制代码

上面的例子中我们注册了一个Extension，它指定了testStruct的TestField字段名绑定到哪些字符串上，所有绑定的字符串在解析时都当成是该字段。更多的说明请参考Extension章节
1.5、快速操作json对象

json-iterator提供了Any对象，可以让你schemaless地从复杂嵌套json串中提取出感兴趣的部分

1. jsoniter.Get([]byte(`{"Field":{"InnerField":{"Name":"Allen"}}}`), "Field", "InnerField", "Name").ToString()
3. // output: Allen

复制代码

这里Get返回的是一个Any对象，我们获取嵌套结构体最内层的Name字段的Any对象，并调用ToString转换得到我们要的"Allen"字符串。更多的说明请参考Any章节
2、Config (重点)

下来内容全部来自官网，Config_cn 点击上面链接即可跳转。
json-iterator提供了一些常用的序列化/反序列化选型供配置，使用者可以根据自己需求打开/关闭特定的选项
2.1、配置选项

要配置序列化/反序列化选项，你需要创建一个Config结构体，并通过设置其字段来设置不同的选项，最后你还需要调用其Froze方法来生成这个Config对应的API对象，通过这个API对象来调用你的配置选项对应的序列化/反序列化函数。

1. api := jsoniter.Config{SortMapKeys:true}.Froze()
2. api.Marshal(data)

复制代码

这里我们创建了一个开启了SortMapKeys选项的Config，并生成其对应的API对象，来进行序列化
2.2、内置配置

json-iterator提供了三个内置的配置：

• ConfigDefault
  ConfigDefault是默认配置,它开启了EscapeHTML选项。默认配置的意思是说，当你不创建自己的Config对象并生成API对象，而是直接以类似jsoniter.xxx的方式调用接口时，实际上你的序列化/反序列化使用的就是这个ConfigDefault配置
  
• ConfigCompatibleWithStandardLibrary
  ConfigCompatibleWithStandardLibrary开启了EscapeHTML、SortMapKeys和ValidateJsonRawMessage选项，当你需要近似100%地保证你的序列化/反序列化行为与encoding/json保持一致时，你可以使用这个配置
  
• ConfigFastest
  ConfigFastest关闭了EscapeHTML，开启了MarshalFloatWith6Digits和ObjectFieldMustBeSimpleString选项，这个配置可以让你的序列化/反序列化达到最高效率，但会有某些限制
  

2.3、选项说明

• IndentionStep
  指定格式化序列化输出时的空格缩进数量
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. // 四空格缩进的格式化输出
  8. c := jsoniter.Config{IndentionStep:4}.Froze()
  9. if s, err := c.MarshalToString(Student{"Allen", 18, 180.43}); err == nil{
  10.     fmt.Println(s)
  11.     // Output:
  12.     // {
  13.     //     "Name": "Allen",
  14.     //     "Age": 18,
  15.     //     "Height": 180.43
  16.     // }
  17. }

  复制代码
• MarshalFloatWith6Digits
  指定浮点数序列化输出时最多保留6位小数
  1. c := jsoniter.Config{MarshalFloatWith6Digits:true}.Froze()
  2. if s, err := c.MarshalToString(3.14159265358979); err == nil{
  3.     fmt.Println(s)
  4.     // Output:
  5.     // 3.141593
  6. }

  复制代码
• EscapeHTML
  开启了这个选项后，如果你的string类型的变量中含有HTML中使用的特殊字符(如'','&'等)，序列化时它们会被转义输出
  1. type Text struct{
  2.     Html string
  3. }
  5. c := jsoniter.Config{EscapeHTML:true}.Froze()
  6. if s, err := c.MarshalToString(Text{``}); err == nil{
  7.     fmt.Println(s)
  8.     // Output:
  9.     // {"Html":"\u003cscript\u003exxx\u003c/script\u003e"}
  10. }

  复制代码
• SortMapKeys
  指定map类型序列化输出时按照其key排序
  1. rgb := map[string][3]int{
  2.     "yellow":{255, 255, 0},
  3.     "red":{0, 0, 255},
  4.     "green":{0, 255, 0},
  5.     "blue":{0, 0, 255},
  6. }
  7. c := jsoniter.Config{SortMapKeys:true}.Froze()
  8. if s, err := c.MarshalToString(rgb); err == nil{
  9.     fmt.Println(s)
  10.     // 按key的字典序排序输出
  11.     // Output:
  12.     // {"blue":[0,0,255],"green":[0,255,0],"red":[0,0,255],"yellow":[255,255,0]}
  13. }

  复制代码
• UseNumber
  指定反序列化时将数字(整数、浮点数)解析成json.Number类型。
  1. var number interface{}
  2. c := jsoniter.Config{UseNumber:true}.Froze()
  3. if err := c.UnmarshalFromString(`3.14159265358979`, &number); err == nil{
  4.     if n, ok := number.(json.Number); ok{
  5.         // 数字被解析成json.Number类型
  6.         f, _ := n.Float64()
  7.         fmt.Println(f)
  8.         // Output:
  9.         // 3.14159265358979
  10.     }
  11. }

  复制代码
• DisallowUnknownFields
  当开启该选项时，反序列化过程如果解析到未知字段，即在结构体的schema定义中找不到的字段时，不会跳过然后继续解析，而会返回错误
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. var std Student
  8. c := jsoniter.Config{DisallowUnknownFields:true}.Froze()
  9. // json串中包含未知字段"Weight"
  10. if err := c.UnmarshalFromString(`{"Name":"Allen","Age":18,"Height":180.43,"Weight":60.56}`, &std); err == nil{
  11.     fmt.Println(std)
  12. }else{
  13.     fmt.Println(err)
  14.     // Output
  15.     // main.Student.ReadObject: found unknown field: Weight, error found in #10 byte of ...|3,"Weight":60.56}|..., bigger context ...|{"Name":"Allen","Age":18,"Height":180.43,"Weight":60.56}|...
  16. }

  复制代码
• TagKey
  指定tag字符串，默认情况为"json"，我们可以指定成另一个字符串
  1. type Student struct{
  2.     Name string `jsoniter:"name"`
  3.     Age int
  4.     Height float32 `jsoniter:"-"`
  5. }
  7. // 将tag指定为"jsoniter"
  8. c := jsoniter.Config{TagKey:"jsoniter"}.Froze()
  9. if s, err := c.MarshalToString(Student{"Allen", 18, 180.43}); err == nil{
  10.     fmt.Println(s)
  11.     // Output:
  12.     // {"name":"Allen","Age":18}
  13. }

  复制代码
• OnlyTaggedField
  当开启该选项时，只有带上tag的结构体字段才会被序列化输出
  1. type Student struct{
  2.     Name string `json:"name"`
  3.     Age int
  4.     Height float32 `json:",omitempty"`
  5. }
  7. c := jsoniter.Config{OnlyTaggedField:true}.Froze()
  8. if s, err := c.MarshalToString(Student{"Allen", 18, 180.43}); err == nil{
  9.     fmt.Println(s)
  10.     // Age字段没有tag，不会编码输出
  11.     // Output:
  12.     // {"name":"Allen","Height":180.43}
  13. }

  复制代码
• ValidateJsonRawMessage
  json.RawMessage类型的字段在序列化时会原封不动地进行输出。开启这个选项后，json-iterator会校验这种类型的字段包含的是否一个合法的json串，如果合法，原样输出；否则会输出"null"
  1. type Book struct{
  2.     Pages int
  3.     Name string
  4.     Description json.RawMessage
  5. }
  7. c := jsoniter.Config{ValidateJsonRawMessage:true}.Froze()
  8. if s, err := c.MarshalToString(Book{361, "X",json.RawMessage(`{"Category":`)}); err == nil{
  9.     fmt.Println(s)
  10.     // Description 字段为非法json串，输出null
  11.     // Output:
  12.     // {"Pages":361,"Name":"X","Description":null}
  13. }

  复制代码
• ObjectFieldMustBeSimpleString
  开启该选项后，反序列化过程中不会对你的json串中对象的字段字符串可能包含的转义进行处理，因此你应该保证你的待解析json串中对象的字段应该是简单的字符串(不包含转义)
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. var std Student
  8. c := jsoniter.Config{ObjectFieldMustBeSimpleString:true}.Froze()
  9. if err := c.UnmarshalFromString(`{"Name":"Allen","Ag\u0065":18,"Height":180.43}`, &std); err == nil{
  10.     fmt.Println(std)
  11.     // Age字段的转义不会处理，因此该字段无法解析出来
  12.     // Output:
  13.     // {Allen 0 180.43}
  14. }

  复制代码
• CaseSensitive
  开启该选项后，你的待解析json串中的对象的字段必须与你的schema定义的字段大小写严格一致
  1. type Student struct{
  2.     Name string
  3.     Age int
  4.     Height float32
  5. }
  7. var std Student
  8. c := jsoniter.Config{CaseSensitive:true}.Froze()
  9. if err := c.UnmarshalFromString(`{"Name":"Allen","Age":18,"height":180.43}`, &std); err == nil{
  10.     fmt.Println(std)
  11.     // Height字段的大小写不一致，无法解析出来
  12.     // Output:
  13.     // {Allen 18 0}
  14. }

  复制代码

我们知道，当我们为为某个类型实现了MarshalJSON()([]byte, error)和UnmarshalJSON(b []byte) error方法，那么这个类型在序列化（MarshalJSON）/反序列化（UnmarshalJSON）时就会使用你定制的相应方法。
知道了这个前提知识后，我们来一起看看如何自定义 序列化和反序列化方式。
3、Extension

Config可以提供部分选项来控制序列化/反序列化的行为，但是不能提供更精细的编码或解析控制，无法应对复杂的需求。json-iterator考虑了这一点，提供了Extension的机制，来满足复杂的序列化/反序列化场景。
3.1、ValEncoder/ValDecoder接口

在介绍Extension的使用之前，需要先介绍一下ValEncoder和ValDecoder，因为Extension的本质上就是针对不同的类型创建不同的ValEncoder和ValDecoder实现的。注意，ValEncoder/ValDecoder和json.Encoder/json.Decoder是不一样的概念，不要混淆了。

• ValEncoder
  1. type ValEncoder interface {
  2.     IsEmpty(ptr unsafe.Pointer) bool
  3.     Encode(ptr unsafe.Pointer, stream *Stream)
  4. }

  复制代码
  ValEncoder实际上是json-iterator内部用于针对某个类型的数据进行序列化编码的编码器，它的两个成员函数说明如下：
  
  
  
  • Encode
    Encode函数用于实现某个类型数据的编码，ptr是指向当前待编码数据的指针，stream提供不同的接口供使用者将各种类型的数据写入到输出设备(详见Stream章节)。那么，在这个函数里面，我们怎么实现编码呢？实际上，我们大部分时间做的，就是将ptr转换成这个ValEncoder对应的数据类型的指针，然后调用stream的接口，将ptr指向的数值进行编码输出
    
  • IsEmpty
    IsEmpty是跟omitempty这个tag相关的函数。我们都知道，在一个结构体里面，如果某个字段的tag带上了omitempty属性，那么当这个字段对应的"数值为空"时，这个字段在序列化时不会被编码输出。那么什么叫"数值为空"呢？对于不同类型的数据，恐怕应该是有不同的定义的。因此IsEmpty这个函数里面，就是需要你去实现，你的ValEncoder对应的数据类型在实际数值是什么的时候，称作"数值为空"
    
  我们看一个具体的例子，来帮助我们理解ValEncoder。json-iterator提供了一个内置的TimeAsInt64Codec，来看看它的实现：
  1. func (codec *timeAsInt64Codec) IsEmpty(ptr unsafe.Pointer) bool {
  2.     ts := *((*time.Time)(ptr))
  3.     return ts.UnixNano() == 0
  4. }
  6. /*
  7. 在这种情况下，`ptr` 被声明为 `unsafe.Pointer`，并且进行了类型转换操作 `*((*time.Time)(ptr))`。让我们逐步解释这个表达式：
  9. 1. `unsafe.Pointer`：`unsafe.Pointer` 是 Go 语言中的一个特殊类型，它可以表示任何指针类型，但是使用它可能会绕过类型安全检查，因此需要非常小心使用。
  11. 2. `(ptr)`：这里的 `(ptr)` 将 `unsafe.Pointer` 类型转换为 `*time.Time` 指针类型。这是一个类型断言（type assertion），将一个指针从 `unsafe.Pointer` 转换为 `*time.Time` 类型的指针。
  13. 3. `*((*time.Time)(ptr))`：外层的 `*` 表示这是一个指针类型的表达式，即一个指向 `time.Time` 类型的指针。这实际上是将 `unsafe.Pointer` 转换后的指针再次转换回 `*time.Time` 指针类型。
  15. 综上所述，`*((*time.Time)(ptr))` 表达的含义是将 `unsafe.Pointer` 类型的指针 `ptr` 首先转换为 `*time.Time` 指针类型，然后通过解引用该指针，可以获取到指向 `time.Time` 类型对象的引用。这种使用 `unsafe.Pointer` 进行类型转换的操作需要格外小心，因为它绕过了 Go 语言的类型安全性，可能会导致未定义行为或内存问题。
  17. * 有两种作用，一个是定义指针类型，一个是根据内容地址取对应的值，这里最外面的 * 就是根据内存地址取值。
  19. */
  21. func (codec *timeAsInt64Codec) Encode(ptr unsafe.Pointer, stream *jsoniter.Stream) {
  22.     ts := *((*time.Time)(ptr))
  23.     stream.WriteInt64(ts.UnixNano() / codec.precision.Nanoseconds())
  24. }

  复制代码
  Encode函数中，将ptr转换成指向time.Time类型的指针，然后对其解引用拿到了其指向的time.Time对象。接下来调用其成员函数计算出它对应的unix时间，最后调用stream的写入接口将这个int64的unix时间数值进行编码输出，这样就完成了将原本以对象方式输出的time.Time数值，转换成int64类型的unix时间输出
  IsEmpty通过同样方式拿到ptr指向的time.Time对象，然后将time.Time类型"数值为空"定义为其转换出来的unix时间为0
  
  
• ValDecoder
  1. type ValDecoder interface {
  2.     Decode(ptr unsafe.Pointer, iter *Iterator)
  3. }

  复制代码
  ValEncoder实际上是json-iterator内部用于针对某个类型的数据进行反序列化解码的解码器，它的成员函数说明如下：
  
  
  
  • Decode
    Decode函数用于实现某个类型数据的解码，ptr是指向当前待写入数据的指针，iter提供不同的接口供使用者将各种类型的数据从输入源读入(详见Iterator章节)。那么，在这个函数里面，我们怎么实现解码呢？首先，我们调用iter提供的接口，从json串的输入源读入ValDecoder对应类型的数据，然后将ptr做一个强转，将其转换成指向ValDecoder对应类型的指针，然后将该指针指向的数据设置成我们通过iter接口读取出来的值
    
  还是看TimeAsInt64Codec的例子
  1. func (codec *timeAsInt64Codec) Decode(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
  2.     nanoseconds := iter.ReadInt64() * codec.precision.Nanoseconds()
  3.     *((*time.Time)(ptr)) = time.Unix(0, nanoseconds)
  4. }

  复制代码
  Decode函数中，调用iter的接口从json输入源中读取了一个int64的数值，接下来因为我们这个ValDecoder对应的数据类型是time.Time，这里把ptr转换成指向time.Time类型的指针，并以我们读入的int64数值为unix时间初始化了一个time.Time对象，最后将它赋给ptr指向的数值。这样，我们就完成了从json串中读入unix时间，并将其转换成time.Time对象的功能
  
  

3.2、定制你的扩展

要定制序列化/反序列化扩展，需要实现Extension接口，并通过RegisterExtension进行注册，Extension包含以下方法：

1. type Extension interface {
2.     UpdateStructDescriptor(structDescriptor *StructDescriptor)
3.     CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
4.     CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
5.     CreateDecoder(typ reflect2.Type) ValDecoder
6.     CreateEncoder(typ reflect2.Type) ValEncoder
7.     DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
8.     DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
9. }

复制代码

当然，很多情况下，我们只需要用到里面的部分功能。json-iterator里面提供了一个DummyExtension，它是一个最基础的Extension实现(基本什么都不做或返回空)。当你在定义自己的Extension时，你可以匿名地嵌入DummyExtension，这样你就不需要实现所有的Extension成员，只需要关注自己需要的功能。下面我们通过一些例子，来说明Extension的各个成员函数可以用来做什么

• UpdateStructDescriptor
  UpdateStructDescriptor函数中，我们可以对结构体的某个字段定制其编码/解码器，或者控制该字段序列化/反序列化时与哪些字符串绑定
  1. type testCodec struct{
  2. }
  4. func (codec *testCodec) Encode(ptr unsafe.Pointer, stream *jsoniter.Stream){
  5.     str := *((*string)(ptr))
  6.     stream.WriteString("TestPrefix_" + str)
  7. }
  9. func (codec *testCodec) IsEmpty(ptr unsafe.Pointer) bool {
  10.     str := *((*string)(ptr))
  11.     return str == ""
  12. }
  14. type sampleExtension struct {
  15.     jsoniter.DummyExtension
  16. }
  18. func (e *sampleExtension) UpdateStructDescriptor(structDescriptor *jsoniter.StructDescriptor) {
  19.     // 这个判断保证我们只针对testStruct结构体，对其他类型无效
  20.     if structDescriptor.Type.String() != "main.testStruct" {
  21.         return
  22.     }
  24.     binding := structDescriptor.GetField("TestField")
  25.     binding.Encoder = &testCodec{}
  26.     binding.FromNames = []string{"TestField", "Test_Field", "Test-Field"}
  27. }
  29. func extensionTest(){
  30.     type testStruct struct {
  31.         TestField string
  32.     }
  34.     t := testStruct{"fieldValue"}
  35.     jsoniter.RegisterExtension(&sampleExtension{})
  36.     s, _ := jsoniter.MarshalToString(t)
  37.     fmt.Println(s)
  38.     // Output:
  39.     // {"TestField":"TestPrefix_fieldValue"}
  41.     jsoniter.UnmarshalFromString(`{"Test-Field":"bbb"}`, &t)
  42.     fmt.Println(t.TestField)
  43.     // Output:
  44.     // bbb
  45. }

  复制代码
  上面的例子，首先我们用testCodec实现了一个ValEncoder，它编码时在字符串的前面加了一个"TestPrefix_"的前缀再输出。接着我们注册了一个sampleExtension，在UpdateStructDescriptor函数中我们将testStruct的TestField字段的编码器设置为我们的testCodec，最后将其与几个别名字符串进行了绑定。得到的效果就是，这个结构体序列化输出时，TestField的内容会添加上"TestPrefix_"前缀；而反序列化时，TestField的别名都将映射成这个字段
  
• CreateDecoder
  
• CreateEncoder
  CreateDecoder和CreateEncoder分别用来创建某个数据类型对应的解码器/编码器
  1. type wrapCodec struct{
  2.     encodeFunc  func(ptr unsafe.Pointer, stream *jsoniter.Stream)
  3.     isEmptyFunc func(ptr unsafe.Pointer) bool
  4.     decodeFunc func(ptr unsafe.Pointer, iter *jsoniter.Iterator)
  5. }
  7. func (codec *wrapCodec) Encode(ptr unsafe.Pointer, stream *jsoniter.Stream) {
  8.     codec.encodeFunc(ptr, stream)
  9. }
  11. func (codec *wrapCodec) IsEmpty(ptr unsafe.Pointer) bool {
  12.     if codec.isEmptyFunc == nil {
  13.         return false
  14.     }
  16.     return codec.isEmptyFunc(ptr)
  17. }
  19. func (codec *wrapCodec) Decode(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
  20.     codec.decodeFunc(ptr, iter)
  21. }
  23. type sampleExtension struct {
  24.     jsoniter.DummyExtension
  25. }
  27. func (e *sampleExtension) CreateDecoder(typ reflect2.Type) jsoniter.ValDecoder {
  28.     if typ.Kind() == reflect.Int {
  29.         return &wrapCodec{
  30.             decodeFunc:func(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
  31.                 i := iter.ReadInt()
  32.                 *(*int)(ptr) = i - 1000
  33.             },
  34.         }
  35.     }
  37.     return nil
  38. }
  40. func (e *sampleExtension) CreateEncoder(typ reflect2.Type) jsoniter.ValEncoder {
  41.     if typ.Kind() == reflect.Int {
  42.         return &wrapCodec{
  43.             encodeFunc:func(ptr unsafe.Pointer, stream *jsoniter.Stream) {
  44.                 stream.WriteInt(*(*int)(ptr) + 1000)
  45.             },
  46.             isEmptyFunc:nil,
  47.         }
  48.     }
  50.     return nil
  51. }
  53. func extensionTest(){
  54.     i := 20000
  55.     jsoniter.RegisterExtension(&sampleExtension{})
  56.     s, _ := jsoniter.MarshalToString(i)
  57.     fmt.Println(s)
  58.     // Output:
  59.     // 21000
  61.     jsoniter.UnmarshalFromString(`30000`, &i)
  62.     fmt.Println(i)
  63.     // Output:
  64.     // 29000
  65. }

  复制代码
  上面的例子我们用wrapCodec实现了ValEncoder和ValDecoder，然后我们注册了一个Extension，这个Extension的CreateEncoder函数中设置了wrapCodec的Encode函数，指定对于Int类型的数值+1000后输出；CreateDecoder函数中设置了wrapCodec的Decode函数，指定读取了Int类型的数值后，-1000再进行赋值。这里要注意的是，不管是CreateEncoder还是CreateDecoder函数，我们都通过其typ参数限定了这个编码/解码器只对Int类型生效
  
• CreateMapKeyDecoder
  
• CreateMapKeyEncoder
  CreateMapKeyDecoder和CreateMapKeyEncoder跟上面的CreateDecoder和CreateEncoder用法差不多，只不过他们的生效对象是map类型的key的，这里不再举例详述了。
  
• DecorateDecoder
  
• DecorateEncoder
  DecorateDecoder和DecorateEncoder可以用于装饰现有的ValEncoder和ValEncoder。考虑这么一个例子，在上述的CreateDecoder和CreateEncoder的说明中所举例的基础上，我们想再做一层扩展。当我们遇到数字字符串时，我们希望也可以解析成整形数，并且要复用基础例子中的解码器，这时候我们就需要用到装饰器。
  1. type decorateExtension struct{
  2.     jsoniter.DummyExtension
  3. }
  5. type decorateCodec struct{
  6.     originDecoder jsoniter.ValDecoder
  7. }
  9. func (codec *decorateCodec) Decode(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
  10.     if iter.WhatIsNext() == jsoniter.StringValue {
  11.         str := iter.ReadString()
  12.         if _, err := strconv.Atoi(str); err == nil{
  13.             newIter := iter.Pool().BorrowIterator([]byte(str))
  14.             defer iter.Pool().ReturnIterator(newIter)
  15.             codec.originDecoder.Decode(ptr, newIter)
  16.         }else{
  17.             codec.originDecoder.Decode(ptr, iter)
  18.         }
  19.     } else {
  20.         codec.originDecoder.Decode(ptr, iter)
  21.     }
  22. }
  24. func (e *decorateExtension) DecorateDecoder(typ reflect2.Type, decoder jsoniter.ValDecoder) jsoniter.ValDecoder{
  25.     if typ.Kind() == reflect.Int {
  26.         return &decorateCodec{decoder}
  27.     }
  29.     return nil
  30. }
  32. func extensionTest(){
  33.     var i int
  34.     jsoniter.RegisterExtension(&sampleExtension{})
  35.     jsoniter.RegisterExtension(&decorateExtension{})
  37.     jsoniter.UnmarshalFromString(`30000`, &i)
  38.     fmt.Println(i)
  39.     // Output:
  40.     // 29000
  42.     jsoniter.UnmarshalFromString(`"40000"`, &i)
  43.     fmt.Println(i)
  44.     // Output:
  45.     // 39000
  46. }

  复制代码
  在CreateDecoder和CreateEncoder的例子基础上，我们在注册一个Extension，这个Extension只实现了装饰器功能，它兼容字符串类型数字的解析，并且解析出来的数字依然要-1000再赋值
  

3.3、作用域

json-iterator有两个RegisterExtension接口可以调用，一个是package级别的jsoniter.RegisterExtension，一个是API(说明见Config章节)级别的API.RegisterExtension。这两个函数都可以用来注册扩展，但是两种注册方式注册的扩展的作用域略有不同。jsoniter.RegisterExtension注册的扩展，对于所有Config生成的API都生效；而API.RegisterExtension只对其对应的Config生成的API接口生效，这个需要注意
4、Any（重点）

很多情况下，对于一个json输入源，我们只对其部分内容感兴趣。为了得到我们需要的小部分信息，去定义跟这个json串匹配的schema是一件麻烦的事件。对于体积庞大或者嵌套层次深的json串尤其如此。json-iterator提供了Any对象，可以很方便地从json串中获取你想要的元素，而不需要去定义schema
4.1、使用简单

假设我们有这么一个json

1. jsonStr := []byte(`{
2.   "users": [
3.     {
4.       "username": "system",
5.       "avatar_template": "/user_avatar/discourse.metabase.com/system/{size}/6_1.png",
6.       "id": -1
7.     },
8.     {
9.       "username": "zergot",
10.       "avatar_template": "https://avatars.discourse.org/v2/letter/z/0ea827/{size}.png",
11.       "id": 89
12.     }
13.   ],
14.   "topics": {
15.     "can_create_topic": false,
16.     "more_topics_url": "/c/uncategorized/l/latest?page=1",
17.     "draft": null,
18.     "draft_key": "new_topic",
19.     "draft_sequence": null,
20.     "per_page": 30,
21.     "topics": [
22.       {
23.         "bumped": true,
24.         "id": 8,
25.         "excerpt": "Welcome to Metabase\u0026#39;s discussion forum. This is a place to get help on installation, setting up as well as sharing tips and tricks.",
26.         "category_id": 1,
27.         "unseen": false,
28.         "slug": "welcome-to-metabases-discussion-forum",
29.         "fancy_title": "Welcome to Metabase\u0026rsquo;s Discussion Forum",
30.         "bookmarked": null,
31.         "archived": false,
32.         "archetype": "regular",
33.         "highest_post_number": 1,
34.         "reply_count": 0,
35.         "visible": true,
36.         "closed": false,
37.         "liked": null,
38.         "posts_count": 1,
39.         "views": 197,
40.         "image_url": "/images/welcome/discourse-edit-post-animated.gif",
41.         "created_at": "2015-10-17T00:14:49.526Z",
42.         "last_posted_at": "2015-10-17T00:14:49.557Z",
43.         "pinned": true,
44.         "title": "Welcome to Metabase's Discussion Forum",
45.         "has_summary": false,
46.         "like_count": 0,
47.         "pinned_globally": true,
48.         "last_poster_username": "system",
49.         "posters": [
50.           {
51.             "extras": "latest single",
52.             "description": "Original Poster, Most Recent Poster",   // 我们需要这个
53.             "user_id": -1
54.           }
55.         ],
56.         "bumped_at": "2015-10-21T02:32:22.486Z",
57.         "unpinned": null
58.       }
59.     ]
60.   }
61. }`)

复制代码

如果用传统的方法，那么首先我们应该先定义一个匹配这个json结构的结构体，然后调用Unmarshal来反序列化，再获取这个结构体中我们需要的字段的值。如果用Any，那么就很简单了：

1. any := jsoniter.Get(jsonStr, "topics", "topics", 0, "posters", 0, "description")
2. fmt.Println(any.ToString())
3. // Output：
4. // Original Poster, Most Recent Poster

复制代码

只需要一行，我们就可以拿到我们想要的元素。然后调用Any对象提供的接口做下转换，就得到了我们要的description字符串
4.2、与schema结合

还是上面的例子

1. jsonStr := []byte(`{
2.   "users": [
3.     {
4.       "username": "system",
5.       "avatar_template": "/user_avatar/discourse.metabase.com/system/{size}/6_1.png",
6.       "id": -1
7.     },
8.     {
9.       "username": "zergot",
10.       "avatar_template": "https://avatars.discourse.org/v2/letter/z/0ea827/{size}.png",
11.       "id": 89
12.     }
13.   ],
14.   "topics": {
15.     "can_create_topic": false,
16.     "more_topics_url": "/c/uncategorized/l/latest?page=1",
17.     "draft": null,
18.     "draft_key": "new_topic",
19.     "draft_sequence": null,
20.     "per_page": 30,
21.     "topics": [
22.       {
23.         "bumped": true,
24.         "id": 8,
25.         "excerpt": "Welcome to Metabase\u0026#39;s discussion forum. This is a place to get help on installation, setting up as well as sharing tips and tricks.",
26.         "category_id": 1,
27.         "unseen": false,
28.         "slug": "welcome-to-metabases-discussion-forum",
29.         "fancy_title": "Welcome to Metabase\u0026rsquo;s Discussion Forum",
30.         "bookmarked": null,
31.         "archived": false,
32.         "archetype": "regular",
33.         "highest_post_number": 1,
34.         "reply_count": 0,
35.         "visible": true,
36.         "closed": false,
37.         "liked": null,
38.         "posts_count": 1,
39.         "views": 197,
40.         "image_url": "/images/welcome/discourse-edit-post-animated.gif",
41.         "created_at": "2015-10-17T00:14:49.526Z",
42.         "last_posted_at": "2015-10-17T00:14:49.557Z",
43.         "pinned": true,
44.         "title": "Welcome to Metabase's Discussion Forum",
45.         "has_summary": false,
46.         "like_count": 0,
47.         "pinned_globally": true,
48.         "last_poster_username": "system",
49.         "posters": [
50.           {    // 这次我们需要这个
51.             "extras": "latest single",
52.             "description": "Original Poster, Most Recent Poster",   
53.             "user_id": -1
54.           }
55.         ],
56.         "bumped_at": "2015-10-21T02:32:22.486Z",
57.         "unpinned": null
58.       }
59.     ]
60.   }
61. }`)

复制代码

这次我们需要"posters"数组的第一个结构体，我们现在已经有它的schema定义了，除此之外这个json的其他信息我都不需要，那么如何通过Any对象获得这个结构体呢？我们需要ToVal接口：

1. type Poster struct {
2.         Extras string `json:"extras"`
3.         Desc string `json:"description"`
4.         UserId int `json:"user_id"`
5. }
7. var p Poster
8. any := jsoniter.Get(jsonStr, "topics", "topics", 0, "posters", 0)
9. any.ToVal(&p)
10. fmt.Printf("extras=%s\ndescription=%s\nuser_id=%d\n", p.Extras, p.Desc, p.UserId)
11. // Output：
12. // extras=latest single
13. // description=Original Poster, Most Recent Poster
14. // user_id=-1

复制代码

这里可以看到，首先我们拿到了"posters"第一个元素的Any对象，然后调用ToVal方法，就可以像之前的反序列化方法一样把数据解析出来。实际上，如果你的Any对象对应的是数组或对象类型的元素，它内部保存了这个元素原始的json串。当你需要获取其字段、元素或者将其反序列化出来的时候，才会触发解析。json-iterator内部将其称为懒解析。来看个数组的例子：

1. type User struct {
2.         UserName string `json:"username"`
3.         Template string `json:"avatar_template"`
4.         Id int `json:"id"`
5. }
7. var users []User
8. any := jsoniter.Get(jsonStr, "users")
9. fmt.Println(any.Get(0, "username").ToString())
10. // Output：
11. // system
13. any.ToVal(&users)
14. fmt.Printf("username=%s\navatar_template=%s\nid=%d\n", users[1].UserName, users[1].Template, users[1].Id)
15. // Output：
16. // username=zergot
17. // avatar_template=https://avatars.discourse.org/v2/letter/z/0ea827/{size}.png
18. // id=89

复制代码

数组元素的获取方法其实也是类似，这里不再详述。
有一点需要说明的是，只有数组和对象的json元素对应的Any才提供ToVal方法，也就是说这两种json元素的Any对象才实现了懒解析，其他诸如int,bool,string等都没有实现，实际上它们也不需要什么懒解析
5、Iterator

json-iterator中使用Iterator来实现流式解析。通过其提供的API，我们可以控制json串的解析行为，我们可以对json串中与schema定义不一致的字段做兼容性的解析处理，也可以跳过我们不关心的json串中的片段
5.1、创建Iterator实例

有三种方法可以创建Iterator实例：

• 从API对象的Iterator实例池中Borrow一个
  1. c := jsoniter.ConfigDefault
  2. i := c.BorrowIterator([]byte(`{"A":"a"}`))
  3. defer c.ReturnIterator(i)
  5. // 你的功能实现
  6. // xxxxxx
  7. // ......

  复制代码
  使用这种方法"借用"的Iterator实例，记得在使用完毕后"返还"回去
  
• 调用NewIterator接口新建一个
  1. i := jsoniter.NewIterator(jsoniter.ConfigDefault)
  2. i.Reset(os.Stdin)
  3. // 或者i.ResetBytes(`{"A":"a"}`)
  5. // 你的功能实现
  6. // xxxxxx
  7. // ......

  复制代码
  使用这种方法，需要传入你的序列化配置对应生成的API对象。对于这种方法，要指定输入源io.Reader或输入json串都只能在创建了Iterator后，调用其重置方法Reset或ResetBytes来设置其待解析输入。如果要在创建的时候就指定输入源，可以用第三种方法
  
• 调用ParseXXX方法新建一个
  1. i := jsoniter.Parse(jsoniter.ConfigDefault, os.Stdin, 1024)
  2. // 或者 i := jsoniter.ParseBytes(jsoniter.ConfigDefault, []byte(`{"A":"a"}`))
  3. // 或者 i := jsoniter.ParseString(jsoniter.ConfigDefault, `{"A":"a"}`)
  5. // 你的功能实现
  6. // xxxxxx
  7. // ......

  复制代码
  使用Parse族的方法，可以在创建Iterator的时候指定待解析json串的输入源。其中Parse方法还可以指定Iterator用于解析的内部缓冲的大小
  

5.2、定制解析行为

想象一个这样的场景：我们的数据结构schema中某个字段定义成了bool类型，但是我们接收到的json串中，该字段对应的值可能是bool类型，可能是int类型，还可能是string类型，我们需要对其做兼容性的解析处理，这时候Iterator(配合Extension或ValDecoder)就可以发挥作用了。

1. type testStructForIterator struct{
2.     BoolField bool
3. }
5. jsoniter.RegisterFieldDecoder(reflect2.TypeOf(testStructForIterator{}).String(), "BoolField",
6.     &wrapDecoder{
7.         func(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
8.             typ := iter.WhatIsNext()
9.             switch typ {
10.             case jsoniter.BoolValue:
11.                 *((*bool)(ptr)) = iter.ReadBool()
12.             case jsoniter.NumberValue:
13.                 number := iter.ReadNumber()
14.                 if n, err := number.Int64(); err == nil{
15.                     if n > 0{
16.                         *((*bool)(ptr)) = true
17.                     }else{
18.                         *((*bool)(ptr)) = false
19.                     }
20.                 }else{
21.                     *((*bool)(ptr)) = false
22.                 }
23.             case jsoniter.StringValue:
24.                 str := iter.ReadString()
25.                 if str == "true"{
26.                     *((*bool)(ptr)) = true
27.                 }else{
28.                     *((*bool)(ptr)) = false
29.                 }
30.             case jsoniter.NilValue:
31.                 iter.ReadNil()
32.                 *((*bool)(ptr)) = false
33.             default:
34.                 iter.ReportError("wrapDecoder", "unknown value type")
35.             }
36.         },
37.     })
39. t := testStructForIterator{}
40. if err := jsoniter.Unmarshal([]byte(`{"BoolField":true}`), &t); err == nil{
41.     fmt.Println(t.BoolField)
42.     // 输出：true
43. }
45. if err := jsoniter.Unmarshal([]byte(`{"BoolField":1}`), &t); err == nil{
46.     fmt.Println(t.BoolField)
47.     // 输出：true
48. }
50. if err := jsoniter.Unmarshal([]byte(`{"BoolField":"true"}`), &t); err == nil{
51.     fmt.Println(t.BoolField)
52.     // 输出：true
53. }
55. if err := jsoniter.Unmarshal([]byte(`{"BoolField":"false"}`), &t); err == nil{
56.     fmt.Println(t.BoolField)
57.     // 输出：false
58. }
60. if err := jsoniter.Unmarshal([]byte(`{"BoolField":null}`), &t); err == nil{
61.     fmt.Println(t.BoolField)
62.     // 输出：false
63. }

复制代码

在上面这个例子里面，我们针对testStructForIterator的BoolField字段注册了一个ValDecoder。在它的Decode方法中，我们先调用Iterator的WhatIsNext方法，通过json串中下一个元素的类似，来决定调用Iterator的哪个方法来解析下一个数值，根据解析结果，设置ptr指向的bool类型的数据值。这样不管我们解析的json串中，BoolField字段实际使用布尔、数值或是字符串来表示，我们都可以做到兼容
Iterator开放了各种接口用于从输入中读入不同类型的数据：

• ReadBool
  
• ReadString
  
• ReadInt
  
• ReadFloat32
  
• ReadMapCB
  
• ReadObjectCB
  
• ReadArrayCB
  
• ......
  

具体每个方法的说明可以参考godoc
5.3、跳过json片段

使用Iterator，我们可以跳过json串中的特定片段，只处理我们感兴趣的部分。考虑这么一个场景：我们接收到一个json串，这个json串中包含了一个对象，我们只想把这个对象的每个字段的字段名记录下来，至于字段对应的具体内容，我们不关心。为了实现这样的需求，我们需要用到Iterator

1. jsonStr := `
2. {
3.         "_id": "58451574858913704731",
4.         "about": "a4KzKZRVvqfBLdnpUWaD",
5.         "address": "U2YC2AEVn8ab4InRwDmu",
6.         "age": 27,
7.         "balance": "I5cZ5vRPmVXW0lhhRzF4",
8.         "company": "jwLot8sFN1hMdE4EVW7e",
9.         "email": "30KqJ0oeYXLqhKMLDUg6",
10.         "eyeColor": "RWXrMsO6xi9cpxPqzJA1",
11.         "favoriteFruit": "iyOuAekbybTUeDJqkHNI",
12.         "gender": "ytgB3Kzoejv1FGU6biXu",
13.         "greeting": "7GXmN2vMLcS2uimxGQgC",
14.         "guid": "bIqNIywgrzva4d5LfNlm",
15.         "index": 169390966,
16.         "isActive": true,
17.         "latitude": 70.7333712683406,
18.         "longitude": 16.25873969455544,
19.         "name": "bvtukpT6dXtqfbObGyBU",
20.         "phone": "UsxtI7sWGIEGvM2N1Mh0",
21.         "picture": "8fiyZ2oKapWtH5kXyNDZJjvRS5PGzJGGxDCAk1he1wuhUjxfjtGIh6agQMbjovF10YlqOyzhQPCagBZpW41r6CdrghVfgtpDy7YH",
22.         "registered": "gJDieuwVu9H7eYmYnZkz",
23.         "tags": [
24.                 "M2b9n0QrqC",
25.                 "zl6iJcT68v",
26.                 "VRuP4BRWjs",
27.                 "ZY9jXIjTMR"
28.         ]
29. }
30. `
31. fieldList := make([]string, 0)
32. iter := jsoniter.ParseString(jsoniter.ConfigDefault, jsonStr)
33. iter.ReadObjectCB(func(iter *jsoniter.Iterator, field string) bool{
34.     fieldList = append(fieldList, field)
35.     iter.Skip()
36.     return true
37. })
39. fmt.Println(fieldList)
40. // 输出：[_id about address age balance company email eyeColor favoriteFruit gender greeting guid index isActive latitude longitude name phone picture registered tags]

复制代码

在上面的例子中，我们调用了ParseString来创建一个Iterator实例。ParseString可以指定Iterator实例对应的配置和作为解析源的json串。然后我们调用了Iterator的ReadObjectCB方法，调用时必须传入一个回调函数。ReadObjectCB方法会解析一个对象类型的json串，并迭代这个json串中的顶层对象的每个字段，对每个字段都会调用我们一开始传进去的回调函数。这里可以看到，在回调函数里面，我们只是将传进来的字段名记录下来，然后调用Iterator的Skip来跳过这个字段对应的实际内容。Skip会自动解析json串中接下来的元素是什么类型的，然后跳过它的解析，跳到下一个字段。当遍历完毕后我们就可以拿到我们需要的字段列表了。
5.4、另一种反序列化接口

Iterator也提供了一个接口，可以实现跟Decoder的Decode方法基本一样的序列化功能

1. type testStructForIterator struct{
2.     Name string
3.     Id int
4. }
6. var dat testStructForIterator
7. iter := jsoniter.Parse(jsoniter.ConfigDefault, nil, 1024)
8. iter.ResetBytes([]byte(`{"Name":"Allen","Id":100}`))
10. if iter.ReadVal(&dat); iter.Error == nil || iter.Error == io.EOF{
11.     fmt.Println(dat)
12.     // 输出：{Allen 100}
13. }

复制代码

在上面这个例子里面，我们调用Parse来创建了一个Iterator实例，不设置输入设备io.Reader，我们用ResetBytes来设置待解析的json串，然后调用ReadVal方法来实现序列化。通过这种方式，也可以完成反序列化。实际上，json-iterator内部也是使用类似的方式，调用Iterator的ReadVal来完成反序列化。这里有一点需要说明：

• 调用Parse创建Iterator实例，可以指定Iterator内部缓冲的大小。对于解析输入源从io.Reader读入的应用场合，由于Iterator的内部流式实现，是不会一次过将数据从io.Reader全部读取出来然后解析的，而是每次读入不超过缓冲区长度的大小的数据，然后解析。当解析过程发现缓冲区中数据已经解析完，又会从io.Reader中读取数据到缓冲区，继续解析，直至整个完整的json串解析完毕。考虑这么一个例子：你的Iterator的缓冲区大小设置为1024，但你的io.Reader里面有10M的json串需要解析，这样大概可以认为要把这个json串解析完，需要从io.Reader读入数据10240次，每次读1024字节。因此，如果你的解析源需要从io.Reader中读入，对性能要求较高，而对内存占用不太敏感，那么不妨放弃直接调用Unmarshal，自己创建Iterator来进行反序列化，并适当将Iterator的缓冲设置得大一点，提高解析效率
  

5.5、复用Iterator实例

你可以调用Reset(解析源为io.Reader)或者ResetBytes(解析源为字符串或字节序列)来复用你的Iterator实例

1. type testStructForIterator struct{
2.     Name string
3.     Id int
4. }
6. var dat testStructForIterator
7. iter := jsoniter.ParseString(jsoniter.ConfigDefault, `{"Name":"Allen","Id":100}`)
8. iter.ReadVal(&dat)
10. // xxxxxx
11. // ......
13. if iter.Error != nil{
14.     return
15. }
17. iter.ResetBytes([]byte(`{"Name":"Tom","Id":200}`))
18. iter.ReadVal(&dat)

复制代码

请注意，如果你的Iterator在反序列化过程中出现了错误，即Iterator.Error不为nil，那么你不能继续使用这个Iterator实例进行新的反序列化或解码，即使你调了Reset/ResetBytes进行重置也不行，只能重新另外创建一个新的Iterator来使用(至少目前的实现必须这样)
6、Stream

json-iterator中使用Stream来控制json的编码输出，通过其提供的API，配合自定义的Extension或ValEncoder，我们可以定制我们的数据如何编码输出成json，甚至可以从头构造并输出一个json串
6.1、创建Stream实例

有两种方法可以创建Stream实例：

• 从API对象的Stream实例池中Borrow一个
  1. c := jsoniter.ConfigDefault
  2. s := c.BorrowStream(os.Stdout)
  3. defer c.ReturnStream(s)
  5. // 你的功能实现
  6. // xxxxxx
  7. // ......

  复制代码
  使用这种方法"借用"的Stream实例，记得在使用完毕后"返还"回去
  
• 调用NewStream接口新建一个
  1. s := jsoniter.NewStream(jsoniter.ConfigDefault, os.Stdout, 1024)
  3. // 你的功能实现
  4. // xxxxxx
  5. // ......

  复制代码
  使用这种方法，需要传入你的序列化配置对应生成的API对象，底层输出的io.Writer和指定Stream的内部缓冲内部大小(见下文详述)
  

6.2、定制编码输出

在定义你的Extension或ValEncoder时，你需要用到Stream来定制你的字段如何输出成json

1. type sampleExtension struct {
2.     jsoniter.DummyExtension
3. }
5. type wrapEncoder struct {
6.     encodeFunc  func(ptr unsafe.Pointer, stream *jsoniter.Stream)
7.     isEmptyFunc func(ptr unsafe.Pointer) bool
8. }
10. func (enc *wrapEncoder) Encode(ptr unsafe.Pointer, stream *jsoniter.Stream) {
11.     enc.encodeFunc(ptr, stream)
12. }
14. func (enc *wrapEncoder) IsEmpty(ptr unsafe.Pointer) bool {
15.     if enc.isEmptyFunc == nil {
16.         return false
17.     }
19.     return enc.isEmptyFunc(ptr)
20. }
22. func (e *sampleExtension) CreateEncoder(typ reflect2.Type) jsoniter.ValEncoder {
23.     if typ.Kind() == reflect.Int {
24.         return &wrapEncoder{
25.             func(ptr unsafe.Pointer, stream *jsoniter.Stream) {
26.                 // 将Int类型的变量的值+1000后，再写入到输出的json
27.                 stream.WriteInt(*(*int)(ptr) + 1000)
28.             },
29.             nil,
30.         }
31.     }
33.     return nil
34. }
36. func streamTest(){
37.     jsoniter.RegisterExtension(&sampleExtension{})
38.     j, _ := jsoniter.MarshalToString(1000)
39.     fmt.Println(j)
40.     // 输出：2000
41. }

复制代码

在上面的例子中，我们注册了一个Extension，这个Extension的CreateEncoder函数中，我们调用了Stream的WriteInt接口，来将ptr指向的数值加1000后，再输出成json；在自定义ValEncoder中，我们同样使用Stream提供的函数来定制我们字段的输出

1. type testStructForStream struct{
2.     Field int
3. }
5. jsoniter.RegisterFieldEncoderFunc(reflect2.TypeOf(testStructForStream{}).String(), "Field",
6. func(ptr unsafe.Pointer, stream *jsoniter.Stream) {
7.     // 将Int类型的值转换成字符串类型的json输出
8.     stream.WriteString(strconv.Itoa(*(*int)(ptr)))
9. }, nil)
11. j, _ := jsoniter.MarshalToString(testStructForStream{1024})
12. fmt.Println(j)
13. // 输出：{"Field":"1024"}

复制代码

这个例子里面，我们针对testStructForStream的Field字段注册了一个ValEncoder，这个ValEncoder调用Stream的WriteString方法，将ptr指向的Int类型数值以字符串的方式写入到json串
Stream开放了各种类型数据的写入方法，可以让我们很方便地去定制自己的数据以何种方式输出成json：

• WriteBool
  
• WriteInt
  
• WriteFloat32
  
• WriteString
  
• WriteArrayStart、WriteArrayEnd
  
• WriteObjectStart、WriteObjectEnd
  
• WriteEmptyArray
  
• WriteEmptyObject
  
• ......
  

具体每个方法的说明可以参考godoc
6.3、手动构造json输出

使用Stream，可以完全手动地构造你的json如何输出成字节流

1. s := jsoniter.ConfigDefault.BorrowStream(nil)
2. // 记得把从Config中borrow过来的Stream实例Return回去
3. defer jsoniter.ConfigDefault.ReturnStream(s)
5. s.WriteObjectStart()
6. s.WriteObjectField("EmbedStruct")
7. s.WriteObjectStart()
8. s.WriteObjectField("Name")
9. s.WriteString("xxx")
10. s.WriteObjectEnd()
11. s.WriteMore()
12. s.WriteObjectField("Id")
13. s.WriteInt(100)
14. s.WriteObjectEnd()
16. fmt.Println(string(s.Buffer()))
17. // 输出：{"EmbedStruct":{"Name":"xxx"},"Id":100}

复制代码

不过一般情况下，我们不会也不需要这么做，更多的时候是创建自己的Extension或ValEncoder时调用Stream的这些方法来定制编码输出
6.4、另一种序列化接口

Stream也提供了一个接口，可以实现跟Encoder的Encode方法基本一样的序列化功能

1. type testStructForStream struct{
2.     Field int
3. }
5. s := jsoniter.NewStream(jsoniter.ConfigDefault, nil, 1024)
6. s.WriteVal(testStructForStream{300})
7. result := s.Buffer()
8. buf := make([]byte, len(result))
9. copy(buf, result)
10. fmt.Println(string(buf))
11. // 输出：{"Field":300}

复制代码

在上面这个例子里面，我们调用NewStream来创建了一个Stream实例，然后调用WriteVal方法来实现序列化，最后将结果字节序列拷贝出来。通过这种方式，也可以完成序列化。实际上，json-iterator内部也是使用类似的方式，调用Stream的WriteVal来完成序列化。这里有两点需要说明：

• 调用NewStream创建Stream实例，可以指定Stream内部缓冲的大小。如果你的使用场景对性能有极致要求，而且序列化输出的json序列长度可以准确估计的话，不妨使用这个方法来取代直接调用Marshal来进行序列化。通过指定内部缓冲的初始大小，避免后续在序列化过程中发生的扩容(Stream内部存储序列化结果的缓存大小由其指定)
  
• 上述例子中的拷贝操作是必须要进行的，不能直接调用Stream的Buffer方法后返回的切片直接使用。因为Stream会复用其内部已经分配的缓冲，每次序列化都会把之前的内容复写掉，因此在下一次调用同一个Stream实例进行序列化前，你必须把结果拷贝走
  

6.5、复用Stream实例

如果你需要复用同一个Stream实例，记得在每次序列化完成后，重置你的Stream

1. type testStructForStream struct{
2.     Field int
3. }
5. s := jsoniter.ConfigDefault.BorrowStream(os.Stdout)
6. defer jsoniter.ConfigDefault.ReturnStream(s)
7. s.WriteVal(testStructForStream{300})
8. result := s.Buffer()
9. tmp := make([]byte, len(result))
10. copy(tmp, result)
12. // xxxxxx
13. // ......
15. if s.Error != nil{
16.     return
17. }
19. // 记得重置你的Stream
20. s.Reset(nil)
21. s.WriteVal(testStructForStream{400})

复制代码

请注意，如果你的Stream在序列化过程中出现了错误，即Stream.Error不为nil，那么你不能继续使用这个Stream实例进行新的序列化或编码输出，即使你调了Reset进行重置也不行，只能重新另外创建一个新的Stream来使用(至少目前的实现必须这样)
6.6、Flush到输出设备

如果你在创建Stream时，指定了使用的io.Writer，并希望你序列化后的json写入到这里，而不是通过调用Buffer来获取结果的话，记得在序列化结束的时候调用Flush来将Stream中的缓冲刷到你的io.Writer中

1. type testStructForStream struct{
2.     Field int
3. }
5. s := jsoniter.NewStream(jsoniter.ConfigDefault, os.Stdout, 1024)
6. s.WriteVal(testStructForStream{300})
7. // 如果没有这个调用，你的序列化结果将不会输出到你指定的Writer
8. s.Flush()
9. // 输出：{"Field":300}

复制代码

参考教程：
Config_cn
https://zhuanlan.zhihu.com/p/105956945
https://juejin.cn/post/7027306493246439431

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！