JSON 다루기 튜토리얼

Go 프로그램에서 JSON 데이터를 읽고 쓰는 일은 생각보다 아주 쉽습니다. encoding/json/v2 패키지가 그걸 해 주거든요. 이 패키지는 예전 encoding/json 패키지보다 더 깔끔한 API와 더 좋은 기본값을 제공합니다. JSON의 기본 개념부터, Go 자료구조를 JSON으로 바꾸고(인코딩), JSON을 Go 자료구조로 되돌리는(디코딩) 과정을 하나씩 따라가 볼게요.

출처: Go 공식 문서

인코딩 (Encoding)

JSON 데이터를 만들 때는 Marshal 함수를 씁니다.

func Marshal(in any, opts ...Options) (out []byte, err error)

아래와 같은 Go 자료구조 Message가 있다고 해 볼게요.

type Message struct {
    Name string
    Body string
    Time time.Time
}

Message의 인스턴스를 하나 만들고,

m := Message{"Alice", "Hello", time.Date(2011, 1, 25, 0, 0, 0, 0, time.UTC)}

json.Marshal로 m의 JSON 버전을 만들 수 있습니다.

b, err := json.Marshal(m)

문제가 없다면 err는 nil이고, b는 아래 JSON 데이터를 담은 []byte가 될 거예요.

b == []byte(`{"Name":"Alice","Body":"Hello","Time":"2011-01-25T00:00:00Z"}`)

유효한 JSON으로 표현할 수 있는 자료구조만 인코딩된다는 점을 기억해 두세요.

포인터는 그 포인터가 가리키는 값으로 인코딩됩니다(포인터가 nil이면 null로).
JSON 객체는 키로 문자열만 지원합니다. 그래서 Go 맵을 인코딩하려면 키가 JSON 문자열로 인코딩되어야 해요. 예를 들어 map[string]T 같은 형태여야 합니다(T는 json 패키지가 지원하는 Go 타입).
channel, complex, function 타입은 인코딩할 수 없어요.
순환 자료구조(cyclic data structure)는 지원되지 않습니다.

Marshal은 전체 인코딩 의미를 문서로 정리해 두고 있으니 필요할 때 참고하면 됩니다.

json 패키지는 구조체 타입의 exported 필드(대문자로 시작하는 필드)에만 접근합니다. 그래서 JSON 출력에는 구조체의 exported 필드만 나타나요.

디코딩 (Decoding)

JSON 데이터를 Go 자료구조로 되돌리는 데는 Unmarshal 함수를 씁니다.

func Unmarshal(in []byte, out any, opts ...Options) (err error)

먼저 디코딩된 데이터가 저장될 자리를 만들어야 합니다.

var m Message

그리고 json.Unmarshal을 호출하는데, JSON 데이터가 담긴 []byte와 m의 포인터를 넘겨줍니다.

err := json.Unmarshal(b, &m)

만약 b가 m에 들어맞는 유효한 JSON이라면, 호출 이후 err는 nil이고 b의 데이터가 구조체 m에 저장됩니다. 정확히 아래와 같은 대입을 한 것과 같다고 보면 돼요.

m = Message{
    Name: "Alice",
    Body: "Hello",
    Time: time.Date(2011, 1, 25, 0, 0, 0, 0, time.UTC),
}

그럼 Unmarshal은 디코딩된 데이터를 어느 필드에 저장할지 어떻게 알까요? 특정 JSON 키 "Foo"에 대해 Unmarshal은 목적지 구조체의 필드를 다음 우선순위로 찾아봅니다.

json:"Foo" 태그가 달린 exported 필드 (Go 명세의 struct tag에 대해 더 알아보고 싶다면 그쪽을 참고하세요).
이름이 Foo인 exported 필드.

JSON 데이터의 구조가 Go 타입과 정확히 일치하지 않으면 어떻게 될까요?

b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
var m Message
err := json.Unmarshal(b, &m)

Unmarshal은 목적지 타입에서 찾을 수 있는 필드만 디코딩합니다. 이 경우 m의 Name 필드만 채워지고 Food 필드는 무시돼요. 이 동작은 큰 JSON 덩어리에서 특정 필드 몇 개만 골라내고 싶을 때 특히 유용합니다. 그리고 목적지 구조체의 unexported 필드는 Unmarshal의 영향을 받지 않는다는 뜻이기도 하죠.

그렇다면, JSON 데이터의 구조를 미리 알 수 없는 경우에는 어떻게 할까요?

`any`로 제네릭하게 다루기

any 타입은 어떤 Go 타입이든 나타냅니다. any는 interface{}(빈 인터페이스)로 정의되는데, 메서드가 0개인 인터페이스를 말해요. 모든 Go 타입은 메서드를 0개 이상 구현하므로 빈 인터페이스를 충족합니다. 그래서 any는 일반적인 컨테이너 타입 역할을 합니다.

var a any
a = "a string"
a = 2011
a = 2.777

타입 단언(type assertion)으로 기저의 구체 타입에 접근할 수 있어요.

r := a.(float64)
fmt.Println("the circle's area", math.Pi*r*r)

아니면 기저 타입을 모를 때는 타입 스위치(type switch)로 그 타입을 알아냅니다.

switch v := a.(type) {
case int:
    fmt.Println("twice a is", v*2)
case float64:
    fmt.Println("the reciprocal of a is", 1/v)
case string:
    h := len(v) / 2
    fmt.Println("a swapped by halves is", v[h:]+v[:h])
default:
    // a isn't one of the types above
}

json 패키지는 map[string]any와 []any 값을 써서 임의의 JSON 객체와 배열을 저장합니다. 유효한 JSON 덩어리라면 뭐든 그냥 any 값으로 Unmarshal해 버리죠. 이때 기본으로 대응되는 구체 Go 타입은 다음과 같습니다.

JSON boolean → bool
JSON number → float64
JSON string → string
JSON null → nil

임의의 데이터 디코딩하기 (Decoding arbitrary data)

변수 b에 담긴 이런 JSON 데이터를 생각해 봅시다.

b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)

이 데이터의 구조를 모르더라도 Unmarshal로 any 값에 디코딩할 수 있어요.

var f any
err := json.Unmarshal(b, &f)

이 시점에 f의 Go 값은 키가 문자열이고 값이 다시 any로 저장된 맵이 됩니다.

f = map[string]any{
    "Name": "Wednesday",
    "Age":  6,
    "Parents": []any{
        "Gomez",
        "Morticia",
    },
}

이 데이터에 접근하려면 타입 단언으로 f의 기저 타입인 map[string]any를 꺼내면 됩니다.

m := f.(map[string]any)

그 다음엔 range 문으로 맵을 순회하고 타입 스위치로 값들에 각자의 구체 타입으로 접근할 수 있어요.

for k, v := range m {
    switch vv := v.(type) {
    case string:
        fmt.Println(k, "is string", vv)
    case float64:
        fmt.Println(k, "is float64", vv)
    case []any:
        fmt.Println(k, "is an array:")
        for i, u := range vv {
            fmt.Println(i, u)
        }
    default:
        fmt.Println(k, "is of a type I don't know how to handle")
    }
}

이렇게 하면 타입 안전성의 이점을 누리면서도 알 수 없는 JSON 데이터를 다룰 수 있습니다.

참조 타입 (Reference Types)

앞 예제의 데이터를 담을 Go 타입을 하나 정의해 볼게요.

type FamilyMember struct {
    Name    string
    Age     int
    Parents []string
}

var m FamilyMember
err := json.Unmarshal(b, &m)

그 데이터를 FamilyMember 값으로 Unmarshal하면 예상대로 되지만, 자세히 들여다보면 놀라운 일이 벌어집니다. var 문으로 FamilyMember 구조체를 할당하고 그 값의 포인터를 Unmarshal에 넘겼는데, 그 시점에 Parents 필드는 nil 슬라이스였죠. 그런데 Parents 필드를 채우기 위해 Unmarshal이 뒤에서 새 슬라이스를 할당해 버립니다. 이건 Unmarshal이 지원하는 참조 타입(포인터, 슬라이스, 맵)에서 전형적으로 나타나는 동작이에요.

이런 자료구조로 Unmarshal하는 경우도 생각해 봅시다.

type Foo struct {
    Bar *Bar
}

JSON 객체에 Bar 필드가 있다면 Unmarshal은 새 Bar를 할당해서 채웁니다. 없다면 Bar는 nil 포인터로 남겨져요.

여기서 유용한 패턴이 나옵니다. 서로 다른 몇 가지 메시지 타입을 받는 애플리케이션이 있다면, 이렇게 '수신용' 구조체를 정의해 둘 수 있어요.

type IncomingMessage struct {
    Cmd *Command
    Msg *Message
}

그리고 보내는 쪽은 전달하고 싶은 메시지 종류에 따라 최상위 JSON 객체의 Cmd 필드나 Msg 필드(또는 둘 다)를 채우면 됩니다. Unmarshal은 JSON 데이터를 IncomingMessage 구조체로 디코딩할 때 JSON 데이터에 실제로 존재하는 자료구조만 할당해요. 그래서 어떤 메시지를 처리할지 알기 위해 프로그래머는 그냥 Cmd나 Msg가 nil이 아닌지만 확인하면 됩니다.

스트리밍 `Marshal`과 `Unmarshal`

io.Reader와 io.Writer 인터페이스는 Go 곳곳에서 쓰입니다. HTTP 연결, WebSocket, 파일 같은 리소스에 스트리밍 방식으로 접근하게 해 주죠. MarshalWrite와 UnmarshalRead 함수를 쓰면 중간에 메시지 전체를 담은 []byte를 만들지 않고도 이 스트림들에 직접 마샬링/언마샬링할 수 있습니다.

func MarshalWrite(out io.Writer, in any, opts ...Options) (err error)
func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error)

예를 들어 마샬 출력을 표준 출력에 직접 쓸 수 있어요.

err := json.MarshalWrite(os.Stdout, m)

커스텀 `Marshal`과 `Unmarshal`

때로는 기본 마샬 동작이 우리 타입에는 맞지 않을 때가 있습니다. 소프트웨어 버전을 나타내는 타입을 하나 가정해 볼게요.

type Version struct {
    Major, Minor, Patch int64
}

v := Version{1, 2, 3}
b, err := json.Marshal(s)

구조체 정의에 따라 이건 {"Major":1,"Minor":2,"Patch":3}으로 마샬됩니다. 하지만 JSON을 소비하는 쪽에겐 "1.2.3" 같은 버전 문자열이 훨씬 나은 표현일 겁니다.

MarshalerTo 인터페이스를 구현하면 커스텀 JSON 표현을 제공할 수 있어요. UnmarshalerFrom은 그 커스텀 JSON 표현의 언마샬링을 담당합니다.

type MarshalerTo interface {
    MarshalJSONTo(*jsontext.Encoder) error
}

type UnmarshalerFrom interface {
    UnmarshalJSONFrom(*jsontext.Decoder) error
}

이 메서드들을 구현해서 문자열 표현으로, 그리고 문자열 표현에서 변환할 수 있습니다.

func (v Version) MarshalJSONTo(enc *jsontext.Encoder) error {
    return json.MarshalEncode(enc, fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch))
}

커스텀 마샬링을 적용하면 Version{1, 2, 3} 값은 이제 "1.2.3"으로 마샬됩니다.

func (v *Version) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
    if k := dec.PeekKind(); k != jsontext.KindString {
        // Value must be a string.
        return &json.SemanticError{JSONKind: k}
    }

    var s string
    if err := json.UnmarshalDecode(dec, &s); err != nil {
        return err
    }

    _, err := fmt.Sscanf(s, "%d.%d.%d", &v.Major, &v.Minor, &v.Patch)
    return err
}

커스텀 언마샬링을 적용하면 "1.2.3"이 이제 Version{1, 2, 3}으로 언마샬됩니다. 이 단순한 예제는 정확한 "major.minor.patch" 형식만 요구하지만, 더 복잡한 UnmarshalJSONFrom은 minor와 patch 버전을 선택 사항으로 만드는 식으로 유연성을 더할 수도 있어요.

참고 자료 (References)

더 자세한 내용은 encoding/json/v2와 encoding/json/jsontext 패키지 문서를 확인하세요.

더 알아보기 (Learn more)

Go에서 JSON을 다루는 또 다른 입문 자료가 궁금하다면 Go 블로그의 "JSON and Go" 글을 찾아보세요.
encoding/json(구버전)과의 차이에 관심이 있다면 encoding/json/v2 패키지 문서를 확인하세요.

JSON 다루기 튜토리얼