JSON to Kotlin Data Class 변환기 완벽 가이드
JSON to Kotlin Data Class 변환기는 개발자가 REST API 응답이나 JSON 데이터 구조를 빠르고 정확하게 Kotlin data class 선언문으로 변환할 수 있도록 설계된 무료 온라인 도구입니다. Kotlin은 JetBrains에서 개발한 현대적인 프로그래밍 언어로, Android 공식 개발 언어이자 서버사이드 개발에서도 널리 사용됩니다. Kotlin의 data class는 데이터 보관 목적의 클래스를 간결하게 선언할 수 있는 강력한 기능으로, equals(), hashCode(), toString(), copy() 등의 메서드를 자동으로 생성해줍니다. 하지만 API 응답 데이터를 수동으로 data class로 변환하는 작업은 반복적이고 실수가 발생하기 쉽습니다. 이 도구는 JSON 데이터를 분석하여 각 프로퍼티의 Kotlin 타입을 자동으로 추론하고, 중첩된 객체는 별도의 data class로 분리하며, 배열 내부의 요소 타입까지 정확하게 파악합니다. 또한 Kotlin의 핵심 기능인 null 안전성(null safety)을 반영하여, JSON에서 null 값이 발견된 필드는 자동으로 nullable 타입(?)으로 처리합니다.
주요 기능 소개
이 변환기는 다양한 JSON 데이터 타입을 정확하게 Kotlin 타입으로 매핑합니다. 문자열(String), 정수(Int/Long), 실수(Double), 불리언(Boolean), null, 리스트(List), 그리고 중첩된 객체까지 모든 JSON 데이터 타입을 지원합니다. 정수 값의 경우 Int 범위를 초과하면 자동으로 Long 타입으로 변환됩니다. 중첩된 객체는 자동으로 별도의 data class로 분리되어 코드의 재사용성과 가독성을 높입니다. 배열의 경우 내부 요소를 분석하여 List<T> 타입으로 정확하게 변환합니다. @SerializedName 어노테이션 옵션을 활성화하면 Gson 라이브러리와 호환되는 코드를 생성하고, @Json 옵션을 활성화하면 Moshi 라이브러리와 호환되는 코드를 생성합니다. 모든 필드를 nullable로 설정하는 옵션도 제공하여 안전한 API 응답 처리가 가능합니다.
활용 시나리오
- Android 앱 개발 시 REST API 응답 데이터를 Kotlin data class로 빠르게 변환
- Retrofit + Gson/Moshi 연동을 위한 데이터 모델 클래스 자동 생성
- Ktor 서버 개발 시 요청/응답 DTO 클래스 생성
- Spring Boot + Kotlin 프로젝트에서 JSON 매핑 클래스 생성
- JSON 설정 파일의 Kotlin 타입 정의 자동 생성
- 레거시 Java 프로젝트를 Kotlin으로 마이그레이션할 때 data class 생성
val 프로퍼티와 data class
Kotlin의 data class는 불변(immutable) 데이터를 다루는 데 최적화되어 있습니다. 이 도구에서 생성되는 모든 프로퍼티는 val(읽기 전용)로 선언되어 불변성을 보장합니다. 만약 변경 가능한 프로퍼티가 필요하다면 생성된 코드에서 val을 var로 수정하면 됩니다. data class는 주 생성자(primary constructor)에 선언된 프로퍼티를 기반으로 equals(), hashCode(), toString(), copy(), componentN() 함수를 자동으로 생성하므로 보일러플레이트 코드를 대폭 줄일 수 있습니다.
@SerializedName과 @Json 어노테이션
API 응답의 JSON 키 이름과 Kotlin 프로퍼티 이름이 다를 때 @SerializedName(Gson) 또는 @Json(Moshi) 어노테이션을 사용하여 매핑할 수 있습니다. 예를 들어 JSON에서 "user_name"이라는 키를 Kotlin에서는 userName으로 사용하고 싶을 때 이 어노테이션이 필요합니다. 이 도구는 원본 JSON 키 이름을 어노테이션 값으로 보존하면서 Kotlin 컨벤션에 맞는 프로퍼티 이름을 생성합니다.
자주 묻는 질문 (FAQ)
Q. 중첩된 객체는 어떻게 처리되나요?
A. 중첩된 객체는 자동으로 별도의 data class로 분리됩니다. 예를 들어 user 객체 안에 address 객체가 있으면, Address라는 별도의 data class가 생성되고, user data class에서는 val address: Address로 참조합니다. 이렇게 하면 코드의 재사용성과 가독성이 크게 향상됩니다.
Q. null 값은 어떻게 변환되나요?
A. JSON의 null 값은 Kotlin에서 nullable 타입(?)으로 변환됩니다. 예를 들어 "metadata": null은 val metadata: Any?로 변환됩니다. 만약 같은 프로퍼티가 배열 내 다른 객체에서는 문자열 값을 가진다면, val metadata: String?과 같이 추론된 타입에 nullable이 적용됩니다. "모든 필드 nullable" 옵션을 켜면 모든 프로퍼티에 ?가 추가되어 안전한 API 응답 처리가 가능합니다.
Q. 배열 내 여러 타입의 요소가 있으면 어떻게 되나요?
A. 배열 내 요소들의 타입을 분석하여 적절한 타입으로 변환합니다. 같은 타입의 요소로만 구성된 배열은 List<String>, List<Int> 등으로 변환됩니다. 배열 내 객체의 경우 모든 객체의 프로퍼티를 병합하여 하나의 data class를 생성하고, 일부 객체에만 존재하는 프로퍼티는 자동으로 nullable(?)로 처리합니다. 여러 타입이 혼합된 경우 List<Any>로 변환됩니다.
Q. 이 도구로 생성된 코드를 프로젝트에 바로 사용해도 되나요?
A. 네, 생성된 Kotlin data class 코드는 프로젝트에 바로 복사하여 사용할 수 있습니다. @SerializedName 옵션을 활성화하면 Gson과 바로 연동되고, @Json 옵션을 활성화하면 Moshi와 호환됩니다. 다만, 비즈니스 로직에 따라 일부 타입을 더 구체적으로 수정해야 할 수 있습니다 (예: String을 enum class로 변경, Int를 특정 value class로 변경 등).
Q. Int와 Long은 어떤 기준으로 구분되나요?
A. JSON의 정수 값이 Kotlin Int의 범위(-2,147,483,648 ~ 2,147,483,647)를 초과하면 자동으로 Long 타입으로 변환됩니다. 예를 들어 타임스탬프(1700000000000)와 같은 큰 숫자는 Long으로 추론됩니다. 범위 내의 정수는 Int로 처리됩니다.