Libraries

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

Read this post in other languages:
English, Français, 日本語, 한국어, Deutsch, Português do Brasil, Español, 简体中文

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

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

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

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

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

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

Преобразование классов Kotlin в строки JSON и обратно — одни из самых популярных функций kotlinx.serialization, поэтому мы постоянно работаем над улучшением их производительности.

Анализ JSON с помощью kotlinx.serialization: до 55 процентов быстрее

В версии 1.2 внутренняя структура библиотеки kotlinx.serialization была полностью переработана, и в результате производительность двух этих важнейших функций значительно выросла. Мы переписали декодер JSON (который отвечает за преобразование текста в объекты Kotlin) и существенно оптимизировали кодер JSON (отвечает за преобразование объектов Kotlin в текст).

Кодирование JSON с помощью kotlinx.serialization: до 339 процентов быстрее

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

Благодаря этим изменениям kotlinx.serialization без дополнительной настройки обеспечивает не менее (а иногда и более) высокую производительность, чем другие библиотеки JSON. Изменения повлияли даже на самые простые примеры:

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

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

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

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

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

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

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

В приведенном выше примере 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), без обрезки, переноса или преобразования в тип со знаком.

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

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

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

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

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

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

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

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

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

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

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

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

Пример новой документации по API — документация JsonElement

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

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

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

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

Используя классы 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:

Затем добавьте в блок dependencies рантайм-библиотеку, включающую форматы, которые нужны вам в вашем приложении:

Рекомендуемые материалы

Если вы столкнулись с проблемами

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

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

Discover more