Lançamento da kotlinx.serialization 1.2: tratamento de JSON de alta velocidade, suporte para value classes, documentos revisados e muito mais

Luiz Di Bella

Read this post in other languages:

• English
,
• Deutsch
,
• Español
,
• Français
,
• 日本語
,
• 한국어
,
• Русский
,
• 简体中文

A kotlinx.serialization 1.2 já está disponível! A versão mais recente da nossa biblioteca de serialização multiplataforma traz uma série de melhorias. Aqui estão os destaques:

• A serialização JSON está mais rápida do que nunca. A versão 1.2 é até duas vezes mais rápida que as versões anteriores ao analisar JSON em objetos Kotlin com segurança de tipos e transformar objetos Kotlin em suas representações de texto.
• Agora, há suporte para adições ao sistema de tipos do Kotlin 1.5. Value classes e números sem sinal podem ser transformados em JSON, e vice-versa, como qualquer outra classe Kotlin.
• A nova documentação de APIs torna mais fácil descobrir toda a funcionalidade que a kotlinx.serialization tem a oferecer.

A versão 1.2 também inclui novo suporte para nomes alternativos para campos JSON e fornece uma nova abordagem experimental que gera esquemas Protobuf a partir de classes Kotlin automaticamente, um recurso sobre o qual estamos ansiosos para receber seus comentários!

Vamos explorar juntos as mudanças e adições nesta nova versão! Se você já se convenceu, também pode saltar diretamente para as instruções de upgrade abaixo!

Comece a usar a kotlinx.serialization 1.2!

Assina o canal do Kotlin no YouTube!

Codificação e decodificação JSON mais rápidas do que nunca

A capacidade de codificar classes Kotlin em strings JSON e a capacidade de transformar strings JSON em classes Kotlin são os recursos mais comumente usados da kotlinx.serialization, e estamos trabalhando constantemente para melhorar o desempenho.

A versão 1.2 revisa completamente a estrutura interna da kotlinx.serialization, resultando em um desempenho significativamente melhor na funcionalidade central. Reescrevemos nosso decodificador JSON (responsável por transformar texto em objetos Kotlin) e fizemos otimizações significativas no nosso codificador JSON (responsável por transformar objetos Kotlin em texto).

Com o simples upgrade para a versão mais recente da nossa biblioteca, você pode esperar até o dobro da velocidade para tarefas típicas de codificação e decodificação. (Como você pode ver, alguns dos nossos benchmarks internos, que foram particularmente afetados por essas novas otimizações, chegaram até mesmo a exceder esse número!)

Com essas mudanças, a kotlinx.serialization atinge (e de certa forma excede) logo de cara a paridade de desempenho com outras bibliotecas JSON. Até mesmo os snippets mais simples se beneficiam com essa revisão:

@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)
}

Para perceber essas melhorias você pode fazer um benchmark da sua aplicação com a versão mais recente da nossa biblioteca. Para alguns números aproximados de desempenho, você pode conferir nossos benchmarks internos para codificação e decodificação, que comparam a versão mais recente da kotlinx.serialization com sua versão anterior.

Serialização e desserialização JSON para value classes e tipos de números sem sinal

O Kotlin 1.5.0 oferece duas adições interessantes: value classes e tipos inteiros sem sinal, para os quais a kotlinx.serialization 1.2 agora oferece suporte de primeira classe em termos de codificação e decodificação JSON. Vejamos cada uma delas mais a fundo.

Suporte para value classes

Value classes (anteriormente chamadas de inline classes) são uma maneira de envolver outro tipo Kotlin ( por exemplo, um número) com segurança de tipos, sem introduzir sobrecarga de tempo de execução adicional. Isso ajuda a tornar seus programas mais expressivos e seguros, sem resultar em penalidades de desempenho.

A serialização JSON embutida da kotlinx.serialization agora funciona para value classes. Assim como outras classes Kotlin, basta anotar uma value class com @Serializable.

@Serializable
value class Color(val rgb: Int)

As value classes são armazenadas (e serializadas) diretamente como seu tipo subjacente. Podemos ver isso adicionando um campo com um tipo de value class a uma data class serializável e inspecionando sua saída:

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

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

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

No exemplo acima, NamedColor trata a value class Color como primitiva subjacente (um Int). Isso significa que você pode aproveitar ao máximo a segurança de tipos dentro do seu código Kotlin e, ao mesmo tempo, se beneficiar de uma representação serializada concisa desses tipos, sem delimitação ou aninhamento desnecessários.

Ainda estamos aperfeiçoando o design para serializadores escritos à mão e personalizados para value classes. Por enquanto, eles continuam sendo recursos experimentais. Você pode descobrir mais sobre esse tópico em documentos no GitHub.

Suporte para inteiros sem sinal

Inteiros sem sinal são uma adição à biblioteca padrão Kotlin que fornecem tipos e operações para números não negativos. Com o lançamento do Kotlin 1.5.0, os seguintes tipos de números sem sinal estão disponíveis:

• UByte, com valores de 0 a 255
• UShort, com valores de 0 a 65535
• UInt, com valores de 0 0 a 2^32 – 1
• ULong, com valores de 0 a 2^64 – 1

O codificador e o decodificador JSON na kotlinx.serialization agora oferecem suporte a esses tipos prontos para uso. Assim como outros tipos de números, valores inteiros sem sinal serão serializados em sua representação numérica simples (a mesma representação que você vê ao invocar .toString), sem truncamento, quebra ou conversão em tipos com sinal.

@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}

Observe que o suporte para value classes e inteiros sem sinal está disponível atualmente para JSON. Em uma versão futura, também forneceremos integrações diretas para CBOR e Protobuf: fique ligado!

Para acompanhar e ficar em dia com os lançamentos futuros da kotlinx.serialization e da linguagem de programação Kotlin, assine o boletim informativo de atualizações de produtos Kotlin usando o formulário ao lado desta postagem de blog!

Para obter informações mais detalhadas sobre como usar value classes e tipos sem sinal com a kotlinx.serialization, confira a documentação no GitHub.

Suporte para nomes alternativos em campos JSON

Às vezes, você precisa analisar campos JSON que têm nomes diferentes, mas com o mesmo significado, por exemplo, para manter a compatibilidade com versões anteriores. Com a nova anotação @JsonNames, agora você pode dar nomes alternativos aos campos JSON, que serão usados durante o processo de decodificação.

Para ilustrar isso, vejamos um exemplo. Vamos supor que, dependendo da sua versão, um servidor nos retorne uma das seguintes respostas:

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

Tanto name quanto title têm o mesmo significado, e queremos mapeá-los para o mesmo campo na nossa classe Kotlin. Com a nova anotação @JsonNames, podemos especificar title como uma chave alternativa para a chave name:

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

Observe como isso é diferente da anotação @SerialName, que permite renomear campos para codificação e decodificação, mas não permite especificar alternativas.

Esperamos que esse recurso torne mais fácil para você trabalhar com serviços que retornam campos com nomes diferentes que representam os mesmos valores, sobreviver a migrações de esquemas e fornecer atualizações elegantes para as suas aplicações!

Documentação de APIs atualizada

Para tornar sua experiência de aprendizado da kotlinx.serialization a mais confortável e divertida possível, tentamos fornecer a você vários materiais de referência. Um deles é o Guia de serialização Kotlin no GitHub, que oferece um passo a passo para a funcionalidade fornecida pela biblioteca e inclui exemplos independentes para fornecer uma compreensão intuitiva de cada recurso.

Outro é a documentação de APIs da kotlinx.serialization, que revisamos completamente. Com base em uma nova versão do Dokka, o mecanismo de documentação do Kotlin, a nova documentação de APIs vem com um novo design responsivo e moderno e símbolos de fácil navegação.

Explore a nova documentação de APIs da kotlinx.serialization!

Protobuf: geração de esquema experimental a partir de classes Kotlin

O Protocol Buffers (Protobuf) é um formato de serialização binário para dados estruturados criado pelo Google. Como formato binário, ele é mais eficiente em termos de espaço do que JSON ou o XML, ao mesmo tempo em que fornece uma estrutura independente de linguagem que pode ser usada para comunicação entre aplicações.

Com a kotlinx.serialization, você pode usar a serialização Protobuf multiplataforma (usando a semântica proto2) com estabilidade experimental. Como os outros formatos, você anota sua classe como @Serializable e usa os métodos internos 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)
}

Com as suas classes Kotlin como “source of truth” – fonte de dados única e confiável – (junto com quaisquer personalizações que você possa querer aplicar), a kotlinx.serialization é capaz de inferir o esquema binário dos dados, tornando a comunicação do Protobuf entre várias aplicações Kotlin concisa e conveniente.

A kotlinx.serialization 1.2 agora também inclui um gerador de esquema experimental para Protocol Buffers. Esse gerador permite que você gere arquivos .proto a partir das suas data classes Kotlin, que, por sua vez, podem ser usadas para gerar representações do seu esquema de comunicação em outras linguagens, incluindo Python, C++ e TypeScript.

Para obter instruções sobre como começar a trabalhar com o novo gerador de esquema, confira as instruções correspondentes na documentação.

Depois que o arquivo .proto for gerado, você poderá armazená-lo no seu repositório e usá-lo para gerar representações das suas classes Kotlin em outras linguagens. Esperamos que isso torne mais fácil para você usar a integração Protobuf da kotlinx.serialization em aplicações compatíveis com várias linguagens sem precisar abrir mão da conveniência de gerenciar seus esquemas diretamente no código-fonte do Kotlin.

Como esta é a primeira iteração do gerador de esquema Protobuf, contamos muito com o seu feedback. Experimente e conte-nos sobre seus casos de uso, como você gerencia seus modelos e arquivos .proto, quaisquer problemas que encontrar e os recursos que gostaria de ver. Para isso, use o Rastreador de issues do GitHub.

Ao trabalhar com o gerador de esquema, tenha em mente algumas de suas limitações. Como regra geral, se uma classe Kotlin puder ser serializada com a implementação do Protobuf incluída com a kotlinx.serialization, o gerador de esquema fornecerá suporte para essa classe. Isso também significa que as mesmas restrições são aplicáveis. Aqui estão alguns pontos a serem observados:

• Classes e nomes de propriedades Kotlin precisam estar em conformidade com a especificação protobuf e não devem conter caracteres ilegais.
• A nulidade do Kotlin não se reflete no esquema (porque o proto2 não tem semântica para isso). Campos opcionais fornecidos por protocol buffers são usados com base no fato de suas propriedades Kotlin definirem ou não valores padrão.
• Os valores padrão do Kotlin não estão incluídos no esquema. (o que significa que você terá que garantir a consistência dos padrões em diferentes implementações da linguagem por conta própria.)

Comece a usar a kotlinx.serialization 1.2!

Isso conclui nossa visão geral. Se você está pronto para aproveitar a codificação e a decodificação JSON mais rápidas, o suporte para adições de sistema do tipo Kotlin 1.5, a geração de esquema Protobuf e muitas outras vantagens, é hora de atualizar!

Se você já está usando a kotlinx.serialization, é muito rápido fazer o upgrade para a versão 1.2 (e se você nunca experimentou a kotlinx.serialization, agora é a ocasião ideal para começar). Primeiro, atualize o bloco plugins no seu arquivo 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"
}

Em seguida, atualize seu bloco dependencies com a biblioteca de tempo de execução, incluindo os formatos que você deseja usar na sua aplicação:

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

Assista e leia mais

• vídeo sobre a kotlinx.serialization 1.2
• Biblioteca no GitHub
• guia para a kotlinx.serialization
• documentação de APIs
• postagem de blog sobre o lançamento do Kotlin 1.5.0

Se você tiver algum problema

• Informe issues no rastreador de issues do GitHub.
• Procure ajuda no canal #serialization do Kotlin no Slack (receba um convite).

Assina o canal do Kotlin no YouTube! Boas (des)serializações!

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!