Kazaam - Golang JSON文档转换插件库

Kazaam是一个强大的Golang库，专门用于JSON文档的转换和操作。它允许你通过简单的配置来转换JSON结构，非常适合数据格式转换、API响应处理等场景。

安装Kazaam

go get github.com/qntfy/kazaam

基本使用

1. 简单字段转换

package main

import (
	"fmt"
	"log"

	"github.com/qntfy/kazaam"
)

func main() {
	// 原始JSON
	inputJSON := `{"user": {"name": "Alice", "age": 30}}`

	// 转换规则：将user.name提取到顶层username字段
	spec := `[{"operation": "shift", "spec": {"username": "user.name"}}]`

	// 创建Kazaam转换器
	k, err := kazaam.NewKazaam(spec)
	if err != nil {
		log.Fatal("Error creating Kazaam instance:", err)
	}

	// 执行转换
	outputJSON, err := k.TransformJSONStringToString(inputJSON)
	if err != nil {
		log.Fatal("Error transforming JSON:", err)
	}

	fmt.Println("Output JSON:", outputJSON)
	// 输出: {"username":"Alice"}
}

2. 复杂转换示例

package main

import (
	"fmt"
	"log"

	"github.com/qntfy/kazaam"
)

func main() {
	input := `{
		"user": {
			"id": 123,
			"name": "Bob",
			"contact": {
				"email": "bob@example.com",
				"phone": "123-456-7890"
			},
			"orders": [
				{"id": 1, "amount": 100},
				{"id": 2, "amount": 200}
			]
		}
	}`

	spec := `[
		{
			"operation": "shift",
			"spec": {
				"userId": "user.id",
				"userName": "user.name",
				"email": "user.contact.email",
				"phoneNumber": "user.contact.phone",
				"orderCount": {
					"operation": "size",
					"spec": "user.orders"
				},
				"totalSpent": {
					"operation": "sum",
					"spec": "user.orders[*].amount"
				}
			}
		}
	]`

	k, err := kazaam.NewKazaam(spec)
	if err != nil {
		log.Fatal(err)
	}

	output, err := k.TransformJSONStringToString(input)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(output)
	/* 输出:
	{
		"userId": 123,
		"userName": "Bob",
		"email": "bob@example.com",
		"phoneNumber": "123-456-7890",
		"orderCount": 2,
		"totalSpent": 300
	}
	*/
}

主要功能特性

1. 字段重命名和移动：使用shift操作可以轻松移动和重命名字段
2. 数组操作：支持对数组进行过滤、映射等操作
3. 计算操作：支持sum、count、size等聚合计算
4. 条件转换：可以根据条件执行不同的转换规则
5. 多步转换：支持定义多个转换步骤按顺序执行

高级用法示例

条件转换

package main

import (
	"fmt"
	"log"

	"github.com/qntfy/kazaam"
)

func main() {
	input := `{
		"user": {
			"name": "Charlie",
			"status": "premium"
		}
	}`

	spec := `[
		{
			"operation": "default",
			"spec": {
				"user.discount": "0%"
			}
		},
		{
			"operation": "shift",
			"spec": {
				"name": "user.name",
				"discount": {
					"operation": "conditional",
					"spec": {
						"condition": {
							"operation": "equal",
							"spec": {
								"left": "user.status",
								"right": "premium"
							}
						},
						"true": "20%",
						"false": "user.discount"
					}
				}
			}
		}
	]`

	k, err := kazaam.NewKazaam(spec)
	if err != nil {
		log.Fatal(err)
	}

	output, err := k.TransformJSONStringToString(input)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(output)
	// 输出: {"name":"Charlie","discount":"20%"}
}

数组操作

package main

import (
	"fmt"
	"log"

	"github.com/qntfy/kazaam"
)

func main() {
	input := `{
		"products": [
			{"id": 1, "name": "Laptop", "price": 999.99, "inStock": true},
			{"id": 2, "name": "Mouse", "price": 19.99, "inStock": false},
			{"id": 3, "name": "Keyboard", "price": 49.99, "inStock": true}
		]
	}`

	spec := `[
		{
			"operation": "shift",
			"spec": {
				"availableProducts": {
					"operation": "filter",
					"spec": {
						"input": "products",
						"condition": {
							"operation": "equal",
							"spec": {
								"left": "@inStock",
								"right": true
							}
						}
					}
				},
				"totalAvailable": {
					"operation": "size",
					"spec": {
						"operation": "filter",
						"spec": {
							"input": "products",
							"condition": {
								"operation": "equal",
								"spec": {
									"left": "@inStock",
									"right": true
								}
							}
						}
					}
				}
			}
		}
	]`

	k, err := kazaam.NewKazaam(spec)
	if err != nil {
		log.Fatal(err)
	}

	output, err := k.TransformJSONStringToString(input)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(output)
	/* 输出:
	{
		"availableProducts": [
			{"id": 1, "name": "Laptop", "price": 999.99, "inStock": true},
			{"id": 3, "name": "Keyboard", "price": 49.99, "inStock": true}
		],
		"totalAvailable": 2
	}
	*/
}

性能考虑

Kazaam在性能方面表现良好，但在处理大型JSON文档或复杂转换规则时，仍需注意：

1. 尽量合并多个转换步骤
2. 避免不必要的深层嵌套
3. 对于超大型文档，考虑流式处理

总结

Kazaam为Golang开发者提供了一个强大而灵活的JSON转换工具，通过简单的配置即可实现复杂的JSON结构转换。它的主要优势在于：

• 声明式的转换规则
• 丰富的内置操作
• 良好的性能
• 易于集成到现有项目中

对于需要处理不同JSON格式的微服务、API网关等场景，Kazaam是一个非常值得考虑的选择。