kotlinx.serialization 1.0正式版

我们很高兴与你分享kotlinx.serialization这个多平台序列化库的1.0版。作为首个稳定版本,我们终于可以认为能用于生产

img

无论你是通过Kotlin Multiplatform Mobile编写Android应用,编写服务端,还是通过Kotlin/JS构建Web前端,kotlinx.serialization都提供了简洁且功能强大的纯Kotlin API,可轻松将JSON解析为类型安全的Kotlin对象,反之亦然。为了庆祝该版本的发布,我们想简述一下kotlinx.serialization 1.0附带的可用于生产的特性,并了解该库与其他方案的区别。

在深入了解之前,我们想邀请你参加Kotlin 1.4在线活动,Leonid Startsev将详细介绍以前,现在,以及kotlinx.serialization的未来。请不要错过!

Register for the Kotlin 1.4 Online Event

首次使用kotlinx.serialization对Kotlin对象进行序列化和反序列化

一般而言,序列化是软件项目中很常见的需求。移动应用或Web前端多通过API将JSON纯文本解析为对象。而服务端和后端用于接受和响应JSON格式化过的请求。并且当你想保存数据到硬盘时,使用JSON是一种易于人阅读的流行格式。

如你所见,对Kotlin对象进行(反)序列化是你在项目中迟早都会遇到的过程。选择kotlinx.serialization可使整个流程变得非常简单:将库添加到项目中后,要将基本的Kotlin对象解析为JSON形式非常简单,通过@Serializable注解其类,并调用Json对象上提供的encodeToStringdecodeFromString<T>扩展函数:

当然,kotlinx.serialization不是唯一可以用来序列化的库。在JVM生态系统中,还有许多其他库用于JSON。但是,最流行的不一定专为Kotlin而设计,而且可能根本不适用于Kotlin Multiplatform项目。除此之外,还有充足理由为你项目去择kotlinx.serialization。

为何选择Kotlinx.serialization?

kotlinx.serialization中包含的几个特性和设计使它与其他库区分开来,通常这会让它的使用体验更让人着迷。让我们仔细看看其中的一些配置。

Kotlin through and through

kotlinx.serialization不只是用纯Kotlin编写,而且还能在所有Kotlin Multiplatform目标(包括Kotlin/Native和Kotli /JS)上使用。它的序列化功能也是考虑到Kotlin的类型系统而构建的。无论你是尝试使用默认的属性初始值来序列化data class,单例object还是尝试对通用的List<T>进行反序列化:kotlinx.serialization都会如期运行。最好看一下具体示例,它将一个复杂的项目对象(由data class所定义)列表转换为其JSON表示,然后返回:

如你所见,kotlinx.serialization仍然可以处理带泛型集合的类型安全反序列化。尽管由于JVM上的集合会受类型擦除影响,这不是一个常规的操作。因此这种情况,其他库会要求使用变通方案,例如使用type-tokens。但由于kotlinx.serialization使用编译器插件进行集成,所以它开箱即用的行为(可以在projectCollection示例中看到)已经是你所希望看到的——不需要依赖任何方案!

我们想保证,即便是应用未曾启动过,你也能尽可能多地发现问题,所以kotlinx.serialization也致力于实现编译时安全性。例如,在上面的示例中,如果未将Account类明确标记为@ Serializable,则会导致编译时异常Account类型非可序列化,这很容易便能发现和修复该错误,避免发布后崩溃。

多态序列化

kotlinx.serialization让轻松且安全地处理序列化对象的继承体系成为可能——这是传统上敏感但非常需要的特性。因为该库了解Kotlin独特的类型系统,所以使用多态序列化的最直接方法是构建一个密封类的层次结构,其中所有子类都被明确标记为@Serializable。因为在编译时就知道了密封类的层次结构,所以kotlinx.serialization插件可以使用该信息,并且子类及超类序列化的代码仍保持简洁:

从字符串变量可以看到,kotlinx.serialization会智能地添加type属性到包含特定子类型的JSON对象中,这个行为完全自动。当你需要兼顾客户端和服务器时,这可以轻松地通过继承关系来构造消息,而无需手动推断另一端的子类型。

密封类是在kotlinx.serialization中使用多态序列化的最便捷方法,并且已涵盖了大量用例,同时该库实际上还提供了超出这些封闭层次体系的功能。要了解相关功能的更多信息,请查看指南中有关多态的部分

强大的可定制性

特别是在与外部系统和API通信时,你可能无法完全控制所接收JSON消息的准确格式。另一方面,你可能会觉得有必要调整kotlinx.serialization的输出,以确保通信的远端能接受。

Kotlinx.serialization带有丰富的DSL配置项,你可以通过它调整常规输入及输出的处理,修改general settings,例如启用pretty-printing,lenient parsing或ignoring unknown keys。对于类和对象的特定配置,你可以通过注解来定义这些行为,例如重命名字段(@SerialName)或序列化时忽略(@Transient)。这些注解以及其他注解,也包含在指南中。如果你的用例有所需要,甚至还可以为特定类型的对象提供完全自定义的序列化

这些功能的组合可以调整库的行为,使其完全符合你对序列化的要求和格式的规范。

框架集成

无论项目中包含了什么库,你都可以使用kotlinx.serialization简洁的接口,但许多框架还可通过直接集成使用kotlinx.serialization。以下是我们要强调的一些示例

  • 如果你将** Ktor 作为服务端框架,可以通过提供的官方集成,将kotlinx.serialization与内容协商结合使用,从而可以直接针对传入和传出请求接收和响应Kotlin对象。而Kotlin Multiplatform项目中可用的Ktor-Clients**对应项也通过kotlinx.serialization提供了JSON有效负载处理
  • Spring MVC最近增加了对kotlinx.serialization的支持,并且SébastienDeleuze对Spring WebFlux提出了类似的集成。
  • Http4k为kotlinx.serialization的HTTP消息往返提供了优先的支持
  • Fuel提供了一个扩展包,让Android HTTP客户端能使用kotlinx.serialization。
  • 如果你在使用MongoDB,则KMongo库通过kotlinx.serialization提供对象映射
  • 如果你通过Retrofit 2将HTTP API转换为Kotlin接口,则可以使用Jake Wharton的序列化转换器和集成kotlinx.serialization。

直接与kotlinx.serialization集成的第三方项目越来越多,我们非常兴奋——现在我们的库已能用于生产,我们希望不久将来能看到更多类似的集成!

未来多格式支持

在1.0版中,与JSON相关的功能都是稳定且可用于生产的——但是kotlinx.serialization并不止步于此!除JSON外,团队还打算兼容HOCON,ProtoBuf,CBOR和Properties的序列化格式。尽管这些格式仍在设计和开发中,因此具有不同程度的稳定性和平台兼容性,但是你可以尝试一下。它们作为单独的工件使用,可以在指引中找到它们,以及对其格式状态的简短描述。

和开发团队的正式格式一样,还有许多由社区维护的格式,例如BSON,XML和YAML。但是请注意,这些格式是由社区成员创建且维护的。并且创建自定义格式仍然是一项实验性功能,因此可能会做出重大更改,它们的维护者或许会收到延迟的更新。

现在,我们重点介绍了使kotlinx.serialization易于使用的许多特性,希望你能了然于心,为什么要为当前(或下一个)项目选择这个库——这是一个快速的过程!

向你的项目添加kotlinx.serialization

要在你的项目中使用kotlinx.serialization,只需将编译器插件和运行时库添加到项目中。在你的build.gradle(.kts)中,将以下项添加到plugin块:

接下来,将运行时库依赖项添加到build.gradle(.kts)文件中的dependencies块。如果你在Kotlin Multiplatform项目中工作,那么可以将依赖项添加到common目标依赖模块中——所有平台特定的依赖项将自动添加:

现在,你就可以开始使用kotlinx.serialization了!可以随意尝试该博文中包含的示例,尝试自己的用例,或尝试使用本指南的示例

深入 & 反馈

我们希望你能喜欢kotlinx.serialization的简要概述!要获取更多信息,包括最新的安装说明,请访问其在GitHub上的主页。请务必查看kotlinx.serialization指引,包含库的基本及高级特性的详细信息,并且涵盖了本博文中提到的许多主题。如果你在使用该库时遇到任何麻烦,可以在项目的问题跟踪器Kotlin Slack的#serialization频道中寻求帮助。

欲了解幕后的独家情况以及对序列化库的更深入解释,Leonid Startsev在Kotlin 1.4在线活动期间有关kotlinx.serialization演讲,这也是一个再次邀请你参加的好时机——我们期待着在那儿见!

Register for the Kotlin 1.4 Online Event

如果你以前使用过kotlinx.serialization,请通过更新日志迁移指南来了解已更改的内容以及如何将项目升级到稳定版本。

感谢团队

我们对提供反馈,提交PR,使用kotlinx.serialization 1.0之前的版本或以任何其他方式对库做出贡献的所有人说“谢谢”。你们的意见对于帮助团队交付功能强大,易于使用且Kotlin优先的多平台序列化库非常有价值。在我们的第一个稳定版本发布之前,你们报告的700多个问题,这些问题有助于解决bug和消除设计中的任何不足。在项目的持续发展过程中,希望你能不断支持和反馈,帮助我们不断改进和创新。所以:谢谢大家——享受绝佳的Kotlin!

此条目发表在官方分类目录。将固定链接加入收藏夹。

发表评论

电子邮件地址不会被公开。 必填项已用*标注