인코딩 출력 함수

json 패키지가 제공하는 인코딩 출력 함수로, 직렬화, 역직렬화, 포맷 및 설정형 인코딩을 포함합니다.

직렬화 함수

Marshal

시그니처: func Marshal(value any, cfg ...Config) ([]byte, error)

Go 값을 JSON 바이트 슬라이스로 직렬화합니다. encoding/json.Marshal과 100% 호환됩니다: cfg 없이 json.Marshal(v)를 호출하면 표준 라이브러리와 완전히 동일합니다.

선택적인 후행 Config로 인코딩 동작 (들여쓰기, 숫자 처리 등) 을 제어할 수 있으며, Processor.Marshal과 패키지 레벨/인스턴스 레벨의 쌍을 이룹니다.

// encoding/json 호환 (cfg 없음)
data, err := json.Marshal(map[string]any{"name": "test"})
if err != nil {
    panic(err)
}
fmt.Println(string(data)) // {"name":"test"}

// 설정과 함께 (비파괴적 선택 매개변수)
data, err = json.Marshal(value, json.PrettyConfig())

Unmarshal

시그니처: func Unmarshal(data []byte, value any, cfg ...Config) error

JSON 바이트 슬라이스를 Go 값으로 역직렬화합니다. encoding/json.Unmarshal과 100% 호환됩니다: cfg 없이 json.Unmarshal(data, &v)를 호출하면 표준 라이브러리와 완전히 동일합니다.

선택적인 후행 Config로 보안 제한, 숫자 보존 등을 제어할 수 있으며, Processor.Unmarshal과 쌍을 이룹니다.

var result struct {
    Name string `json:"name"`
}
// encoding/json 호환 (cfg 없음)
err := json.Unmarshal([]byte(`{"name":"test"}`), &result)

// 설정과 함께
err = json.Unmarshal(data, &v, json.SecurityConfig())

MarshalIndent

시그니처: func MarshalIndent(v any, prefix, indent string, cfg ...Config) ([]byte, error)

들여쓰기가 있는 직렬화입니다. encoding/json.MarshalIndent와 100% 호환됩니다: cfg 없이 json.MarshalIndent(v, prefix, indent)를 호출하면 표준 라이브러리와 완전히 동일합니다.

선택적인 후행 Config로 설정을 추가할 수 있습니다; prefix와 indent 매개변수는 Config의 해당 필드를 덮어씁니다.

// encoding/json 호환 (cfg 없음)
data, err := json.MarshalIndent(user, "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(string(data))

// 설정과 함께
data, err = json.MarshalIndent(v, "", "  ", json.SecurityConfig())

포맷 함수

Compact

시그니처: func Compact(dst *bytes.Buffer, src []byte, cfg ...Config) error

JSON 을 압축하여 불필요한 공백 문자를 제거하고 결과를 dst에 씁니다. encoding/json.Compact와 호환됩니다.

var buf bytes.Buffer
err := json.Compact(&buf, []byte(`{"name": "test"}`))
if err != nil {
    panic(err)
}
fmt.Println(buf.String()) // {"name":"test"}

CompactString

시그니처: func CompactString(jsonStr string, cfg ...Config) (string, error)

문자열 입력/출력 형식으로 JSON 을 압축하여 불필요한 공백 문자를 제거합니다. Processor.Compact의 패키지 레벨 미러이며, Prettify(Processor.Prettify 미러) 와 대칭을 이룹니다.

Compact vs CompactString

Compact(dst, src): buffer 형식, encoding/json.Compact 호환, Processor.CompactBuffer 미러
CompactString(s): 문자열 형식, Processor.Compact 미러

compact, err := json.CompactString(`{
    "name": "Alice",
    "age": 30
}`)
// compact == `{"name":"Alice","age":30}`

// 설정과 함께 (예: 원본 숫자 형식 보존)
cfg := json.DefaultConfig()
cfg.PreserveNumbers = true
compact, err = json.CompactString(jsonStr, cfg)

Indent

시그니처: func Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

JSON 을 포맷하여 들여쓰기를 추가하고 결과를 dst에 씁니다. encoding/json.Indent와 호환됩니다.

var buf bytes.Buffer
err := json.Indent(&buf, []byte(`{"name":"test"}`), "", "  ")
if err != nil {
    panic(err)
}
fmt.Println(buf.String())
// {
//   "name": "test"
// }

HTMLEscape

시그니처: func HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

JSON 내용을 HTML 이스케이프하여 <, >, & 등의 특수 문자 (및 U+2028, U+2029) 를 대응하는 유니코드 이스케이프 시퀀스로 교체하고 결과를 dst에 씁니다. 반환값이 없습니다.

var buf bytes.Buffer
json.HTMLEscape(&buf, []byte(`{"html":"<script>alert(1)</script>"}`))
fmt.Println(buf.String())
// {"html":"\u003cscript\u003ealert(1)\u003c/script\u003e"}

Prettify

시그니처: func Prettify(jsonStr string, cfg ...Config) (string, error)

기본 포맷 인쇄 들여쓰기를 사용하여 JSON 문자열을 포맷하고, 포맷된 문자열을 반환합니다.

pretty, err := json.Prettify(`{"name":"Alice","age":30}`)
if err != nil {
    panic(err)
}
fmt.Println(pretty)
// {
//   "name": "Alice",
//   "age": 30
// }

설정형 인코딩 함수

Encode

시그니처: func Encode(value any, cfg ...Config) (string, error)

Go 값을 JSON 문자열로 인코딩하며, 선택적 설정 매개변수를 지원합니다.

더 이상 사용되지 않음

Encode는 기능상 EncodeWithConfig와 완전히 동일합니다 (둘 다 동일한 구현에 위임). 대신 EncodeWithConfig를 사용하거나, []byte 출력이 허용되는 경우 Marshal을 사용하십시오. Encode는 향후 메이저 버전에서 제거될 예정입니다.

result, err := json.Encode(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

설정과 함께 사용

result, err := json.Encode(user, json.SecurityConfig())

EncodePretty

시그니처: func EncodePretty(value any, cfg ...Config) (string, error)

Go 값을 포맷된 JSON 문자열로 인코딩합니다 (들여쓰기 포함). 선택적 설정 매개변수를 지원합니다.

result, err := json.EncodePretty(user)
if err != nil {
    panic(err)
}
fmt.Println(result)

설정과 함께 사용

result, err := json.EncodePretty(user, json.PrettyConfig())

EncodeWithConfig

시그니처: func EncodeWithConfig(value any, cfg ...Config) (string, error)

지정된 설정을 사용하여 Go 값을 JSON 문자열로 인코딩합니다. 인코딩 동작을 세밀하게 제어해야 하는 시나리오에 적합합니다.

// 포맷 인쇄 설정 사용
result, err := json.EncodeWithConfig(data, json.PrettyConfig())
if err != nil {
    panic(err)
}
fmt.Println(result)

보안 설정 사용

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

배치 인코딩 함수

EncodeBatch

시그니처: func EncodeBatch(pairs map[string]any, cfg ...Config) (string, error)

키 - 값 쌍을 배치로 JSON 객체 문자열로 인코딩합니다.

result, err := json.EncodeBatch(map[string]any{
    "name":  "Alice",
    "age":   30,
    "email": "[email protected]",
})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"age":30,"email":"[email protected]","name":"Alice"}

EncodeFields

시그니처: func EncodeFields(value any, fields []string, cfg ...Config) (string, error)

지정된 필드만 인코딩하여 필드 필터링 출력을 구현합니다.

user := struct {
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password"`
}{
    Name: "Alice", Email: "[email protected]", Password: "secret",
}

// 공개 필드만 출력
result, err := json.EncodeFields(user, []string{"name", "email"})
if err != nil {
    panic(err)
}
fmt.Println(result) // {"name":"Alice","email":"[email protected]"}

EncodeStream

시그니처: func EncodeStream(values any, cfg ...Config) (string, error)

여러 값을 JSON 배열 스트림 (array stream) 으로 인코딩합니다. values는 일반적으로 슬라이스나 열거 가능한 컬렉션이며, [v1,v2,...] 형태의 JSON 배열 문자열을 출력합니다.

values := []map[string]any{
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
}

result, err := json.EncodeStream(values)
if err != nil {
    panic(err)
}
fmt.Println(result)

Processor 포맷 메서드

Processor 타입은 추가 포맷 메서드를 제공합니다. json.New()로 Processor 를 생성합니다 ((*Processor, error) 반환):

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

Processor.CompactBuffer

시그니처: func (p *Processor) CompactBuffer(dst *bytes.Buffer, src []byte, cfg ...Config) error

JSON 바이트를 압축하여 dst 버퍼에 씁니다. 패키지 레벨 Compact 함수가 이 메서드에 위임합니다.

var buf bytes.Buffer
err := p.CompactBuffer(&buf, []byte(`{"name": "Alice"}`))
// buf.String() => {"name":"Alice"}

Processor.Indent

시그니처: func (p *Processor) Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

들여쓰기 포맷의 JSON 을 dst 버퍼에 씁니다. encoding/json.Indent와 호환됩니다.

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

Processor.HTMLEscape

시그니처: func (p *Processor) HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

HTML 이스케이프된 JSON 을 dst 버퍼에 씁니다. 반환값이 없습니다. encoding/json.HTMLEscape와 호환됩니다.

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

TIP

전체 Processor 문서는 Processor를 참조하세요.

설정 프리셋

다음 보조 함수는 미리 설정된 Config 값을 반환하며, ...Config를 받는 모든 함수에 전달할 수 있습니다:

// 기본 설정
cfg := json.DefaultConfig()

// 포맷 인쇄 설정
cfg = json.PrettyConfig()

// 보안 설정
cfg = json.SecurityConfig()

TIP

전체 Config 필드 문서는 설정을 참조하세요.

인코딩 출력 함수 ​

직렬화 함수 ​

Marshal ​

Unmarshal ​

MarshalIndent ​

포맷 함수 ​

Compact ​

CompactString ​

Indent ​

HTMLEscape ​

Prettify ​

설정형 인코딩 함수 ​

Encode ​

EncodePretty ​

EncodeWithConfig ​

배치 인코딩 함수 ​

EncodeBatch ​

EncodeFields ​

EncodeStream ​

Processor 포맷 메서드 ​

Processor.CompactBuffer ​

Processor.Indent ​

Processor.HTMLEscape ​

설정 프리셋 ​

관련 문서 ​