GET请求返回null而非列表时KotlinxSerializer空指针异常如何解决

问题原因说明 #

你遇到的异常是因为后端返回的JSON根节点为null，默认配置下Kotlinx序列化器尝试将根节点null反序列化为列表类型时触发了空指针。

对应问题解答 #

1. 最佳处理方案 #

优先调整后端返回空列表[]而非null，这是成本最低、长期维护性最好的方案，不需要客户端做额外兼容，也符合API设计的通用逻辑。

2. 客户端侧的解决方法 #

如果暂时无法推动后端修改，可以通过两种方式在客户端修复：

方案1：调整Ktor序列化配置

创建Ktor客户端时修改Json序列化参数，开启输入值强制转换规则，允许将输入的null转为对应类型的默认值（列表类型的默认值就是空列表）：

val httpClient = HttpClient(CIO) {
    install(JsonFeature) {
        serializer = KotlinxSerializer(Json {
            ignoreUnknownKeys = true
            // 开启输入值强制适配，null会自动转为目标类型的默认值
            coerceInputValues = true
            // kotlinx.serialization 1.5+ 版本可加这个参数，允许可空类型接收null值不抛出异常
            explicitNulls = false
        })
    }
}

方案2：捕获序列化异常兜底

如果不想全局修改序列化配置，可以只在当前请求加异常捕获逻辑，遇到序列化相关异常时返回空列表或null：

override suspend fun getDevices(accessToken: String): List<Device>? {
    return runCatching {
        client.get {
            url(path = "/devices")
            header("Authorization", "Bearer $accessToken")
        }
    }.getOrElse { e ->
        // 仅序列化相关异常走兜底逻辑，网络异常、权限错误等其他异常仍正常抛出
        if (e is NullPointerException || e is SerializationException) {
            emptyList()
            // 如果你需要保留null的语义也可以返回null
        } else {
            throw e
        }
    }
}

3. 业界通用约定 #

业界的API设计规范普遍要求集合类型返回空集合而非null，核心原因有两点：

• 语义更明确：空列表代表「请求处理成功，没有符合条件的资源」，null通常代表「请求处理异常/参数错误」，二者可以清晰区分业务状态
• 降低客户端出错概率：不需要额外做非空判断，避免大量不必要的防御性代码，减少NPE出现的可能
  目前国内外大厂的开放API、RESTful设计规范都遵循这个约定。

内容的提问来源于stack exchange，提问作者H.Step