Spring Boot升级后Kotlin父类ConfigurationProperties无法绑定环境变量

问题背景 #

将Spring Boot-Kotlin项目从Spring 5、Java 8升级至Spring 6、Java 21后，出现配置属性继承结构中父类字段无法绑定的异常。该问题仅在引入kotlin("reflect")依赖时触发，旧环境下无此问题。

复现代码 #

build.gradle.kts配置 #

plugins {
    kotlin("jvm") version "2.1.20"
    id("org.springframework.boot") version "3.4.4"
    id("org.jetbrains.kotlin.plugin.spring") version "2.1.20"
    id("io.spring.dependency-management") version "1.1.7"
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter")
    implementation(kotlin("reflect"))
}

配置属性类MyProperties.kt #

@ConfigurationProperties(prefix = "my.test")
@Component
class MyProperties {
    var customs: List<CustomA> = listOf()
    var bases: List<Base> = listOf()

    open class Base(
        var type: String = ""
    )

    class CustomA(
        var y: String = "",
        var z: String = "",
    ) : Base()
}

启动环境变量 #

MY_TEST_BASES_0_TYPE=value4;MY_TEST_CUSTOMS_0_TYPE=value3;MY_TEST_CUSTOMS_0_Y=value1;MY_TEST_CUSTOMS_0_Z=value2

问题现象 #

启动后，myProperties.customs[0].type预期返回value3，但实际为空字符串，父类属性完全未绑定。手动给父类属性添加open修饰符、子类属性添加override后，字段可正常绑定：

open class Base(
   open var type: String = ""
)

class CustomA(
   override var type: String = "",
   var y: String = "",
   var z: String = "",
) : Base()

但代码库中存在大量此类继承结构，手动修改效率极低，需要批量修复方案。

批量修复方案 #

方案一：利用Kotlin All-Open插件自动开放属性 #

Kotlin默认类和属性为final，Spring 6的配置属性绑定依赖可覆盖的属性来处理继承结构。通过all-open插件，可自动为配置属性相关类的属性添加open修饰符：

1. 在build.gradle.kts中添加all-open插件：

plugins {
    // 保留原有插件
    kotlin("jvm") version "2.1.20"
    id("org.springframework.boot") version "3.4.4"
    id("org.jetbrains.kotlin.plugin.spring") version "2.1.20"
    id("org.jetbrains.kotlin.plugin.allopen") version "2.1.20"
    id("io.spring.dependency-management") version "1.1.7"
}

allOpen {
    // 为带有ConfigurationProperties注解的类开放所有属性
    annotation("org.springframework.boot.context.properties.ConfigurationProperties")
    // 若内部类也需要，可添加Component注解或自定义规则
    annotation("org.springframework.stereotype.Component")
}

该插件会自动为指定注解标记的类的所有var属性生成open修饰符，子类无需手动添加override即可让Spring绑定识别父类属性。

方案二：批量代码修改脚本 #

若插件无法满足需求，可编写Kotlin脚本结合AST解析工具（如kotlin-compiler-api）批量修改代码：

1. 遍历代码库中所有配置属性类
2. 识别继承结构中的父类var属性，自动添加open修饰符
3. 为子类对应的属性添加override修饰符

示例脚本核心逻辑（简化版）：

import org.jetbrains.kotlin.com.intellij.openapi.project.Project
import org.jetbrains.kotlin.psi.KtClass
import org.jetbrains.kotlin.psi.KtProperty
import org.jetbrains.kotlin.utils.addToStdlib.cast

// 初始化Kotlin项目解析环境
val project = ... // 配置项目路径
// 扫描所有配置属性类
project.getFilesByAnnotation("org.springframework.boot.context.properties.ConfigurationProperties").forEach { file ->
    file.classes.forEach { ktClass ->
        // 处理父类属性
        ktClass.superTypes.forEach { superType ->
            val superClass = superType.resolve()?.cast<KtClass>() ?: return@forEach
            superClass.properties.filterIsInstance<KtProperty>().forEach { prop ->
                if (!prop.isOpen) {
                    // 为父类属性添加open修饰符
                    prop.addModifier("open")
                }
            }
        }
        // 处理子类属性，添加override
        ktClass.properties.filterIsInstance<KtProperty>().forEach { prop ->
            val superProp = ktClass.superTypes.flatMap { it.resolve()?.cast<KtClass>()?.properties ?: emptyList() }
                .find { it.name == prop.name }
            if (superProp != null && !prop.hasModifier("override")) {
                prop.addModifier("override")
            }
        }
    }
}

执行脚本前需备份代码，避免意外修改。

方案三：自定义配置属性绑定处理器（不推荐） #

通过自定义ConfigurationPropertiesBindingPostProcessor修改Spring的绑定逻辑，强制识别父类的非open属性。但该方式需要深入Spring绑定源码，维护成本高，仅作为临时应急方案，不建议长期使用。

问题根源 #

Spring 6的配置属性绑定机制在结合kotlin-reflect时，依赖Kotlin的可覆盖属性（open）来处理继承结构的字段映射；而Spring 5的绑定逻辑未依赖此特性，因此旧环境下可正常工作。Kotlin默认var属性为final，导致父类属性无法被Spring绑定机制识别。

内容的提问来源于stack exchange，提问作者minh tri Vo