README
¶
GCJSON - High-Performance JSON Processing Library
GCJSON 是一个高性能的 Go JSON 处理库，专为大规模、高频次的 JSON 数据处理场景设计。
特性
- 🚀 极高性能: 零拷贝、内联优化、热点路径缓存
- 🎯 智能优化: 简单路径快速处理，复杂路径回退到 gjson
- 🔧 灵活易用: 支持泛型、自动类型推断、数据下钻
- 🛡️ 类型安全: 完整的类型检查和错误处理
- 📦 模块化设计: 清晰的包结构，便于维护和扩展
快速开始
package main
import (
"fmt"
"gcjson"
)
func main() {
data := `{
"data": {
"user": {
"name": "Alice",
"age": 30,
"scores": [95, 87, 92]
}
}
}`
// 基础用法
name := gcjson.Any(data, "data.user.name")
fmt.Println("Name:", name) // Name: Alice
// 泛型用法
age, ok := gcjson.AnyAs[int64](data, "data.user.age")
if ok {
fmt.Println("Age:", age) // Age: 30
}
// 数组处理
gcjson.EachArray(data, "data.user.scores", func(i int, r gjson.Result) bool {
fmt.Printf("Score %d: %v\n", i, r.Int())
return true
})
}
API 分类
基础查询 API
GetAny(v, path)- 获取任意路径的 gjson.ResultGetData(v, path)- 自动下钻到 data 字段后查询Any(v, path)- 自动类型推断，返回原生 Go 类型
泛型 API
AnyAs[T](v, path)- 泛型类型断言AnyAsFast[T](v, path)- 零分配泛型快路径AnyOr(v, path, def)- 带默认值的查询
迭代器 API
EachObject(v, path, fn)- 遍历对象EachArray(v, path, fn)- 遍历数组ForEachArrayResult(v, path, fn)- Result 版本数组迭代
原始数据 API
Raw(v, path)- 获取原始 JSON 字符串RawBytes(v, path)- 零拷贝获取原始字节RawMany(v, paths...)- 批量获取多个路径
性能优化
热点路径缓存
自动缓存常用的 JSON 路径，提升重复查询性能。
简单路径快速处理
对于简单的顶层键（如 user, data），使用 O(n) 扫描而非完整解析。
零拷贝操作
尽可能使用 unsafe 指针操作，避免不必要的内存分配。
泛型快路径
针对常见类型（string, int64, float64, bool）提供零分配路径。
模块架构
gcjson/
├── cache/ # 热点路径缓存
├── convert/ # 类型转换和序列化
├── fast/ # 快速路径优化
├── iterator/ # 迭代器功能
├── parser/ # 数字解析和类型推断
├── picker/ # 数据提取和下钻
└── raw/ # 原始数据处理
基准测试
go test -bench=. -benchmem
典型性能表现：
- 简单路径查询: ~10ns/op, 0 allocs/op
- 复杂路径查询: ~50ns/op, 1 allocs/op
- 泛型快路径: ~15ns/op, 0 allocs/op
Documentation
¶
Overview ¶
Package gcjson 提供基于 gjson 的高性能 JSON 查询能力。
特点：
- 零反序列化：无需 json.Unmarshal，直接路径访问 JSON 数据。
- 零或极少分配：多数查询仅需 0~2 次内存分配。
- 泛型直达：支持 Go 泛型 API，直接返回指定类型。
- 支持数组、对象遍历，以及路径下钻（drill）。
输入类型：
- 仅接受 []byte 或 string 类型作为输入。
内部依赖：
- 使用 gjson 进行路径解析与取值。
示例 ¶
基础用法：
jsonData := []byte(`{"name":"Alice","age":30}`)
name := gcjson.Any(jsonData, "name") // 动态类型
age, _ := gcjson.AnyAs[int64](jsonData, "age") // 泛型类型安全
泛型快速访问（零分配版本）：
name, _ := gcjson.AnyAsFast[string](jsonData, "name")
自动下钻：
sample := []byte(`{"data":{"id":123}}`)
gcjson.SetDefaultDrillKeys("data")
id := gcjson.AnyData(sample, "id") // 等价于 gcjson.Any(sample, "data.id")
数组遍历：
gcjson.EachArray(jsonData, "tags", func(i int, r gjson.Result) bool {
fmt.Println(i, r.String())
return true
})
Index ¶
- func Any(v any, path string) any
- func AnyAs[T any](v any, path string) (T, bool)
- func AnyAsFast[T any](v any, path string) (T, bool)
- func AnyData(v any, path string) any
- func AnyDataAs[T any](v any, path string) (T, bool)
- func AnyDataAsFast[T any](v any, path string) (T, bool)
- func AnyDataWithKeys(v any, keys []string, path string) any
- func AnyMany(v any, paths ...string) ([]any, error)
- func AnyOr(v any, path string, def any) any
- func AnyOrAs[T any](v any, path string, def T) T
- func AnyOrAsFast[T any](v any, path string, def T) T
- func ArrayAny(v any, path string) []any
- func EachArray(v any, path string, fn func(i int, r gjson.Result) bool) bool
- func EachArrayZero(v any, path string, fn func(i int, r gjson.Result) bool) bool
- func EachObject(v any, path string, fn func(k string, r gjson.Result) bool) bool
- func EachObjectBytes(v any, path string, fn func(keyBytes []byte, val gjson.Result) bool) bool
- func ForEachArrayResult(v any, path string, fn func(idx int, r gjson.Result) bool) bool
- func ForEachDataArrayResult(v any, path string, fn func(idx int, r gjson.Result) bool) bool
- func ForEachObjectResult(v any, path string, fn func(key string, r gjson.Result) bool) bool
- func GetAny(v any, path string) (gjson.Result, error)
- func GetData(v any, path string) (gjson.Result, error)
- func GetDataWithKeys(v any, keys []string, path string) (gjson.Result, error)
- func MapAny(v any, path string) map[string]any
- func Raw(v any, path string) (string, bool)
- func RawBytes(v any, path string) ([]byte, bool)
- func RawMany(v any, paths ...string) ([]string, error)
- func RawManyBytes(v any, paths ...string) ([][]byte, error)
- func SetDefaultDrillKeys(keys ...string)
- func TypeOfAny(v any, path string) string
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AnyOrAsFast ¶
func EachArrayZero ¶
func EachObject ¶
EachObject 迭代器 API
func EachObjectBytes ¶
func ForEachArrayResult ¶
func ForEachDataArrayResult ¶
func ForEachObjectResult ¶
func GetDataWithKeys ¶
Types ¶
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.