JSON → Kotlin 데이터 클래스

타입 매핑

• 문자열 → String, 불리언 → Boolean
• −2,147,483,648~2,147,483,647 정수 → Int, 더 크면 → Long, Long 범위 밖 → Double
• 소수점이나 지수가 있는 숫자(9.5, 19.0, 1e3) → Double
• 배열 → List<T>. Int·Long·Double이 섞이면 가장 넓은 타입, 그 밖의 혼합과 빈 배열은 List<JsonElement>
• null → nullable 타입, 항상 null인 필드 → JsonElement?
• 중첩 객체 → 별도 data class, 빈 객체 {} → class Name(data class는 속성이 하나 이상 필요)

예시: snake_case API 응답

snake_case 키, null 필드, Int.MAX_VALUE를 넘는 카운터, 4.0으로 쓴 평점이 있는 입력:

{"user_id": 1024, "display_name": "Alice", "is_active": true, "last_login": null, "follower_count": 3000000000, "rating": 4.0, "tags": ["admin", "editor"], "address": {"city": "Tokyo", "zip_code": "100-0001"}}

출력:

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonElement

@Serializable
data class RootObject(
  @SerialName("user_id")
  val userId: Int = 0,
  @SerialName("display_name")
  val displayName: String = "",
  @SerialName("is_active")
  val isActive: Boolean = false,
  @SerialName("last_login")
  val lastLogin: JsonElement? = null,
  @SerialName("follower_count")
  val followerCount: Long = 0L,
  val rating: Double = 0.0,
  val tags: List<String> = emptyList(),
  val address: Address = Address()
)

@Serializable
data class Address(
  val city: String = "",
  @SerialName("zip_code")
  val zipCode: String = ""
)

camelCase 이름이 JSON 키와 다른 필드는 @SerialName으로 원래 키를 유지합니다. 키로 쓰인 Kotlin 키워드(class, in, fun)는 백틱으로 감쌉니다. last_login은 샘플에서 null뿐이라 JsonElement?가 됩니다. 타임스탬프임을 알면 String?으로 바꾸세요.

예시: 객체 배열

루트가 배열이면 모든 객체를 하나의 클래스로 합칩니다. price가 2와 1.5이므로 Double이 됩니다. 일부 요소에만 있는 키는 nullable이며 기본값은 null입니다.

[{"id": 1, "name": "Pen", "price": 2}, {"id": 2, "name": "Ink", "price": 1.5, "discount": 0.1}]

import kotlinx.serialization.Serializable

@Serializable
data class RootObject(
  val id: Int = 0,
  val name: String = "",
  val price: Double = 0.0,
  val discount: Double? = null
)

상태 표시줄에 List<RootObject>로 디코딩하라는 안내가 나옵니다.

예시: 같은 이름의 키, 다른 객체

필드가 다른 meta 객체가 두 개 있으면 클래스도 두 개가 생성되고, 두 번째에는 부모 이름이 앞에 붙습니다.

{"order": {"id": 7, "meta": {"source": "web"}}, "payment": {"meta": {"method": "card", "last4": "4242"}}}

import kotlinx.serialization.Serializable

@Serializable
data class RootObject(
  val order: Order = Order(),
  val payment: Payment = Payment()
)

@Serializable
data class Order(
  val id: Int = 0,
  val meta: Meta = Meta()
)

@Serializable
data class Meta(
  val source: String = ""
)

@Serializable
data class Payment(
  val meta: PaymentMeta = PaymentMeta()
)

@Serializable
data class PaymentMeta(
  val method: String = "",
  val last4: String = ""
)

디코딩

빌드 설정에 직렬화 플러그인과 JSON 라이브러리를 추가하고(Kotlin 직렬화 가이드 참고) 다음처럼 디코딩합니다.

import kotlinx.serialization.json.Json

val user = Json.decodeFromString<RootObject>(body)
val items = Json.decodeFromString<List<RootObject>>(arrayBody)

// 샘플에 없던 키 허용
val lenient = Json { ignoreUnknownKeys = true }

기본 Json은 클래스에 없는 키를 오류로 처리합니다. 이 페이지의 예시는 모두 Kotlin 2.4.20과 kotlinx.serialization 1.11.0으로 컴파일하고 기본 설정으로 디코딩되는 것을 확인했습니다.

제한 사항

• 타입은 샘플 하나로만 정합니다. 샘플의 ID가 작으면 Int가 되므로, 실제 ID가 2,147,483,647을 넘는다면 Long으로 바꾸세요.
• 브라우저는 JSON 숫자를 64비트 부동소수점으로 읽기 때문에 9,007,199,254,740,991보다 큰 정수는 타입을 정하기 전에 자릿수를 잃습니다. 타입은 Long이지만 범위는 직접 확인하세요.
• 19.0을 소수로 판단하는 것은 JSON.parse에 원본 텍스트를 넘겨주는 브라우저(Chrome 114+, Firefox 135+, Safari 18.4+)뿐입니다. 오래된 브라우저에서는 Int가 됩니다.
• JsonElement 필드는 Json 포맷에서만 동작하며 CBOR, ProtoBuf에서는 쓸 수 없습니다.
• 날짜는 String으로 남습니다. JSON에는 날짜 타입이 없으므로 디코딩 후 파싱하거나 커스텀 시리얼라이저를 추가하세요.
• 모든 속성에 기본값이 있어 키가 빠져도 조용히 기본값이 됩니다. 꼭 있어야 하는 키는 기본값을 지우세요.