如何用自定义Spring Converter转换含多配置属性的复杂对象？

我正尝试使用Spring手动将一组配置属性转换为对象。

目标类代码：

class ComplexConfigurationProperties {
  private final Map<String, ComplexObject> objects;

  public ComplexConfigurationProperties(Map<String, ComplexObject> objects) {
    this.objects = objects;
  }
}

自定义转换器代码：

class CustomConverter implements Converter<Map<String, Object>, ComplexObject> {

  @Override
  public ComplexObject convert(Map<String, Object> source) {
    ComplexObject result;
    // do some stuff
    return result;
  }
}

测试代码：

@Test
void test() {
  DefaultConversionService conversionService = new DefaultConversionService();
  conversionService.addConverter(new CustomConverter());
  ComplexConfigurationProperties props = new Binder(
      Collections.singleton(
          new MapConfigurationPropertySource(
              Map.of(
                  "prefix.objects.a.property1", "property1",
                  "prefix.objects.a.property2", "property2"
              )
          )
      ), null,
      conversionService
  ).bind("prefix", ComplexConfigurationProperties.class).get();

  assertNotNull(props);
}

但绑定结果始终为null，且自定义转换器从未被调用。请问我哪里出错了？是否需要更换转换器的源类型？我的需求是否无法实现？我在官方文档中未找到关于复杂类型转换的相关内容。

1. 类访问权限问题 #

你的ComplexConfigurationProperties和CustomConverter都是包私有类（未加public修饰符），Spring Binder需要通过反射实例化类、调用构造器和转换器，包私有类无法被外部反射访问，这是导致绑定结果为null的核心原因之一。

解决： 将这两个类改为public修饰。

2. 构造器参数与配置节点的映射问题 #

Spring Binder默认无法自动识别普通类构造器的参数与配置节点的对应关系，需要明确告知Binder如何映射。有三种解决方式：

• 方式一：添加@ConstructorBinding注解
  给ComplexConfigurationProperties类添加该注解，明确告知Binder使用构造器进行属性绑定：

  import org.springframework.boot.context.properties.bind.ConstructorBinding;
  
  @ConstructorBinding
  public class ComplexConfigurationProperties {
      private final Map<String, ComplexObject> objects;
  
      public ComplexConfigurationProperties(Map<String, ComplexObject> objects) {
          this.objects = objects;
      }
  
      // 可选：添加getter方便测试验证
      public Map<String, ComplexObject> getObjects() {
          return objects;
      }
  }
  

• 方式二：改用Java 16+ Record类型
  Record类型会自动生成构造器和参数映射，无需额外注解：

  public record ComplexConfigurationProperties(Map<String, ComplexObject> objects) {}
  

• 方式三：编译时保留参数名
  在编译命令或IDE编译配置中添加-parameters参数，让JVM保留构造器参数名称，Binder可通过参数名匹配配置节点（如objects参数对应配置里的objects节点）。

3. 确保转换器正常生效 #

自定义转换器的源类型Map<String, Object>是正确的，Binder处理Map<String, ComplexObject>时，会将每个子节点（如prefix.objects.a下的属性）转换为Map<String, Object>，再调用你的转换器生成ComplexObject。只要转换器是public且正确注册到ConversionService，就能被触发。

修改后的完整示例代码 #

ComplexObject类（需为public）

public class ComplexObject {
    private final String property1;
    private final String property2;

    public ComplexObject(String property1, String property2) {
        this.property1 = property1;
        this.property2 = property2;
    }

    public String getProperty1() {
        return property1;
    }

    public String getProperty2() {
        return property2;
    }
}

自定义转换器（public）

import org.springframework.core.convert.converter.Converter;

public class CustomConverter implements Converter<Map<String, Object>, ComplexObject> {

    @Override
    public ComplexObject convert(Map<String, Object> source) {
        String property1 = (String) source.get("property1");
        String property2 = (String) source.get("property2");
        return new ComplexObject(property1, property2);
    }
}

测试代码

import org.junit.jupiter.api.Test;
import org.springframework.boot.context.properties.bind.Binder;
import org.springframework.boot.context.properties.source.MapConfigurationPropertySource;
import org.springframework.core.convert.support.DefaultConversionService;

import java.util.Collections;
import java.util.Map;

import static org.junit.jupiter.api.Assertions.*;

public class ConfigurationBindingTest {

    @Test
    void test() {
        DefaultConversionService conversionService = new DefaultConversionService();
        conversionService.addConverter(new CustomConverter());

        ComplexConfigurationProperties props = new Binder(
                Collections.singleton(
                        new MapConfigurationPropertySource(
                                Map.of(
                                        "prefix.objects.a.property1", "property1",
                                        "prefix.objects.a.property2", "property2"
                                )
                        )
                ),
                null,
                conversionService
        ).bind("prefix", ComplexConfigurationProperties.class).get();

        assertNotNull(props);
        assertNotNull(props.getObjects());
        assertEquals(1, props.getObjects().size());
        ComplexObject obj = props.getObjects().get("a");
        assertEquals("property1", obj.getProperty1());
        assertEquals("property2", obj.getProperty2());
    }
}

内容的提问来源于stack exchange，提问作者Adrian Diemer