ヘルパー関数

json パッケージは JSON 比較、キャッシュ管理、ユーティリティ処理のための豊富なヘルパー関数を提供します。

JSON 比較関数

CompareJSON

シグネチャ：func CompareJSON(json1, json2 string, cfg ...Config) (bool, error)

2 つの JSON 文字列が等しいか比較します。数値精度の差異とキー順序の差異を処理します。

cfg なしの場合、従来の動作と同じです（セキュリティ検証を行わず、両側を encoding/json でマーシャル）。cfg を渡すと、2 つの入力にセキュリティ検証（サイズ/深度/危険パターン制限）を適用し、設定のエンコードで対称的な比較を行います。

// キー順序は異なるが内容は同じ
equal, _ := json.CompareJSON(`{"a":1,"b":2}`, `{"b":2,"a":1}`)
fmt.Println(equal) // true

// 数値精度は異なるが値は同じ
equal, _ = json.CompareJSON(`{"num":1}`, `{"num":1.0}`)
fmt.Println(equal) // true

// 内容が異なる
equal, _ = json.CompareJSON(`{"a":1}`, `{"a":2}`)
fmt.Println(equal) // false

// 設定付き（セキュリティ検証とエンコード制御を適用）
equal, err = json.CompareJSON(a, b, json.SecurityConfig())

Processor の同等メソッド

Processor.CompareJSON は常にセキュリティ検証を実行します（cfg またはプロセッサ自身の設定に従い）、パッケージレベル関数の cfg なしパスとは動作が異なります。詳しくは Processor データ変更を参照してください。

JSON マージ関数

MergeJSON

シグネチャ：func MergeJSON(json1, json2 string, cfg ...Config) (string, error)

2 つの JSON オブジェクトをマージします。Config でマージモードを設定可能。詳細は変更関数を参照。

MergeMany

シグネチャ：func MergeMany(jsons []string, cfg ...Config) (string, error)

複数の JSON オブジェクトをマージします。詳細は変更関数を参照。

キャッシュと統計

ClearCache（パッケージレベル関数）

シグネチャ：func ClearCache()

グローバルプロセッサの内部キャッシュをクリアします。

json.ClearCache()

GetStats（パッケージレベル関数）

シグネチャ：func GetStats() Stats

グローバルプロセッサの統計情報を取得します。

stats := json.GetStats()
fmt.Printf("キャッシュヒット率：%.2f%%\n", stats.HitRatio * 100)
fmt.Printf("キャッシュサイズ：%d\n", stats.CacheSize)

GetHealthStatus（パッケージレベル関数）

シグネチャ：func GetHealthStatus() HealthStatus

グローバルプロセッサのヘルスステータスを取得します。

status := json.GetHealthStatus()
if status.Healthy {
    fmt.Println("プロセッサは正常")
}

Processor.ClearCache

シグネチャ：func (p *Processor) ClearCache()

プロセッサの内部キャッシュをクリアします。

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

p.ClearCache()

Processor.GetStats

シグネチャ：func (p *Processor) GetStats() Stats

プロセッサの統計情報を取得します。

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

stats := p.GetStats()
fmt.Printf("キャッシュヒット率：%.2f%%\n", stats.HitRatio * 100)
fmt.Printf("キャッシュサイズ：%d\n", stats.CacheSize)

Processor.GetHealthStatus

シグネチャ：func (p *Processor) GetHealthStatus() HealthStatus

プロセッサのヘルスステータスを取得します。

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

status := p.GetHealthStatus()
if status.Healthy {
    fmt.Println("プロセッサは正常")
}

WarmupCache

シグネチャ：func WarmupCache(jsonStr string, paths []string, cfg ...Config) (*WarmupResult, error)

キャッシュをウォームアップし、後続の操作のパフォーマンスを向上させます。

data := `{"user": {"name": "Alice", "email": "[email protected]"}, "items": [{"id": 1}]}`
paths := []string{"user.name", "user.email", "items[*].id"}
result, err := json.WarmupCache(data, paths)
if err != nil {
    panic(err)
}
fmt.Printf("%d 個のパスのウォームアップに成功\n", result.Successful)

グローバルプロセッサ管理

グローバルプロセッサはすべてのパッケージレベル関数（Get、GetString など）で使用されます。

SetGlobalProcessor

シグネチャ：func SetGlobalProcessor(processor *Processor)

カスタムグローバルプロセッサを設定します。

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

json.SetGlobalProcessor(p)

// 以降、すべてのパッケージレベル関数がこのプロセッサを使用
val := json.GetString(data, "user.name")

ShutdownGlobalProcessor

シグネチャ：func ShutdownGlobalProcessor()

グローバルプロセッサをシャットダウンし、リソースを解放します。

package main

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

func main() {
    cfg := json.DefaultConfig()
    p, err := json.New(cfg)
    if err != nil {
        panic(err)
    }
    json.SetGlobalProcessor(p)

    defer json.ShutdownGlobalProcessor()

    // アプリケーションロジック...
}

出力関数

API 変更のお知らせ

Print、PrintPretty、PrintE、PrintPrettyE はライブラリから削除され、提供されなくなりました。EncodeWithConfig、EncodePretty、または Prettify を fmt.Println と組み合わせて使用してください（Encode は非推奨です）。詳細は出力関数を参照。

Buffer 互換関数

説明

以下の関数は encoding/json 標準ライブラリと完全に互換性があり、cfg パラメータを通じて追加設定をサポートします。

Compact

シグネチャ：func Compact(dst *bytes.Buffer, src []byte, cfg ...Config) error

JSON を圧縮して Buffer に書き込みます。encoding/json.Compact と 100% 互換。

var buf bytes.Buffer
err := json.Compact(&buf, []byte(`{"name": "test"}`))

Indent

シグネチャ：func Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

JSON をフォーマットして Buffer に書き込みます。encoding/json.Indent と 100% 互換。

var buf bytes.Buffer
err := json.Indent(&buf, []byte(`{"name":"test"}`), "", "  ")

HTMLEscape

シグネチャ：func HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

JSON を HTML エスケープして Buffer に書き込みます。encoding/json.HTMLEscape と 100% 互換。

var buf bytes.Buffer
json.HTMLEscape(&buf, []byte(`{"html":"<script>alert(1)</script>"}`))

セキュリティパターン関数

Config.AddDangerousPattern

Config の AddDangerousPattern メソッドまたは AdditionalDangerousPatterns フィールドでカスタム危険パターンを登録します。

cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "malicious_keyword",
    Name:    "カスタム悪意キーワード",
    Level:   json.PatternLevelCritical,
})
p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

Config 作成後に AdditionalDangerousPatterns フィールドを設定することも可能です：

cfg := json.DefaultConfig()
cfg.AdditionalDangerousPatterns = []json.DangerousPattern{
    {Pattern: "malicious_keyword", Name: "カスタム悪意キーワード", Level: json.PatternLevelCritical},
}
p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

DangerousPattern 構造体

フィールド	型	説明
`Pattern`	`string`	検出する部分文字列
`Name`	`string`	人間可読なリスクの説明
`Level`	`PatternLevel`	重大度レベル

PatternLevel レベル

レベル	説明
`PatternLevelCritical`	常に操作をブロック
`PatternLevelWarning`	厳格モードではブロック、緩やかなモードでは警告を記録
`PatternLevelInfo`	ログ記録のみ、ブロックしない

エラー処理関数

SafeError

シグネチャ：func SafeError(err error) string

クライアントに安全なエラーメッセージを返します。内部詳細情報は含まれません。API レスポンスでの使用に適しています。

val, err := json.Get(data, "user.name")
if err != nil {
    // 安全なエラーメッセージを返す（パス、内部状態などの機密情報を含まない）
    fmt.Println(json.SafeError(err))
}

RedactedPath

シグネチャ：func RedactedPath(path string) string

編集済みのパスを返します。セキュアなログ記録に使用します。パス内の機密部分を隠します。

path := "users[0].ssn"
fmt.Println(json.RedactedPath(path)) // 安全なパス表現

AccessResult 型変換メソッド

AccessResult は Processor.SafeGet() とパッケージレベル SafeGet() の戻り値の型で、型安全な変換メソッドを提供します。

AccessResult.AsString

シグネチャ：func (r AccessResult) AsString() (string, error)

文字列型への安全な変換。値自体が文字列の場合のみ成功します。

result := json.SafeGet(data, "user.name")
name, err := result.AsString()
if err != nil {
    return
}
fmt.Println(name)

AccessResult.AsStringConverted

シグネチャ：func (r AccessResult) AsStringConverted() (string, error)

任意の値を文字列に変換します（fmt.Sprintf でフォーマット）。

result := json.SafeGet(data, "user.age")
ageStr, err := result.AsStringConverted()
// "30" (文字列フォーマット)

AccessResult.AsInt

シグネチャ：func (r AccessResult) AsInt() (int, error)

整数への安全な変換。bool から int への変換はサポートしていません。

result := json.SafeGet(data, "user.age")
age, err := result.AsInt()

AccessResult.AsFloat64

シグネチャ：func (r AccessResult) AsFloat64() (float64, error)

float64 への安全な変換。bool から float64 への変換はサポートしていません。

result := json.SafeGet(data, "item.price")
price, err := result.AsFloat64()

AccessResult.AsBool

シグネチャ：func (r AccessResult) AsBool() (bool, error)

ブール値への安全な変換。bool と string 型のみサポート。

result := json.SafeGet(data, "feature.enabled")
enabled, err := result.AsBool()

ヘルパー関数 ​

JSON 比較関数 ​

CompareJSON ​

JSON マージ関数 ​

MergeJSON ​

MergeMany ​

キャッシュと統計 ​

ClearCache（パッケージレベル関数） ​

GetStats（パッケージレベル関数） ​

GetHealthStatus（パッケージレベル関数） ​

Processor.ClearCache ​

Processor.GetStats ​

Processor.GetHealthStatus ​

WarmupCache ​

グローバルプロセッサ管理 ​

SetGlobalProcessor ​

ShutdownGlobalProcessor ​

出力関数 ​

Buffer 互換関数 ​

Compact ​

Indent ​

HTMLEscape ​

セキュリティパターン関数 ​

Config.AddDangerousPattern ​

エラー処理関数 ​

SafeError ​

RedactedPath ​

AccessResult 型変換メソッド ​

AccessResult.AsString ​

AccessResult.AsStringConverted ​

AccessResult.AsInt ​

AccessResult.AsFloat64 ​

AccessResult.AsBool ​

関連 ​