JSON → Go 변환

자신이 나온 JSON을 디코딩하는 구조체

JSON 샘플을 붙여넣으면 이 페이지가 그 샘플을 위한 Go 선언을 써 줍니다. 샘플 안의 객체마다 이름 있는 구조체를 하나씩 만들고, 모든 필드에는 그 필드가 읽는 키를 가리키는 json 태그를 붙입니다. 아래의 모든 것은 하나의 약속으로 정해집니다. Go 1.27로 빌드한 프로그램에 넣으면, 선언은 붙여넣은 JSON을 "encoding/json"으로 오류 없이 디코딩하고 모든 키가 필드로 읽힙니다. 예외는 어떤 구조체 태그로도 나타낼 수 없는 키이며, 그런 키는 구조체에서 빠집니다. Go가 이 약속을 지킬 수 없게 하거나 데이터가 정하지 않은 것을 페이지가 고르게 만드는 곳에서는, 출력 아래의 알림이 그곳이 어디인지 알려 줍니다. 드문 예외가 하나 있으며, 태그를 다루는 절에서 설명합니다.

형태 자체는 Go로 한 줄도 쓰기 전에, JSON → TypeScript 변환 페이지에 쓰이는 것과 같은 JSON 읽기로 정해집니다. 배열의 요소를 병합하는 일, 일부 요소에만 있는 키를 알아차리는 일, null과 한 번도 보내지지 않은 키를 구분하는 일, 다른 객체 안에서 발견된 모든 객체에 이름을 붙이는 일은 모두 그 페이지의 가이드가 다루므로 아래에서 다시 설명하지 않습니다. 이어지는 내용은 Go의 몫입니다. 숫자마다의 타입, 포인터, 값의 종류가 서로 다른 키를 위한 타입, 필드 이름, 태그, 그리고 알림이 던지는 질문을 다룹니다.

각 숫자가 쓰인 방식으로 고르는 세 가지 숫자 타입

JSON을 읽는 브라우저는 10과 10.0을 같은 숫자로 바꿉니다. Go는 그렇지 않습니다. "int64" 필드는 소수점이나 지수를 붙여 쓴 숫자 — 10.0, 1e3, 심지어 -0.0 — 를 받아들이지 않지만, 11과 -0은 받아들입니다. 그래서 페이지는 값만 보고 숫자 타입을 고르지 않습니다. 브라우저 자체의 파서에 각 숫자가 어떻게 쓰였는지 물어보고, 그에 따라 다음과 같이 정합니다.

• 한 위치의 모든 숫자가 소수점도 지수도 없이 정수로 쓰여 있는 곳에서는 필드가 "int64"가 되며, 정수에 관한 알림이 그 필드를 짚어 줍니다.
• 그 밖의 숫자는 "float64"입니다. 그래서 10.0으로 쓰인 가격은 샘플의 모든 가격이 딱 떨어지더라도 "float64"가 됩니다. Python의 "json" 모듈은 값이 정수인 float를 바로 그렇게 쓰므로, 이것을 보통 만나게 되는 곳은 Python으로 제공되는 API입니다.
• "json.Number"는 두 타입 중 어느 쪽도 정확히 담지 못하는 숫자를 위해 남겨 둔 타입입니다. "int64" 범위를 어느 쪽 끝으로든 넘는 정수, 1e999처럼 "float64"로는 아예 너무 큰 숫자, 그리고 [9007199254740993, 1.5]처럼 소수 옆에 있으면서 "float64"로는 너무 긴 정수가 그렇습니다. 이 타입은 그 모두를 정확히 담으며, 여러분의 프로그램은 값을 쓰는 곳에서 그것을 변환합니다.

다른 정수들 사이에 있는 긴 정수에는 그런 주의가 필요 없습니다. [9007199254740993, 1]은 "[]int64"입니다. "float64"가 보관하는 것보다 자릿수가 많은 소수는 "float64"로 남고 따로 알림으로 짚어지는데, 디코딩한 뒤 다시 인코딩하면 0.30000000000000001이 0.3으로 돌아오기 때문입니다.

숫자가 어떻게 쓰였는지 읽으려면 그것을 알려 주는 브라우저가 필요합니다. 알려 주지 않는 브라우저는 각 숫자를 값만으로 읽으므로, 거기서는 10.0이 정수로 보여 그 필드가 "int64"가 되고, 이 필드는 그 JSON을 디코딩하지 못합니다. 페이지는 정수와 구별하지 못한 숫자를 세고 첫 번째가 어디인지 보여 줍니다. 그런 브라우저는 "float64"가 버리는 자릿수도 보지 못하므로, 거기서는 소수 옆의 긴 정수에 "float64" 타입이 매겨지고, 반올림되는 소수는 짚어지지 않습니다.

값이 빠질 수 있는 곳에는 포인터

일부 객체가 빠뜨리거나 null로 두는 키는 포인터가 됩니다. "*string", "*int64", 또는 객체를 위해 작성된 구조체를 가리키는 포인터입니다. null을 담은 배열의 요소도 포인터이므로 [1, null]은 "[]*int64"입니다. 일부 객체에서 빠지는 키는 태그에 "omitzero"도 붙습니다. 이 둘이 갖춰지면 필드는 값이 도착했는지를 말해 줄 수 있고, 디코딩한 구조체를 다시 인코딩하면 샘플에서 빠지기만 했던 키는 빠진 채로, null로만 쓰였던 키는 null로 다시 쓰입니다.

슬라이스, 맵, "any", "json.RawMessage"는 포인터가 되지 않습니다. 아무것도 디코딩되지 않으면 모두 이미 nil이기 때문입니다. 그래도 슬라이스는 키가 빠질 수 있는 곳에서 "omitzero"를 받고, 있었지만 비어 있던 배열은 []로 다시 쓰입니다.

한 가지 구분은 살아남지 못합니다. 일부 객체에는 없고 다른 객체에서는 null인 키는 Go에서 하나의 nil이므로, 프로그램은 둘을 구별할 수 없고, 구조체를 다시 인코딩하면 샘플에 null이 있던 곳에서도 그 키는 빠집니다. 페이지는 이런 일이 생기는 필드를 모두 짚어 줍니다. 종류가 섞인 키는 그 차이를 지킵니다. "json.RawMessage"가 null을 null이라는 바이트로 담기 때문입니다.

종류가 섞이면 json.RawMessage, 아무것도 보지 못한 곳에는 any

키의 값들이 서로 종류가 다를 때 — 한 곳에서는 숫자, 다른 곳에서는 문자열이나 객체 — 필드는 "json.RawMessage"가 됩니다. 값 자체의 바이트로, 어떤 종류가 도착했는지 살펴본 뒤 프로그램이 디코딩하도록 남겨 두는 것입니다. 그 사이에 null이 있어도 달라지는 것은 없습니다. 종류 중 하나가 객체라면, 그것을 위해 추출된 구조체도 다른 구조체들 곁에 그대로 출력됩니다. "any"도 모든 종류를 받아들이겠지만 섞인 종류에는 쓰지 않습니다. "any"로 디코딩된 숫자는 "float64"가 되어 "float64"가 담지 못하는 것을 잃기 때문입니다.

샘플에는 배울 값이 없는 부분도 있습니다. 늘 null만 담았던 키, 매번 비어 있던 배열, 키가 없는 객체, 그리고 추론이 따라갈 수 있는 것보다 깊이 중첩된 값입니다. Go에서는 null 키와 깊이 중첩된 값에 "any", 빈 배열의 요소에 "[]any", 객체에 "map[string]any"가 쓰입니다. "any"는 어떤 종류의 값이든 받아들입니다. 맵은 객체나 null을 받아들이고, 그 자리에 문자열, 숫자, 배열, 불리언이 오면 디코딩이 실패합니다.

그 깊이를 넘어서면 알림이 말하지 않는 것이 두 가지 있습니다. 거기서 일부 객체에는 없고 다른 객체에서는 null인 키는 타입을 추론할 근거가 없는 위치로만 짚어지며, Go는 그 null을 빠진 것으로 다시 씁니다. 또 "float64"가 담는 것보다 긴 정수는 반올림되어 돌아와서, 9007199254740993이 9007199254740992가 됩니다. 그 위치가 "any"이기 때문입니다.

필드 이름은 Go 방식으로, 구조체 이름은 TypeScript 페이지와 같게

필드 이름은 키를 Go 방식으로 적은 것입니다. 키는 문자도 숫자도 아닌 모든 것에서, 그리고 소문자 뒤에 대문자가 오는 모든 곳에서 단어로 나뉘고, 단어들은 각각 대문자로 시작해 이어 붙여지므로 "user_name", "last-name", "firstName"은 UserName, LastName, FirstName이 됩니다. staticcheck의 기본 약어 목록에 있는 단어는 대문자로 쓰여 "id"는 ID, "api_key"는 APIKey, "video_url"은 VideoURL이 됩니다. 다만 단어 전체만 해당하므로 "idle"은 Idle, 복수형 "ids"는 Ids입니다. 전부 대문자로 쓰인 키는 단어로 읽혀 "USER_ID"는 UserID가 됩니다.

키 자신의 문자는 그대로 남으므로 "имя"는 Имя가 됩니다. 이름이 대문자로 시작하지 않게 되는 경우 — "名前"처럼 대문자가 없는 문자 체계의 키, "1st"처럼 숫자로 시작하는 키, "ß"처럼 한 글자짜리 대문자 형태가 없는 글자로 시작하는 키 — 에는 앞에 X가 붙어 X名前, X1st, Xß 형태가 되고, 그래도 필드는 자신의 키를 읽습니다. 결합 문자는 이름에서 빠지고 태그에는 남습니다. "@"처럼 문자나 숫자가 전혀 없는 키는 Field라는 이름이 되고, 같은 구조체에서 이미 쓰인 이름에는 번호가 붙습니다. "user_id", "userId", "USER_ID"가 함께 있으면 각각 UserID, UserID2, UserID3입니다.

Go 방식은 필드 이름까지만 미치고 거기서 멈춥니다. 모든 구조체는 추론이 그 객체에 고른 이름을 그대로 지니므로, 여기의 선언과 TypeScript 페이지의 인터페이스는 같은 이름을 쓰고, 필드는 그 필드가 담은 구조체와 다르게 적힐 수 있습니다. 그 이름을 고르는 방식은 TypeScript 가이드에서 설명합니다.

Go 1.27을 위한 태그, 그리고 어떤 태그로도 나타낼 수 없는 키

각 필드의 태그는 json:"user_id"처럼 키를 정확히 적고, 키가 빠질 수 있는 곳에서는 키 뒤에 ,omitzero가 붙습니다. 키 안의 제어 문자는 Go 자신이 쓰는 이스케이프로 적힙니다. 키가 "-"일 때는 json:"-," 형태로 적는데, Go는 이것을 바로 그 키로 읽습니다.

태그는 Go 1.27을 위해 쓰입니다. Go 1.26은 태그를 통해 더 적은 키를 읽습니다. 문자, 숫자, ASCII 공백, 일부 ASCII 문장 부호 말고 다른 것이 들어 있는 키 — "Price (€)", "temp °C", 이모지, 제어 문자, 결합 문자 — 는 거기서 읽히지 않으며, 페이지는 그런 필드를 하나하나 짚어 줍니다. 이 절반은 "GOEXPERIMENT=nojsonv2"로 빌드한 Go 1.27로 확인합니다. 이 빌드는 Go 1.26과 같은 방식으로 태그를 읽지만 유니코드 표는 Go 1.27의 더 새로운 것을 쓰므로, Go 1.26의 오래된 표에 없는 문자가 들어 있는 키는 이 확인에서 읽히고 알림도 생기지 않습니다.

쉼표, 백슬래시, 큰따옴표, 작은따옴표, 백틱 중 하나를 포함한 키와 빈 키는 어떤 구조체 태그로도 나타낼 수 없으므로 필드를 전혀 받지 못합니다. 그래도 JSON은 디코딩됩니다. "json.Unmarshal"은 그 키를 아무 불평 없이 건너뛰지만, "DisallowUnknownFields"를 설정한 "json.Decoder"는 거기서 멈춥니다. 알림은 그런 키를 Order["note,internal"]처럼 그 구조체와, Go가 문자열을 인용하는 방식대로 인용한 키로 짚어 줍니다. 그런 키 아래에 있는 객체도 구조체는 그대로 출력됩니다. 알림이 나오지 않는 경우가 하나 있습니다. 어떤 문자도 나타내지 않는 이스케이프인 짝이 없는 서로게이트만 다른 두 키는 Go에게는 하나의 키이며, 두 필드 중 어느 것도 채워지지 않습니다.

선언만, gofmt의 레이아웃으로

출력에는 타입 선언만 들어 있고 그 밖에는 아무것도 없습니다. package 절도 import도 없으므로, 이미 있는 파일에 그 파일 자신의 package 절 아래로 넣으면 됩니다. "json.RawMessage"나 "json.Number"를 쓰는 곳에서는 파일이 "encoding/json"도 가져와야 하며, 이것이 여러분이나 편집기에 맡겨지는 유일한 한 줄입니다. 레이아웃은 gofmt 그대로입니다. 각 필드 앞에 탭이 오고 각 구조체의 이름, 타입, 태그가 열을 맞춰 정렬되므로, gofmt는 그것을 조금도 바꾸지 않습니다. 루트의 타입이 가장 먼저 출력되고, 모든 객체는 자신을 담은 필드 안에 바로 적힌 구조체가 아니라 이름 있는 타입이며, 최상위가 배열이나 단일 값인 JSON도 "type Root []RootItem"처럼 이름 있는 타입이 되므로, 그것을 디코딩해 넣을 타입이 늘 있습니다.

알림이 확인해 달라고 하는 것

Go가 강요한 결정은 종류마다 선언 아래에 알림을 하나씩 받고, 그 알림은 해당하는 모든 위치를 모아 보여 줍니다. 그래서 정수 필드가 많은 샘플도 필드마다 하나가 아니라 알림 하나를 받습니다. 위치는 선언이 적는 방식 그대로, 필드는 Order.UserID처럼, 배열의 요소는 Order.Tags[]처럼 적고, 루트는 이름만 적습니다. 다만 두 알림은 대신 행과 열로 JSON 안을 가리킵니다. 두 번 쓰인 키, 그리고 이 브라우저가 정수와 구별하지 못한 숫자입니다. 어떤 알림도 선언을 바꾸지 않습니다. 각각을 여러분의 데이터에 대한 질문으로 읽으세요.

• "int64" 타입이 매겨진 정수. 그곳의 숫자는 모두 정수로 쓰여 있었습니다. 나중에 도착하는 값에 가격이나 측정값처럼 소수점이나 지수가 붙을 수 있다면 그 값은 디코딩되지 않으므로, 그 필드를 "float64"로 바꾸세요. ID나 개수라면 그대로 두어도 됩니다.
• "json.Number". 다른 어떤 숫자 타입도 그 값들을 정확히 담지 못합니다. 프로그램이 쓰는 곳에서 각각을 변환하거나, 실제 값이 더 좁은 타입에 들어간다는 것을 알고 있다면 필드를 직접 바꾸세요.
• "float64"가 반올림하는 소수. 그곳에는 "float64"가 보관하는 것보다 자릿수가 많은 숫자가 있어서, 프로그램은 쓰인 값이 아니라 그에 가까운 값을 받습니다. 모든 자릿수가 중요한 곳에서는 필드를 "json.Number"로 바꾸세요.
• "json.RawMessage"로 남은 섞인 종류. 값이 도착할 때마다 살펴보고, 드러난 종류에 맞게 디코딩하세요. 종류 중 하나가 객체라면 그 구조체가 출력에 그대로 남아 있어 그 값을 거기로 디코딩할 수 있습니다.
• 타입을 추론할 근거가 없음. 샘플의 그곳에는 배울 값이 없었으므로 필드는 "any"이거나 "any"의 맵입니다. 그 필드가 담는다고 알고 있는 타입으로 바꾸거나, 실제 값이 들어 있는 JSON으로 다시 변환하세요.
• 일부 객체에는 없고 다른 객체에서는 null. Go는 둘 다 하나의 nil로 담으므로, 키는 빠진 것으로 다시 쓰입니다. 이것은 여러분의 출력을 읽는 쪽이 null을 없는 키와 다르게 다룰 때만 문제가 됩니다.
• Go 1.26이 읽지 않는 키. Go 1.27로 빌드하거나, 그 키들이 만들어지는 곳에서 이름을 바꾸세요. Go 1.26에서는 읽히지 않은 채로 남습니다.
• 구조체에서 뺀 키. 이런 키에는 필드가 없습니다. 읽으려면 알림 자체가 권하는 대로 객체를 "map[string]json.RawMessage"로 디코딩하거나 구조체에 "UnmarshalJSON" 메서드를 작성하세요.
• 두 번 쓰인 키. 타입은 그 키의 마지막 것을 따르지만 Go는 각각을 차례로 디코딩하므로, 타입에 담을 수 없는 앞의 것이 있으면(예를 들어 마지막 것은 숫자인데 문자열이면) 디코딩이 오류를 돌려주고, 객체의 앞의 것에만 있는 키는 읽히지 않습니다. 표시된 행과 열에서 JSON을 고치세요.
• 이 브라우저는 10과 10.0을 구별하지 못합니다. 숫자가 어떻게 쓰였는지 알려 주지 않으므로, 소수점이나 지수를 붙여 쓴 값 때문에 "int64" 타입이 매겨진 필드는 여러분의 JSON을 디코딩하지 못합니다. 값이 그렇게 쓰인 필드를 확인하거나, 그것을 알려 주는 브라우저에서 JSON을 변환하세요.

날짜, 형식, 정해진 값 집합에 관한 알림은 없습니다. 페이지는 문자열에서 그런 것을 결코 추측하지 않기 때문입니다. 예제의 "created_at"은 어떻게 보이든 "string"으로 남습니다.