Вышла библиотека kotlinx.serialization 1.2: быстрая обработка JSON, поддержка классов значений, переработанная документация и многое другое

Sebastian Aigner

Read this post in other languages:

• English
,
• Deutsch
,
• Español
,
• Français
,
• 日本語
,
• 한국어
,
• 简体中文
,
• Português do Brasil

Представляем библиотеку kotlinx.serialization 1.2! Мы внесли ряд улучшений в новую версию мультиплатформенной библиотеки сериализации:

• Cериализация в JSON теперь работает гораздо быстрее. В версии 1.2 парсинг JSON в типобезопасные объекты Kotlin и преобразование объектов Kotlin в их текстовые представления может осуществляться вдвое быстрее.
• Появилась поддержка новых элементов системы типов Kotlin 1.5. Классы значений и числа без знака можно преобразовать в JSON и обратно точно так же, как любой другой класс Kotlin.
• Новая документация API упрощает изучение возможностей kotlinx.serialization.

Кроме того, в версии 1.2 добавлена поддержка альтернативных имен полей JSON и реализован новый экспериментальный подход с автоматическим созданием схем Protobuf из классов Kotlin. Мы очень ждем от вас отзывов об этой новой функции!

Теперь давайте подробно разберем новые и улучшенные возможности этой версии. А если вы уже готовы использовать ее в работе, просто переходите к инструкциям по обновлению версии в конце статьи.

Начать использовать kotlinx.serialization 1.2

Подписывайтесь на канал Kotlin в YouTube!

Ускоренное кодирование и декодирование JSON

Преобразование классов Kotlin в строки JSON и обратно — одни из самых популярных функций 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.

Стабильная (де)сериализация в JSON для классов значений и типов чисел без знака

В Kotlin 1.5.0 появились два полезных дополнения: классы значений и типы чисел без знака. Версия kotlinx.serialization 1.2 обеспечивает для них полную поддержку кодирования и декодирования JSON. Давайте рассмотрим ее подробнее.

Поддержка классов значений

Классы значений (раньше они назывались inline-классы) — это способ обертывания объектов Kotlin другого типа (например, чисел) типобезопасным образом и без дополнительной нагрузки при выполнении кода. Таким образом код можно сделать более выразительным и безопасным, не теряя в производительности.

Встроенная в kotlinx.serialization сериализация в JSON теперь работает и с классами значений. Как и для других классов Kotlin classes, достаточно просто добавить к классу значений аннотацию @Serializable.

@Serializable
value class Color(val rgb: Int)

Классы значений хранятся (и сериализуются) непосредственно как их базовый тип. Чтобы увидеть это, можно добавить поле с типом value class (класс значений) к сериализуемому классу данных — data class — и посмотреть выведенный результат:

@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 class Color как базовый примитив (тип Int). Благодаря этому обеспечивается максимальная типобезопасность кода Kotlin и одновременно компактное сериализованное представление этих типов без ненужного преобразования их в объекты или вложенного кода.

Структуру для написанных вручную пользовательских сериализаторов классов значений мы еще дорабатываем, поэтому они пока остаются в статусе экспериментальных. Подробнее об этом можно прочитать в документации на GitHub.

Поддержка чисел без знака

Числа без знака — это функциональность, добавленная в стандартную библиотеку Kotlin. Они обеспечивают типы и операции с неотрицательными числами. После выхода Kotlin 1.5.0 пользователям доступны следующие типы чисел без знака:

• UByte со значениями от 0 до 255;
• UShort со значениями от 0 до 65535;
• UInt, со значениями от 0 до 2^32 – 1;
• ULong, со значениями от 0 до 2^64 – 1.

Кодер и декодер JSON в библиотеке kotlinx.serialization теперь по умолчанию поддерживают эти типы. Как и другие типы чисел, значения целых чисел без знака сериализуются в простом числовом представлении (так же, как при вызове .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}

Обратите внимание: в настоящее время поддержка классов значений и чисел обеспечена для JSON. В будущих версиях мы добавим прямую интеграцию с CBOR и Protobuf. Следите за новостями!

Если вы хотите получать актуальную информацию о будущих релизах библиотеки kotlinx.serialization и языка программирования Kotlin, подпишитесь на рассылку новостей о продуктах Kotlin, заполнив форму рядом со статьей.

Подробную информацию об использовании классов значений и типов чисел без знака с библиотекой kotlinx.serialization вы найдете в документации на GitHub.

Поддержка альтернативных имен полей JSON

Иногда приходится анализировать поля JSON, имеющие разные имена, но одинаковые значения, например, для обеспечения обратной совместимости. Новая аннотация @JsonNames позволяет присваивать полям JSON альтернативные имена, которые будут использоваться при декодировании.

В качестве иллюстрации рассмотрим следующий пример. Предположим, что, в зависимости от версии, сервер дает нам один из двух вариантов ответа:

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

И name, и title имеют одинаковое значение, и мы хотим сопоставить их с одним полем в классе Kotlin. Используя новую аннотацию @JsonNames, можно указать title как альтернативу для ключа name:

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

Обратите внимание на отличие от аннотации @SerialName: она позволяет переименовать поля для кодирования и декодирования, но не позволяет указать альтернативные варианты.

Надеемся, что эта возможность упростит работу с сервисами, которые возвращают для одних и тех же значений поля с разными именами, поможет осуществить миграцию схем и сделать обновления ваших приложений контролируемыми.

Новая документация по API

Чтобы изучать библиотеку kotlinx.serialization было удобно и интересно, мы подготовили ряд справочных материалов. Один из них — Руководство по сериализации Kotlin на GitHub. Там дан обзор всех возможностей библиотеки и приведены самостоятельные примеры, которые помогут разобраться с каждой функцией.

Другой — полностью переработанная документация по API библиотеки kotlinx.serialization. Она создана на основе новой версии Dokka — инструмента для документирования кода Kotlin, — имеет удобную современную структуру и снабжена понятными значками навигации.

Посмотреть новую документацию по API kotlinx.serialization

Protobuf: экспериментальное создание схем из классов Kotlin

Protocol Buffers (Protobuf) — двоичный формат сериализации структурированных данных, разработанный Google. Естественно, бинарный формат экономичнее, чем JSON или XML, при этом он так же обеспечивает независимую от языка структуру, которую можно использовать для коммуникации между приложениями.

Библиотека kotlinx.serialization позволяет использовать мультиплатформенную сериализацию Protobuf (с семантикой proto2) в режиме экспериментальной стабильности. Как и при работе с другими форматами, класс можно аннотировать как @Serializable и использовать встроенные методы encode / decode methods:

@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 как источник истины (вместе с возможными индивидуальными настройками), kotlinx.serialization может создавать двоичную схему данных, чтобы коммуникация между различными приложениями Kotlin в формате Protobuf была лаконичной и удобной.

Кроме того, kotlinx.serialization 1.2 включает в себя экспериментальный генератор схем для Protocol Buffers. Он позволяет создавать из классов данных Kotlin файлы .proto, которые затем можно использовать для создания представлений схемы коммуникации в других языках, в том числе Python, C++ и TypeScript.

Инструкции по работе с новым генератором схемы приведены в документации.

После создания файла .proto его можно сохранить в репозитории и использовать для создания представлений классов Kotlin в других языках. Мы надеемся, что теперь использовать интеграцию kotlinx.serialization с Protobuf в многоязычных приложениях станет проще, и вам не придется жертвовать удобным управлением схемами прямо в исходном коде Kotlin.

Это первая версия генератора схем Protobuf, поэтому нам особенно важно знать, что вы о нем думаете. Пожалуйста, попробуйте с ним поработать и расскажите нам в баг-трекере GitHub, как вы его использовали, как управляли моделями и файлами .proto, с какими проблемами столкнулись и каких функций вам не хватает.

Используя генератор схем, не забывайте о его ограничениях. Как правило, если класс Kotlin можно сериализовать, используя возможности protobuf, реализованные в библиотеке kotlinx.serialization, значит, генератор схем его поддерживает. В то же время это значит, что здесь действуют те же ограничения. Вот на что следует обращать внимание:

• классы и имена свойств Kotlin должны соответствовать спецификации protobuf и не должны содержать запрещенных символов;
• допустимость значения null в Kotlin не отражена в схеме, потому что в proto2 нет соответствующей семантики. Дополнительные поля, основанные на Protocol Buffers, используются в зависимости от того, определены ли значения по умолчанию в свойствах Kotlin;
• значения по умолчанию Kotlin не включены в схему. Это означает, что вам необходимо самостоятельно обеспечить последовательность значений по умолчанию для разных языков.

Начинаем работу с kotlinx.serialization 1.2!

На этом наш обзор завершен. Если вы уже готовы перейти к более быстрому кодированию и декодированию JSON, а также использовать поддержку системных дополнений типа Kotlin 1.5, создание схем Protobuf и другие новые возможности, переходите на новую версию.

Если вы уже используете kotlinx.serialization, переход на версию 1.2 будет очень быстрым, а если вы еще не работали с этой библиотекой, сейчас самое время начать. Сначала обновите блок plugins в файле build.gradle.kts:

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.
• Обратитесь за помощью в канале #serialization в Kotlin Slack (воспользуйтесь приглашением).

Подписывайтесь на канал Kotlin в YouTube!! Удачной (де)сериализации!

Ваша команда Kotlin
The Drive to Develop

Subscribe to Kotlin Blog updates

Subscribe form

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

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!