gojmapr - Golang JSON路径提取库

gojmapr 是一个轻量级的 Golang 库，用于通过 JSON 路径从复杂的 JSON 结构中提取数据并转换为简单的结构体。它提供了一种简洁的方式来处理复杂的 JSON 数据，特别适合 API 响应处理和 JSON 数据转换场景。

主要特性

• 支持 JSON 路径表达式提取数据
• 自动类型转换
• 支持嵌套结构
• 轻量级且无外部依赖
• 易于使用的 API

安装

go get github.com/limiu82214/gojmapr

基本用法

1. 简单提取示例

package main

import (
	"encoding/json"
	"fmt"
	"github.com/limiu82214/gojmapr"
)

func main() {
	// 原始JSON数据
	jsonStr := `{
		"user": {
			"name": "John",
			"age": 30,
			"address": {
				"city": "New York",
				"zip": "10001"
			}
		}
	}`

	var data interface{}
	_ = json.Unmarshal([]byte(jsonStr), &data)

	// 定义目标结构
	type SimpleUser struct {
		Name string `jpath:"user.name"`
		Age  int    `jpath:"user.age"`
		City string `jpath:"user.address.city"`
	}

	var result SimpleUser
	err := gojmapr.Unmarshal(data, &result)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", result)
	// 输出: {Name:John Age:30 City:New York}
}

2. 处理数组

package main

import (
	"encoding/json"
	"fmt"
	"github.com/limiu82214/gojmapr"
)

func main() {
	jsonStr := `{
		"users": [
			{"id": 1, "name": "Alice"},
			{"id": 2, "name": "Bob"},
			{"id": 3, "name": "Charlie"}
		]
	}`

	var data interface{}
	_ = json.Unmarshal([]byte(jsonStr), &data)

	// 提取数组中的特定字段
	type User struct {
		ID   int    `jpath:"id"`
		Name string `jpath:"name"`
	}

	var users []User
	err := gojmapr.UnmarshalFromPath(data, "users", &users)
	if err != nil {
		panic(err)
	}

	for _, user := range users {
		fmt.Printf("%+v\n", user)
	}
	// 输出:
	// {ID:1 Name:Alice}
	// {ID:2 Name:Bob}
	// {ID:3 Name:Charlie}
}

3. 复杂嵌套结构处理

package main

import (
	"encoding/json"
	"fmt"
	"github.com/limiu82214/gojmapr"
)

func main() {
	jsonStr := `{
		"store": {
			"book": [
				{
					"category": "reference",
					"author": "Nigel Rees",
					"title": "Sayings of the Century",
					"price": 8.95
				},
				{
					"category": "fiction",
					"author": "Evelyn Waugh",
					"title": "Sword of Honour",
					"price": 12.99
				}
			],
			"bicycle": {
				"color": "red",
				"price": 19.95
			}
		}
	}`

	var data interface{}
	_ = json.Unmarshal([]byte(jsonStr), &data)

	// 定义目标结构
	type Book struct {
		Title    string  `jpath:"title"`
		Author   string  `jpath:"author"`
		Price    float64 `jpath:"price"`
		Category string  `jpath:"category"`
	}

	type StoreInfo struct {
		Books     []Book `jpath:"store.book"`
		BikeColor string `jpath:"store.bicycle.color"`
	}

	var result StoreInfo
	err := gojmapr.Unmarshal(data, &result)
	if err != nil {
		panic(err)
	}

	fmt.Printf("Bike color: %s\n", result.BikeColor)
	fmt.Println("Books:")
	for _, book := range result.Books {
		fmt.Printf("- %s by %s ($%.2f)\n", book.Title, book.Author, book.Price)
	}
}

高级特性

1. 默认值设置

type User struct {
	Name string `jpath:"user.name"`
	Age  int    `jpath:"user.age,default=18"`
}

// 如果user.age不存在，Age将被设置为18

2. 必填字段

type User struct {
	Name string `jpath:"user.name,required"`
}

// 如果user.name不存在，Unmarshal会返回错误

3. 自定义转换函数

type User struct {
	Name      string `jpath:"user.name"`
	BirthYear int    `jpath:"user.age"`
	// 假设我们需要从年龄计算出生年份
	CalculatedBirthYear int `jpath:"user.age,transform=calculateBirthYear"`
}

// 注册转换函数
func calculateBirthYear(age int) int {
	return time.Now().Year() - age
}

func main() {
	gojmapr.RegisterTransformFunc("calculateBirthYear", calculateBirthYear)
	// ... 其余代码
}

性能考虑

gojmapr 在性能上做了优化，适合处理大量 JSON 数据。对于特别大的 JSON 文档，建议：

1. 尽量只提取需要的字段
2. 避免不必要的嵌套结构
3. 对于重复操作，可以考虑缓存解析结果

与其他库的比较

相比于标准库的 encoding/json，gojmapr 提供了更灵活的字段映射能力。与更复杂的 JSON 处理库如 github.com/tidwall/gjson 相比，gojmapr 更专注于将 JSON 映射到结构体的场景，API 更加简洁。

总结

gojmapr 是一个简单实用的 Golang JSON 路径提取库，特别适合以下场景：

• 从复杂的 API 响应中提取特定字段
• 将嵌套的 JSON 结构扁平化为简单结构体
• 处理不一致的 JSON 数据结构

它的轻量级设计和易用性使其成为处理 JSON 数据的有力工具。