Spring Boot @ConfigurationProperties部分属性绑定失败求助

问题 #

使用@ConfigurationProperties绑定Kafka配置时，仅groupId、topic、offset属性绑定成功，securityProtocol、bootstrapServers等属性为null，部署到OpenShift后触发Bean实例化异常（NullPointerException）。本地用相同环境变量运行容器无问题，直接通过Spring Environment能读取所有属性，配置文件属性名无明显错误。

相关代码与配置 #

KafkaProperties 记录类

@ConfigurationProperties(prefix = "kafka")
public record KafkaProperties(
        String securityProtocol,
        String bootstrapServers,
        String groupId,
        String topic,
        String offset,
        String sslTruststoreLocation,
        String sslTruststorePassword,
        String messageKeyFilter) {
}

KafkaConfig 配置类

@Configuration
@EnableConfigurationProperties(KafkaProperties.class)
@EnableKafka
public class KafkaConfig {

    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, Payload> kafkaListenerContainerFactory(KafkaProperties kafkaProperties) {
        ConcurrentKafkaListenerContainerFactory<String, Payload> factory = new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory(kafkaProperties));
        if (StringUtils.hasText(kafkaProperties.messageKeyFilter())) {
            factory.setRecordFilterStrategy(consumerRecord -> !consumerRecord.key().contains(kafkaProperties.messageKeyFilter()));
        }
        return factory;
    }

    private ConsumerFactory<String, Payload> consumerFactory(KafkaProperties kafkaProperties) {
        Map<String, Object> props = createConsumerConfig(kafkaProperties);
        props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false);
        return new DefaultKafkaConsumerFactory<>(props, new StringDeserializer(), getPayloadJsonDeserializer());
    }

    private Map<String, Object> createConsumerConfig(KafkaProperties kafkaProperties) {
        Map<String, Object> props = new HashMap<>();
        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, kafkaProperties.bootstrapServers());
        props.put(ConsumerConfig.GROUP_ID_CONFIG, kafkaProperties.groupId());
        props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, kafkaProperties.offset());

        if("SSL".equals(kafkaProperties.securityProtocol())) {
            props.put("security.protocol", kafkaProperties.securityProtocol());
            props.put("ssl.truststore.location", kafkaProperties.sslTruststoreLocation());
            props.put("ssl.truststore.password", kafkaProperties.sslTruststorePassword());
        }
        return props;
    }

    private static JsonDeserializer<Payload> getPayloadJsonDeserializer() {
        JsonDeserializer<Payload> deserializer = new JsonDeserializer<>(Payload.class);
        deserializer.trustedPackages("kafka.listener.model.*");
        return deserializer;
    }
} 

application.yml 配置

kafka:
  bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVER}
  group-id: ${KAFKA_GROUP_ID}
  topic: ${KAFKA_TOPIC}
  offset: ${KAFKA_OFFSET}
  security-protocol: ${SECURITY_PROTOCOL}
  ssl-truststore-location: ${SSL_TRUSTSTORE_LOCATION}
  ssl-truststore-password: ${SSL_TRUSTSTORE_PASSWORD}
  message-key-filter: ${MESSAGE_KEY_FILTER}

deployment.yml 环境变量配置

env:
    - name: SSL_TRUSTSTORE_LOCATION
      value: "/mypath/kafka-truststore.jks"
    - name: KAFKA_BOOTSTRAP_SERVER
      value: "my-bootstratp-server"
    - name: KAFKA_TOPIC
      value: "testtopic"
    - name: KAFKA_GROUP_ID
      value: "tesgroup"
    - name: KAFKA_OFFSET
      value: "earliest"
    - name: MESSAGE_KEY_FILTER
      value: "testkey"
    - name: SECURITY_PROTOCOL
      value: "SSL"

异常信息

Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.kafka.config.ConcurrentKafkaListenerContainerFactory]: Factory method 'kafkaListenerContainerFactory' threw exception with message: null
at org.springframework.beans.factory.support.SimpleInstantiationStrategy.instantiate(SimpleInstantiationStrategy.java:171)
at org.springframework.beans.factory.support.ConstructorResolver.instantiate(ConstructorResolver.java:643)
... 37 common frames omitted
Caused by: java.lang.NullPointerException: null
at java.base/java.util.concurrent.ConcurrentHashMap.putVal(Unknown Source)
at java.base/java.util.concurrent.ConcurrentHashMap.putAll(Unknown Source)
at java.base/java.util.concurrent.ConcurrentHashMap.<init>(Unknown Source)

排查方案与解决思路 #

1. 修复记录类编译参数，保留参数名
   Spring Boot对Record类的@ConfigurationProperties绑定依赖构造函数参数名匹配，若编译时开启参数名擦除会导致绑定失败。需在编译配置中添加-parameters参数：

• Maven项目：

  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
          <compilerArgs>
              <arg>-parameters</arg>
          </compilerArgs>
      </configuration>
  </plugin>
  

• Gradle项目：

  compileJava {
      options.compilerArgs << '-parameters'
  }
  

2. 延迟KafkaProperties初始化，适配OpenShift环境变量加载时机
   OpenShift中环境变量加载可能存在延迟，导致Bean初始化过早时部分属性未注入。给KafkaProperties添加@Lazy注解延迟初始化：

@ConfigurationProperties(prefix = "kafka")
@Lazy
public record KafkaProperties(...) { ... }

3. 校验环境变量完整性，排查Secret挂载问题
   在OpenShift容器中执行printenv命令，确认SSL_TRUSTSTORE_PASSWORD等Secret对应的环境变量是否存在且值正确，确保Secret已正确挂载为环境变量。

4. 添加null校验，避免NPE触发
   异常源于ConcurrentHashMap.putAll时传入null值，修改createConsumerConfig方法，先校验属性非null再放入Map：

private Map<String, Object> createConsumerConfig(KafkaProperties kafkaProperties) {
    Map<String, Object> props = new HashMap<>();
    if (kafkaProperties.bootstrapServers() != null) {
        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, kafkaProperties.bootstrapServers());
    }
    props.put(ConsumerConfig.GROUP_ID_CONFIG, kafkaProperties.groupId());
    props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, kafkaProperties.offset());

    if("SSL".equals(kafkaProperties.securityProtocol())) {
        props.put("security.protocol", kafkaProperties.securityProtocol());
        if (kafkaProperties.sslTruststoreLocation() != null) {
            props.put("ssl.truststore.location", kafkaProperties.sslTruststoreLocation());
        }
        if (kafkaProperties.sslTruststorePassword() != null) {
            props.put("ssl.truststore.password", kafkaProperties.sslTruststorePassword());
        }
    }
    return props;
}

5. 开启配置绑定调试日志，定位绑定失败原因
   在application.yml中添加日志配置，查看属性绑定的详细过程：

logging:
  level:
    org.springframework.boot.context.properties: DEBUG

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