Json 인스턴스 커스터마이징
기본 Json 인스턴스는 JSON 사양과 Kotlin 클래스의 선언을 엄격하게 따릅니다.
Json() 빌더 함수로 커스텀 Json 인스턴스를 생성하면 더 유연한 JSON 기능이나 타입 변환을 사용할 수 있습니다.
// 기본 구성을 기반으로 특수 부동소수점 값을 허용하는 Json 인스턴스를 생성합니다.
val customJson = Json {
allowSpecialFloatingPointValues = true
}
// 문자열을 인코딩할 때 기본 인스턴스와 동일한 구문으로 customJson 인스턴스를 사용합니다.
val jsonString = customJson.encodeToString(Data(Double.NaN))
println(jsonString)이러한 방식으로 생성된 Json 인스턴스는 불변(immutable)이며 스레드 안전(thread-safe)하므로, 재사용을 위해 최상위 프로퍼티에 안전하게 보관할 수 있습니다.
커스텀 Json 인스턴스를 재사용하면 클래스별 정보를 캐시할 수 있어 성능이 향상됩니다.
또한 동일한 빌더 구문을 사용하여 기존 인스턴스를 기반으로 새 Json 인스턴스를 만들고 설정을 수정할 수도 있습니다.
// 기존 Json을 기반으로 새 인스턴스를 생성합니다.
val lenientJson = Json(customJson) {
isLenient = true
prettyPrint = true
}JSON 구조 커스터마이징
인코딩 및 디코딩 중에 Json 인스턴스가 데이터를 구조화하는 방식을 커스터마이징할 수 있습니다. 이를 통해 출력에 어떤 값이 나타날지, 특정 타입이 어떻게 표현될지 제어할 수 있습니다.
기본값 인코딩
기본적으로 JSON 인코더는 기본 프로퍼티 값을 생략합니다. 디코딩 시 누락된 프로퍼티에 기본값이 자동으로 적용되기 때문입니다. 이 동작은 불필요한 null 값을 쓰는 것을 방지하므로, null을 기본값으로 갖는 널 허용(nullable) 프로퍼티에 특히 유용합니다. 자세한 내용은 기본 프로퍼티의 직렬화 관리 섹션을 참조하세요.
이 기본 동작을 변경하려면 Json 인스턴스에서 encodeDefaults 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 기본값을 인코딩하도록 Json 인스턴스를 구성합니다.
val format = Json { encodeDefaults = true }
@Serializable
class Project(
val name: String,
val language: String = "Kotlin",
val website: String? = null
)
fun main() {
val data = Project("kotlinx.serialization")
// 기본값을 포함하여 모든 프로퍼티 값을 인코딩합니다.
println(format.encodeToString(data))
// {"name":"kotlinx.serialization","language":"Kotlin","website":null}
}명시적 null 생략
기본적으로 모든 null 값은 JSON 출력으로 인코딩됩니다. null 값을 생략하려면 Json 인스턴스에서 explicitNulls 프로퍼티를 false로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 직렬화 중 null 값을 생략하도록 Json 인스턴스를 구성합니다.
val format = Json { explicitNulls = false }
@Serializable
data class Project(
val name: String,
val language: String,
val version: String? = "1.2.2",
val website: String?,
val description: String? = null
)
fun main() {
val data = Project("kotlinx.serialization", "Kotlin", null, null, null)
val json = format.encodeToString(data)
// JSON 출력에서 version, website, description 프로퍼티를 생략합니다.
println(json)
// {"name":"kotlinx.serialization","language":"Kotlin"}
// 기본값이 없는 누락된 널 허용 프로퍼티를 null로 처리합니다.
// 기본값이 있는 프로퍼티는 해당 기본값으로 채웁니다.
println(format.decodeFromString<Project>(json))
// Project(name=kotlinx.serialization, language=Kotlin, version=1.2.2, website=null, description=null)
}explicitNulls를 false로 설정하면 인코딩과 디코딩이 비대칭적으로 동작할 수 있습니다. 이 예제에서 version 프로퍼티는 인코딩 전에는 null이었지만, 디코딩 후에는 1.2.2가 됩니다.
coerceInputValues 프로퍼티를 사용하여 특정 유효하지 않은 입력 값을 누락된 프로퍼티로 취급하도록 디코더를 구성할 수 있습니다. 자세한 내용은 입력 값 강제 변환 섹션을 참조하세요.
구조화된 맵 키 허용
JSON 키는 원시 타입(primitive)이나 열거형(enum)만을 나타내는 문자열이어야 하므로, JSON 형식은 구조화된 키를 가진 맵을 기본적으로 지원하지 않습니다. 사용자 정의 클래스를 키로 사용하는 맵을 직렬화 및 역직렬화하려면 allowStructuredMapKeys 프로퍼티를 사용하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 구조화된 키를 가진 맵을 인코딩하도록 Json 인스턴스를 구성합니다.
val format = Json { allowStructuredMapKeys = true }
@Serializable
data class Project(val name: String)
fun main() {
val map = mapOf(
Project("kotlinx.serialization") to "Serialization",
Project("kotlinx.coroutines") to "Coroutines"
)
// 구조화된 키를 가진 맵을 JSON 배열로 직렬화합니다:
// [key1, value1, key2, value2,...]
println(format.encodeToString(map))
// [{"name":"kotlinx.serialization"},"Serialization",{"name":"kotlinx.coroutines"},"Coroutines"]
}특수 부동소수점 값 허용
기본적으로 Double.NaN 및 무한대(infinities)와 같은 특수 부동소수점 값은 JSON 사양에서 금지하고 있으므로 JSON에서 지원되지 않습니다.
이러한 값의 인코딩과 디코딩을 활성화하려면 Json 인스턴스에서 allowSpecialFloatingPointValues 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 특수 부동소수점 값을 허용하도록 Json 인스턴스를 구성합니다.
val format = Json { allowSpecialFloatingPointValues = true }
@Serializable
class Data(
val value: Double
)
fun main() {
val data = Data(Double.NaN)
// 특수 부동소수점 값을 나타내는 데 사용되는 비표준 JSON 출력을 생성합니다.
println(format.encodeToString(data))
// {"value":NaN}
}다형성을 위한 클래스 판별자(Class Discriminator) 지정
다형성 데이터(Polymorphic data)를 다룰 때, 직렬화된 다형성 객체의 타입을 식별하는 키 이름을 지정하기 위해 classDiscriminator 프로퍼티를 사용할 수 있습니다. @SerialName 어노테이션으로 정의된 명시적 직렬 이름(serial name)과 결합하면 결과 JSON 구조를 완벽하게 제어할 수 있습니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 커스텀 클래스 판별자를 사용하도록 Json 인스턴스를 구성합니다.
val format = Json { classDiscriminator = "#class" }
@Serializable
sealed class Project {
abstract val name: String
}
// OwnedProject 클래스에 커스텀 직렬 이름을 지정합니다.
@Serializable
@SerialName("owned")
class OwnedProject(override val name: String, val owner: String) : Project()
// SimpleProject 클래스에 커스텀 직렬 이름을 지정합니다.
@Serializable
@SerialName("simple")
class SimpleProject(override val name: String) : Project()
fun main() {
val simpleProject: Project = SimpleProject("kotlinx.serialization")
val ownedProject: Project = OwnedProject("kotlinx.coroutines", "kotlin")
// #class: "simple"을 포함하여 SimpleProject를 직렬화합니다.
println(format.encodeToString(simpleProject))
// {"#class":"simple","name":"kotlinx.serialization"}
// #class: "owned"를 포함하여 OwnedProject를 직렬화합니다.
println(format.encodeToString(ownedProject))
// {"#class":"owned","name":"kotlinx.coroutines","owner":"kotlin"}
}Json 인스턴스의 classDiscriminator 프로퍼티는 모든 다형성 타입에 대해 단일 판별자 키를 지정할 수 있게 해주는 반면, 실험적(Experimental) 기능인 @JsonClassDiscriminator 어노테이션은 더 많은 유연성을 제공합니다. 이를 통해 기본(base) 클래스에 직접 커스텀 판별자를 정의할 수 있으며, 이 판별자는 모든 하위 클래스에 자동으로 상속됩니다.
상속 가능한 직렬 어노테이션에 대해 자세히 알아보려면 @InheritableSerialInfo를 참조하세요.
예시는 다음과 같습니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// @JsonClassDiscriminator 어노테이션은 상속 가능하므로 Base의 모든 하위 클래스는 동일한 판별자를 갖습니다.
@Serializable
@OptIn(ExperimentalSerializationApi::class)
@JsonClassDiscriminator("message_type")
sealed class Base
// Base로부터 판별자를 상속받습니다.
@Serializable
sealed class ErrorClass: Base()
// 메시지와 선택적 오류를 결합하는 클래스를 정의합니다.
@Serializable
data class Message(val message: Base, val error: ErrorClass?)
@Serializable
@SerialName("my.app.BaseMessage")
data class BaseMessage(val message: String) : Base()
@Serializable
@SerialName("my.app.GenericError")
data class GenericError(@SerialName("error_code") val errorCode: Int) : ErrorClass()
val format = Json { classDiscriminator = "#class" }
fun main() {
val data = Message(BaseMessage("not found"), GenericError(404))
// 모든 하위 클래스에 대해 Base의 판별자를 사용합니다.
println(format.encodeToString(data))
// {"message":{"message_type":"my.app.BaseMessage","message":"not found"},"error":{"message_type":"my.app.GenericError","error_code":404}}
}봉인된(sealed) 기본 클래스의 하위 클래스에서 서로 다른 클래스 판별자를 지정할 수는 없습니다. 서로 겹치지 않는 별개의 하위 클래스 계층 구조만 자체 판별자를 정의할 수 있습니다.
둘 다 판별자를 지정한 경우, @JsonClassDiscriminator가 Json 구성의 판별자보다 우선 적용됩니다.
클래스 판별자 출력 모드 설정
JsonBuilder.classDiscriminatorMode 프로퍼티를 사용하여 클래스 판별자가 JSON 출력에 추가되는 방식을 제어할 수 있습니다. 기본적으로 판별자는 다형성 타입에 대해서만 추가되며, 이는 다형성 클래스 계층 구조를 다룰 때 유용합니다.
이 동작을 조정하려면 ClassDiscriminatorMode 프로퍼티를 다음 옵션 중 하나로 설정하세요.
POLYMORPHIC: (기본값) 다형성 타입에 대해서만 클래스 판별자를 추가합니다.ALL_JSON_OBJECTS: 가능한 모든 JSON 객체에 클래스 판별자를 추가합니다.NONE: 클래스 판별자를 완전히 생략합니다.
다음은 ClassDiscriminatorMode 프로퍼티를 NONE으로 설정한 예시입니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 출력에서 클래스 판별자를 생략하도록 Json 인스턴스를 구성합니다.
val format = Json { classDiscriminatorMode = ClassDiscriminatorMode.NONE }
@Serializable
sealed class Project {
abstract val name: String
}
@Serializable
class OwnedProject(override val name: String, val owner: String) : Project()
fun main() {
val data: Project = OwnedProject("kotlinx.coroutines", "kotlin")
// 판별자 없이 직렬화합니다.
println(format.encodeToString(data))
// {"name":"kotlinx.coroutines","owner":"kotlin"}
}판별자가 없으면 기본 클래스의 직렬 변환기(serializer)가 출력을 적절한 타입으로 다시 역직렬화할 수 없습니다.
들여쓰기 출력 (Pretty printing)
기본적으로 Json은 압축된 한 줄 출력을 생성합니다.
출력에서 pretty printing을 활성화하여 들여쓰기와 줄 바꿈을 추가하면 가독성을 높일 수 있습니다. 이렇게 하려면 Json 인스턴스에서 prettyPrint 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 커스텀 Json 포맷을 생성합니다.
val format = Json { prettyPrint = true }
@Serializable
data class Project(val name: String, val language: String)
fun main() {
val data = Project("kotlinx.serialization", "Kotlin")
// 줄 바꿈과 들여쓰기가 적용된 JSON 출력을 출력합니다.
println(format.encodeToString(data))
}이 예제는 다음과 같은 결과를 출력합니다.
{
"name": "kotlinx.serialization",
"language": "Kotlin"
}prettyPrintIndent 옵션을 사용하여 들여쓰기 출력 시 적용할 들여쓰기를 커스터마이징할 수 있습니다.
예를 들어, 기본 4개의 공백을 \t나 \n과 같이 허용되는 공백 문자로 바꿀 수 있습니다.
JSON 역직렬화 커스터마이징
Kotlin의 Json 파서는 JSON 데이터의 파싱과 역직렬화를 커스터마이징할 수 있는 몇 가지 설정을 제공합니다.
알 수 없는 키 무시
서드파티 서비스나 기타 동적 소스의 JSON 데이터를 다룰 때, 시간이 지남에 따라 JSON 객체에 새로운 프로퍼티가 추가될 수 있습니다.
기본적으로 역직렬화 중에 알 수 없는 키(JSON 입력에 있는 프로퍼티 이름)가 있으면 오류가 발생합니다. 이를 방지하려면 Json 인스턴스에서 ignoreUnknownKeys 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 알 수 없는 키를 무시하도록 Json 인스턴스를 생성합니다.
val format = Json { ignoreUnknownKeys = true }
@Serializable
data class Project(val name: String)
fun main() {
val data = format.decodeFromString<Project>("""
{"name":"kotlinx.serialization","language":"Kotlin"}
""")
// language 키는 Project 클래스에 없으므로 무시됩니다.
println(data)
// Project(name=kotlinx.serialization)
}특정 클래스에 대해 알 수 없는 키 무시
모든 클래스에 대해 ignoreUnknownKeys를 활성화하는 대신, @JsonIgnoreUnknownKeys 어노테이션을 사용하여 특정 클래스에 대해서만 알 수 없는 키를 무시할 수 있습니다. 이를 통해 기본적으로는 엄격한 역직렬화를 유지하면서 필요한 곳에만 유연성을 허용할 수 있습니다.
@JsonIgnoreUnknownKeys 어노테이션은 실험적(Experimental) 기능입니다. 사용하려면 @OptIn(ExperimentalSerializationApi::class) 어노테이션을 사용하거나 컴파일러 옵션 -opt-in=kotlinx.serialization.ExperimentalSerializationApi를 추가하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@OptIn(ExperimentalSerializationApi::class)
@Serializable
// Outer의 알 수 없는 프로퍼티는 역직렬화 중에 무시됩니다.
@JsonIgnoreUnknownKeys
data class Outer(val a: Int, val inner: Inner)
@Serializable
data class Inner(val x: String)
fun main() {
val outer = Json.decodeFromString<Outer>(
"""{"a":1,"inner":{"x":"value"},"unknownKey":42}"""
)
println(outer)
// Outer(a=1, inner=Inner(x=value))
// 예외가 발생합니다.
// Inner에는 어노테이션이 지정되지 않았으므로 inner 내부의 unknownKey는 무시되지 않습니다.
println(
Json.decodeFromString<Outer>(
"""{"a":1,"inner":{"x":"value","unknownKey":"unexpected"}}"""
)
)
}이 예제에서 Inner는 @JsonIgnoreUnknownKeys 어노테이션이 붙어있지 않기 때문에 알 수 없는 키에 대해 SerializationException을 던집니다.
입력 값 강제 변환 (Coerce input values)
서드파티 서비스나 기타 동적 소스의 JSON 데이터를 다룰 때 포맷이 변경될 수 있습니다. 이로 인해 실제 값이 예상 타입과 일치하지 않을 때 디코딩 중 예외가 발생할 수 있습니다.
기본 Json 구현은 입력 타입에 대해 엄격합니다. 이 제한을 완화하려면 Json 인스턴스에서 coerceInputValues 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
val format = Json { coerceInputValues = true }
@Serializable
data class Project(val name: String, val language: String = "Kotlin")
fun main() {
val data = format.decodeFromString<Project>("""
{"name":"kotlinx.serialization","language":null}
""")
// language의 잘못된 null 값을 기본값으로 강제 변환합니다.
println(data)
// Project(name=kotlinx.serialization, language=Kotlin)
}coerceInputValues 프로퍼티는 디코딩에만 영향을 줍니다. 특정 유효하지 않은 입력 값을 해당 프로퍼티가 누락된 것처럼 취급합니다. 현재 다음 경우에 적용됩니다.
- 널 불가(non-nullable) 타입에 대한
null입력 - 열거형(enum)의 알 수 없는 값
이 목록은 향후 버전에서 확장될 수 있으며, 유효하지 않은 값을 기본값이나 null로 대체함으로써 이 프로퍼티가 설정된 Json 인스턴스를 훨씬 더 관대하게 만들 수 있습니다.
값이 누락된 경우, 기본 프로퍼티 값이 존재한다면 기본값으로 대체됩니다.
열거형의 경우 다음 조건이 모두 충족될 때만 값이 null로 대체됩니다.
- 기본값이 정의되지 않음.
explicitNulls프로퍼티가false로 설정됨.- 프로퍼티가 널 허용(nullable)임.
coerceInputValues와 explicitNulls 프로퍼티를 결합하여 잘못된 열거형 값을 처리할 수 있습니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
enum class Color { BLACK, WHITE }
@Serializable
data class Brush(val foreground: Color = Color.BLACK, val background: Color?)
val json = Json {
coerceInputValues = true
explicitNulls = false
}
fun main() {
// 알 수 없는 foreground 값을 기본값으로 강제 변환하고 background를 null로 강제 변환합니다.
val brush = json.decodeFromString<Brush>("""{"foreground":"pink", "background":"purple"}""")
println(brush)
// Brush(foreground=BLACK, background=null)
}후행 쉼표(Trailing commas) 허용
JSON 입력에서 후행 쉼표를 허용하려면 allowTrailingComma 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// JSON 객체 및 배열에서 후행 쉼표를 허용합니다.
val format = Json { allowTrailingComma = true }
fun main() {
val numbers = format.decodeFromString<List<Int>>(
"""
[1, 2, 3,]
"""
)
println(numbers)
// [1, 2, 3]
}JSON 내 주석 허용
JSON 입력에서 주석을 허용하려면 allowComments 프로퍼티를 사용하세요. 이 프로퍼티가 활성화되면 파서는 입력에서 다음과 같은 주석 형식을 허용합니다.
- 줄 바꿈
\n에서 끝나는//한 줄 주석 /* */블록 주석
예시는 다음과 같습니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// JSON 입력에서 주석을 허용합니다.
val format = Json { allowComments = true }
fun main() {
val numbers = format.decodeFromString<List<Int>>(
"""
[
// 첫 번째 요소
1,
/* 두 번째 요소 */
2
]
"""
)
println(numbers)
// [1, 2]
}관대한 파싱 (Lenient parsing)
기본적으로 Json 파서는 키와 문자열 리터럴을 따옴표로 묶도록 요구하는 RFC-8259 사양을 준수하도록 엄격한 JSON 규칙을 적용합니다.
이러한 제한을 완화하려면 Json 인스턴스에서 isLenient 프로퍼티를 true로 설정하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
val format = Json { isLenient = true }
enum class Status { SUPPORTED }
@Serializable
data class Project(val name: String, val status: Status, val votes: Int)
fun main() {
// 관대한 파싱으로 JSON 문자열을 디코딩합니다.
// 관대한 파싱은 따옴표가 없는 키, 문자열 및 열거형 값을 허용합니다.
val data = format.decodeFromString<Project>("""
{
name : kotlinx.serialization,
status : SUPPORTED,
votes : "9000"
}
""")
println(data)
// Project(name=kotlinx.serialization, status=SUPPORTED, votes=9000)
}JSON과 Kotlin 간 이름 매핑 커스터마이징
일부 JSON 데이터는 Kotlin의 명명 규칙이나 예상 형식과 완벽하게 일치하지 않을 수 있습니다. 이러한 문제를 해결하기 위해 Kotlin serialization은 이름 불일치를 관리하고, 여러 JSON 프로퍼티 이름을 처리하며, 직렬화된 데이터 전반에 일관된 명명 전략을 적용할 수 있는 여러 도구를 제공합니다.
단일 Kotlin 프로퍼티에 대해 여러 JSON 프로퍼티 이름 허용
스키마 버전 간에 JSON 프로퍼티 이름이 변경되는 경우, @SerialName 어노테이션을 사용하여 JSON 프로퍼티 이름을 바꿀 수 있습니다.
그러나 이렇게 하면 이전 프로퍼티 이름을 여전히 사용하는 데이터를 디코딩할 수 없게 됩니다. 단일 프로퍼티에 대해 대체 가능한 여러 JSON 프로퍼티 이름을 허용하려면 @JsonNames 어노테이션을 사용하세요.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
// name과 title JSON 프로퍼티를 모두 name 프로퍼티에 매핑합니다.
data class Project(@JsonNames("title") val name: String)
fun main() {
val project = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""")
println(project)
// Project(name=kotlinx.serialization)
val oldProject = Json.decodeFromString<Project>("""{"title":"kotlinx.coroutines"}""")
// name과 title Json 프로퍼티가 모두 name 프로퍼티에 해당합니다.
println(oldProject)
// Project(name=kotlinx.coroutines)
}JsonBuilder의 useAlternativeNames 프로퍼티는 @JsonNames 어노테이션을 활성화합니다. 이 프로퍼티는 기본적으로 true로 설정되어 있어 Json이 단일 프로퍼티에 대한 여러 이름을 인식하고 디코딩할 수 있도록 합니다.
@JsonNames를 사용하지 않으며 성능을 개선하고 싶은 경우(특히 ignoreUnknownKeys로 수많은 알 수 없는 프로퍼티를 건너뛸 때), 이 프로퍼티를 false로 설정할 수 있습니다.
대소문자를 구분하지 않고 열거형 디코딩
Kotlin의 명명 규칙은 열거형 값을 대문자와 밑줄(SCREAMING_SNAKE_CASE) 또는 대문자 카멜 케이스(UpperCamelCase)로 작성하도록 권장합니다. 기본적으로 Json은 디코딩 시 Kotlin 열거형 상수의 정확한 이름을 사용합니다.
그러나 외부 소스의 JSON 데이터는 소문자나 혼합된 대소문자를 사용할 수 있습니다. 이러한 경우를 처리하려면 JsonBuilder.decodeEnumsCaseInsensitive 프로퍼티를 사용하여 대소문자를 구분하지 않고 열거형 값을 디코딩하도록 Json 인스턴스를 구성할 수 있습니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// 대소문자를 구분하지 않고 열거형 값을 디코딩하도록 Json 인스턴스를 구성합니다.
val format = Json { decodeEnumsCaseInsensitive = true }
enum class Cases { VALUE_A, @JsonNames("Alternative") VALUE_B }
@Serializable
data class CasesList(val cases: List<Cases>)
fun main() {
// 대체 이름을 포함하여 대소문자에 관계없이 열거형 값을 디코딩합니다.
println(format.decodeFromString<CasesList>("""{"cases":["value_A", "alternative"]}"""))
// CasesList(cases=[VALUE_A, VALUE_B])
}이 프로퍼티는 직렬 이름(serial names)과 @JsonNames 어노테이션으로 지정된 대체 이름 모두에 적용되어, 모든 값이 성공적으로 디코딩되도록 보장합니다. 이 프로퍼티는 인코딩에는 영향을 미치지 않습니다.
전역 명명 전략 적용
JSON 입력의 프로퍼티 이름이 Kotlin의 프로퍼티 이름과 다른 경우, @SerialName 어노테이션을 사용하여 각 프로퍼티의 이름을 명시적으로 지정할 수 있습니다. 그러나 다른 프레임워크나 레거시 코드베이스에서 마이그레이션할 때는 모든 직렬 이름을 동일한 방식으로 변환해야 할 수도 있습니다.
이러한 시나리오에서는 Json 인스턴스에서 JsonBuilder.namingStrategy 프로퍼티를 사용하여 전역 명명 전략을 지정할 수 있습니다. Kotlin serialization은 JsonNamingStrategy.SnakeCase와 같은 기본 제공 전략을 지원합니다.
// 직렬화 라이브러리의 선언들을 임포트합니다.
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
data class Project(val projectName: String, val projectOwner: String)
// SnakeCase 명명 전략을 적용하도록 Json 인스턴스를 구성합니다.
val format = Json { namingStrategy = JsonNamingStrategy.SnakeCase }
fun main() {
val project = format.decodeFromString<Project>("""{"project_name":"kotlinx.coroutines", "project_owner":"Kotlin"}""")
// 모든 직렬 이름이 카멜 케이스에서 스네이크 케이스로 변환된 것처럼 직렬화 및 역직렬화합니다.
println(format.encodeToString(project.copy(projectName = "kotlinx.serialization")))
// {"project_name":"kotlinx.serialization","project_owner":"Kotlin"}
}JsonNamingStrategy와 함께 전역 명명 전략을 사용할 때는 다음 사항을 유의하세요.
- 변환은 모든 프로퍼티에 적용됩니다. 직렬 이름이 프로퍼티 이름에서 파생되었든
@SerialName어노테이션으로 명시적으로 정의되었든 상관없이 적용됩니다. 직렬 이름을 지정한다고 해서 변환 대상에서 프로퍼티를 제외할 수는 없습니다. 직렬화 중에 특정 이름을 변경하지 않고 유지하려면 대신@JsonNames어노테이션을 사용하세요. - 변환된 이름이 변환된 다른 프로퍼티 이름이나
@JsonNames어노테이션으로 지정된 대체 이름과 충돌하는 경우, 역직렬화가 실패하고 예외가 발생합니다. - 전역 명명 전략은 암시적(implicit)입니다. 클래스 정의만 보고는 직렬화된 이름을 파악하기 어렵게 만듭니다. 이로 인해 IDE에서의 Find Usages(사용처 찾기), Rename(이름 변경) 또는
grep같은 도구를 사용한 전문 검색(full-text search) 작업이 더 까다로워져 버그 발생 위험과 유지보수 비용이 증가할 수 있습니다.
이러한 요소를 고려하여 애플리케이션에 전역 명명 전략을 도입하기 전에 트레이드오프(trade-off)를 면밀히 검토하세요.
다음 단계
- 데이터가 파싱되거나 직렬화되기 전에 JSON 데이터를 직접 조작하고 다루려면 고급 JSON 요소 처리를 살펴보세요.
- 데이터를 더 정밀하게 제어하려면 직렬화 및 역직렬화 중 JSON 변환 방법을 확인해 보세요.
