kotlinx.serialization 1.2 출시: 고속 JSON 처리, value 클래스 지원, 새롭게 개편된 문서 등 다양한 개선 사항 제공

Jessie Cho

Read this post in other languages:

• English
,
• Deutsch
,
• Español
,
• Français
,
• 日本語
,
• Русский
,
• 简体中文
,
• Português do Brasil

kotlinx.serialization 1.2가 출시되었습니다! 최신 버전의 멀티 플랫폼 직렬화 라이브러리가 여러 가지 개선 사항을 제공합니다. 주요 내용은 다음과 같습니다.

• JSON 직렬화가 그 어느 때보다 빨라졌습니다. 버전 1.2는 JSON을 유형이 안전한 Kotlin 객체로 분석하고 Kotlin 객체를 텍스트 표현으로 변환할 때 이전 버전보다 최대 2배 빨라졌습니다.
• 이제 Kotlin 1.5 유형 시스템 추가가 지원됩니다. value 클래스와 부호 없는 숫자를 다른 Kotlin 클래스와 마찬가지로 JSON으로 변환할 수 있습니다.
• 새 API 문서를 사용하면 kotlinx.serialization이 제공하는 모든 기능을 쉽게 찾을 수 있습니다.

버전 1.2에는 JSON 필드의 대체 이름에 대한 새로운 지원이 포함되었으며, Kotlin 클래스에서 Protobuf 스키마를 자동으로 생성하는 새로운 실험적 접근 방식을 제공합니다. 이 부분에서 여러분의 많은 의견을 기다립니다!

이 새 버전의 변경 사항과 추가 사항을 살펴보겠습니다! 물론, 이미 기능에 대한 확신이 든다면 아래 업그레이드 지침으로 바로 이동하여 확인해 주세요!

kotlinx.serialization 1.2 사용하기!

Kotlin YouTube 구독하기!

그 어느 때보다 빠른 JSON 인코딩 및 디코딩

Kotlin 클래스를 JSON 문자열로 인코딩하는 기능과 JSON 문자열을 Kotlin 클래스로 변환하는 기능은 kotlinx.serialization에서 가장 일반적으로 사용되는 기능이며, 이를 개선하기 위해 지속적으로 노력하고 있습니다.

버전 1.2는 kotlinx.serialization의 내부 구조를 완전히 개편하여 이 핵심 기능의 성능을 크게 향상시켰습니다. JSON 디코더(텍스트를 Kotlin 객체로 변환하는 역할)를 다시 작성하고 JSON 인코더(Kotlin 객체를 텍스트로 변환하는 역할)를 크게 최적화했습니다.

최신 버전의 라이브러리로 업그레이드하기만 하면 일반적인 인코딩 및 디코딩 작업의 속도를 최대 두 배까지 높일 수 있습니다. (보시다시피 이러한 새로운 최적화의 영향을 받은 내부 벤치마크 중 일부는 이 수치를 넘어섭니다!)

이러한 변경으로 kotlinx.serialization은 별도 설정없이 바로 사용할 수 있는 다른 JSON 라이브러리와 동등한 성능을 발휘합니다(어떤 면에서는 이를 능가함). 매우 간단한 스니펫도 이 개편의 이점을 얻을 수 있습니다.

@Serializable
data class User(val name: String, val yearOfBirth: Int)

fun main() {
// Faster encoding...
val data = User("Louis", 1901)
val string = Json.encodeToString(data)
println(string) // {"name":"Louis","yearOfBirth":1901}

// ...and faster decoding!
val obj = Json.decodeFromString(string)
println(obj) // User(name=Louis, yearOfBirth=1901)
}

이러한 개선 사항을 체감하기에 가장 좋은 방법은 최신 버전의 라이브러리로 자신의 애플리케이션을 벤치마크하는 것입니다. 대략적인 성능 수치를 알아보려면 인코딩 및 디코딩에 대한 내부 벤치마크를 살펴볼 수 있습니다. 여기에는 최신 버전의 kotlinx.serialization을 이전 릴리스와 비교한 내용이 담겨 있습니다.

value 클래스 및 부호 없는 숫자 유형에 대한 안정적인 JSON (역)직렬화

Kotlin 1.5.0은 value 클래스 및 부호 없는 정수 유형의 두 가지 흥미로운 추가 기능을 제공햐며, 이를 위해 kotlinx.serialization 1.2는 이제 최고 수준의 JSON 인코딩 및 디코딩 지원을 제공합니다. 좀 더 자세히 살펴보겠습니다.

value 클래스 지원

value 클래스(이전에 inline 클래스라고 부름)는 추가 런타임의 오버헤드없이 유형에 안전한 방식으로 다른 Kotlin 유형(예를 들어, 숫자)을 래핑하는 방법을 제공합니다. 이를 통해 성능 저하 없이 프로그램을 보다 표현적이고 안전하게 만들 수 있습니다.

이제 kotlinx.serialization의 기본 제공 JSON 직렬화는 value 클래스에서 작동합니다. 다른 Kotlin 클래스와 마찬가지로 @Serializable로 value 클래스에 어노테이션을 추가하면 됩니다.

@Serializable
value class Color(val rgb: Int)

value 클래스는 기본 유형으로 직접 저장(및 직렬화)됩니다. 직렬화 가능한 data 클래스에 value 클래스 유형의 필드를 추가하고 그 출력을 검사하여 이를 확인할 수 있습니다.

@Serializable
data class NamedColor(val color: Color, val name: String)

fun main() {
println(Json.encodeToString(NamedColor(Color(0), "black")))
}

// {"color": 0, "name": "black"}

위의 예에서 NamedColor는 value 클래스 Color를 기본 요소(Int)로 취급합니다. 즉, Kotlin 코드 내에서 최대의 유형 안전성을 누리면서 불필요한 박싱이나 중첩 없이도 이러한 유형의 간결한 직렬화된 표현의 이점을 누릴 수 있습니다.

value 클래스에 적합하게 직접 작성한 사용자 지정 직렬 변환기의 디자인을 개선하고 있으며 현재로서는 실험적 단계입니다. 이 주제에 대한 자세한 내용은 GitHub 문서에서 찾을 수 있습니다.

부호 없는 정수 지원

부호 없는 정수는 Kotlin 표준 라이브러리에 추가되었으며 음수가 아닌 숫자에 대한 유형과 연산을 제공합니다. Kotlin 1.5.0 출시와 함께 다음과 같은 부호 없는 숫자 유형을 사용할 수 있습니다.

• UByte, 값 범위는 0에서 255
• UShort, 값 범위는 0에서 65535
• UInt, 값 범위는 0 ~ 2^32 – 1
• ULong, 값 범위는 0 ~ 2^64 – 1

이제 kotlinx.serialization의 JSON 인코더 및 디코더가 이러한 유형을 별도의 설정 없이 바로 사용할 수 있도록 지원합니다. 다른 숫자 유형과 마찬가지로 부호 없는 정수 값은 자르기, 줄바꿈 또는 부호 있는 유형으로의 변환 없이 일반 숫자 표현(.toString 호출시 표시되는 것과 동일한 표현)으로 직렬화됩니다.

@Serializable
class Counter(val counted: UByte, val description: String)

@Serializable
class BigCounter(val counted: ULong)

val counted = 239.toUByte()
println(Json.encodeToString(Counter(counted, "tries")))
// {"counted":239,"description":"tries"}

println(Json.encodeToString(BigCounter(ULong.MAX_VALUE)))
// {"counted":18446744073709551615}

value 클래스 및 부호 없는 정수에 대한 지원은 현재 JSON에 사용할 수 있는 점을 유의해 주세요. 향후 릴리스에서는 CBOR 및 Protobuf에 대한 직접 통합도 제공할 예정입니다. 계속 지켜봐주세요!

kotlinx.serialization 및 Kotlin 프로그래밍 언어의 향후 릴리스에 대한 최신 정보를 지속적으로 받으려면 이 블로그 게시물 옆에 있는 양식을 작성하여 Kotlin 제품 업데이트 뉴스레터를 구독하세요!

kotlinx.serialization과 함께 value 클래스 및 부호 없는 유형을 사용하는 방법에 대한 자세한 내용은 GitHub 문서를 살펴보세요.

JSON 필드에 대한 대체 이름 지원

예를 들어, 이전 버전과의 호환성을 유지하기 위해 이름은 다르지만 의미는 동일한 JSON 필드를 구문 분석해야 하는 경우가 있을 수 있습니다. 새로운 @JsonNames 어노테이션을 사용하여 이제 JSON 필드에 대체 이름을 지정할 수 있으며, 디코딩 프로세스 중에 이 이름이 사용됩니다.

이를 설명하기 위해 예를 살펴보겠습니다. 버전에 따라 서버가 다음 두 가지 응답 중 하나를 제공한다고 가정해 보겠습니다.

{"name":"kotlinx.serialization"}
/* ...or: */
{"title":"kotlinx.serialization"}

name과 title은 모두 동일한 의미를 가지며 Kotlin 클래스의 동일한 필드에 이를 매핑하려고 합니다. 새로운 @JsonNames 어노테이션을 사용하여 name 키의 대체 키로 title을 지정할 수 있습니다.

@Serializable
data class Project(@JsonNames("title") val name: String)

인코딩과 디코딩 모두에 대해 필드 이름을 변경할 수 있지만 대안을 지정할 수는 없는 @SerialName 어노테이션과 어떤 차이가 있는지 확인해 주세요.

이 기능을 통해 동일한 값을 나타내는 이름 필드를 다르게 반환하고 스키마 마이그레이션 후에도 남아 있으며 애플리케이션에 단계적인 업그레이드를 제공하는 서비스를 보다 쉽게 ​​사용할 수 있기를 바랍니다.

새로운 API 문서

kotlinx.serialization을 최대한 편안하고 재미 있게 학습할 수 있도록 다양한 참조 자료를 제공하려고 노력하고 있습니다. 그 중 하나가 GitHub의 Kotlin 직렬화 가이드입니다. 이 가이드에서는 라이브러리에서 제공하는 기능을 단계별로 안내하고, 각 기능에 대한 직관적인 이해를 제공하는 모든 요소가 완비된 예제도 포함되어 있습니다.

또 하나는 완전히 새롭게 개편된 kotlinx.serialization API 문서입니다. Kotlin 문서 엔진인 Dokka의 새 버전을 기반으로 하는 새로운 API 문서는 빠르게 반응하는 새롭고 현대적인 디자인과 심볼을 이용한 간편한 탐색 방법을 제공합니다.

새로운 kotlinx.serialization API 문서를 살펴보세요!

Protobuf: Kotlin 클래스에서 실험적인 스키마 생성

프로토콜 버퍼(Protobuf)는 Google이 만든 구조화된 데이터를 위한 바이너리 직렬화 형식입니다. 이는 바이너리 형식으로서 JSON 또는 XML보다 공간 효율적이면서 여전히 애플리케이션 간 정보 소통에 사용할 수 있는 언어에 구애받지 않는 구조를 제공합니다.

kotlinx.serialization을 통해 실험적 안정성으로 멀티 플랫폼 Protobuf 직렬화(proto2 의미 체계 사용)를 사용할 수 있습니다. 다른 형식과 마찬가지로 클래스에 @Serializable로 어노테이션을 추가하고 기본 제공 encode / decode 메서드를 사용합니다.

@Serializable
data class Project(val name: String, val language: String)

fun main() {
val data = Project("kotlinx.serialization", "Kotlin")
val bytes = ProtoBuf.encodeToByteArray(data)
println(bytes.toAsciiHexString())
val obj = ProtoBuf.decodeFromByteArray(bytes)
println(obj)
}

Kotlin 클래스를 진실 공급원(source of truth)으로 삼아(적용해야 할 수 있는 모든 사용자 지정과 함께) kotlinx.serialization은 데이터의 바이너리 스키마를 추론함으로써 여러 Kotlin 애플리케이션 간의 Protobuf 커뮤니케이션을 간결하고 편리하게 만들어줍니다.

kotlinx.serialization 1.2에는 이제 실험적인 프로토콜 버퍼용 스키마 생성기도 포함됩니다. 이를 통해 Kotlin 데이터 클래스에서 .proto 파일을 생성할 수 있으며, 이 파일은 Python, C ++, TypeScript를 비롯한 다른 언어로 된 커뮤케이션 스키마 표현을 생성하는 데 사용할 수 있습니다.

새 스키마 생성기를 시작하는 방법에 대한 내용은 문서의 해당 지침을 확인해 주세요.

.proto 파일이 생성되면 저장소에 저장하고 이를 사용하여 다른 언어로 된 Kotlin 클래스 표현을 생성할 수 있습니다. 이렇게 하면 스키마를 Kotlin 소스 코드에서 직접 관리하는 편리함을 포기하지 않고도 여러 언어로 된 애플리케이션에서 kotlinx.serialization의 Protobuf 통합을 더 쉽게 사용할 수 있게 될 것으로 기대합니다.

이번이 Protobuf 스키마 생성기의 첫 개발 시도이므로 여러분의 많은 의견이 필요합니다. 한 번 사용해 보고 모델과 .proto 파일을 관리하는 방법, 발생한 문제 및 희망하는 기능 등의 사용 경험을 GitHub 이슈 트래커를 이용하여 알려주세요.

스키마 생성기로 작업할 때 몇 가지 제한 사항을 염두에 두세요. 일반적으로, Kotlin 클래스를 kotlinx.serialization에 포함된 protobuf 구현으로 직렬화할 수 있는 경우, 스키마 생성기가 이를 지원합니다. 이는 동일한 제한 사항이 적용된다는 의미도 됩니다. 주의해야 할 몇 가지 사항은 다음과 같습니다.

• Kotlin 클래스 및 프로퍼티 이름은 protobuf 사양을 준수해야 하며 금지된 문자를 포함하지 않아야 합니다.
• Kotlin의 null 값 가능성은 스키마에 반영되지 않습니다(proto2에 해당 의미 체계가 없기 때문). 프로토콜 버퍼에서 제공하는 선택 필드는 Kotlin 프로퍼티가 디폴트 값을 정의하는지 여부에 따라 사용됩니다.
• Kotlin 디폴트 값은 스키마에 포함되지 않습니다. (즉, 다른 언어 구현에서 디폴트 값의 일관성을 직접 확인해야 합니다.)

kotlinx.serialization 1.2를 사용해 보세요!

이것으로 개요 소개를 마칩니다! 더 빠른 JSON 인코딩 및 디코딩, Kotlin 1.5 유형 시스템 추가 지원, Protobuf 스키마 생성 등을 즐길 준비가 되었다면 이제 업그레이드를 할 때입니다!

이미 kotlinx.serialization을 사용하고 있는 경우, 버전 1.2로 업그레이드하는 과정이 매우 빠릅니다. 이전에 kotlinx.serialization을 사용한 적이 없다면 지금이 시작하기에 좋은 시기입니다! 먼저, build.gradle.kts 파일에서 plugins 블록을 업데이트하세요.

plugins {
kotlin("jvm") version "1.5.0" // or kotlin("multiplatform") or any other kotlin plugin
kotlin("plugin.serialization") version "1.5.0"
}

그런 다음 애플리케이션에서 사용하려는 형식을 포함하여 런타임 라이브러리로 dependencies 블록을 업데이트하세요.

dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-protobuf:1.2.0")
// . . .
}

동영상 및 읽을거리

• kotlinx.serialization 1.2 동영상
• GitHub의 라이브러리
• kotlinx.serialization 가이드
• API 문서
• Kotlin 1.5.0 릴리스 블로그 게시물

문제가 발생한 경우,

• GitHub 이슈 트래커에 이슈 보고해 주세요.
• Kotlin Slack의 #serialization 채널에서 도움을 요청하세요(초대 받기).

Kotlin YouTube를 구독하세요! (역)직렬화로 즐거운 시간 보내세요!

이 게시물은 Sebastian Aigner가 작성한 kotlinx.serialization 1.2 Released: High-Speed JSON Handling, Value Class Support, Overhauled Docs, and more를 번역한 글입니다.

Subscribe to Kotlin Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

이 양식을 제출함으로써 본인은 JetBrains s.r.o.("JetBrains"가 본인의 이름, 이메일 주소 및 위치 데이터를 사용하여 상업적 커뮤니케이션을 포함한 뉴스레터를 보내고 이러한 목적으로 개인 데이터를 처리할 수 있음에 동의합니다. 본인은 JetBrains가 JetBrains 개인정보보호정책에 따라 이러한 목적으로 제3자 서비스를 사용하여 해당 데이터를 처리할 수 있음에 동의합니다. 본인은 내 프로필에서 언제든지 이 동의를 철회할 수 있음을 이해합니다. 또한 각 이메일에는 수신 거부 링크가 포함됩니다.

Submit

감사합니다!