解析与验证函数

json 包提供的解析和验证函数，支持将 JSON 解析到目标对象、通过 Processor 实例解析，以及 JSON 有效性验证和 JSON Schema 验证。

解析函数

Parse

签名：func Parse(jsonStr string, target any, cfg ...Config) error

将 JSON 字符串解析到 target 指针所指向的对象中。target 必须是一个指针。

参数

名称	类型	必需	说明
jsonStr	string	是	JSON 字符串
target	any	是	目标对象指针
cfg	Config	否	可选配置

基本解析

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    var data map[string]any
    err := json.Parse(`{"name": "test"}`, &data)
    if err != nil {
        panic(err)
    }
    fmt.Println(data) // map[name:test]
}

解析到结构体

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    var person Person
    err := json.Parse(`{"name": "CyberGo", "age": 30}`, &person)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Name: %s, Age: %d\n", person.Name, person.Age)
}

使用自定义配置

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    cfg := json.DefaultConfig()
    var data map[string]any
    err := json.Parse(`{"name": "test"}`, &data, cfg)
    if err != nil {
        panic(err)
    }
    fmt.Println(data)
}

ParseAny

签名：func ParseAny(jsonStr string, cfg ...Config) (any, error)

将 JSON 字符串解析并返回根值为 any 类型，无需预先声明目标变量。

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    result, err := json.ParseAny(`{"name": "test"}`)
    if err != nil {
        panic(err)
    }
    fmt.Println(result) // map[name:test]
}

Parse vs ParseAny

• Parse(jsonStr, &target) — 解析到目标指针，需要预先声明变量
• ParseAny(jsonStr) — 直接返回 any 类型，无需预先声明

Processor.Parse

签名：func (p *Processor) Parse(jsonStr string, target any, cfg ...Config) error

通过 Processor 实例解析 JSON 到目标指针。

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

var data map[string]any
err = p.Parse(`{"name": "test"}`, &data)
if err != nil {
    panic(err)
}

Processor.ParseAny

签名：func (p *Processor) ParseAny(jsonStr string, cfg ...Config) (any, error)

通过 Processor 实例解析 JSON 并返回 any 类型，行为与包级 ParseAny 相同。

p, err := json.New()
if err != nil {
    panic(err)
}
defer p.Close()

data, err := p.ParseAny(`{"name": "test"}`)

详见 Processor 解析方法。

验证函数

Valid

签名：func Valid(data []byte, cfg ...Config) bool

验证 JSON 字节切片是否有效。100% 兼容 encoding/json.Valid：无 cfg 调用 json.Valid(data) 与标准库完全一致，返回普通 bool。

通过可选的尾随 Config 可应用安全限制（大小、嵌套深度、完整安全扫描等）。传入 cfg 时，Valid 委托给 Processor.Valid 并将任何错误折叠为 false。

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    data := []byte(`{"name": "test"}`)
    // 兼容 encoding/json（无 cfg）
    if json.Valid(data) {
        fmt.Println("有效 JSON")
    }

    // 带配置（非破坏性可选参数）
    if json.Valid(data, json.SecurityConfig()) {
        fmt.Println("通过安全验证")
    }
}

Valid vs ValidWithConfig

• Valid(data, cfg) 返回单个 bool（兼容 encoding/json），任何错误折叠为 false
• ValidWithConfig(jsonStr, cfg) 返回 (bool, error)，便于检查验证失败原因

两者都接受 cfg；命名差异是历史遗留。

ValidWithConfig

签名：func ValidWithConfig(jsonStr string, cfg ...Config) (bool, error)

使用配置验证 JSON 字符串是否有效，并返回可能的错误信息。

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    cfg := json.DefaultConfig()
    valid, err := json.ValidWithConfig(`{"name": "test"}`, cfg)
    if err != nil {
        panic(err)
    }
    if valid {
        fmt.Println("有效 JSON")
    }
}

ValidateSchema

签名：func ValidateSchema(jsonStr string, schema *Schema, cfg ...Config) ([]ValidationError, error)

使用 JSON Schema 验证 JSON 数据。返回所有验证错误的列表。

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    schema := &json.Schema{
        Type:     "object",
        Required: []string{"name", "email"},
        Properties: map[string]*json.Schema{
            "name":  {Type: "string", MinLength: 1},
            "email": {Type: "string", Format: "email"},
            "age":   {Type: "integer", Minimum: 0},
        },
    }

    errors, err := json.ValidateSchema(`{"name":"Alice","email":"[email protected]","age":25}`, schema)
    if err != nil {
        panic(err)
    }
    for _, e := range errors {
        fmt.Printf("路径 %s: %s\n", e.Path, e.Message)
    }
}

详见

完整的 Schema 类型定义和验证器用法请参考 验证器。

相关

• 查询获取函数 - Get, GetString 等查询操作
• Processor 解析方法 - Processor 级解析与验证方法详解