解析与验证函数
json 包提供的解析和验证函数，支持将 JSON 解析到目标对象、通过 Processor 实例解析，以及 JSON 有效性验证和 JSON Schema 验证。
解析函数
Parse
签名：func Parse(jsonStr string, target any, cfg ...Config) error
将 JSON 字符串解析到 target 指针所指向的对象中。target 必须是一个非 nil 指针（传 nil 或非指针会返回参数错误）。与 Get 一致，Parse 在解析前对输入执行安全校验（大小、嵌套深度、危险模式，受 cfg 与处理器配置约束）。
参数
| 名称 | 类型 | 必需 | 说明 |
|---|---|---|---|
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），任何错误折叠为falseValidWithConfig(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"},
"email": {Type: "string", Format: "email"},
"age": {Type: "number"}, // 数值可用 "number" 或 "integer"
},
}
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 类型定义和验证器用法请参考 Schema 校验。
相关
- 查询获取函数 - Get, GetString 等查询操作
- Processor 解析方法 - Processor 级解析与验证方法详解