使用@ConfigurationProperties读取YAML Map属性时返回null的问题

原因分析 #

调用getTokenHeaderName("gitlab")返回null，本质是配置文件中的headers属性未成功绑定到WebhooksConsumerTokenHeadersProperties类的headers Map中，通常是因为配置属性类未被Spring正确注册，或者绑定机制未生效。

解决步骤 #

1. 确保配置属性类被Spring注册并启用绑定

有两种实现方式：

方式一：给配置类添加@Component注解

直接在配置类上添加@Component，让Spring自动扫描注册该Bean，同时结合@ConfigurationProperties完成配置绑定：

@Component
@ConfigurationProperties(prefix = "acme.cloud.platform.incoming.webhook")
public class WebhooksConsumerTokenHeadersProperties {

    private final Map<String, String> headers;

    public WebhooksConsumerTokenHeadersProperties(Map<String, String> headers) {
        this.headers = headers;
    }

    public String getTokenHeaderName(String app) {
        return headers.get(app);
    }
}

方式二：通过@EnableConfigurationProperties显式启用

若不想给配置类加@Component，可在Spring Boot启动类或任意配置类上添加@EnableConfigurationProperties注解，指定要启用的配置属性类：

@SpringBootApplication
@EnableConfigurationProperties(WebhooksConsumerTokenHeadersProperties.class)
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

2. 兼容旧版本Spring Boot的构造函数绑定

如果使用Spring Boot 2.2.x及更早版本，构造函数绑定需要额外添加@ConstructorBinding注解，明确告诉Spring通过构造函数注入配置值：

@ConstructorBinding
@ConfigurationProperties(prefix = "acme.cloud.platform.incoming.webhook")
public class WebhooksConsumerTokenHeadersProperties {

    private final Map<String, String> headers;

    public WebhooksConsumerTokenHeadersProperties(Map<String, String> headers) {
        this.headers = headers;
    }

    public String getTokenHeaderName(String app) {
        return headers.get(app);
    }
}

注意：这种方式必须配合@EnableConfigurationProperties使用，不能搭配@Component。

3. 验证配置文件格式正确性

确认application.yaml的缩进、拼写完全正确：

acme:
  cloud:
    platform:
      incoming:
        webhook:
          headers:
            gitlab: X-Gitlab-Token

4. 调试验证绑定结果

可在配置类中添加初始化日志，确认headers Map是否正确加载：

@Component
@ConfigurationProperties(prefix = "acme.cloud.platform.incoming.webhook")
public class WebhooksConsumerTokenHeadersProperties {

    private final Map<String, String> headers;

    public WebhooksConsumerTokenHeadersProperties(Map<String, String> headers) {
        this.headers = headers;
        // 打印日志验证Map内容
        System.out.println("Loaded headers: " + headers);
    }

    public String getTokenHeaderName(String app) {
        return headers.get(app);
    }
}

启动应用后查看控制台，若输出Loaded headers: {gitlab=X-Gitlab-Token}，说明绑定成功，此时调用getTokenHeaderName("gitlab")即可返回正确值。

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