定数とエラー

エラー変数

主要なエラー

var (
    // 基本エラー
    ErrInvalidJSON     = errors.New("invalid JSON format")
    ErrPathNotFound    = errors.New("path not found")
    ErrTypeMismatch    = errors.New("type mismatch")
    ErrInvalidPath     = errors.New("invalid path format")
    ErrProcessorClosed = errors.New("processor is closed")

    // 制限エラー
    ErrSizeLimit        = errors.New("size limit exceeded")
    ErrDepthLimit       = errors.New("depth limit exceeded")
    ErrConcurrencyLimit = errors.New("concurrency limit exceeded") // 制御された操作（Get/Set/Delete など）が MaxConcurrency に達したときに返されます

    // セキュリティとバリデーションエラー
    ErrSecurityViolation = errors.New("security violation detected")
    ErrUnsupportedPath   = errors.New("unsupported path operation")

    // リソースとパフォーマンスエラー（いずれも Deprecated：現在どの操作からも返されず、将来の使用のために予約）
    ErrOperationTimeout  = errors.New("operation timeout")
    ErrResourceExhausted = errors.New("system resources exhausted")
)

エラーチェック

errors.Is を使用してエラー型をチェックします：

val, err := json.Get(data, "user.name")
if err != nil {
    if errors.Is(err, json.ErrPathNotFound) {
        // パスが存在しない
        fmt.Println("パスが見つかりません")
    } else if errors.Is(err, json.ErrTypeMismatch) {
        // 型が一致しない
        fmt.Println("型が一致しません")
    } else if errors.Is(err, json.ErrInvalidJSON) {
        // JSON 形式エラー
        fmt.Println("無効な JSON")
    }
}

JsonsError 型

構造定義

type JsonsError struct {
    Op      string `json:"op"`      // 操作名
    Path    string `json:"path"`    // エラーが発生したパス
    Message string `json:"message"` // 人間可読なエラーメッセージ
    Err     error  `json:"err"`     // 基底エラー
}

メソッド

func (e *JsonsError) Error() string
func (e *JsonsError) Unwrap() error
func (e *JsonsError) Is(target error) bool

使用例

val, err := json.Get(data, "complex.path[0]")
if err != nil {
    var jsonErr *json.JsonsError
    if errors.As(err, &jsonErr) {
        fmt.Printf("操作: %s\n", jsonErr.Op)
        fmt.Printf("パス: %s\n", jsonErr.Path)
        fmt.Printf("メッセージ: %s\n", jsonErr.Message)
        if jsonErr.Err != nil {
            fmt.Printf("原因: %v\n", jsonErr.Err)
        }
    }
}

エラーヘルパー関数

上記のエラー型に加え、ライブラリは 2 つのエラー処理ヘルパー関数を提供します（詳細はヘルパーユーティリティを参照）：

関数	シグネチャ	説明
`SafeError`	`func SafeError(err error) string`	クライアントに安全なエラーメッセージを返し、パス名などの内部詳細を省略します（CWE-209）
`RedactedPath`	`func RedactedPath(path string) string`	マスク済みのパスを返します（空でないパスは `"***"` にマスクされます）。ログとエラーレスポンスに使用

設定プリセット

デフォルト値定数

const (
    // サイズ制限
    DefaultMaxJSONSize     = 100 * 1024 * 1024  // 100MB
    DefaultMaxNestingDepth = 200
    DefaultMaxPathDepth    = 50
    DefaultMaxDepth        = 100                 // エンコード/デコードのデフォルトネスト深度 (Config.MaxDepth)
    DefaultMaxConcurrency  = 50

    // セキュリティ制限
    DefaultMaxSecuritySize   = 10 * 1024 * 1024  // 10MB
    DefaultMaxObjectKeys     = 100000
    DefaultMaxArrayElements  = 100000
    DefaultMaxBatchSize      = 2000
    DefaultParallelThreshold = 10

    // キャッシュ
    DefaultCacheTTL = 5 * time.Minute
)

設定プリセット関数

DefaultConfig

シグネチャ：func DefaultConfig() Config

デフォルト設定を返します。

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

SecurityConfig

シグネチャ：func SecurityConfig() Config

セキュリティ設定を返します。信頼できない入力の処理に適しています。

// 以下の用途に推奨：
// - パブリック API と Web サービス
// - ユーザー送信データ
// - 外部 Webhook
// - 認証エンドポイント
// - 金融データ処理
cfg := json.SecurityConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

セキュリティ設定の特徴：

完全セキュリティスキャン
厳格モード
控えめな制限値
キャッシュ有効

PrettyConfig

シグネチャ：func PrettyConfig() Config

フォーマット出力設定を返します。

result, err := json.EncodeWithConfig(data, json.PrettyConfig())

マージモード定数

// MergeMode はマージモード型（internal パッケージからエクスポート）
type MergeMode = internal.MergeMode

const (
    // MergeUnion - ユニオンマージ（デフォルト）
    // オブジェクト：すべてのキーをマージ、競合値は上書き値を使用
    // 配列：すべての要素をマージして重複排除
    MergeUnion = internal.MergeUnion

    // MergeIntersection - 積集合マージ
    // オブジェクト：共通キーのみ保持
    // 配列：共通要素のみ保持
    MergeIntersection = internal.MergeIntersection

    // MergeDifference - 差集合マージ
    // オブジェクト：ベースに存在し上書きに存在しないキーのみ保持
    // 配列：ベースに存在し上書きに存在しない要素のみ保持
    MergeDifference = internal.MergeDifference
)

パスセグメント型

PathSegment は internal パッケージからエクスポートされたパスセグメント型で、解析後のパス構成要素を表します。

type PathSegment = internal.PathSegment

内部実装のエイリアス

PathSegment は internal.PathSegment の型エイリアスです。具体的なフィールド、フィールド型（PathSegmentType、PathSegmentFlags など）およびメソッドは internal パッケージに属し、公開 API としてはエクスポートされていません。バージョン間で変更される可能性があるため、ビジネスコードで内部構造に直接依存しないでください。

カスタムパス構文を実装する際は、PathParser インターフェースの ParsePath メソッドで []PathSegment を返します。
プリコンパイル済みパスには Processor.CompilePath を使用し、*CompiledPath を返します。

セキュリティパターンレベル

type PatternLevel int

const (
    // PatternLevelCritical - 重大リスク、常に操作をブロック
    PatternLevelCritical PatternLevel = iota

    // PatternLevelWarning - 警告レベル、厳格モードではブロック
    PatternLevelWarning

    // PatternLevelInfo - 情報レベル、ログ記録のみ
    PatternLevelInfo
)

DangerousPattern 構造体

type DangerousPattern struct {
    Pattern string       // 検出する部分文字列
    Name    string       // 人間可読なセキュリティリスクの説明
    Level   PatternLevel // 処理レベル
}

エラー処理のベストプラクティス

errors.Is で型をチェック

result, err := json.Get(data, path)
if errors.Is(err, json.ErrPathNotFound) {
    return defaultValue
}
if errors.Is(err, json.ErrTypeMismatch) {
    return defaultValue
}

errors.As で詳細を取得

var jsonErr *json.JsonsError
if errors.As(err, &jsonErr) {
    log.Printf("操作 %s がパス %s で失敗: %s",
        jsonErr.Op, jsonErr.Path, jsonErr.Message)
}

エラーラッピング

val := json.GetString(data, path)
if val == "" {
    return fmt.Errorf("設定 %s の取得で空の値が返されました", path)
}

定数とエラー ​

エラー変数 ​

主要なエラー ​

エラーチェック ​

JsonsError 型 ​

構造定義 ​

メソッド ​

使用例 ​

エラーヘルパー関数 ​

設定プリセット ​

デフォルト値定数 ​

設定プリセット関数 ​

DefaultConfig ​

SecurityConfig ​

PrettyConfig ​

マージモード定数 ​

パスセグメント型 ​

セキュリティパターンレベル ​

DangerousPattern 構造体 ​

エラー処理のベストプラクティス ​

errors.Is で型をチェック ​

errors.As で詳細を取得 ​

エラーラッピング ​

関連 ​