jscan - Go高性能零内存分配JSON迭代器库

jscan是一个高性能的零内存分配JSON解析器，特别适合需要高效处理大量JSON数据的场景。下面我将详细介绍它的使用方法和示例代码。

主要特性

• 零内存分配：解析过程中不分配内存，极大提高性能
• 流式处理：可以逐元素处理JSON，无需加载整个文档到内存
• 高性能：比标准库encoding/json快3-10倍
• 简单API：提供直观的迭代器接口

安装

go get github.com/romshark/jscan

基本使用示例

1. 简单解析

package main

import (
	"fmt"
	"github.com/romshark/jscan"
)

func main() {
	const json = `{"name":"John","age":30,"city":"New York"}`

	// 创建解析器
	p := jscan.NewParser[[]byte](64) // 64是初始token缓存大小

	// 解析JSON
	if err := p.Scan(
		json,
		func(i *jscan.Iterator[[]byte]) (err error) {
			switch i.Key() {
			case "name":
				fmt.Printf("Name: %s\n", i.Value())
			case "age":
				fmt.Printf("Age: %s\n", i.Value())
			case "city":
				fmt.Printf("City: %s\n", i.Value())
			}
			return nil
		},
	); err != nil {
		panic(err)
	}
}

2. 处理数组

package main

import (
	"fmt"
	"github.com/romshark/jscan"
)

func main() {
	const json = `[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]`

	p := jscan.NewParser[[]byte](64)

	if err := p.Scan(
		json,
		func(i *jscan.Iterator[[]byte]) (err error) {
			if i.Level() == 1 && i.TokenType() == jscan.TokenTypeObject {
				fmt.Println("Found object in array:")
				return nil
			}
			switch i.Key() {
			case "id":
				fmt.Printf("  ID: %s\n", i.Value())
			case "name":
				fmt.Printf("  Name: %s\n", i.Value())
			}
			return nil
		},
	); err != nil {
		panic(err)
	}
}

3. 高级用法 - 选择性解析

package main

import (
	"fmt"
	"github.com/romshark/jscan"
)

func main() {
	const json = `{
		"users": [
			{"id":1,"name":"Alice","details":{"age":25,"email":"alice@example.com"}},
			{"id":2,"name":"Bob","details":{"age":30,"email":"bob@example.com"}}
		],
		"metadata": {"count":2, "timestamp":1234567890}
	}`

	p := jscan.NewParser[[]byte](128)

	if err := p.Scan(
		json,
		func(i *jscan.Iterator[[]byte]) (err error) {
			// 只处理users数组中的name字段
			if i.Level() == 3 && i.Parent().Key() == "users" && i.Key() == "name" {
				fmt.Printf("User name: %s\n", i.Value())
				// 跳过当前对象的后续处理
				return jscan.Skip
			}
			return nil
		},
	); err != nil {
		panic(err)
	}
}

4. 性能优化技巧

package main

import (
	"fmt"
	"github.com/romshark/jscan"
)

func main() {
	const json = `{"a":1,"b":2,"c":3}`

	// 重用解析器实例可以减少内存分配
	p := jscan.NewParser[[]byte](64)
	
	// 预分配回调函数
	callback := func(i *jscan.Iterator[[]byte]) error {
		fmt.Printf("%s: %s\n", i.Key(), i.Value())
		return nil
	}

	// 多次解析
	for i := 0; i < 1000; i++ {
		if err := p.Scan(json, callback); err != nil {
			panic(err)
		}
	}
}

性能对比

jscan相比标准库encoding/json有以下优势：

1. 零内存分配：解析过程中不创建临时对象
2. 流式处理：可以边解析边处理，不需要完整加载JSON
3. 选择性解析：可以只处理感兴趣的字段

注意事项

1. jscan是迭代器模式，不适合需要随机访问JSON结构的场景
2. 回调函数中不要保留对迭代器或值的引用，因为它们会被重用
3. 对于非常复杂的JSON处理，可能需要结合其他库使用

结论

jscan是处理大型JSON数据或高性能场景下的优秀选择。它的零内存分配特性和流式处理能力使其在性能敏感的应用中表现出色。对于简单的用例，标准库可能更合适，但在需要极致性能时，jscan是一个强大的工具。