Spring Boot嵌套@ConfigurationProperties类使用Kotlin值类触发"object is not an instance of declaring class"异常的解决方法

我完全理解你遇到的这个棘手问题——Kotlin内联值类在Spring Boot的顶层@ConfigurationProperties类里用得好好的，一放到嵌套配置类里就触发反射异常，这个问题的根源是Spring的Bean实例化逻辑和Kotlin值类的JVM包装机制之间的交互冲突。

先复现你的问题场景 #

首先明确你的代码结构和报错信息，方便后续分析：

1. Kotlin值类与配置类代码

@JvmInline
value class BooleanWrapper(val value: Boolean)

@ConfigurationProperties(prefix = "demo")
data class DemoConfig(
    val enabled: BooleanWrapper, // 正常工作
    val works: BooleanWrapper, // 正常工作
    val nestedItem: ComplexConfigItem, // 嵌套类包含值类参数时出错
) {
    data class ComplexConfigItem(
        val name: String,
        val blowUp: BooleanWrapper, // 触发异常的参数
    )

    @PostConstruct
    fun logConfig() {
        println("Demo config: [$this]")
    }
}

2. 配置文件application.yaml

demo:
  enabled: false
  works: true
  nested-item:
    name: "Demo Name"
    blow-up: true

3. 核心异常栈

Caused by: java.lang.IllegalArgumentException: object is not an instance of declaring class
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:na]
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[na:na]
at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:na]
at java.base/java.lang.reflect.Method.invoke(Method.java:568) ~[na:na]
at kotlin.reflect.jvm.internal.calls.ValueClassAwareCaller.call(ValueClassAwareCaller.kt:200) ~[kotlin-reflect-2.1.21.jar:2.1.21-release-317]
at kotlin.reflect.jvm.internal.KCallableImpl.callDefaultMethod$kotlin_reflection(KCallableImpl.kt:207) ~[kotlin-reflect-2.1.21.jar:2.1.21-release-317]
at kotlin.reflect.jvm.internal.KCallableImpl.callBy(KCallableImpl.kt:112) ~[kotlin-reflect-2.1.21.jar:2.1.21-release-317]
at org.springframework.beans.BeanUtils$KotlinDelegate.instantiateClass(BeanUtils.java:940) ~[spring-beans-6.2.7.jar:6.2.7]
at org.springframework.beans.BeanUtils.instantiateClass(BeanUtils.java:190) ~[spring-beans-6.2.7.jar:6.2.7]

问题原因分析 #

这个异常的本质是：
当Spring Boot实例化嵌套的ComplexConfigItem类时，会通过Kotlin反射调用其构造函数。而Kotlin的内联值类（@JvmInline）在JVM层面是特殊的包装类型，Spring的BeanUtils在配合Kotlin反射的ValueClassAwareCaller处理嵌套类构造函数参数时，会出现参数类型匹配错误——反射调用时无法正确将配置值映射为值类的包装实例，最终抛出“对象不是声明类的实例”的异常。

简单来说：顶层配置类的构造函数参数处理逻辑已经适配了值类，但嵌套类的实例化流程中，Spring与Kotlin反射的交互存在兼容性缺口。

可行的解决办法 #

1. 将嵌套配置类改为顶层类（最稳妥的方案）

你已经发现了这个方案：把ComplexConfigItem从DemoConfig内部移到文件顶层，这样Spring实例化它时，反射逻辑会完全按照顶层类处理，值类参数的映射也会正常工作。

修改后的代码：

@JvmInline
value class BooleanWrapper(val value: Boolean)

@ConfigurationProperties(prefix = "demo")
data class DemoConfig(
    val enabled: BooleanWrapper,
    val works: BooleanWrapper,
    val nestedItem: ComplexConfigItem,
) {
    @PostConstruct
    fun logConfig() {
        println("Demo config: [$this]")
    }
}

// 移到顶层的嵌套配置类
data class ComplexConfigItem(
    val name: String,
    val blowUp: BooleanWrapper,
)

2. 给嵌套配置类属性添加@NestedConfigurationProperty注解

显式告诉Spring Boot这是一个嵌套的配置属性，让它使用专门的逻辑处理嵌套类的实例化，有时候能修复反射类型匹配的问题：

@ConfigurationProperties(prefix = "demo")
data class DemoConfig(
    val enabled: BooleanWrapper,
    val works: BooleanWrapper,
    // 显式标记为嵌套配置属性
    @NestedConfigurationProperty
    val nestedItem: ComplexConfigItem,
) {
    data class ComplexConfigItem(
        val name: String,
        val blowUp: BooleanWrapper,
    )

    @PostConstruct
    fun logConfig() {
        println("Demo config: [$this]")
    }
}

3. 升级Spring Boot与Kotlin的版本

这个问题大概率是Spring和Kotlin版本的兼容性bug，升级到最新稳定版的依赖可以修复：

• 升级Spring Boot到3.3.x及以上版本
• 升级Kotlin到2.2.x及以上版本（保证kotlin-reflect与Kotlin编译器版本一致）

新版本的Spring Beans模块或Kotlin反射库已经修复了ValueClassAwareCaller处理嵌套类构造函数的逻辑缺陷。

总结 #

如果不想调整代码结构，优先尝试添加@NestedConfigurationProperty注解；如果还是不行，将嵌套类移到顶层是最可靠的解决方案；长期来看，升级依赖版本可以从根源上避免这类反射兼容性问题。

内容来源于stack exchange