如何将顶层Map<String, Object>绑定到@ConfigurationProperties？

问题场景 #

想通过@ConfigurationProperties直接绑定YAML中apps节点下的顶层Map结构，尝试让配置类继承HashMap<String, AppConfig>但绑定失败，不想通过额外添加下层嵌套属性（比如加config字段）的方式实现，询问是否有直接绑定的办法。

期望使用的YAML结构 #

apps:
  google:
    name: Google
    type: Search Engine
  bing:
    name: Bing
    type: Search Engine

无效的配置类尝试 #

@Getter
@Setter
@Component
@ConfigurationProperties("apps")
public class Apps extends HashMap<String, Apps.AppConfig> {

  @Getter
  @Setter
  static class AppConfig {
    private String name;
    private String type;
  }
}

可行但不想要的嵌套方式（作为对比） #

YAML配置

apps:
  config:
    google:
      name: Google
      type: Search Engine
    bing:
      name: Bing
      type: Search Engine

Spring配置类

@Getter
@Setter
@Component
@ConfigurationProperties("apps")
public class Apps {

  private Map<String, AppConfig> config;

  @Getter
  @Setter
  static class AppConfig {
    private String name;
    private String type;
  }
}

为什么继承HashMap无效？ #

Spring Boot的@ConfigurationProperties绑定依赖**JavaBean属性访问器（getter/setter）**机制，它会尝试将配置键映射到对应的属性方法。HashMap本身没有针对google、bing这类动态键的属性setter，继承它的配置类也无法提供符合要求的属性绑定入口，因此绑定失败。

可行解决方案 #

方案1：直接绑定Map类型Bean #

无需自定义配置类载体，直接定义Map类型的Bean，通过@ConfigurationProperties指定前缀即可绑定顶层Map：

@Configuration
public class AppConfigRegistry {

    @Bean
    @ConfigurationProperties(prefix = "apps")
    public Map<String, AppDetails> appDetailsMap() {
        return new HashMap<>();
    }

    @Getter
    @Setter
    public static class AppDetails {
        private String name;
        private String type;
    }
}

使用时直接注入Map<String, AppDetails>即可访问配置：

@Service
public class AppService {
    private final Map<String, AppConfigRegistry.AppDetails> appDetailsMap;

    public AppService(Map<String, AppConfigRegistry.AppDetails> appDetailsMap) {
        this.appDetailsMap = appDetailsMap;
    }

    // 使用示例
    public void printAppInfo() {
        appDetailsMap.forEach((key, details) -> 
            System.out.printf("%s: %s(%s)%n", key, details.getName(), details.getType())
        );
    }
}

方案2：自定义配置类持有顶层Map（无额外嵌套） #

如果希望保留自定义配置类的形式，可通过构造函数绑定直接接收前缀下的整个Map：

@ConfigurationProperties(prefix = "apps")
@Component
@Getter
public class Apps {
    private final Map<String, AppConfig> appConfigs;

    // Spring自动将apps节点下的所有键值对注入到该构造函数的参数中
    public Apps(Map<String, AppConfig> appConfigs) {
        this.appConfigs = appConfigs;
    }

    @Getter
    @Setter
    static class AppConfig {
        private String name;
        private String type;
    }
}

使用时注入Apps类，通过apps.getAppConfigs().get("google")访问配置内容。

方案3：让配置类本身实现Map接口 #

如果想让配置类直接具备Map的使用能力（比如apps.get("google")），可实现Map<String, AppConfig>接口并委托给内部Map，同时提供setter让Spring注入配置：

@ConfigurationProperties(prefix = "apps")
@Component
public class Apps implements Map<String, Apps.AppConfig> {
    private final Map<String, AppConfig> delegate = new HashMap<>();

    // 实现Map接口的所有方法，委托给delegate
    @Override
    public int size() { return delegate.size(); }
    @Override
    public boolean isEmpty() { return delegate.isEmpty(); }
    @Override
    public boolean containsKey(Object key) { return delegate.containsKey(key); }
    @Override
    public boolean containsValue(Object value) { return delegate.containsValue(value); }
    @Override
    public AppConfig get(Object key) { return delegate.get(key); }
    @Override
    public AppConfig put(String key, AppConfig value) { return delegate.put(key, value); }
    @Override
    public AppConfig remove(Object key) { return delegate.remove(key); }
    @Override
    public void putAll(Map<? extends String, ? extends AppConfig> m) { delegate.putAll(m); }
    @Override
    public void clear() { delegate.clear(); }
    @Override
    public Set<String> keySet() { return delegate.keySet(); }
    @Override
    public Collection<AppConfig> values() { return delegate.values(); }
    @Override
    public Set<Entry<String, AppConfig>> entrySet() { return delegate.entrySet(); }

    // 必须提供setter，Spring通过该方法注入apps节点下的Map
    public void setDelegate(Map<String, AppConfig> delegate) {
        this.delegate.putAll(delegate);
    }

    @Getter
    @Setter
    static class AppConfig {
        private String name;
        private String type;
    }
}

使用时直接注入Apps类，即可像操作普通Map一样访问配置。

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