Retrofit 2 集成 kotlinx.serialization从 JSON 到 Protobuf 的 Converter 实战指南【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit本文介绍 Retrofit 2 官方提供的converter-kotlinx-serialization转换器如何用一行asConverterFactory()把 kotlinx.serialization 接入 Retrofit既支持StringFormat如 JSON也支持BinaryFormat如 Protobuf让Body请求体与响应体直接完成 Kotlin 序列化对象的自动编解码。读完本文你将掌握依赖配置、JSON/Protobuf 两种接入方式、Converter 注册顺序的注意事项以及 Contextual 序列化器等高级用法。依赖引入在模块的build.gradle中添加依赖implementation com.squareup.retrofit2:converter-kotlinx-serialization:latest.version使用 Maven 时对应dependency groupIdcom.squareup.retrofit2/groupId artifactIdconverter-kotlinx-serialization/artifactId versionlatest.version/version /dependency其中latest.version请替换为当前最新正式版本。同时需要引入 kotlinx.serialization 的运行时与 Gradle 插件org.jetbrains.kotlin.plugin.serialization否则Serializable注解不会生成序列化器。开发版本的快照可以从 Sonatype 的snapshots仓库获取。该模块的 Maven 坐标信息可在 gradle.properties 中确认POM_ARTIFACT_IDconverter-kotlinx-serialization。快速上手JSON 文本格式kotlinx.serialization 的核心抽象是StringFormat文本格式典型代表是Json与BinaryFormat二进制格式典型代表是ProtoBuf。converter 为这两类格式分别提供了asConverterFactory()扩展函数传入一个MediaType作为请求体的Content-Type头即可得到Converter.Factoryval retrofit Retrofit.Builder() .baseUrl(https://example.com/) .addConverterFactory( Json.asConverterFactory( application/json; charsetutf-8.toMediaType())) .build()随后定义接口与数据类即可直接使用Serializable data class User(val name: String) interface UserService { GET(/user) suspend fun getUser(): User POST(/user) suspend fun createUser(Body user: User): User }注意请求体的Content-Type正是我们在asConverterFactory()中传入的 MediaType上例为application/json; charsetutf-8这一点在模块测试 KotlinSerializationConverterFactoryStringTest.kt 中有明确验证测试断言请求体文本为{name:Bob}且请求头Content-Type为application/json; charsetutf-8。二进制格式Protobuf对于 protobuf 这类二进制场景改为对ProtoBuf调用asConverterFactory()数据类字段使用ProtoNumber指定字段编号Serializable data class User(ProtoNumber(1) val name: String) val retrofit Retrofit.Builder() .baseUrl(https://example.com/) .addConverterFactory( ProtoBuf.asConverterFactory(application/x-protobuf.toMediaType())) .build()测试 KotlinSerializationConverterFactoryBytesTest.kt 演示了完整流程响应体被解码为字节数组后经ProtoBuf.decodeFromByteArray还原为User(Bob)请求体则被编码为0x0a 0x03 B o b的 protobuf 字节序列Content-Type为application/x-protobuf。源码剖析Converter 是如何工作的整个转换器模块只有 4 个核心文件链路非常清晰Factory.kt —— 入口工厂重写responseBodyConverter()与requestBodyConverter()两个方法分别构建反序列化与序列化 ConverterSerializer.kt —— 内部密封类封装格式差异DeserializationStrategyConverter.kt —— 响应体 → 对象的转换器SerializationStrategyConverter.kt —— 对象 →RequestBody的转换器。在Factory中无论是请求还是响应方向都会调用serializer.serializer(type)解析出对应 JavaType的KSerializer。Serializer是一个密封类它的两个子类体现了格式的二分FromString持有StringFormat响应体通过body.string()读取文本后调用decodeFromString请求体通过encodeToString编码后用toRequestBody(contentType)包装FromBytes持有BinaryFormat响应体通过body.bytes()读取字节后调用decodeFromByteArray请求体通过encodeToByteArray编码后用toRequestBody(contentType, 0, bytes.size)包装。从源码结构可以推断正是因为Serializer屏蔽了文本与二进制两种格式的差异上层Factory才能用完全相同的逻辑处理 JSON 与 Protobuf。关键注意点Converter 的注册顺序Factory.kt的 KDoc 中有一条对使用方式影响很大的说明因为 kotlinx.serialization 支持的类型非常灵活这个 converter 默认认为自己能处理所有类型如果与其他 converter 混用必须把它放在最后注册给其他 converter 先处理各自类型的机会。原因在于 Retrofit 的addConverterFactory()是顺序遍历的Retrofit会按注册顺序依次询问每个工厂是否支持某个类型返回第一个非空结果。若把 kotlinx.serialization 放在前面它会截胡本应由 Gson、Moshi 等处理的类型。因此混用多个序列化方案时请将Json.asConverterFactory(...)放在addConverterFactory链的末尾。进阶用法Contextual 序列化器对于无法用Serializable注解标注的类型例如第三方类或需要自定义编解码规则的类kotlinx.serialization 提供了 Contextual 序列化机制该 converter 完整支持。做法是在构造Json时通过SerializersModule注册自定义KSerializerval json Json { serializersModule SerializersModule { contextual(UserSerializer) } }测试 KotlinxSerializationConverterFactoryContextualTest.kt 中User本身不是Serializable而是通过自定义UserSerializer内部委托给UserResponse.serializer()完成编解码KotlinxSerializationConverterFactoryContextualListTest.kt 进一步验证了ListUser这类泛型容器也能正常工作——因为serializer(type)走的是format.serializersModule的类型解析泛型参数会一并参与。适用范围与限制该 converter 适用于文本格式JSON 等StringFormat与二进制格式Protobuf 等BinaryFormat两种场景媒体类型需自行传入并保持与实际数据一致序列化对象的类必须满足 kotlinx.serialization 的要求Serializable或注册了 Contextual 序列化器否则运行时会在类型解析阶段报错与多个 converter 混用时务必遵循最后注册原则否则会导致类型被错误接管更多代码细节可继续阅读 模块主源码目录 与 测试目录。【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Retrofit 2 集成 kotlinx.serialization：从 JSON 到 Protobuf 的 Converter 实战指南
Retrofit 2 集成 kotlinx.serialization从 JSON 到 Protobuf 的 Converter 实战指南【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit本文介绍 Retrofit 2 官方提供的converter-kotlinx-serialization转换器如何用一行asConverterFactory()把 kotlinx.serialization 接入 Retrofit既支持StringFormat如 JSON也支持BinaryFormat如 Protobuf让Body请求体与响应体直接完成 Kotlin 序列化对象的自动编解码。读完本文你将掌握依赖配置、JSON/Protobuf 两种接入方式、Converter 注册顺序的注意事项以及 Contextual 序列化器等高级用法。依赖引入在模块的build.gradle中添加依赖implementation com.squareup.retrofit2:converter-kotlinx-serialization:latest.version使用 Maven 时对应dependency groupIdcom.squareup.retrofit2/groupId artifactIdconverter-kotlinx-serialization/artifactId versionlatest.version/version /dependency其中latest.version请替换为当前最新正式版本。同时需要引入 kotlinx.serialization 的运行时与 Gradle 插件org.jetbrains.kotlin.plugin.serialization否则Serializable注解不会生成序列化器。开发版本的快照可以从 Sonatype 的snapshots仓库获取。该模块的 Maven 坐标信息可在 gradle.properties 中确认POM_ARTIFACT_IDconverter-kotlinx-serialization。快速上手JSON 文本格式kotlinx.serialization 的核心抽象是StringFormat文本格式典型代表是Json与BinaryFormat二进制格式典型代表是ProtoBuf。converter 为这两类格式分别提供了asConverterFactory()扩展函数传入一个MediaType作为请求体的Content-Type头即可得到Converter.Factoryval retrofit Retrofit.Builder() .baseUrl(https://example.com/) .addConverterFactory( Json.asConverterFactory( application/json; charsetutf-8.toMediaType())) .build()随后定义接口与数据类即可直接使用Serializable data class User(val name: String) interface UserService { GET(/user) suspend fun getUser(): User POST(/user) suspend fun createUser(Body user: User): User }注意请求体的Content-Type正是我们在asConverterFactory()中传入的 MediaType上例为application/json; charsetutf-8这一点在模块测试 KotlinSerializationConverterFactoryStringTest.kt 中有明确验证测试断言请求体文本为{name:Bob}且请求头Content-Type为application/json; charsetutf-8。二进制格式Protobuf对于 protobuf 这类二进制场景改为对ProtoBuf调用asConverterFactory()数据类字段使用ProtoNumber指定字段编号Serializable data class User(ProtoNumber(1) val name: String) val retrofit Retrofit.Builder() .baseUrl(https://example.com/) .addConverterFactory( ProtoBuf.asConverterFactory(application/x-protobuf.toMediaType())) .build()测试 KotlinSerializationConverterFactoryBytesTest.kt 演示了完整流程响应体被解码为字节数组后经ProtoBuf.decodeFromByteArray还原为User(Bob)请求体则被编码为0x0a 0x03 B o b的 protobuf 字节序列Content-Type为application/x-protobuf。源码剖析Converter 是如何工作的整个转换器模块只有 4 个核心文件链路非常清晰Factory.kt —— 入口工厂重写responseBodyConverter()与requestBodyConverter()两个方法分别构建反序列化与序列化 ConverterSerializer.kt —— 内部密封类封装格式差异DeserializationStrategyConverter.kt —— 响应体 → 对象的转换器SerializationStrategyConverter.kt —— 对象 →RequestBody的转换器。在Factory中无论是请求还是响应方向都会调用serializer.serializer(type)解析出对应 JavaType的KSerializer。Serializer是一个密封类它的两个子类体现了格式的二分FromString持有StringFormat响应体通过body.string()读取文本后调用decodeFromString请求体通过encodeToString编码后用toRequestBody(contentType)包装FromBytes持有BinaryFormat响应体通过body.bytes()读取字节后调用decodeFromByteArray请求体通过encodeToByteArray编码后用toRequestBody(contentType, 0, bytes.size)包装。从源码结构可以推断正是因为Serializer屏蔽了文本与二进制两种格式的差异上层Factory才能用完全相同的逻辑处理 JSON 与 Protobuf。关键注意点Converter 的注册顺序Factory.kt的 KDoc 中有一条对使用方式影响很大的说明因为 kotlinx.serialization 支持的类型非常灵活这个 converter 默认认为自己能处理所有类型如果与其他 converter 混用必须把它放在最后注册给其他 converter 先处理各自类型的机会。原因在于 Retrofit 的addConverterFactory()是顺序遍历的Retrofit会按注册顺序依次询问每个工厂是否支持某个类型返回第一个非空结果。若把 kotlinx.serialization 放在前面它会截胡本应由 Gson、Moshi 等处理的类型。因此混用多个序列化方案时请将Json.asConverterFactory(...)放在addConverterFactory链的末尾。进阶用法Contextual 序列化器对于无法用Serializable注解标注的类型例如第三方类或需要自定义编解码规则的类kotlinx.serialization 提供了 Contextual 序列化机制该 converter 完整支持。做法是在构造Json时通过SerializersModule注册自定义KSerializerval json Json { serializersModule SerializersModule { contextual(UserSerializer) } }测试 KotlinxSerializationConverterFactoryContextualTest.kt 中User本身不是Serializable而是通过自定义UserSerializer内部委托给UserResponse.serializer()完成编解码KotlinxSerializationConverterFactoryContextualListTest.kt 进一步验证了ListUser这类泛型容器也能正常工作——因为serializer(type)走的是format.serializersModule的类型解析泛型参数会一并参与。适用范围与限制该 converter 适用于文本格式JSON 等StringFormat与二进制格式Protobuf 等BinaryFormat两种场景媒体类型需自行传入并保持与实际数据一致序列化对象的类必须满足 kotlinx.serialization 的要求Serializable或注册了 Contextual 序列化器否则运行时会在类型解析阶段报错与多个 converter 混用时务必遵循最后注册原则否则会导致类型被错误接管更多代码细节可继续阅读 模块主源码目录 与 测试目录。【免费下载链接】retrofitA type-safe HTTP client for Android and the JVM项目地址: https://gitcode.com/gh_mirrors/re/retrofit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考