Kotlinx.serialization中构建JSON数组的正确方式

在使用Kotlinx.serialization库构建JSON请求负载时，开发者经常会遇到如何正确处理列表数据的问题。本文将通过一个典型场景，详细介绍如何正确使用buildJsonObject和putJsonArray方法来构建包含数组的JSON对象。

问题背景

假设我们有一个数据类ComplexObject，包含id和text两个属性：

data class ComplexObject(
    val id: String,
    val text: String
)

开发者最初尝试使用joinToString方法将对象列表转换为字符串列表：

val payload = buildJsonObject {
    if(complexObjects.isNotEmpty()) {
        put("key", complexObjects.joinToString() { it.text })
    }
}

这种方法会产生不理想的输出结果：["fq, Label #2, Label #3"]，而不是期望的["fq", "Label 2", "Label 3"]格式。

正确解决方案

方法一：使用putJsonArray

Kotlinx.serialization提供了专门的putJsonArray方法来处理数组类型的值：

val payload = buildJsonObject {
    putJsonArray("key") {
        complexObjects.forEach { add(it.text) }
    }
}

这种方法会生成正确的JSON数组格式：{"key":["text 1","text 2"]}

方法二：使用map转换

另一种简洁的方式是使用map函数将对象列表转换为属性列表：

val payload = buildJsonObject {
    put("key", JsonArray(complexObjects.map { it.text }))
}

常见误区

1. 直接使用joinToString：这会将所有元素合并为一个字符串，而不是创建JSON数组
2. 误用putAll方法：putAll适用于Map类型，不适用于构建JSON数组
3. 嵌套数组问题：某些框架可能在序列化时自动添加额外嵌套层，这不是kotlinx.serialization的问题

最佳实践建议

1. 对于简单列表，优先使用putJsonArray方法
2. 对于复杂转换场景，可以先用map处理数据，再构建JSON
3. 注意检查最终输出格式，确保符合API要求
4. 当遇到格式问题时，先隔离kotlinx.serialization的输出，确认问题来源

通过掌握这些技巧，开发者可以更高效地使用Kotlinx.serialization构建符合要求的JSON数据结构。