보조 함수

json 패키지는 JSON 비교, 캐시 관리 및 유틸리티 처리를 위한 풍부한 보조 함수를 제공합니다.

JSON 비교 함수

CompareJSON

시그니처: func CompareJSON(json1, json2 string, cfg ...Config) (bool, error)

두 JSON 문자열이 같은지 비교합니다. 숫자 정밀도 차이와 키 순서 차이를 처리합니다.

cfg 가 없으면 기존 동작과 동일합니다 (보안 검증을 수행하지 않고, 양쪽 모두 encoding/json으로 마샬링). cfg 를 전달하면 두 입력에 보안 검증 (크기/깊이/위험 모드 제한) 을 적용하고, 설정의 인코딩으로 대칭 비교를 수행합니다.

// 키 순서가 다르지만 내용이 같음
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)

두 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 ​

관련 문서 ​