코틀린(Kotlin) 직렬화

이 페이지의 내용

개요

지원되는 유형
프로젝트에 코틀린(Kotlin) 직렬화를 추가합니다.
데이터 클래스에 어노테이션을 첨가합니다.
사용자 지정 직렬 변환기 예시
직렬 변환기 구성을 사용자 지정합니다.
사용자 지정 코덱 예시
다형성 직렬화
다형성 데이터 클래스 예시
날짜 및 시간 직렬화
kotlinx-datetime 라이브러리
날짜 및 시간이 있는 데이터 클래스 예시

개요

코틀린(Kotlin) 드라이버는 코틀린(Kotlin) 객체 직렬화 및 역직렬화를 위한 kotlinx.serialization 라이브러리를 지원합니다.

이 드라이버는 @Serializable 로 표시된 클래스와 함께 사용할 수 있는 효율적인 Bson 직렬화기를 제공하여 코틀린(Kotlin) 객체를 BSON 데이터로 직렬화하는 작업을 처리합니다.

bson-kotlinx 라이브러리를 설치하여 기본값을 인코딩하고, null을 인코딩하고, 클래스 판별자를 정의하는 구성으로 사용자 지정 코덱 을 지원할 수도 있습니다.

참고

코틀린( 코틀린 (Kotlin) ) 직렬화 라이브러리 대신 Codec 인터페이스를 사용하여 BSON 데이터에 대한 코틀린( 코틀린 (Kotlin) ) 객체의 사용자 지정 인코딩 및 디코딩을 지정하는 방법을 학습 보려면 코덱 가이드 를 참조하세요.

프레임워크에 이미 익숙하거나 관용적인 코틀린(Kotlin) 접근 방식을 선호하는 경우 코틀린(Kotlin) 직렬화를 선택할 수 있습니다.

코틀린(Kotlin) 드라이버를 코틀린(Kotlin) 직렬화 Json 라이브러리와 함께 사용할 수 있지만 Json 직렬 변환기는 ObjectId 같은 BSON 값 유형을 직접 지원하지 않습니다. BSON과 JSON 간의 변환을 처리할 수 있는 사용자 지정 직렬 변환기를 제공해야 합니다.

지원되는 유형

코틀린(Kotlin) 드라이버는 다음과 같이 지원합니다.

코틀린(Kotlin) 직렬화 라이브러리가 지원하는 모든 코틀린(Kotlin) 유형
사용 가능한 모든 BSON types

프로젝트에 코틀린(Kotlin) 직렬화를 추가합니다.

코틀린( 코틀린 (Kotlin) ) 운전자 의 직렬화 지원은 공식 코틀린( 코틀린 (Kotlin) ) 직렬화 라이브러리에 따라 달라집니다.

Gradle 및 Maven 패키지 관리자를 사용하여 프로젝트에 직렬화 종속성을 추가하는 방법을 보려면 다음 탭에서 선택합니다.

Gradle 을 사용하는 경우 종속성을 관리 하려면 build.gradle.kts 종속성 목록에 다음을 추가하세요.

build.gradle.kts

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("org.mongodb:bson-kotlinx:5.2.0")

Maven 을 사용하는 경우 종속성을 관리 하려면 pom.xml 종속성 목록에 다음을 추가하세요.

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-core</artifactId>
    <version>1.5.1</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.0</version>
</dependency>

데이터 클래스에 어노테이션을 첨가합니다.

클래스를 직렬화 가능으로 선언하려면 코틀린(Kotlin) 직렬화 프레임워크의 @Serializable 어노테이션을 사용하여 코틀린(Kotlin) 데이터 클래스에 주석을 첨가하면 됩니다.

데이터 클래스를 직렬화 가능으로 표시한 다음 코드에서 정상적으로 사용할 수 있습니다. 코틀린(Kotlin) 드라이버와 코틀린 직렬화 프레임워크는 BSON 직렬화 및 역직렬화를 처리합니다.

이 예에서는 다음과 같이 어노테이션이 첨가된 간단한 데이터 클래스를 보여줍니다.

@Serializable 클래스를 직렬화 가능으로 표시하려면
@SerialName BSON 문서에서 id 및 manufacturer 속성의 이름을 지정합니다. 직렬화 가능 클래스에서 지원되지 않는 @BsonId 및 @BsonProperty 어노테이션 대신 이를 사용할 수 있습니다.
@Contextual 내장된 ObjectIdSerializer 을 사용하는 데 BSON id 속성을 표시합니다. 이와 같은 어노테이션은 BSON types이 제대로 직렬화되는 데 필요합니다.

@Serializable
data class PaintOrder(
    @SerialName("_id") // Use instead of @BsonId
    @Contextual val id: ObjectId?,
    val color: String,
    val qty: Int,
    @SerialName("brand")
    val manufacturer: String = "Acme" // Use instead of @BsonProperty
)

참고

패키지의 어노테이션 org.bson.codecs.pojo.annotations 데이터 클래스에 사용할 수 없습니다.@Serializable

직렬화 가능한 클래스와 사용 가능한 어노테이션 클래스에 대한 자세한 내용은 official Kotlin Serialization 문서를 참조합니다.

사용자 지정 직렬 변환기 예시

사용자 지정 직렬 변환기를 생성하여 BSON에서 데이터가 표시되는 방식을 처리할 수 있습니다. 코틀린 드라이버는 kotlinx.serialization 패키지의 KSerializer 인터페이스를 사용하여 사용자 지정 직렬 변환기를 구현합니다. 특정 필드에 대한 @Serializable 주석에 대한 매개변수로 사용자 지정 직렬 변환기를 지정할 수 있습니다.

다음 예에서는 kotlinx.datetime.Instant를 BsonDateTime으로 변환하기 위해 사용자 지정 KSerializer 인스턴스를 만드는 방법을 보여 줍니다.

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilliseconds()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.fromEpochMilliseconds(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

다음 코드는 orderDate 필드에 이전 코드에 정의된 사용자 지정 직렬 변환기 클래스를 지정하는 주석이 있는 PaintOrder 데이터 클래스를 보여 줍니다.

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

이 섹션에 언급된 메서드 및 클래스에 대한 자세한 내용은 다음 API 문서를 참조하세요.

직렬 변환기 구성을 사용자 지정합니다.

KotlinSerializerCodec org.bson.codecs.kotlinx 패키지의 클래스를 사용하여 @Serializable 데이터 클래스에 대한 코덱을 생성하고 저장되는 내용을 사용자 지정할 수 있습니다.

BsonConfiguration 클래스를 사용하여 기본값을 인코딩할지, null을 인코딩할지 또는 클래스 판별자를 정의할지 여부 등 구성을 정의합니다.

사용자 지정 코덱을 생성하려면 프로젝트에 bson-kotlinx 종속성을 설치합니다. Gradle 및 Maven 패키지 관리자를 사용하여 프로젝트에 종속성을 추가하는 방법을 보려면 다음 탭 중에서 선택합니다.

Gradle 을 사용하는 경우 종속성을 관리 하려면 build.gradle.kts 종속성 목록에 다음을 추가하세요.

build.gradle.kts

implementation("org.mongodb:bson-kotlinx:5.2.0")

Maven 을 사용하는 경우 종속성을 관리 하려면 pom.xml 종속성 목록에 다음을 추가하세요.

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.0</version>
</dependency>

참고

bson-kotlin 종속성

기본 코덱 레지스트리를 통해 bson-kotlin 종속성을 선택적으로 설치할 수도 있습니다. 이 종속성은 리플렉션과 코덱 레지스트리를 사용하여 Kotlin 데이터 클래스를 지원하지만 BsonDiscriminator, BsonExtraElements 및 BsonConstructor 과 같은 특정 POJO 주석은 지원하지 않습니다. 자세한 내용은 bson-kotlin API 설명서를 참조하세요.

일반적으로 코덱 구성을 위해 조뮤더 빠른 bson-kotlinx 라이브러리를 설치하고 사용하는 것이 좋습니다.

그런 다음 KotlinSerializerCodec.create() 를 사용하여 코덱을 정의할 수 있습니다 메서드를 호출하여 이를 레지스트리에 추가합니다.

사용자 지정 코덱 예시

다음 예시에서는 KotlinSerializerCodec.create() 메서드를 사용하여 코덱을 생성하고 기본값을 인코딩하지 않도록 구성하는 방법을 설명합니다.

import org.bson.codecs.configuration.CodecRegistries
import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.KotlinSerializerCodec

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

이 섹션에 언급된 메서드 및 클래스에 대한 자세한 내용은 다음 API 문서를 참조하세요.

다형성 직렬화

코틀린( 코틀린 (Kotlin) ) 운전자 는 기본적으로 다형성 클래스의 직렬화 및 역직렬화를 지원합니다. 봉인된 인터페이스와 해당 인터페이스를 상속하는 데이터 클래스를 @Serializable 주석으로 표시하면 운전자 는 KSerializer 구현 을 사용하여 BSON 과의 유형 변환을 처리하다 합니다.

다형성 데이터 클래스의 인스턴스 를 MongoDB 에 삽입하면 운전자 는 판별자 필드 인 _t 필드 를 추가합니다. 이 필드 의 값은 데이터 클래스 이름입니다.

다형성 데이터 클래스 예시

다음 예시 에서는 인터페이스와 해당 인터페이스를 상속하는 두 개의 데이터 클래스를 만듭니다. 데이터 클래스에서 id 필드 는 데이터 클래스 에 주석 달기 섹션에 설명된 주석으로 표시됩니다.

@Serializable
sealed interface Person {
    val name: String
}
@Serializable
data class Student(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val grade: Int,
) : Person
@Serializable
data class Teacher(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val department: String,
) : Person

그런 다음 평소와 같이 데이터 클래스로 작업을 수행할 수 있습니다. 다음 예시 에서는 Person 인터페이스를 사용하여 컬렉션 을 매개변수화한 다음 다형성 클래스 Teacher 및 Student 를 사용하여 작업을 수행합니다. 문서를 조회 할 때 운전자 는 판별자 값을 기반으로 유형을 자동으로 감지하고 그에 따라 역직렬화합니다.

val collection = database.getCollection<Person>("school")
val teacherDoc = Teacher(ObjectId(), "Vivian Lee", "History")
val studentDoc = Student(ObjectId(), "Kate Parker", 10)
collection.insertOne(teacherDoc)
collection.insertOne(studentDoc)
println("Retrieving by using data classes")
collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .first().also { println(it) }
collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .first().also { println(it) }
println("\nRetrieving by using Person interface")
val resultsFlow = collection.withDocumentClass<Person>().find()
resultsFlow.collect { println(it) }
println("\nRetrieving as Document type")
val resultsDocFlow = collection.withDocumentClass<Document>().find()
resultsDocFlow.collect { println(it) }

Retrieving by using data classes
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interface
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document type
Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

날짜 및 시간 직렬화

이 섹션에서는 코틀린 (Kotlin) 직렬화를 사용하여 날짜 및 시간 유형으로 작업하는 방법에 학습 수 있습니다.

kotlinx-datetime 라이브러리

kotlinx-datetime 날짜 및 시간 값이 직렬화되는 방식을 높은 수준으로 제어할 수 있는 코틀린 (Kotlin) 라이브러리입니다. 라이브러리를 사용하려면 프로젝트의 종속성 목록에 kotlinx-datetime 종속성을 추가합니다.

다음 탭에서 선택하여 Gradle 및 Maven 패키지 관리자를 사용하여 프로젝트 에 kotlinx-datetime 종속성을 추가하는 방법을 확인합니다.

build.gradle.kts

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.6.1</version>
</dependency>

이 라이브러리에 학습 보려면 kotlinx-datetime 리포지토리 를 Github 참조하세요. 에서 .

날짜 및 시간이 있는 데이터 클래스 예시

라이브러리 종속성을 추가한 후 데이터 클래스 필드 값을 BSON 의 예상 유형에 매핑하는 직렬 변환기를 kotlinx-datetime 라이브러리에서 구현 수 있습니다.

이 예시 에서 운전자 는 다음 동작을 사용하여 Appointment 데이터 클래스의 필드를 직렬화합니다.

name: 운전자 가 값을 string 로 직렬화합니다.
date: 필드 에 @Contextual 주석이 있으므로 운전자 가 kotlinx-datetime 직렬 변환기를 사용합니다. LocalDate 값은 BSON 날짜로 직렬화됩니다.
time: @Contextual 주석이 없기 때문에 운전자 가 값을 string 로 직렬화합니다. 이는 LocalTime 값에 대한 기본값 직렬화 동작입니다.

@Serializable
data class Appointment(
    val name: String,
    @Contextual val date: LocalDate,
    val time: LocalTime,
)

다음 예시 에서는 Appointment 데이터 클래스의 인스턴스 를 appointments 컬렉션 에 삽입합니다.

val collection = database.getCollection<Appointment>("appointments")
val apptDoc = Appointment(
    "Daria Smith",
    LocalDate(2024, 10, 15),
    LocalTime(hour = 11, minute = 30)
)
collection.insertOne(apptDoc)

MongoDB 에서 LocalDate 값은 BSON 날짜로 저장되고 time 필드 는 직렬화 기본값 string 로 저장됩니다.

{
  "_id": ...,
  "name": "Daria Smith",
  "date": {
    "$date": "2024-10-15T00:00:00.000Z"
  },
  "time": "11:30",
}

돌아가기

문서

코덱