1. 先搞清楚报错在说什么Spring容器里根本没有这个Bean一个很常见的场景你在Service里写了一个Autowired的JdbcTemplate字段项目一启动Spring直接红屏甩给你一句——No qualifying bean of type org.springframework.jdbc.core.JdbcTemplate available: expected at least 1 bean which qualifies as autowire candidate.说实话Spring的报错文案已经足够直白了但我发现很多初学者看到这句话第一反应是检查自己的Autowired是不是写错了、字段名是不是不对、构造器是不是少了参数甚至有人反复把注入方式从字段注入改成构造器注入问题还是原样。我刚工作那会儿也干过这种事白白浪费了不少时间。这句报错翻译成大白话是你问Spring要一个JdbcTemplate但Spring翻遍了整个IoC容器发现根本没有这个类型的Bean。注意问题不是你“要”的方式不对而是容器里压根没有这个东西。所以你该排查的方向不是注入代码而是这个Bean为什么没被创建、没被注册进容器。1.1 完整报错长什么样不同版本的Spring报错措辞略有差异但结构基本一致。Spring Boot 2.x和3.x项目里最常见的报错堆栈长这样Parameter 0 of method setJdbcTemplate in com.example.demo.UserController required a bean of type org.springframework.jdbc.core.JdbcTemplate that could not be found. Action: Consider defining a bean of type org.springframework.jdbc.core.JdbcTemplate in your configuration.如果是在字段注入的场景报错会直接指向那个字段Autowired private JdbcTemplate jdbcTemplate; // 报错No qualifying bean of type JdbcTemplate available无论是哪种注入方式核心信息都是一样的容器里没有JdbcTemplate实例。Spring还特别贴心地给了Action提示——“Consider defining a bean of type JdbcTemplate in your configuration”意思是建议你在配置里手动定义一个JdbcTemplate的Bean。这个提示很有用但也挺误导人因为很多时候问题根本不在于“缺一个JdbcTemplate”而是底下更深层的依赖没就位。强行按提示结构去加Bean反而可能加重症状。1.2 用一个食堂的比喻理解IoC容器把Spring的IoC容器想象成食堂后厨所有Bean都是提前备好的菜。你在代码里Autowired相当于拿着餐盘跟打菜师傅说“我要一份鱼香肉丝”。打菜师傅回应“没有这道菜”这时候你反复解释“我真的点了鱼香肉丝”甚至换个窗口改成setter注入再点一次是没用的。真正的问题是后厨今天压根没备这道菜的原料或者备了原料但师傅没下锅。所以排查思路必须转变别盯着你的点单方式Autowired看要去看后厨的备菜台账Bean注册来源和原料情况依赖项。JdbcTemplate这个Bean在Spring Boot项目里通常来自自动配置而自动配置要生效依赖于一个完整的链条。链条上任何一环断了报错就会不期而至。下面把最常见的原因一个个过一遍这些场景我这些年基本都踩过。2. 高频触发原因逐个排查依赖缺失、配置失效、扫描遗漏2.1 项目根本没有引入spring-jdbc这是最基础但意外高发的原因。Spring Boot项目里JdbcTemplate类位于spring-jdbc这个模块中。Spring Boot本身只是框架不会替你把这个类变出来。很多人会以为“我引了数据库驱动就等于支持JdbcTemplate了”——这是不对的。我曾经接手过一个项目pom.xml里只有mysql-connector-java和mybatis-spring-boot-starter按理说MyBatis的starter会传递依赖spring-jdbc所以平时用MyBatis完全没问题。但如果哪天你想直接用JdbcTemplate写个批量更新编译能过运行时报No qualifying bean就卡在这里了。还有一种情况是手动管理依赖的Maven工程依赖写得不全或者子模块之间依赖关系没理清比如只有spring-context和spring-web没有spring-jdbc。这种情况下即使你手动写了JdbcTemplate的Bean编译阶段IDE可能还给你临时“自动补全”出类路径等项目真正打包运行才暴露问题。确认方式很简单直接在依赖树里查mvn dependency:tree -Dincludesorg.springframework:spring-jdbc如果没有输出或者输出里看不到spring-jdbc那就说明依赖缺失。Spring Boot项目最省心的做法是引入spring-boot-starter-jdbc它会连带spring-jdbc和HikariCP连接池一起带进来dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependencyGradle对应写法implementation org.springframework.boot:spring-boot-starter-jdbc这里有两点需要说明。第一如果你的项目用的是MyBatis或JPA的starter一般会自动传递依赖到spring-jdbc所以这个原因在MyBatis项目里少见但在纯Spring Web项目、Spring Cloud Gateway这类非数据访问服务里很常见。第二引完依赖后记得刷新Maven别项目结构都变了IDE还沿用旧的classpath。2.2 数据源DataSource压根没装配出来这才是“正主”。Spring Boot里JdbcTemplate的自动配置逻辑是AutoConfiguration ConditionalOnClass({ DataSource.class, JdbcTemplate.class }) ConditionalOnSingleCandidate(DataSource.class) EnableConfigurationProperties(JdbcProperties.class) Import({ DatabaseInitializationDependencyConfigurer.class, JdbcTemplateAutoConfiguration.JdbcTemplateConfiguration.class, JdbcTemplateAutoConfiguration.JdbcQueryTemplateConfiguration.class }) public class JdbcTemplateAutoConfiguration { // ... }注意这两个条件注解ConditionalOnClass({ DataSource.class, JdbcTemplate.class })必须classpath里有DataSource和JdbcTemplate这两个类。ConditionalOnSingleCandidate(DataSource.class)容器里必须有一个且唯一的DataSource对象或者说至少能明确选出一个主数据源。也就是说**JdbcTemplate自动配置的前提是容器里存在DataSource Bean。**如果DataSource没有创建出来JdbcTemplate自动配置会静默跳过不报任何错误然后你代码里Autowired时它才以“No qualifying bean”的形式爆发出来。那DataSource为什么没创建我列几个最常见的翻车姿势。第一spring.datasource.url没配。有些人图省事只写了username和password或者只写了driver-class-nameSpring Boot没法凭空构建连接地址DataSource自然起不来。低配的application.yml至少得长这样spring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver第二配置写在了别的profile文件里。比如你把数据源配在application-dev.yml但启动时激活的是prod环境prod配置里没有数据库信息DataSource一样创建不了。这个坑相当隐蔽因为IDE默认启动时可能会加载某个固定的profile换台机器、换种启动方式报错就冒出来了。检查方式很简单启动日志里如果没看到类似HikariPool-1 - Starting...的日志说明数据源压根没初始化。第三有人手动排除了DataSourceAutoConfiguration。如果你在启动类或配置里写了exclude DataSourceAutoConfiguration.class目的是“我不需要数据库”但代码里还留着JdbcTemplate的注入那必然报错。我见过有人copy配置时把排除项一起抄过来事后完全忘了这回事排查了半天。所以排查时要先确定容器里到底有没有DataSource Bean。方法后面专门章节讲但这一步不要跳过去它是整个链条的地基。2.3 包扫描范围没覆盖到你的Bean定义另外一个常见原因是JdbcTemplate的Bean确实存在但根本没被注册进Spring容器。典型场景发生在多模块项目里。假设项目结构长这样com.example.application ├── DemoApplication.java # SpringBootApplication启动类 com.example.common ├── JdbcConfig.java # Configuration, 声明了JdbcTemplate BeanSpringBootApplication注解默认会扫描启动类所在包及其子包。如果启动类放在com.example.application那com.example.common下的配置类根本不会被扫描到。结果就是看上去JdbcConfig写得没问题但容器里就是没有JdbcTemplate。解决方式有两种。推荐的做法是把启动类放在所有子包的根上比如放在com.example下这样com.example.application和com.example.common都在扫描范围内。如果根包位置不方便动就显式指定扫描路径SpringBootApplication ComponentScan(basePackages {com.example.application, com.example.common}) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }关于包扫描我还想多提醒一句这种问题不只影响JdbcTemplate你自定义的Service、Mapper、配置类都会受影响。排查时如果发现某个Bean一直找不到先看看启动类所在的包结构别只顾着在报错代码附近找问题。2.4 一个容易被忽略的边角情况多数据源导致自动配置失效在这个报错的上下文里多数据源是个很有意思的场景。Spring Boot对JdbcTemplate自动配置有个ConditionalOnSingleCandidate(DataSource.class)条件当容器里只有一个DataSource时它才会帮你自动创建JdbcTemplate。一旦你配置了主备两个数据源这个条件就不满足了自动配置直接放弃。也就是说你在多数据源项目里正常使用Autowired JdbcTemplate报错的原因既不是依赖缺失也不是配置错误而是Spring Boot觉得“有多个DataSource我不确定该给JdbcTemplate绑定哪个干脆不自动配了”。这个逻辑对系统来说是安全的但对开发者来说相当隐晦。这个原因放到第3章具体展开因为它的解决方案和单数据源场景完全不同。3. 分场景修复实操从最小修复到多数据源方案3.1 场景一普通Spring Boot单数据源项目这类项目占报错案例的大多数。修复就是两个动作确认依赖、确认配置。第一步确认pom.xml里有spring-boot-starter-jdbc或者至少能传递依赖到spring-jdbc。没有就加上上一节已经给了代码。第二步确认application.yml或application.properties里有完整的数据库配置。我建议四个要素齐全spring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver配置里的driver-class-name值得单独留意一下。com.mysql.jdbc.Driver是MySQL 5.x时代的驱动类从MySQL Connector/J 6.0开始官方推荐com.mysql.cj.jdbc.Driver如果你用的驱动版本比较新写旧类名会导致驱动加载失败。虽然有些版本会自动降级兼容但没必要给自己添麻烦直接写带cj的。第三步启动项目观察日志里是否出现HikariPool-1 - Starting...和HikariPool-1 - Start completed。出现这两行说明DataSource已经创建成功JdbcTemplate顺理成章也会被自动配置出来。然后再去访问那个依赖JdbcTemplate的接口报错通常就消失了。如果日志里没有HikariPool说明DataSource创建失败回头检查配置项和依赖。3.2 场景二传统Spring项目非Spring Boot如果你维护的是老式Spring MVC项目基于XML配置或者JavaConfig那JdbcTemplate不会由自动配置魔法般出现你必须手动定义。JavaConfig方式的配置类Configuration public class JdbcConfig { Bean public DataSource dataSource() { DriverManagerDataSource dataSource new DriverManagerDataSource(); dataSource.setDriverClassName(com.mysql.cj.jdbc.Driver); dataSource.setUrl(jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai); dataSource.setUsername(root); dataSource.setPassword(123456); return dataSource; } Bean public JdbcTemplate jdbcTemplate(DataSource dataSource) { return new JdbcTemplate(dataSource); } }注意jdbcTemplate(Bean方法参数)这里Spring会自动把容器里的DataSource注入进来不需要加Autowired。这种参数注入的方式在Spring 4.3之后很常用代码也干净。如果是XML配置的老项目对应写法是bean iddataSource classorg.springframework.jdbc.datasource.DriverManagerDataSource property namedriverClassName valuecom.mysql.cj.jdbc.Driver/ property nameurl valuejdbc:mysql://localhost:3306/demo?useUnicodetrueamp;characterEncodingutf8amp;serverTimezoneAsia/Shanghai/ property nameusername valueroot/ property namepassword value123456/ /bean bean idjdbcTemplate classorg.springframework.jdbc.core.JdbcTemplate property namedataSource refdataSource/ /beanXML里的符号需要转义成amp;这个细节在把配置从YAML搬到XML时非常容易踩SQL参数那些?倒是没问题只有和号需要转义。值得补一句的是这个手动方案其实也适用于Spring Boot项目。如果你不想完全依赖自动配置也完全可以在自己项目的配置类里显式声明JdbcTemplate。只不过如果容器里已经有自动配置创建的JdbcTemplate了自己再声明一个可能会遇到“expected single matching bean but found 2”这种冲突。所以手动声明前要确认自动配置没在背后再给你加一个。3.3 场景三多数据源项目多数据源场景是我见过最容易让人头秃的因为它的报错和修法都不直观。先解释原理Spring Boot的JdbcTemplateAutoConfiguration要求容器里只有一个DataSource候选ConditionalOnSingleCandidate。一旦你有两套数据库连接比如一个主库做业务、一个从库做报表容器里就有两个DataSource Bean自动配置判断不了该用哪个就放弃治疗不帮你创建JdbcTemplate了。修法是自己动手为主备数据源分别声明JdbcTemplate。一个比较标准的配置类如下Configuration public class MultiDataSourceConfig { Bean Primary ConfigurationProperties(prefix spring.datasource.primary) public DataSource primaryDataSource() { return DataSourceBuilder.create().build(); } Bean ConfigurationProperties(prefix spring.datasource.secondary) public DataSource secondaryDataSource() { return DataSourceBuilder.create().build(); } Bean public JdbcTemplate primaryJdbcTemplate(Qualifier(primaryDataSource) DataSource dataSource) { return new JdbcTemplate(dataSource); } Bean public JdbcTemplate secondaryJdbcTemplate(Qualifier(secondaryDataSource) DataSource dataSource) { return new JdbcTemplate(dataSource); } }对应配置文件spring: datasource: primary: url: jdbc:mysql://localhost:3306/main_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver secondary: url: jdbc:mysql://localhost:3306/report_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver关于这个配置有几个特别容易出错的地方一是Primary别漏。如果两个DataSource都没有Primary不仅JdbcTemplate自动配置会失效Spring在注入DataSource时也会分不清该用哪个可能抛出“expected single matching bean but found 2”之类的冲突。建议给主库加上Primary。二是Bean的命名。默认情况下primaryDataSource()对应的Bean名是primaryDataSourcesecondaryDataSource()对应secondaryDataSource。如果方法名改了Qualifier里的字符串要跟着改两者必须严格对应。三是使用时的注入。既然有了两个JdbcTemplate原来那种不带限定符的注入方式就不行了Autowired private JdbcTemplate jdbcTemplate; // 会报错容器里有2个JdbcTemplate必须带QualifierAutowired Qualifier(secondaryJdbcTemplate) private JdbcTemplate reportJdbcTemplate;这种设计意味着你的业务代码要明确知道自己操作的是哪个库对代码结构有要求。如果大部分场景只是走主库少数报表场景走从库可以把主库的JdbcTemplate做成无Qualifier也能注入的默认Bean其实不行因为Qualifier解析规则是精确匹配优先容器里有多个候选时不带Qualifier依然会报歧义。在这种情况下你只能靠注释或者规范去约束团队用法。四是多数据源的事务管理器。声明了多个DataSource后事务管理器也要跟着适配。Spring Boot自动配置的DataSourceTransactionManagerAutoConfiguration同样依赖ConditionalOnSingleCandidate(DataSource.class)多数据源下不再自动创建事务管理器。这个坑会在你使用Transactional时以另一种报错形式出现不在本文主题内但要知道它是同一套依赖链的问题。3.4 场景四测试环境上下文加载不完整还有一个高频场景发生在单元测试里。很多人喜欢在集成测试里通过SpringBootTest加载整个应用上下文然后直接注入JdbcTemplate。如果测试类上没加对应的ContextConfiguration或相关配置测试上下文根本没加载到你定义JdbcTemplate的配置类就会报同样的No qualifying bean错误。建议是测试类尽量使用SpringBootTest并确保测试包路径在启动类扫描范围内。如果需要轻量级测试只验证JdbcTemplate相关的SQL逻辑就显式指定需要加载的配置类SpringBootTest ContextConfiguration(classes JdbcConfig.class) public class JdbcTemplateIntegrationTest { Autowired private JdbcTemplate jdbcTemplate; // ... }这样做的好处是测试启动速度快坏的方面是如果JdbcConfig里依赖了其他Bean容易触达缺失。如果你只是想让测试快速跑起来我还是推荐直接SpringBootTest让容器全量加载省去思考哪个配置类该加载的成本。4. 排查链路复盘一套能照搬的定位方法写完解决方案再说说排查方法。我接下来这套排查路径是自己被坑过无数次之后总结出来的可以复用到几乎所有涉及“Bean创建失败”“Bean缺失”的Spring问题里。4.1 从自动配置报告找线索--debug启动Spring Boot内置了一个很强大的能力以--debug参数启动时会打印一份自动配置评估报告。里面会把每个自动配置类为什么匹配、为什么不匹配全部列出来。命令行方式java -jar your-app.jar --debugIDE里则可以在Program arguments里填--debug然后启动。启动后控制台会打出一个很长的报告。找到Negative matches不匹配的自动配置一栏搜JdbcTemplateAutoConfiguration和DataSourceAutoConfiguration你会看到类似这样的内容JdbcTemplateAutoConfiguration: Did not match: - ConditionalOnClass - Missing classes: org.springframework.jdbc.core.JdbcTemplate (via ConditionalOnClass)看到Missing classes说明依赖里没有spring-jdbc问题定位到2.1。如果看到JdbcTemplateAutoConfiguration: Did not match: - ConditionalOnSingleCandidate - No single matching bean of type javax.sql.DataSource but found 0说明DataSource没创建出来问题定位到2.2的配置链路。如果看到JdbcTemplateAutoConfiguration: Did not match: - ConditionalOnSingleCandidate - No single matching bean of type javax.sql.DataSource but found 2说明容器里有多个DataSource自动配置判定为不匹配问题定位到2.4多数据源场景。这份报告能直接缩小排查范围比对着代码瞎猜高效得多。我现在的习惯是任何Spring Boot启动异常先--debug跑一遍看报告而不是直接翻代码。4.2 用ApplicationContext探针检查容器注册情况如果你没条件用--debug再启一遍或者想更主动地观察容器状态可以写个小的测试代码把容器里的相关Bean全部打个照面。最轻量的做法是写一个测试类SpringBootTest class BeanInspectTest { Autowired private ApplicationContext context; Test void inspectJdbcBeans() { System.out.println( DataSource Beans ); System.out.println(DataSource count: context.getBeanNamesForType(DataSource.class).length); System.out.println( JdbcTemplate Beans ); System.out.println(JdbcTemplate count: context.getBeanNamesForType(JdbcTemplate.class).length); for (String name : context.getBeanNamesForType(JdbcTemplate.class)) { System.out.println( -- name); } System.out.println( All Bean Names Containing dataSource or jdbc ); for (String name : context.getBeanDefinitionNames()) { if (name.toLowerCase().contains(datasource) || name.toLowerCase().contains(jdbc)) { System.out.println( -- name); } } } }这段测试代码的输出能告诉我们几件事如果DataSource count为0那问题在数据源创建链路别急着看JdbcTemplate。如果DataSource count大于0但JdbcTemplate count为0说明自动配置因为条件不满足被跳过了这时看启动类有没有排除项、有没有多个DataSource、classpath里有没有JdbcTemplate类。如果JdbcTemplate count大于0但你的代码仍然报No qualifying bean那大概率是你注入时用了类型以外的指定条件比如Qualifier指定了一个不存在的JdbcTemplate名字。这个探针方法通用性很高以后遇到任何“容器里少Bean”的问题都可以用。顺便建议不用太频繁地在线上环境打印这些测试或本地环境玩够了就删掉。4.3 临时加Bean做最小验证在定位过程中有用的一招是“加入一个临时Bean看后续报错”类似排障时的二分法。比如你怀疑是DataSource没有创建但不确定那就在某个临时配置类里加上一个最小DataSource BeanConfiguration public class TemporaryConfig { Bean public DataSource dataSource() { return DataSourceBuilder.create() .url(jdbc:mysql://localhost:3306/demo?...) .username(root) .password(123456) .driverClassName(com.mysql.cj.jdbc.Driver) .build(); } }如果加了之后原来的No qualifying bean报错消失了哪怕是换成别的报错比如连接不上数据库也基本能确定原先容器里确实没DataSource。之后再根据新报错去修连接信息。反过来如果你手动声明了DataSource和JdbcTemplate后一切正常那就说明自动配置被不知什么原因屏蔽了再往exclude和pom依赖方向查。这个方法的思路是用“能不能跑通”去验证推断而不是非要一步到位猜对原因。我处理复杂依赖问题时经常用至少比干瞪眼盯着日志强。4.4 整理一张快速定位表最后把排查要点收拢成一张表方便对照使用检查项现象结论修复方向依赖树里有没有spring-jdbc没有缺少依赖引入spring-boot-starter-jdbc自动配置报告里JdbcTemplate条件Missing classes同上检查依赖和classpath容器中DataSource Bean数量0数据源没建立检查spring.datasource配置、排除项、profile容器中DataSource Bean数量≥2自动配置因多数据源失效手动声明多个JdbcTemplate并加Primary容器中有DataSource和JdbcTemplate代码仍报错包扫描或Qualifier问题检查扫描路径和限定符名称测试类报错测试上下文未加载配置类配置类未扫描到用SpringBootTest或显式加载配置类这张表的顺序就是排查顺序从上往下走一遍大部分问题都能找到根因。我在实际项目里处理这个报错最大的一点体会是**Spring的报错信息本身往往是对的但很多人只看到了“缺少JdbcTemplate”没有继续往上游追问为什么缺少。**这个报错链条里JdbcTemplate能不能被创建前提是DataSource能不能被创建而DataSource能不能被创建前提是依赖、配置、扫描基线都正常。从上往下逐层排查比自己钻进报错代码里反复改注入方式效率要高太多了。最后再分享一个真实教训。项目里有次只需要做一个数据同步功能我把一个老模块的pom copy过来把mybatis相关依赖都删了结果没把spring-boot-starter-jdbc补上。代码写完IDE里到处都能点到JdbcTemplate的方法运行之后愣是报No qualifying bean我还以为是自动配置没生效排查了快一个小时。后来发现IDE能点出方法是因为Maven的依赖解析在我本地仓库里还能找到类打包到服务器上就暴露了。所以这类问题先把依赖确认清楚再想别的。