Maven多模块Spring Boot项目Kafka消费者无法连接Broker

算力阿峰

2026-8-28

问题描述

基于Spring Boot构建Kafka消费者时采用Maven多模块结构：consumer-app为Spring Boot启动应用模块，其余模块均作为依赖引入父项目。
项目可正常构建、启动，但应用无法连接本地部署的Kafka Broker（bootstrap server），启动日志末尾内容如下：

.   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (v2.3.12.RELEASE)

2022-06-28 20:26:50.849  INFO 17284 --- [  restartedMain] c.t.c.c.c.CardConsumerApplication        : Starting CardConsumerApplication on WorkIsOn with PID 17284 (C:\Users\myuser\Workspace\card-consumer\card-consumer\target\classes started by myuser in C:\Users\myuser\Workspace\card-consumer)
2022-06-28 20:26:50.851  INFO 17284 --- [  restartedMain] c.t.c.c.c.CardConsumerApplication        : No active profile set, falling back to default profiles: default
2022-06-28 20:26:50.900  INFO 17284 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : Devtools property defaults active! Set 'spring.devtools.add-properties' to 'false' to disable
2022-06-28 20:26:50.901  INFO 17284 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : For additional web related logging consider setting the 'logging.level.web' property to 'DEBUG'
2022-06-28 20:26:51.778  INFO 17284 --- [  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 9090 (http)
2022-06-28 20:26:51.784  INFO 17284 --- [  restartedMain] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-06-28 20:26:51.785  INFO 17284 --- [  restartedMain] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.46]
2022-06-28 20:26:51.850  INFO 17284 --- [  restartedMain] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-06-28 20:26:51.850  INFO 17284 --- [  restartedMain] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 949 ms
2022-06-28 20:26:51.977  INFO 17284 --- [  restartedMain] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing ExecutorService 'applicationTaskExecutor'
2022-06-28 20:26:52.157  INFO 17284 --- [  restartedMain] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
2022-06-28 20:26:52.182  INFO 17284 --- [  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 9090 (http) with context path ''
2022-06-28 20:26:52.189  INFO 17284 --- [  restartedMain] c.t.c.c.c.CardConsumerApplication        : Started CardConsumerApplication in 1.688 seconds (JVM running for 3.215)

将该Kafka消费者模块的同等代码迁移至非多模块的普通Maven项目中，使用完全相同的Spring Boot配置，即可正常连接Kafka bootstrap server，也可正常消费消息。

排查步骤与修复方案

从日志特征看，应用启动全程没有Kafka客户端初始化、连接Broker的相关日志，说明Kafka消费者相关Bean根本没有被Spring容器初始化，不是网络层面的连接问题，优先从多模块项目的配置、依赖、类加载层面排查：

校验组件扫描范围
Spring Boot默认只会扫描启动类所在包及其子包下的组件，如果其他模块的Kafka监听器类、Kafka配置类所在包不在这个扫描范围内，@KafkaListener、Kafka自动配置都不会生效。直接在启动类的@SpringBootApplication注解上显式配置scanBasePackages参数，指定所有模块的统一根包即可，示例：
```
@SpringBootApplication(scanBasePackages = "com.example.card")
public class CardConsumerApplication {
    public static void main(String[] args) {
        SpringApplication.run(CardConsumerApplication.class, args);
    }
}
```
校验Kafka依赖是否被启动模块正确加载
多模块项目中如果spring-boot-starter-kafka依赖只配置在了公共子模块，且没有被启动模块正确传递引入，启动时不会加载Kafka相关自动配置。直接在启动模块consumer-app的pom.xml中显式引入Kafka starter依赖即可，注意版本要和当前Spring Boot版本匹配：
```
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>
```
验证方式：启动应用后如果能在日志中找到KafkaAutoConfiguration相关的初始化日志，说明依赖加载正常。
校验配置文件是否被正确加载
多模块项目下如果多个子模块都存在同名的application.yml/application.properties，可能出现配置覆盖，导致spring.kafka.bootstrap-servers配置项没有被正确读取。可以在启动时加--debug参数查看配置绑定结果，确认Kafka连接地址配置值和预期一致。建议把Kafka连接相关的全局配置统一放在启动模块的配置文件中，避免配置覆盖问题。
排查DevTools类加载隔离问题
从启动日志可以看到项目开启了Spring DevTools，DevTools的双类加载器机制会把第三方依赖、非当前模块的类归为基础类加载器加载，可能导致Kafka自动配置类、自定义监听器类无法被识别。可以先临时移除DevTools依赖验证问题是否复现，如果确定是DevTools导致的，在启动模块的resources/META-INF/spring-devtools.properties中添加配置，把Kafka依赖、自定义公共模块加入重启类加载器的加载范围：
```
restart.include.kafka=/spring-kafka-.*.jar
restart.include.card-common=/card-common-.*.jar
```

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