类型定义

json 包提供多种类型安全的类型，用于处理 JSON 操作结果。

Result[T] - 统一结果类型

Result[T] 是泛型操作结果类型，提供类型安全的错误处理和值访问。

结构定义

type Result[T any] struct {
    Value  T     // 结果值
    Exists bool  // 值是否被找到
    Error  error // 错误（如有）
}

字段说明

字段	类型	说明
`Value`	`T`	结果值，类型由泛型参数 `T` 决定
`Exists`	`bool`	路径是否存在（是否找到值）
`Error`	`error`	操作错误（无错为 `nil`）

方法

方法	签名	说明
`Ok()`	`func (r Result[T]) Ok() bool`	检查结果是否有效（无错误且已找到）
`Unwrap()`	`func (r Result[T]) Unwrap() T`	返回值，失败时返回零值
`UnwrapOr()`	`func (r Result[T]) UnwrapOr(defaultValue T) T`	返回值或默认值

使用示例

package main

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

func main() {
	data := `{"user": {"name": "Alice", "age": 30}}`

	// 使用 GetTyped 获取类型化值
	name := json.GetTyped[string](data, "user.name")
	fmt.Printf("姓名: %s\n", name)

	// 使用 defaultValue 参数提供默认值
	nickname := json.GetTyped[string](data, "user.nickname", "未设置")
	fmt.Printf("昵称: %s\n", nickname)

	age := json.GetTyped[int](data, "user.age", 0)
	fmt.Printf("年龄：%d\n", age)
}

命名约定

GetTyped[T] - 获取指定类型的值，返回 T，支持 defaultValue 参数
Result[T] - 内部结果类型，用于需要精细错误处理的场景

CompiledPath - 预编译路径

CompiledPath 是预编译的 JSON 路径类型别名，用于在频繁访问同一路径时避免重复解析路径字符串，提升性能。

类型定义

type CompiledPath = internal.CompiledPath

使用场景

当需要对同一个路径进行大量重复操作时（如循环中批量查询），可以预先编译路径，避免每次调用时重复解析路径字符串。

编译函数

Processor.CompilePath

签名：func (p *Processor) CompilePath(path string) (*CompiledPath, error)

通过 Processor 预编译 JSON 路径，返回可在后续操作中复用的 *CompiledPath 实例。

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

compiled, err := processor.CompilePath("user.profile.name")
if err != nil {
    panic(err)
}
// 可在后续操作中重复使用 compiled
val, err := processor.GetCompiled(jsonStr, compiled)

性能提示

对于高频重复路径访问，预编译路径可显著减少路径解析开销。适用于批量操作、循环查询等场景。

方法

方法	签名	说明
`Get`	`func (cp *CompiledPath) Get(data any) (any, error)`	从已解析的 JSON 数据中按编译路径取值
`Exists`	`func (cp *CompiledPath) Exists(data any) bool`	检查已解析数据中该路径是否存在值
`Len`	`func (cp *CompiledPath) Len() int`	返回路径的段数
`IsEmpty`	`func (cp *CompiledPath) IsEmpty() bool`	路径没有任何段时返回 true
`Path`	`func (cp *CompiledPath) Path() string`	返回编译时的原始路径字符串
`String`	`func (cp *CompiledPath) String() string`	与 `Path` 等价的字符串表示
`Segments`	`func (cp *CompiledPath) Segments() []PathSegment`	返回解析后的路径段（详见下文 PathSegment 一节）
`Release`	`func (cp *CompiledPath) Release()`	归还对象池；调用后不得再使用该实例

编译时还会预计算路径哈希（FNV-1a）——它只是内部缓存键，没有公开访问器。

使用示例

package main

import (
	"fmt"

	"github.com/cybergodev/json"
)

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

	cp, err := p.CompilePath("user.name")
	if err != nil {
		panic(err)
	}
	defer cp.Release()

	// GetCompiled 接收原始 JSON 字符串，无需先解析成 Go 值
	val, err := p.GetCompiled(`{"user": {"name": "CyberGo"}}`, cp)
	if err != nil {
		panic(err)
	}
	fmt.Println(val) // 输出：CyberGo
}

GetCompiled 与 PreParse 的取舍

GetCompiled 每次调用都会完整解析输入字符串，适合一次性查询；对同一文档做多次查询时，请改用 PreParse 获得 ParsedJSON 后调用 GetFromParsed，或先 Parse 再用 cp.Get(data)，避免重复解析。

PathSegment - 路径段

PathSegment 表示解析后的单个路径段，是 PathParser 接口 ParsePath 方法的返回元素，也可通过 CompiledPath 的 Segments 方法获得。

类型定义

type PathSegment = internal.PathSegment

内部实现别名

与 CompiledPath 一样，PathSegment 是 internal.PathSegment 的类型别名：字段类型 PathSegmentType、PathSegmentFlags 及段类型常量（PropertySegment 等）未从根包导出。判断段类型请使用 TypeString、IsArrayAccess 等访问方法，不要直接比较 Type 字段与内部常量。

字段说明

字段	类型	说明
`Type`	PathSegmentType	段类型枚举（属性/数组索引/切片/通配符等；判断请用 `TypeString`）
`Key`	`string`	属性段与提取段使用的键名
`Index`	`int`	数组索引段的下标；切片段的起始值（是否设置见 `HasStart`）
`End`	`int`	切片段的结束值（是否设置见 `HasEnd`）
`Step`	`int`	切片段的步长（是否设置见 `HasStep`）
`Flags`	PathSegmentFlags	位标志，记录负索引、通配符、扁平提取及起始/结束/步长是否设置

方法

方法	签名	说明
`TypeString`	`func (ps PathSegment) TypeString() string`	段类型名称：`property` / `array` / `slice` / `wildcard` / `recursive` / `filter` / `extract` / `append`
`String`	`func (ps PathSegment) String() string`	段的路径表示（如 `name`、`[0]`、`[1:3]`、`[*]`）
`IsArrayAccess`	`func (ps PathSegment) IsArrayAccess() bool`	数组索引段、切片段或通配符段返回 true
`IsWildcardSegment`	`func (ps *PathSegment) IsWildcardSegment() bool`	通配符段（`[*]`）返回 true
`IsFlatExtract`	`func (ps *PathSegment) IsFlatExtract() bool`	扁平提取段返回 true
`IsNegativeIndex`	`func (ps *PathSegment) IsNegativeIndex() bool`	数组索引为负数（如 `[-1]`）返回 true
`HasStart`	`func (ps *PathSegment) HasStart() bool`	切片段是否设置了起始值
`HasEnd`	`func (ps *PathSegment) HasEnd() bool`	切片段是否设置了结束值
`HasStep`	`func (ps *PathSegment) HasStep() bool`	切片段是否设置了步长
`GetStart`	`func (ps *PathSegment) GetStart() (int, bool)`	返回起始值及是否设置（未设置时为 0, false）
`GetEnd`	`func (ps *PathSegment) GetEnd() (int, bool)`	返回结束值及是否设置
`GetStep`	`func (ps *PathSegment) GetStep() (int, bool)`	返回步长及是否设置
`GetArrayIndex`	`func (ps PathSegment) GetArrayIndex(arrayLength int) (int, error)`	解析数组下标：负索引换算为正向（`-1` 表示末元素），越界或非数组索引段返回 error

使用示例

package main

import (
	"fmt"

	"github.com/cybergodev/json"
)

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

	cp, err := p.CompilePath("users[0].name")
	if err != nil {
		panic(err)
	}
	defer cp.Release()

	// Segments 返回解析后的路径段
	for _, seg := range cp.Segments() {
		fmt.Printf("段 %s（%s）\n", seg.String(), seg.TypeString())
	}

	// 数组索引段：GetArrayIndex 解析实际下标（负索引换算为正向，越界返回 error）
	arrSeg := cp.Segments()[1]
	idx, err := arrSeg.GetArrayIndex(1)
	if err != nil {
		panic(err)
	}
	fmt.Println("数组下标：", idx)
	// 输出：
	// 段 users（property）
	// 段 [0]（array）
	// 段 name（property）
	// 数组下标：0
}

AccessResult - 属性访问结果

AccessResult 是安全属性访问结果，提供链式类型转换。

结构定义

type AccessResult struct {
    Value  any    // 结果值
    Exists bool   // 路径是否存在
    Type   string // 运行时类型信息（用于调试）
}

字段说明

字段	类型	说明
`Value`	`any`	结果值
`Exists`	`bool`	路径是否存在
`Type`	`string`	运行时类型信息（用于调试）

创建方法

Processor.SafeGet

签名：func (p *Processor) SafeGet(jsonStr, path string, cfg ...Config) AccessResult

安全获取属性，返回 AccessResult 用于链式类型转换。

也可以使用包级函数 SafeGet：

签名：func SafeGet(jsonStr, path string, cfg ...Config) AccessResult

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

result := processor.SafeGet(data, "user.age")

if !result.Exists {
    fmt.Println("路径不存在")
    return
}

// 检查类型
fmt.Println("类型：", result.Type)

链式类型转换方法

方法	返回类型	说明
`Unwrap()`	`any`	返回值，不存在时返回 nil
`UnwrapOr(defaultValue)`	`any`	返回值或默认值
`AsString()`	`(string, error)`	转换为字符串（严格类型检查）
`AsStringConverted()`	`(string, error)`	格式化转换为字符串
`AsInt()`	`(int, error)`	转换为整数（bool 不转换）
`AsFloat64()`	`(float64, error)`	转换为 float64（bool 不转换）
`AsBool()`	`(bool, error)`	转换为布尔值
`Ok()`	`bool`	检查路径是否存在

注意

AsInt64(), AsArray(), AsObject() 方法已移除。请使用 GetTyped[T] 获取这些类型。

result := processor.SafeGet(data, "user.profile")

// 链式调用
name, _ := result.AsString()
email, _ := result.AsString()
age, _ := result.AsInt()
price, _ := result.AsFloat64()
active, _ := result.AsBool()

// 需要数组或对象类型时使用 GetTyped
arr := json.GetTyped[[]any](data, "items")
obj := json.GetTyped[map[string]any](data, "user.profile")

使用示例

package main

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

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

	data := `{"user": {"name": "Alice", "age": 30, "active": true}}`

	// 安全获取并转换
	result := processor.SafeGet(data, "user.age")

	// 直接使用 AccessResult 方法
	age, err := result.AsInt()
	if err != nil {
		panic(err)
	}
	fmt.Printf("年龄：%d\n", age)

	// 获取不存在的路径
	missing := processor.SafeGet(data, "user.nickname")
	if !missing.Exists {
		fmt.Println("昵称不存在")
	}
}

Schema - JSON Schema 类型

Schema 用于定义 JSON 数据的结构验证规则，支持 JSON Schema Draft 7 的子集。

结构定义

type Schema struct {
    Type                 string            `json:"type,omitempty"`
    Properties           map[string]*Schema `json:"properties,omitempty"`
    Items                *Schema           `json:"items,omitempty"`
    Required             []string          `json:"required,omitempty"`
    MinLength            int               `json:"minLength,omitempty"`
    MaxLength            int               `json:"maxLength,omitempty"`
    Minimum              float64           `json:"minimum,omitempty"`
    Maximum              float64           `json:"maximum,omitempty"`
    Pattern              string            `json:"pattern,omitempty"`
    Format               string            `json:"format,omitempty"`
    AdditionalProperties bool              `json:"additionalProperties,omitempty"`
    MinItems             int               `json:"minItems,omitempty"`
    MaxItems             int               `json:"maxItems,omitempty"`
    UniqueItems          bool              `json:"uniqueItems,omitempty"`
    Enum                 []any             `json:"enum,omitempty"`
    Const                any               `json:"const,omitempty"`
    MultipleOf           float64           `json:"multipleOf,omitempty"`
    ExclusiveMinimum     bool              `json:"exclusiveMinimum,omitempty"`
    ExclusiveMaximum     bool              `json:"exclusiveMaximum,omitempty"`
    Title                string            `json:"title,omitempty"`
    Description          string            `json:"description,omitempty"`
    Default              any               `json:"default,omitempty"`
    Examples             []any             `json:"examples,omitempty"`
}

创建 Schema

直接构造

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"},
    },
}

两条硬性限制

Type 支持 object/array/string/number/integer/boolean/null 七种取值；integer 按 JSON Schema 语义接受数学上为整数的值（1、1.0 均通过，1.5 报 expected type integer 错误），详见 Schema 校验。
MinLength/MaxLength/Minimum/Maximum/MinItems/MaxItems/ExclusiveMinimum/ExclusiveMaximum 通过结构体字面量赋值不会生效，必须经 NewSchema（弃用别名 NewSchemaWithConfig）的指针字段启用。详见 Schema 校验。

使用 NewSchema

签名：func NewSchema(cfg SchemaConfig) *Schema——创建已配置 Schema 的规范构造函数，长度/区间类指针约束经此启用。

cfg := json.DefaultSchemaConfig()
cfg.Type = "object"
cfg.Required = []string{"name", "email"}
schema := json.NewSchema(cfg)

旧名 NewSchemaWithConfig(cfg) 与 NewSchema 完全等价，已废弃（v1 生命周期内保留）；新代码请使用 NewSchema(cfg)。

使用 DefaultSchema

签名：func DefaultSchema() *Schema

返回包含默认配置的空 Schema 实例。

schema := json.DefaultSchema()
schema.Type = "object"
schema.Required = []string{"id"}

SchemaConfig 结构

type SchemaConfig struct {
    Type                 string
    Properties           map[string]*Schema
    Items                *Schema
    Required             []string
    MinLength            *int
    MaxLength            *int
    Minimum              *float64
    Maximum              *float64
    Pattern              string
    Format               string
    AdditionalProperties *bool
    MinItems             *int
    MaxItems             *int
    UniqueItems          bool
    Enum                 []any
    Const                any
    MultipleOf           *float64
    ExclusiveMinimum     *bool
    ExclusiveMaximum     *bool
    Title                string
    Description          string
    Default              any
    Examples             []any
}

字段类别	字段	类型	说明
直接字段	`Type`/`Pattern`/`Format`/`UniqueItems`/`Enum`/`Const`/`Title`/`Description`/`Default`/`Examples`	值类型	直接赋值即生效
结构字段	`Properties`/`Items`/`Required`	值类型	子 Schema、必填属性
指针字段	`MinLength`/`MaxLength`/`Minimum`/`Maximum`/`MinItems`/`MaxItems`/`MultipleOf`/`ExclusiveMinimum`/`ExclusiveMaximum`	`int`/`float64`/`*bool`	非 nil 才启用对应约束（传指针是为了区分「未设置」与「零值」）
指针字段	`AdditionalProperties`	`*bool`	非 nil 生效；nil 时默认 `true`

DefaultSchemaConfig

签名：func DefaultSchemaConfig() SchemaConfig

返回带默认值的 SchemaConfig（AdditionalProperties 指向 true，其余为零值）。

cfg := json.DefaultSchemaConfig()
cfg.Type = "object"
cfg.Required = []string{"name", "email"}
schema := json.NewSchema(cfg)

使用示例

package main

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

func main() {
	// 长度/区间约束经 NewSchema 的指针字段启用
	minLen, maxLen := 1, 100
	minAge, maxAge := 0.0, 150.0

	nameCfg := json.DefaultSchemaConfig()
	nameCfg.Type = "string"
	nameCfg.MinLength = &minLen
	nameCfg.MaxLength = &maxLen

	ageCfg := json.DefaultSchemaConfig()
	ageCfg.Type = "number" // "number" 接受一切数字；仅限整数可用 "integer"
	ageCfg.Minimum = &minAge
	ageCfg.Maximum = &maxAge

	schema := &json.Schema{
		Type:     "object",
		Required: []string{"name", "email"},
		Properties: map[string]*json.Schema{
			"name":  json.NewSchema(nameCfg),
			"email": {Type: "string", Format: "email"},
			"age":   json.NewSchema(ageCfg),
		},
	}

	// 验证 JSON
	data := `{"name": "Alice", "email": "[email protected]", "age": 30}`
	errors, err := json.ValidateSchema(data, schema)
	if err != nil {
		panic(err)
	}

	if len(errors) > 0 {
		for _, e := range errors {
			fmt.Printf("验证错误 [%s]: %s\n", e.Path, e.Message)
		}
	} else {
		fmt.Println("验证通过")
	}
	// 输出：验证通过
}

ValidationError

Schema 验证错误类型。

结构定义

type ValidationError struct {
    Path    string `json:"path"`    // 错误发生的路径
    Message string `json:"message"` // 错误消息
}

字段说明

字段	类型	说明
`Path`	`string`	验证错误发生的 JSON 路径
`Message`	`string`	验证失败的描述消息

方法

Error

签名：func (ve *ValidationError) Error() string

实现 error 接口。

for _, e := range errors {
    fmt.Println(e.Error())
}

BatchOperation

批量操作定义，ProcessBatch 的输入单元。

结构定义

type BatchOperation struct {
    Type    string `json:"type"`     // 操作类型："get", "set", "delete", "validate"
    JSONStr string `json:"json_str"` // JSON 数据字符串
    Path    string `json:"path"`     // 目标路径
    Value   any    `json:"value"`    // Set 操作的值
    ID      string `json:"id"`       // 操作标识
}

字段说明

字段	类型	说明
`Type`	`string`	操作类型，仅支持 `"get"`、`"set"`、`"delete"`、`"validate"`；其他值在对应 `BatchResult.Error` 中报 `unknown operation type`
`JSONStr`	`string`	该操作作用的目标 JSON 字符串（每个操作独立携带）
`Path`	`string`	目标路径
`Value`	`any`	仅 `"set"` 操作使用，要写入的值
`ID`	`string`	操作标识，原样回填到 `BatchResult.ID`，用于结果对账

批量上限

ProcessBatch 的操作数超过 Config.MaxBatchSize（默认 2000）时整体返回 ErrSizeLimit 错误；"validate" 操作的 BatchResult.Result 为 map[string]any{"valid": bool}。

BatchResult

批量操作结果。

结构定义

type BatchResult struct {
    ID     string `json:"id"`     // 操作标识（对应 BatchOperation.ID）
    Result any    `json:"result"` // 操作结果
    Error  error  `json:"error"`  // 错误（如有）
}

字段说明

字段	类型	说明
`ID`	`string`	对应 `BatchOperation.ID`，与输入顺序一一对应
`Result`	`any`	操作结果；`"get"` 为取到的值，`"set"`/`"delete"` 为修改后的 JSON 字符串，`"validate"` 为 `map[string]any{"valid": bool}`
`Error`	`error`	该单条操作的错误；逐项返回，单条失败不中断整批（是否继续由实现内部逐项执行）

WarmupResult

缓存预热结果，由 WarmupCache 返回。

结构定义

type WarmupResult struct {
    TotalPaths  int      `json:"total_paths"`            // 总路径数
    Successful  int      `json:"successful"`             // 成功预热数
    Failed      int      `json:"failed"`                 // 失败数
    SuccessRate float64  `json:"success_rate"`           // 成功率
    FailedPaths []string `json:"failed_paths,omitempty"` // 失败路径列表
}

字段说明

字段	类型	说明
`TotalPaths`	`int`	提交预热的路径总数
`Successful`	`int`	成功写入缓存的路径数
`Failed`	`int`	预热失败的路径数
`SuccessRate`	`float64`	成功率，百分比 0–100（非 0–1）
`FailedPaths`	`[]string`	失败路径清单（全部成功时为 nil）

全部失败时返回 error

WarmupCache 在所有路径都失败时除返回 WarmupResult 外还会返回非 nil 的 error（含最后一条错误）；缓存被禁用（EnableCache: false）时直接返回错误。

ParsedJSON

预解析的 JSON 文档，可复用于多次查询操作。

结构定义

ParsedJSON 的内部字段不导出，通过方法访问。

type ParsedJSON struct {
    // 内部字段（不导出）
    // 使用 Data() 方法获取已解析数据
}

方法

方法	签名	说明
`Data`	`func (p *ParsedJSON) Data() any`	返回底层已解析的数据；`Release` 之后返回 nil
`Release`	`func (p *ParsedJSON) Release()`	将内部数据置 nil，即使 `ParsedJSON` 本身仍被引用，解析树也可被垃圾回收

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

// 预解析 JSON
parsed, err := processor.PreParse(`{"user": {"name": "Alice", "age": 30}}`)
if err != nil {
    panic(err)
}

// 多次查询预解析结果
name, _ := processor.GetFromParsed(parsed, "user.name")
age, _ := processor.GetFromParsed(parsed, "user.age")

使用场景

场景	说明
高频查询	同一 JSON 多次查询时避免重复解析
批量路径获取	使用 `GetMultiple` 批量获取多个路径
性能优化	预解析后查询性能提升显著

性能提示

对于需要多次查询同一 JSON 字符串的场景，使用 PreParse 预解析可显著提升性能，避免重复解析开销。

Stats

处理器统计信息，通过包级 GetStats() 或 Processor.GetStats() 获取。

结构定义

type Stats struct {
    CacheSize        int64         `json:"cache_size"`        // 当前缓存大小
    CacheMemory      int64         `json:"cache_memory"`      // 缓存内存占用（字节）
    MaxCacheSize     int           `json:"max_cache_size"`    // 最大缓存大小
    HitCount         int64         `json:"hit_count"`         // 缓存命中数
    MissCount        int64         `json:"miss_count"`        // 缓存未命中数
    HitRatio         float64       `json:"hit_ratio"`         // 缓存命中率
    CacheTTL         time.Duration `json:"cache_ttl"`         // 缓存过期时间
    CacheEnabled     bool          `json:"cache_enabled"`     // 缓存是否启用
    IsClosed         bool          `json:"is_closed"`         // 处理器是否已关闭
    MemoryEfficiency float64       `json:"memory_efficiency"` // 内存效率
    OperationCount   int64         `json:"operation_count"`   // 操作总数
    ErrorCount       int64         `json:"error_count"`       // 错误总数
}

字段说明

字段	类型	说明
`CacheSize`	`int64`	当前缓存条目数
`CacheMemory`	`int64`	缓存占用内存估算（字节）
`MaxCacheSize`	`int`	配置的缓存条目上限（`Config.MaxCacheSize`）
`HitCount`	`int64`	缓存命中次数
`MissCount`	`int64`	缓存未命中次数
`HitRatio`	`float64`	命中率（0–1）
`CacheTTL`	`time.Duration`	当前缓存条目 TTL
`CacheEnabled`	`bool`	缓存是否启用
`IsClosed`	`bool`	处理器是否已 `Close`
`MemoryEfficiency`	`float64`	内存效率指标（缓存命中次数 / 每 MB 缓存内存，可大于 1）
`OperationCount`	`int64`	处理器累计操作数
`ErrorCount`	`int64`	处理器累计错误数

Config 安全字段总览

安全限制不设独立的汇总类型，直接以 Config 的字段形式提供：

Config 字段	类型	默认值	说明
`MaxJSONSize`	`int64`	100MB（`DefaultMaxJSONSize`）	输入 JSON 大小上限，超出返回 `ErrSizeLimit`
`MaxPathDepth`	`int`	50（`DefaultMaxPathDepth`）	路径段数上限，超出返回 `ErrInvalidPath`
`MaxBatchSize`	`int`	2000（`DefaultMaxBatchSize`）	批处理操作的单批数量上限，超出返回 `ErrSizeLimit`
`MaxNestingDepthSecurity`	`int`	200（`DefaultMaxNestingDepth`）	输入嵌套深度上限（安全扫描用），超出返回 `ErrDepthLimit`；勿与编码/解码嵌套深度 `Config.MaxDepth`（默认 100）混淆
`MaxSecurityValidationSize`	`int64`	10MB（`DefaultMaxSecuritySize`）	安全校验的大小阈值（阈值型）
`MaxObjectKeys`	`int`	100000（`DefaultMaxObjectKeys`）	对象最大键数，超出返回 `ErrSizeLimit`
`MaxArrayElements`	`int`	100000（`DefaultMaxArrayElements`）	数组最大元素数，超出返回 `ErrSizeLimit`
`FullSecurityScan`	`bool`	`false`（分层扫描）	是否对所有输入做全量安全扫描（设为 `true` 时全量）

Config.Validate 会把越界值钳制回合法区间（如 MaxNestingDepthSecurity 钳至 10–200、MaxObjectKeys 钳至 100–100000），可用 ValidateWithWarnings 查看调整明细；各字段完整语义见 Config。

HealthStatus

健康状态信息，通过包级 GetHealthStatus() 或 Processor.GetHealthStatus() 获取。

结构定义

type HealthStatus struct {
    Timestamp time.Time              `json:"timestamp"` // 检查时间戳
    Healthy   bool                   `json:"healthy"`   // 是否健康
    Checks    map[string]CheckResult `json:"checks"`    // 各检查项结果
}

字段说明

字段	类型	说明
`Timestamp`	`time.Time`	本次健康检查的时间戳
`Healthy`	`bool`	总体健康结论（全部检查项通过为 true）
`Checks`	`map[string]CheckResult`	各检查项结果，键为检查项名称

CheckResult 结构

单项健康检查结果。

type CheckResult struct {
    Healthy bool   `json:"healthy"` // 该检查项是否健康
    Message string `json:"message"` // 检查消息
}

字段	类型	说明
`Healthy`	`bool`	该检查项是否通过
`Message`	`string`	通过/失败的描述消息

IterableValue

迭代值封装。

方法概览

基础访问

方法	说明
`Get(path)`	按路径获取值
`GetString(path)`	获取字符串
`GetInt(path)`	获取整数
`GetFloat64(path)`	获取浮点数
`GetBool(path)`	获取布尔值
`GetArray(path)`	获取数组
`GetObject(path)`	获取对象

带默认值获取

方法	说明
`GetWithDefault(path, defaultValue)`	获取值，不存在时返回默认值
`GetStringWithDefault(path, defaultValue)`	获取字符串，不存在时返回默认值
`GetIntWithDefault(path, defaultValue)`	获取整数，不存在时返回默认值
`GetFloat64WithDefault(path, defaultValue)`	获取浮点数，不存在时返回默认值
`GetBoolWithDefault(path, defaultValue)`	获取布尔值，不存在时返回默认值

检查与遍历

方法	说明
`Exists(path)`	检查字段是否存在
`IsNull(path)`	检查指定路径是否为 null
`IsNullData()`	检查底层值是否为 null
`IsEmpty(path)`	检查指定路径是否为空
`IsEmptyData()`	检查底层值是否为空
`GetData()`	获取底层原始数据
`Break()`	返回中断信号，停止迭代
`ForeachNested(path, fn)`	遍历嵌套结构
`Release()`	释放资源

详见迭代器文档。

编码错误类型

json 包导出以下编码/解码过程中的错误类型，用于精细化的错误处理。

SyntaxError - 语法错误

JSON 语法解析错误，表示输入数据不是合法的 JSON 格式。

结构定义

type SyntaxError struct {
    Offset int64 // 错误发生的位置（字节偏移量）
    // 包含其他未导出字段
}

方法

方法	签名	说明
`Error`	`func (e *SyntaxError) Error() string`	返回错误描述，包含偏移位置

data := `{invalid json}`
_, err := json.ParseAny(data)
if syntaxErr, ok := err.(*json.SyntaxError); ok {
    fmt.Printf("语法错误，偏移量：%d\n", syntaxErr.Offset)
}

UnmarshalTypeError - 反序列化类型错误

当 JSON 值无法转换为目标 Go 类型时返回此错误。

结构定义

type UnmarshalTypeError struct {
    Value  string       // JSON 值的描述（如 "string", "number"）
    Type   reflect.Type // 目标 Go 类型
    Offset int64        // 错误发生的位置（字节偏移量）
    Struct string       // 包含该字段的结构体名称（如有）
    Field  string       // 字段名（如有）
    Err    error        // 内部错误（如有）
}

方法

方法	签名	说明
`Error`	`func (e *UnmarshalTypeError) Error() string`	返回类型不匹配的错误描述
`Unwrap`	`func (e *UnmarshalTypeError) Unwrap() error`	返回内部错误

type User struct {
    Age int `json:"age"`
}
var user User
err := json.Unmarshal([]byte(`{"age": "not_a_number"}`), &user)
if typeErr, ok := err.(*json.UnmarshalTypeError); ok {
    fmt.Printf("类型错误: JSON 值 %s 无法转换为 %v\n", typeErr.Value, typeErr.Type)
}

UnsupportedTypeError - 不支持的类型错误

当尝试编码 Go 中不支持的类型时返回此错误。

结构定义

type UnsupportedTypeError struct {
    Type reflect.Type // 不支持的 Go 类型
}

方法

方法	签名	说明
`Error`	`func (e *UnsupportedTypeError) Error() string`	返回不支持的类型描述

type Chan chan int
data := Chan(make(chan int))
_, err := json.Marshal(data)
if unsupportedErr, ok := err.(*json.UnsupportedTypeError); ok {
    fmt.Printf("不支持的类型: %v\n", unsupportedErr.Type)
}

UnsupportedValueError - 不支持的值错误

当尝试编码不支持的值时返回此错误（如 NaN、Infinity）。

结构定义

type UnsupportedValueError struct {
    Value reflect.Value // 不支持的值
    Str   string        // 错误描述
}

方法

方法	签名	说明
`Error`	`func (e *UnsupportedValueError) Error() string`	返回不支持的值描述

val := math.NaN()
_, err := json.Marshal(val)
if valErr, ok := err.(*json.UnsupportedValueError); ok {
    fmt.Printf("不支持的值: %s\n", valErr.Str)
}

InvalidUnmarshalError - 无效的反序列化目标错误

当 Unmarshal 的目标参数不是指针或 nil 时返回此错误。

结构定义

type InvalidUnmarshalError struct {
    Type reflect.Type // 目标参数的类型
}

方法

方法	签名	说明
`Error`	`func (e *InvalidUnmarshalError) Error() string`	返回无效目标的错误描述

var target string // 应传指针
err := json.Unmarshal([]byte(`"hello"`), target) // 错误：未传指针
if invalidErr, ok := err.(*json.InvalidUnmarshalError); ok {
    fmt.Printf("无效的反序列化目标: %v\n", invalidErr.Type)
}

MarshalerError - 编码器错误

当类型的 MarshalJSON 或 MarshalText 方法返回错误时包装此错误。

结构定义

type MarshalerError struct {
    Type reflect.Type // 实现 MarshalJSON 或 MarshalText 的类型
    Err  error        // MarshalJSON 或 MarshalText 返回的错误
    // 包含其他未导出字段
}

方法

方法	签名	说明
`Error`	`func (e *MarshalerError) Error() string`	返回编码器错误描述
`Unwrap`	`func (e *MarshalerError) Unwrap() error`	返回内部错误

type BadMarshaler struct{}

func (BadMarshaler) MarshalJSON() ([]byte, error) {
    return nil, errors.New("marshal failed")
}

_, err := json.Marshal(BadMarshaler{})
if marshalErr, ok := err.(*json.MarshalerError); ok {
    fmt.Printf("编码器错误 (类型: %v): %v\n", marshalErr.Type, marshalErr.Err)
}

Encoder - JSON 编码器

Encoder 将 JSON 值写入输出流。100% 兼容 encoding/json.Encoder。

创建

签名：func NewEncoder(w io.Writer, cfg ...Config) *Encoder

创建写入 w 的编码器。支持可选 Config 参数自定义编码行为。

file, _ := os.Create("output.json")
defer file.Close()

encoder := json.NewEncoder(file)
err := encoder.Encode(map[string]any{"name": "Alice"})

方法

方法	签名	说明
`Encode`	`func (enc *Encoder) Encode(v any) error`	将 Go 值编码为 JSON 写入流
`SetEscapeHTML`	`func (enc *Encoder) SetEscapeHTML(on bool)`	设置是否转义 HTML 特殊字符
`SetIndent`	`func (enc *Encoder) SetIndent(prefix, indent string)`	设置缩进格式

使用示例

package main

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

func main() {
	var buf bytes.Buffer
	encoder := json.NewEncoder(&buf)
	encoder.SetIndent("", "  ")
	encoder.SetEscapeHTML(true)

	err := encoder.Encode(map[string]any{
		"name":  "Alice",
		"email": "[email protected]",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(buf.String())
}

Decoder - JSON 解码器

Decoder 从输入流读取并解码 JSON 值。100% 兼容 encoding/json.Decoder。

创建

签名：func NewDecoder(r io.Reader, cfg ...Config) *Decoder

创建从 r 读取的解码器。支持可选 Config 参数。

file, _ := os.Open("data.json")
defer file.Close()

decoder := json.NewDecoder(file)
for decoder.More() {
    var obj map[string]any
    if err := decoder.Decode(&obj); err != nil {
        break
    }
    fmt.Println(obj)
}

方法

方法	签名	说明
`Decode`	`func (dec *Decoder) Decode(v any) error`	从流中读取下一个 JSON 值并解码
`UseNumber`	`func (dec *Decoder) UseNumber()`	使解码器将数字解析为 `Number` 而非 `float64`
`DisallowUnknownFields`	`func (dec *Decoder) DisallowUnknownFields()`	解码时遇到未知字段返回错误
`Buffered`	`func (dec *Decoder) Buffered() io.Reader`	返回解码器缓冲区中剩余数据的 Reader
`InputOffset`	`func (dec *Decoder) InputOffset() int64`	返回当前输入位置的偏移量
`More`	`func (dec *Decoder) More() bool`	检查流中是否还有更多 JSON 值
`Token`	`func (dec *Decoder) Token() (Token, error)`	读取下一个 JSON token

使用示例

package main

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

func main() {
	input := `{"name":"Alice","age":30}{"name":"Bob","age":25}`
	decoder := json.NewDecoder(strings.NewReader(input))

	for decoder.More() {
		var person map[string]any
		if err := decoder.Decode(&person); err != nil {
			break
		}
		fmt.Printf("姓名: %s, 年龄: %v\n", person["name"], person["age"])
	}
}

流式解码示例

package main

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

func main() {
	// 解码 JSON 流中的多个值
	input := `[1,2,3][4,5,6]`
	decoder := json.NewDecoder(strings.NewReader(input))

	for decoder.More() {
		var arr []any
		if err := decoder.Decode(&arr); err != nil {
			panic(err)
		}
		fmt.Println(arr)
	}
}

Token 读取示例

decoder := json.NewDecoder(strings.NewReader(`{"name":"Alice"}`))
for {
    token, err := decoder.Token()
    if err != nil {
        break
    }
    switch v := token.(type) {
    case json.Delim:
        fmt.Printf("分隔符: %s\n", string(v))
    case string:
        fmt.Printf("字符串: %s\n", v)
    case float64:
        fmt.Printf("数字: %v\n", v)
    case bool:
        fmt.Printf("布尔: %v\n", v)
    case nil:
        fmt.Println("null")
    }
}

Token - JSON Token

Token 是 JSON token 值，保存以下类型之一：

Delim，表示四个 JSON 分隔符 [ ] { }
bool，表示 JSON 布尔值
float64，表示 JSON 数字
Number，表示启用 UseNumber 时的 JSON 数字
string，表示 JSON 字符串
nil，表示 JSON null

type Token any

通过 Decoder.Token() 获取。

Number - JSON 数字

Number 表示 JSON 数字字符串，在启用 UseNumber 模式时由 Decoder 使用。

type Number string

方法

方法	签名	说明
`String`	`func (n Number) String() string`	返回数字的字符串表示
`Float64`	`func (n Number) Float64() (float64, error)`	转换为 float64
`Int64`	`func (n Number) Int64() (int64, error)`	转换为 int64

decoder := json.NewDecoder(strings.NewReader(`{"price": 19.99}`))
decoder.UseNumber()
var obj map[string]any
decoder.Decode(&obj)

if num, ok := obj["price"].(json.Number); ok {
    f, _ := num.Float64()
    fmt.Println(f) // 19.99
}

Delim - JSON 分隔符

Delim 是 JSON 分隔符类型，对应 [、]、{、} 四个字符。

type Delim rune

方法

String

签名：func (d Delim) String() string

返回分隔符的字符串表示。

token, _ := decoder.Token()
if delim, ok := token.(json.Delim); ok {
    fmt.Println(delim.String()) // "[" 或 "{" 等
}

类型定义 ​

Result[T] - 统一结果类型 ​

结构定义 ​

字段说明 ​

方法 ​

使用示例 ​

CompiledPath - 预编译路径 ​

类型定义 ​

使用场景 ​

编译函数 ​

Processor.CompilePath ​

方法 ​

使用示例 ​

PathSegment - 路径段 ​

类型定义 ​

字段说明 ​

方法 ​

使用示例 ​

AccessResult - 属性访问结果 ​

结构定义 ​

字段说明 ​

创建方法 ​

Processor.SafeGet ​

链式类型转换方法 ​

使用示例 ​

Schema - JSON Schema 类型 ​

结构定义 ​

创建 Schema ​

直接构造 ​

使用 NewSchema ​

使用 DefaultSchema ​

SchemaConfig 结构 ​

DefaultSchemaConfig ​

使用示例 ​

ValidationError ​

结构定义 ​

字段说明 ​

方法 ​

Error ​

BatchOperation ​

结构定义 ​

字段说明 ​

BatchResult ​

结构定义 ​

字段说明 ​

WarmupResult ​

结构定义 ​

字段说明 ​

ParsedJSON ​

结构定义 ​

方法 ​

使用场景 ​

Stats ​

结构定义 ​

字段说明 ​

Config 安全字段总览 ​

HealthStatus ​

结构定义 ​

字段说明 ​

CheckResult 结构 ​

IterableValue ​

方法概览 ​

编码错误类型 ​

SyntaxError - 语法错误 ​

结构定义 ​

方法 ​

UnmarshalTypeError - 反序列化类型错误 ​

结构定义 ​

方法 ​

UnsupportedTypeError - 不支持的类型错误 ​

结构定义 ​

方法 ​

UnsupportedValueError - 不支持的值错误 ​

结构定义 ​

方法 ​

InvalidUnmarshalError - 无效的反序列化目标错误 ​

结构定义 ​

方法 ​

MarshalerError - 编码器错误 ​

结构定义 ​

类型定义

Result[T] - 统一结果类型

结构定义

字段说明

方法

使用示例

CompiledPath - 预编译路径

类型定义

使用场景

编译函数

Processor.CompilePath

方法

使用示例

PathSegment - 路径段

类型定义

字段说明

方法

使用示例

AccessResult - 属性访问结果

结构定义

字段说明

创建方法

Processor.SafeGet

链式类型转换方法

使用示例

Schema - JSON Schema 类型

结构定义

创建 Schema

直接构造

使用 NewSchema

使用 DefaultSchema

SchemaConfig 结构

DefaultSchemaConfig

使用示例

ValidationError

结构定义

字段说明

方法

Error

BatchOperation

结构定义

字段说明

BatchResult

结构定义

字段说明

WarmupResult

结构定义

字段说明

ParsedJSON

结构定义

方法

使用场景

Stats

结构定义

字段说明

Config 安全字段总览

HealthStatus

结构定义

字段说明

CheckResult 结构

IterableValue

方法概览

编码错误类型

SyntaxError - 语法错误

结构定义

方法

UnmarshalTypeError - 反序列化类型错误

结构定义

方法

UnsupportedTypeError - 不支持的类型错误

结构定义

方法

UnsupportedValueError - 不支持的值错误

结构定义

方法

InvalidUnmarshalError - 无效的反序列化目标错误

结构定义

方法

MarshalerError - 编码器错误

结构定义