JSON Toolkit

JSON에서 Go Struct로: 생성기는 뼈대까지만, 이 네 가지는 직접 고쳐야 합니다

핵심 요약: API 응답 샘플을 변환기에 붙여넣으면 json 태그가 붙은 Go 구조체가 10초 만에 나옵니다. 하지만 number는 float64로 떨어지고, 빈 구조체는 omitempty로도 사라지지 않으며, time.Time은 RFC 3339만 받아들입니다. 타입 매핑 표, 포인터와 omitzero의 선택 기준, 생성 후 반드시 사람이 마쳐야 할 4단계 점검 목록을 정리했습니다.

중급약 6분 소요2026-11-22 발행2026-11-22 업데이트
JSON 샘플을 Go 구조체 코드로 생성하는 변환 도구 커버

결론부터: 변환기가 10초 만에 내놓는 구조체는 그대로 컴파일은 되지만, 그대로 프로덕션에 넣을 수는 없습니다. 생성기는 "붙여넣은 한 개의 샘플"만 기술합니다. 숫자는 float64로 떨어지고, 옵션 필드가 저절로 포인터가 되지 않으며, omitempty는 빈 구조체를 없애지 못하고, 날짜 문자열 대부분은 time.Time이 되지 못합니다. 이 네 가지는 붙여넣은 뒤에도 직접 손봐야 합니다.

API 응답을 Go 구조체로 옮기는 일은 순수한 기계적 노동입니다. 그런데 기계적 노동의 비용은 조용한 곳에 숨어 있습니다. 필드 이름을 한 글자 잘못 써도 컴파일 오류는 나지 않고, 그 필드는 영원히 영값(0)으로 남습니다. null 처리 스위치를 하나만 잘못 켜도 프로덕션 응답에 아무도 예상하지 못한 "note": null이 나타납니다. 구조체 생성이 풀어주는 것은 이름과 타입의 정렬 문제이고, 결저 저절로 맞춰지지 않는 것은 딱 두 곳입니다. 샘플 밖의 변형과, Go 타입 시스템과 JSON 타입 시스템 사이의 틈입니다.

생성기가 무엇을 읽는지: 타입 매핑 표

모든 JSON → Go 변환기의 핵심은 같은 매핑 표입니다. 전형적인 주문 응답을 이 사이트의 /convert/go 페이지에서 실측했습니다. 샘플을 붙여넣고 "json 태그 생성"을 켜면 다음 구조가 나옵니다.

JSON 값 생성되는 Go 타입 설명
문자열 string 날짜 문자열은 대부분 string으로 남음. 아래 time.Time 참조
정수 float64 encoding/json은 내부에서 숫자를 double로 파싱
소수 float64 금액 필드는 decimal 라이브러리나 int64 최소 단위로
true / false bool 함정 없음
null any null 한 개 샘플로는 타입을 증명할 수 없어 보수적으로 폴백
객체 이름 붙은 struct 중첩 객체는 독립 구조체로 생성
빈 객체 {} map[string]any 관찰할 필드가 없어 생성기는 추측하지 않음
배열 []요소타입 요소 타입은 첫 샘플에서 추론
혼합 타입 any Go에는 유니언 타입이 없어 다중 타입 필드는 any로 폴백
// 입력 샘플
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
  ID     string `json:"id"`
  Items  []Item `json:"items"`
  Coupon any    `json:"coupon"`
}

type Item struct {
  Sku string `json:"sku"`
  Qty int    `json:"qty"`
}

관찰 포인트는 세 가지입니다. 중첩된 items 객체는 독립적인 Item 구조체가 되고 슬라이스로 참조됩니다. coupon은 null로만 등장했기 때문에 생성기는 앞으로 무엇이 될지 증명할 수 없어 any로 폴백합니다. 숫자 qty는 int 또는 float64로 떨어집니다. 도구마다 정책은 다르지만 모두 "샘플 = 전체 사실"이라는 가정 위에 서 있습니다.

json 태그: 원래 이름, 옵션, 그리고 놓치기 쉬운 세 가지 표기

태그는 변환기 출력에서 정보 밀도가 가장 높은 부분이자, 가장 고치다 누락되기 쉬운 부분입니다. 규칙은 encoding/json 패키지 문서에서 바로 나옵니다.

Field int `json:"myName"`            // 키 myName으로 나타남
Field int `json:"myName,omitempty"`  // 빈 값이면 필드 전체 생략
Field int `json:",omitempty"`        // 기본 필드 이름 유지, 옵션만 추가
Field int `json:"-"`                 // 항상 무시, 인코딩·디코딩하지 않음
Field int64 `json:"id,string"`       // 숫자를 문자열 안에 넣어 정밀도 보존

놓치기 쉬운 표기 세 가지. 첫째, json:",omitempty"의 선행 콤마입니다. 빈 값 생략만 원하고 키 이름을 바꾸고 싶지 않다면 콤마가 필수이며, 콤마를 빠뜨리면 필드 전체가 ,omitempty라는 이름의 키로 취급됩니다. 둘째, 태그에는 원래 JSON 키(user_id, html_url)를 남기고 Go 필드는 관용적 표기(UserID, HTMLURL)를 쓰는 것. 태그가 없으면 Go는 필드 이름 그대로 매칭하므로 응답 키가 userId면 조용히 매핑에 실패합니다. 셋째, json:"-" 외에 json:"-,"가 있으며 후자는 "키 이름이 진짜로 -"라는 뜻입니다.

포인터: nil만이 "없음"과 "영값"을 구분합니다

Go의 영값 체계에서는 int와 string이 "필드가 없다"를 표현할 수 없습니다. 0과 ""은 진짜 데이터일 수도 있고, 그저 파싱되지 않았을 수도 있으니까요. JSON의 같은 키에는 세 가지 상태가 있습니다. 값을 가지고 등장, null로 등장, 아예 등장하지 않음. 값 타입은 첫 번째만 커버합니다.

type Config struct {
  Note    string  `json:"note,omitempty"`   // 생략 조건: 정확히 ""
  Alias   *string `json:"alias,omitempty"`  // 생략 조건: nil
  Details *Meta   `json:"details,omitempty"`
}

포인터 필드의 영값은 nil입니다. json.Unmarshal은 키가 없거나 null일 때 nil을 유지하고, omitempty는 nil일 때만 생략합니다. 대부분의 변환기가 "중첩 객체에 포인터 사용" 스위치를 제공하는 이유가 이것입니다. 켜면 중첩 구조체가 *Item이 되고, PATCH 요청에서 "필드 미전송"과 "null 전송으로 삭제"가 비로소 구분됩니다. 대가는 사용 전마다 nil 검사입니다. p.Address.Street는 Address가 nil이면 곧바로 패닉하며, Go JSON 코드에서 가장 흔한 런타임 크래시 중 하나입니다.

omitempty가 지우지 못하는 빈 구조체, 그 구멍을 메우는 omitzero

omitempty의 공식 정의는 값 기준입니다. false, 0, nil 포인터, nil 인터페이스, 길이가 0인 배열·슬라이스·map·문자열. 이 목록에는 "빈 구조체"가 없습니다.

type Order struct {
  Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
  Version string
  Build   int
}

// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{}              → "meta":{}   ← omitempty가 작동하지 않음

구조체 필드는 omitempty로 절대 생략되지 않습니다. 메모리 안에서 고정 크기 컨테이너로 존재하고, 존재하는 컨테이너는 "빈 것"이 아니기 때문입니다. 수정 방법은 필드를 *Meta로 바꾸는 것. nil 포인터만 생략됩니다. Go 1.24부터 두 번째 스위치 omitzero가 추가됐습니다. Go 영값 기준으로 판정하고, 타입이 IsZero() bool을 정의하면 그것을 호출합니다. time.Time의 영값이 생략될 수 있는 이유가 바로 이것입니다. encoding/json/v2(Go 1.25 실험 도입)에서는 의미론이 다시 변합니다. v2의 omitempty는 인코딩된 JSON 결과로 판정하고(null, "", {}, []만 빈 것으로 봄) count: 0은 출력에 남습니다. 오래된 코드를 옮길 때는 bool과 숫자 필드의 omitempty를 omitzero로 바꿔야 원래 의미가 유지됩니다.

모든 숫자는 float64가 된다: 큰 정수와 정밀도의 함정

명시적 타입이 없으면 encoding/json 디코더는 숫자를 float64로 처리하고, float64의 유효 가수는 53비트입니다. JavaScript의 고전 사례 — 9007199254740993이 9007199254740992로 변하는 것 — 는 Go에서도 존재합니다. 대상 필드가 float64이거나 any인 한.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"]는 float64(9007199254740992). 정밀도가 이미 손실됨

출구는 세 가지입니다. 구조체 필드를 명시적으로 int64로 쓰면 디코더가 정확히 int64로 파싱합니다. any를 거칠 수밖에 없다면 decoder.UseNumber()를 호출해 숫자를 json.Number 문자열로 받고 의도적으로 변환합니다. 금액에는 어떤 부동소수점도 쓰지 말고 int64로 최소 단위를 저장하거나 decimal 라이브러리를 씁니다. API가 스노우플레이크 ID나 64비트 주문 번호를 반환한다면 이 절은 필수 확인 항목입니다.

time.Time은 RFC 3339만 받아들입니다

생성기는 "2024-01-15T10:30:00Z"를 보면 time.Time으로 매핑하고, "2024-01-15 10:30:00"을 보면 string으로 남겨둡니다. 이건 게으름이 아니라 encoding/json의 강제 제약입니다. time.Time은 UnmarshalJSON을 구현했고 내부에서 RFC 3339 레이아웃 2006-01-02T15:04:05Z07:00으로 고정 파싱합니다. T 누락, 타임존 누락, Z 뒤에 오프셋이 붙는 표기는 모두 오류가 됩니다.

parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""

상류 포맷을 바꿀 수 없을 때의 표준 수정법은 time.Time을 감싸는 커스텀 타입을 정의하고 UnmarshalJSON에서 여러 레이아웃을 시도하는 것입니다.

type CustomDate struct{ time.Time }

func (c *CustomDate) UnmarshalJSON(b []byte) error {
  s := strings.Trim(string(b), `"`)
  t, err := time.Parse("2006-01-02 15:04:05", s)
  if err != nil {
    t, err = time.Parse(time.RFC3339, s)
    if err != nil {
      return fmt.Errorf("invalid date format: %w", err)
    }
  }
  c.Time = t
  return nil
}

생성 후 4단계 점검 목록

생성기 출력과 프로덕션 코드 사이에는 4단계가 있습니다. 한 번씩 훑는 것이 나중에 장애를 추적하는 것보다 훨씬 쌉니다.

  1. any 폴백을 없애기: any를 검색하고 폴백된 각 필드를 3~5개의 실제 샘플로 검증한 뒤 구체적 타입이나 포인터로 확정;
  2. 숫자 폭 재확인: ID·금액·카운터를 float64에서 int64 / int32 / decimal로. 폭이 불확실하면 int64로;
  3. 선택성 표기: 배열 내 객체 필드, PATCH 바디, 서드파티 API의 nullable 필드에 포인터나 omitempty/omitzero를 붙여 nil 의미론을 여기서 확정;
  4. 컴파일과 왕복 테스트: go vet을 통과시키고 Marshal→Unmarshal 왕복 테스트로 wire 포맷을 고정. encoding/json의 향후 버전 업그레이드로 인한 동작 변화를 CI에서 잡아냅니다.

샘플에서 계약으로: 변환기의 경계

변환기가 답하는 질문은 "이 샘플은 어떻게 생겼는가"이지 "이 인터페이스가 항상 어떻게 생겼는가"가 아닙니다. 경쟁 도구들도 자기 문서에서 솔직하게 말합니다. 샘플 한 개로는 프로덕션 변형을 증명할 수 없으며, 선택성·시간 포맷·열거값은 모두 사람의 검토가 필요하다고. 그러니 사용 습관을 만드세요. 붙여넣기 전에 차이를 가장 잘 드러내는 응답들(빈 목록, 전체 필드, null 포함)을 모으고, 생성 후에는 출력을 결과물이 아니라 초안으로 다룹니다. 인터페이스에 계약 문서가 있다면 JSON Schema로 제약을 명시하고 생성 코드를 Schema에 맞추는 편이 샘플 역추정보다 한 자릿수 신뢰할 만합니다. 같은 문제의 언어 간 시각은 Java 쪽은 Java 엔티티 생성 실측 글에서, 프런트엔드 계약은 TypeScript 인터페이스 변환에서 다룹니다. 숫자 정밀도라는 틈은 모든 언어에서 다른 모습으로 나타나며, 자세한 것은 JSON 큰 숫자 정밀도 함정 글을 참고하세요.

생성 후 사람이 확인해야 할 필드는?

최소 네 곳입니다. any 폴백, 숫자 폭(float64 → int64), 선택 필드의 포인터화, 날짜 필드가 string인지 time.Time인지. 네 곳 모두 샘플에서는 보이지 않는 프로덕션 변형이며, 생성기는 추측하지 않으므로 사람이 반드시 채워야 합니다.

omitempty를 붙였는데 필드가 여전히 JSON에 있는 이유는?

omitempty는 영값만 생략합니다. false, 0, "", nil, 빈 슬라이스. 빈 구조체 {}는 영값이 아니므로 남고, 필드를 포인터 타입으로 바꿔야 사라집니다. time.Time 영값에는 omitempty가 아니라 omitzero가 필요합니다.

큰 정수 ID가 역직렬화 후 변한 이유는?

명시적 타입이 없으면 encoding/json은 숫자를 float64로 파싱하고, float64의 가수는 53비트라 2^53을 넘는 정수는 정밀도를 잃습니다. 필드를 int64로 쓰거나 UseNumber()로 숫자를 json.Number로 유지하세요.

중첩 객체 필드를 포인터로 해야 하는 때는?

두 가지 경우입니다. 필드 전체가 빠지거나 null이 될 수 있을 때(nil이 "미전송"과 "영값"을 구분), PATCH 요청에서 "미제출"과 "null 제출로 삭제"를 구분해야 할 때. 일반 응답 구조의 non-nullable 필드에는 값 타입이 더 안전하고, nil 검사 비용은 정말 필요할 때만 지불하면 됩니다.