1. 数据库连接Spring Boot 到底帮你做了什么先说个我见过无数遍的场景很多人照着网上的教程往application.yml里塞了几行spring.datasource配置然后项目启动了CRUD 也能跑通就认为自己会配置数据库了。但真到线上环境出问题——连接超时、连接池报错、事务莫名其妙回滚——就完全傻眼。Spring Boot 的数据库配置远不止写几行 yaml这么简单。它的核心机制是自动配置Auto-Configuration。你引入spring-boot-starter-jdbc或spring-boot-starter-data-jpa时Spring Boot 会在启动阶段尝试自动创建一个DataSourceBean。这个尝试遵循一套条件判断逻辑Classpath 里有 HikariCP 就用 Hikari有 Tomcat 连接池就用 Tomcat有 Commons DBCP2 就用 DBCP2什么连接池都没有就退回SimpleDriverDataSource一个没有池化能力的兜底实现。这就是为什么很多初学者发现自己只写了依赖和连接串CRUD 就能跑——Spring Boot 把脏活累活都过滤掉了。但自动配置只解决能不能连上的问题不保证连得好、连得稳。理解这个机制后你才能明白为什么后续的连接池调优、多数据源、读写分离都要自己动手覆盖默认 Bean。另外一个让很多人困惑的细节是Spring Boot 2.x 和 3.x 的默认连接池不一样。2.x 系列默认用 HikariCP这是目前公认性能最好的连接池之一在 Spring Boot 里是首选3.x 基于 Spring Framework 6 / Jakarta EE 9 重新整理过依赖但连接池默认依然是 HikariCP。所以如果你用 Spring Boot 2.0 之前的老版本默认可能是 Tomcat JDBC Pool配置项写法有小差别——网上很多老教程的配置新版本跑不通多半是这个问题。接下来我要从最基础的数据源配置讲起一路延伸到连接池参数调优、MyBatis 集成、多数据源场景以及实际生产环境中那些文档不写但你一定会踩的坑。这不是一篇复制粘贴即可跑通的快速入门而是一份我在项目里反复验证过的配置实战笔记。2. 一份完整的单数据源配置从选驱动到写连接串2.1 依赖引入只加 Starter 还不够最基础的单数据源方案在pom.xml里加这段dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency注意第二行我用的是mysql-connector-j而不是老版本的mysql-connector-java。这是 MySQL 官方从 2022 年开始改的 artifactId如果你还在用mysql-connector-java在 Spring Boot 3.x 下会因为版本漂移出现一些奇怪问题。类似地PostgreSQL 驱动是org.postgresql:postgresqlSQL Server 是com.microsoft.sqlserver:mssql-jdbcSQLite 则是org.xerial:sqlite-jdbc但 Spring Boot 官方不推荐生产环境用 SQLite事务和并发能力都有限。提示Starter 里的版本号可以省去由 Spring Boot 的 BOMBill of Materials依赖清单统一管理。但如果你用了某些数据库的特殊驱动版本比如为了适配公司内部老版本数据库就必须显式声明 version。2.2 配置文件到底怎么写用了 Spring Boot 的自动配置最标准的单库配置是这样spring: datasource: url: jdbc:mysql://127.0.0.1:3306/my_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver这段配置里藏了不少信息。driver-class-name在老版本 MySQL 驱动里是com.mysql.jdbc.Driver而在 8.x 之后的驱动里必须写成com.mysql.cj.jdbc.Driver——但如果你用的是 Spring Boot 2.2 和 MySQL 8.x 驱动这行其实可以省略Spring Boot 能从url里推断出驱动类。不过我还是建议显式写出来一方面不容易被 IDE 误报另一方面升级驱动版本后一眼就能看出该改什么。URL 里我加了 4 个参数逐个说useUnicodetruecharacterEncodingutf8中文不乱码的基本保障老生常谈但总有人忘。serverTimezoneAsia/ShanghaiMySQL 8.0 之后必须指定时区否则连接时会报The server time zone value Öйú±ê׼ʱ¼ä is unrecognized。这个错很多人第一次见都会懵其实就是时区映射问题。useSSLfalse本地开发建议关掉 SSL否则驱动会输出大量警告日志还拖慢速度但生产环境如果数据库服务端启用了 SSL 证书验证这行就不该是 false。allowPublicKeyRetrievaltrueMySQL 8.0 的 caching_sha2_password 认证插件在非 SSL 连接下需要这一步否则会直接报Public Key Retrieval is not allowed。本地开发很常见但对安全性要求严格的场景更推荐用 SSL 而不是开这个开关。这些参数不是随便加的每一个背后都是一个真实踩坑现场。特别是serverTimezone我记得有同事部署到海外服务器时忘了改时区结果所有时间字段从 DB 读出后都比北京时间慢了 14 个小时排查了大半天。2.3 配置方式的优先级问题Spring Boot 配置文件的加载优先级是启动参数 环境变量 application-{profile}.ymlapplication.yml 默认值的链路。这个顺序非常实用比如生产环境密码不想写进代码仓库就可以只留占位符然后用环境变量注入spring: datasource: url: ${DB_URL} username: ${DB_USER} password: ${DB_PASSWORD}启动时指定DB_PASSWORD环境变量即可。这个方案在 Docker 部署时尤其好用。注意 Spring Boot 用SPRING_DATASOURCE_PASSWORD这样的大写下划线形式环境变量也能直接映射到配置属性不需要写${}占位符也能生效——两种方式二选一即可。2.4 最容易被忽略的驱动版本坑驱动版本是 Spring Boot 数据库配置里最容易出问题的隐性环节。MySQL 官方驱动从 8.0.19 开始把域名解析和 socket 连接超时默认改成了绑定到 JDBC 层导致你设置了 OS 级 TCP 超时也未必生效需要在 JDBC URL 里单独加connectTimeout5000socketTimeout60000参数。PostgreSQL 驱动 42.x 系列在 JDK 版本升级后也有几轮行为变化——42.2.x 和 42.3.x 对sslmode的默认值处理方式不同。遇到昨天还好好的今天突然报超时这类玄学问题第一反应应该是去看驱动更新日志而不是先怀疑代码。3. 连接池调优HikariCP 的默认值远远不够3.1 为什么默认配置只适合 DemoHikariCP 是 Spring Boot 默认采用的连接池它的默认参数确实做得很保守、很安全最大连接数 10最小空闲连接 10连接超时 30 秒。这两个 10 在小型系统里没什么问题但一旦你的服务 QPS 上去了或者下游有慢 SQL10 个连接很快会被占满新的请求只能排队等着获取连接——当你看到HikariPool-1 - Connection is not available, request timed out after 30000ms这个异常时项目实际上已经在崩溃边缘了。另一个更隐蔽的默认值是maximumPoolSize和minimumIdle相等。HikariCP 作者Brett Woolridge其实建议这两个值别设成一样理由是想避免空闲连接被频繁创建销毁让连接池保持懒加载特性。默认相等更像是为了兼容直觉而非性能最优。连接池的配置逻辑用一句话概括就是连接池的大小不是越大越好而是取决于数据库实例能扛住的并发数、单个连接处理查询的时间和业务请求的峰值速率。3.2 我常用的 HikariCP 配置基线spring: datasource: hikari: pool-name: MyAppHikariPool maximum-pool-size: 20 minimum-idle: 5 idle-timeout: 300000 connection-timeout: 3000 max-lifetime: 1800000 connection-test-query: SELECT 1 validation-timeout: 1000 leak-detection-threshold: 60000逐个解释这些参数以及为什么这么定pool-name给连接池一个名字监控和多实例排查时一目了然。maximum-pool-size: 20我一般根据数据库配置和业务并发来定中小型服务 20 左右开始试压测后加减。注意这里讲的是连接数不是并发请求数一个连接在同一瞬间只能执行一个查询但连接复用率很高。minimum-idle: 5保留几个空闲连接应对突发流量。如果系统并发波动极大可以设成和 maximum 一致如果有周期性空闲时段建议留 5~10 就够。idle-timeout: 300000空闲 5 分钟后回收连接。注意 HikariCP 有检查机制如果minimumIdle小于maximumPoolSize它会在空闲期逐渐收缩到 minimum。connection-timeout: 3000客户端等待连接的超时时间设太大会让请求堆积设太小容易在数据库瞬时慢时误伤。3 秒是我在多个项目里试出来比较均衡的值很多团队也喜欢用 5 秒。max-lifetime: 1800000连接最长存活 30 分钟。这个值必须小于数据库服务端的wait_timeoutMySQL 默认 8 小时否则会出现数据库已断开但连接池不知道的情况。connection-test-query: SELECT 1MySQL 下测活语句。有些数据库比如 PostgreSQL不需要配置这个HikariCP 会自动用 JDBC 协议的 isValid 方法检测但为了统一我就都配上。validation-timeout: 1000测活超时 1 秒避免数据库卡死时连接被反复试探拖慢启动。leak-detection-threshold: 60000连接泄漏检测阈值。如果一个连接从连接池借出超过 60 秒未归还HikariCP 会打警告日志并输出泄漏时的调用栈。这个参数对排查连接不够用但是没慢 SQL的问题帮助极大。连接池参数要在越小越不浪费资源和越大扛得住峰值之间找平衡没有银弹。我见过很多团队把 maximum 开到 200结果数据库自己先扛不住慢查询拖垮整个链路——连接池调大不等于性能变好它只是把压力下移到了数据库。3.3 怎么验证连接池参数有效配置完了别急着上线先在灰度环境做一次压测 进程线程分析。压测时重点看两个指标获取连接耗时connection acquire time和连接等待线程数。如果每秒请求量 1000但maximum-pool-size只有 10你大概率会看到大量线程阻塞在HikariPool.getConnection上应用响应时间从 50ms 直接飙到 3 秒以上。另一个验证方式是通过启动日志确认连接池名称和参数生效HikariPool-1 - Start completed.日志里各个参数会完整打印检查 expected maximum 是否和你配置的一致。连接池没生效的常见原因是你配置了spring.datasource.hikari.*但项目里其实混入了其他连接池依赖比如某个公司内部脚手架强制引入了 commons-dbcp2Spring Boot 自动配置选中了别的池子。这类问题通过日志里的 Start completed 一眼就能看出名堂。4. 从 JDBC 到 MyBatis让配置真正落地到业务代码4.1 JDBC 方式下的数据源使用如果你用的是最原始的JdbcTemplate配置好数据源后可以直接注入使用Service public class UserService { private final JdbcTemplate jdbcTemplate; public UserService(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } public User findById(Long id) { return jdbcTemplate.queryForObject( SELECT id, name, email FROM user WHERE id ?, new Object[]{id}, (rs, rowNum) - new User(rs.getLong(id), rs.getString(name), rs.getString(email)) ); } }这个方式简单直接不引入更多依赖适合超轻量场景。但项目一旦复杂起来SQL 拼接、字段映射、分页查询会让你在维护地狱里挣扎。所以现实中绝大多数项目选 MyBatis 或 JPA。4.2 MyBatis 集成时的数据源配置要点MyBatis 和 Spring Boot 集成引入mybatis-spring-boot-starter后DataSource 依然是同一个spring.datasource配置不需要单独特配。它真正独特的是另外两类配置Mapper 扫描和 SQL 映射。mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.demo.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImplmapper-locations指向 XML 文件位置。别低估这个路径很多人拼错后启动不报错一执行 Mapper 方法就提示Invalid bound statement (not found)。map-underscore-to-camel-case把数据库的user_name自动映射到 Java 的userName强烈建议开启。log-impl开发环境把 SQL 打印到控制台可以直观看到 MyBatis 实际执行了什么 SQL、参数是什么。生产环境记得关闭否则日志量翻倍。在 Spring Boot 启动类或配置类上加MapperScan(com.example.demo.mapper)后MyBatis 会扫描指定包下的 Mapper 接口并自动注册为 Spring Bean。这块和数据库配置的关联在于MyBatis 会话工厂SqlSessionFactory在初始化时需要用到DataSource如果数据源配置有误很多 MyBatis 相关的错误会在启动时暴露出来比如Failed to determine a suitable driver class。4.3 事务和连接池的关系不讲这个等于没讲配置说完 MyBatis 必须连带上事务。Spring 的事务管理是基于连接池的Transactional方法执行时Spring 从连接池里借一个连接开启事务方法执行完要么提交要么回滚最后把连接还给连接池。这里有几个经典注意点第一Transactional只对RuntimeException和Error默认回滚checked exception 不会触发回滚。这是一个让无数人困惑的事务细节——你抛了个自定义业务异常继承了Exception事务依然提交了。解决办法是在注解里指定rollbackFor Exception.class。**第二**Spring 事务的传播级别中REQUIRED是默认值。如果同类内部方法调用A 方法调 B 方法都在同一个类里Transactional注解实际上不生效因为 Spring 代理机制拦不住内部调用。这个问题和连接池间接相关事务不生效意味着连接可能提前归还业务在多线程/异步场景下就会出诡异问题。**第三**连接池的maxLifetime和数据库的wait_timeout要配合好否则会出现 连接已死但 Spring 事务还拿它干活的情况。MySQL 默认wait_timeout是 8 小时一般到近 6 小时就断开空闲连接而 HikariCP 的max-lifetime默认 30 分钟小于 6 小时所以默认值下没什么问题——但如果你手动调大了max-lifetime而数据库 wait_timeout 是 2 小时那你就会不断遇到连接失效的报错。5. 多数据源方案从一个库到一堆库的演进5.1 什么时候需要多数据源项目初期单库单连接是常态但慢慢会碰到这些场景业务库和日志库分离日志写得多、业务查得多订单中心和用户中心处于不同数据库实例甚至不同物理机报表和主业务隔离报表查询都是重 SQL会拖垮主库读写分离主库写入从库查询。遇到多数据源时最忌讳的是在代码里new两个DataSource然后互相赋值。这一步走错了后面全是洞。更规范的做法是利用 Spring Boot 的配置分组和ConfigurationProperties隔离生成多个数据源 Bean。5.2 双数据源配置模板比如在application.yml里自定义两组连接信息app: datasource: primary: url: jdbc:mysql://127.0.0.1:3306/main_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: primary_pwd driver-class-name: com.mysql.cj.jdbc.Driver secondary: url: jdbc:mysql://127.0.0.1:3306/log_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: secondary_pwd driver-class-name: com.mysql.cj.jdbc.Driver然后在配置类里手动创建两个数据源 BeanConfiguration public class DataSourceConfig { Bean Primary ConfigurationProperties(prefix app.datasource.primary) public DataSource primaryDataSource() { return DataSourceBuilder.create().build(); } Bean ConfigurationProperties(prefix app.datasource.secondary) public DataSource secondaryDataSource() { return DataSourceBuilder.create().build(); } }Primary关键。它告诉 Spring 这个 Bean 在自动注入DataSource时优先使用否则启动会因为存在多个候选 Bean 而报NoUniqueBeanDefinitionException。如果你用 MyBatis还需要指定多个SqlSessionFactoryBean Primary public SqlSessionFactory primarySqlSessionFactory( Qualifier(primaryDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath:mapper/primary/*.xml)); return factoryBean.getObject(); }注意Qualifier(primaryDataSource)指定数据源名称然后 Mapper XML 分开放在不同目录下避免两个库的表结构混乱。初学阶段最容易忽略的是myBatis mapper-locations的通配符会同时匹配两个目录下的 XML导致 Mapper 方法绑定到错误的 SqlSessionFactory。5.3 动态数据源一个更优雅的套路多数据源配置多了代码里到处Qualifier会很累更合理的方案是引入AbstractRoutingDataSource做动态路由。原理是这个类维护一个MapObject, Object目标数据源每次getConnection()时根据determineCurrentLookupKey()的返回值路由到对应的数据源。你可以结合ThreadLocal或者自定义注解比如DS(secondary)在运行时切换数据源。网上很多 MyBatis-Plus 多数据源插件就是基于这个思路实现的。但要注意AbstractRoutingDataSource只解决连接从哪个池来的问题不解决事务切换——如果在事务里切换了数据源事务还是绑定在原连接上新库不在事务范围内分布式事务需要额外引入 Seata 之类的方案。我自己的经验是除非数据源数量固定且在 3 个以内否则别手写动态路由直接用一个成熟的多数据源库或者中间件。手写方案首版跑通容易后续维护才是真正的无底洞尤其是连接池隔离和监控告警很难面面俱到。6. 把配置揉碎了看从启动报错到线上抽风6.1 启动报错归因手册配置数据库最容易遇到的启动错误我按常见顺序列成一张表报错信息大概率原因解决思路Failed to configure a DataSource: url attribute is not specified没配spring.datasource.url或拼写错误检查 yml/key 名Spring Boot 属性名从 2.x 后要求使用spring.datasource.url而非spring.datasource.jdbc-url后者仅限自定义配置Failed to determine a suitable driver class缺少数据库驱动依赖或者 url 里 jdbc prefix 和驱动不匹配确认pom.xml里有对应驱动确认jdbc:mysql://、jdbc:postgresql://前缀Access denied for user rootlocalhost账号密码错误、用户没有远程访问权限检查 MySQL 的用户权限表GRANT ALL ON db.* TO user%Unknown database: xxx数据库名没建或连错实例登录数据库确认库存在注意大小写敏感Public Key Retrieval is not allowedMySQL 8 caching_sha2_password 非 SSL加allowPublicKeyRetrievaltrue或改用mysql_native_password认证Communications link failure网络不通、防火墙拦了端口、数据库服务没启动telnet 127.0.0.1 3306检查连通性确认数据库监听中HikariPool-1 - Exception during pool initialization连接池初始化失败通常是 URL/账号细节错逐项核对 username/password测试 url 能否用命令行客户端连上每个错误背后都有具体原因不要盯着报错日志最后一行反复看应该往上翻找 Caused by 部分——Spring Boot 的异常栈很长真正的根因往往藏在最底部。6.2 连接池提前死亡一个经典线上故障我在一家公司做订单系统时遇到过这样一个问题系统每天早上 8 点半到 9 点半之间准时出现大量连接超时过了 10 点又恢复了。排查了很久才发现数据库运维每天 8:30 执行一次FLUSH HOSTS;清理异常连接把超过 5 分钟的 TCP 连接全断掉了。我们的 HikariCPmax-lifetime默认 30 分钟根本来不及检测到连接已经失效到了高峰期所有请求都在跟一堆死连接纠缠。这个问题暴露了一个配置层面的盲区连接池检测连接失效的机制和你运维策略的配合比任何单点参数都重要。后来我们在连接池配置里额外加了中间件层做连接探活同时把max-lifetime调小到 10 分钟早于数据库清理时间问题消失。上线前最好问清楚底层数据库的运维周期这比看任何调优指南都值钱。6.3 连接泄漏排查思路连接池调优做得再好也挡不住代码泄漏连接。数据库连接泄漏的场景通常是这样的方法里手动getConnection()拿了连接中间抛异常没有 finally 归还。此时连接池可用连接数逐秒下降直到归零后所有新请求都等着获取连接。HikariCP 的leak-detection-threshold就是为这个设计的。把它设成一个合理值比如 60000ms后如果连接借出超时未归还日志里会出现Connection leak detection triggered, stack trace: java.lang.Exception at com.example.service.OrderService.save(OrderService.java:55)这条日志直接把泄漏点定位到业务代码行比猜测高效太多了。但要注意leak-detection-threshold本身有性能开销文档也不建议在生产环境全天开启一般排查问题时临时打开排查完再关掉。6.4 换数据库的配置周期比你想象的长最后说一个生产上常见的真实场景把数据库从 MySQL 换到 PostgreSQL或者加一个 Oracle 实例。一下改动一堆配置不说还得注意驱动类名、连接串格式、方言和驱动行为差异。很多团队在这个环节栽跟头因为单测里用的是 H2 内存库和生产不一致导致单测全绿、一上线就红。如果你的项目允许数据库连接这块的配置建议把它抽象成基础设施层单独封装、统一读取而不是散落在业务代码里各处 new DataSource。这样换库时只改一行代码加一份配置。7. 配置管理把秘密藏好把环境分开7.1 多环境配置的最佳姿势application-dev.yml、application-prod.yml这种按 profile 分文件的方式简单直观大多数项目都在用。但还有一个细分问题不同 profile 之间重复的公共配置怎么办重复的配置散落在多份文件里维护成本会逐渐失控。Spring Boot 支持spring.config.import机制可以把公共段抽到application-common.ymlspring: application: name: order-service config: import: classpath:application-common.ymlapplication-common.yml里放连接池的公共参数、MyBatis 通用配置、Jackson 设置等差异部分留在各自 profile 里比如 dev 用本地库、prod 用云数据库。7.2 密码安全别把口令裸奔在仓库里代码仓库里明文写数据库密码是我见过最普遍也最危险的做法。一旦仓库变成公开或被内部员工批量拉取数据库等于裸奔。最低成本的改进是用 Jasypt 或 Spring Cloud Config 做配置加密/外部化。用 Jasypt 加密后配置长这样spring: datasource: password: ENC(加密后的密文)启动时通过环境变量传入加密密钥JASYPT_ENCRYPTOR_PASSWORD。这样仓库里不出现明文密码又能正常启动。要强调的是加密不是万能的只要应用运行时能解出密码拿到服务器权限的人照样能破。所以更可靠的长期方案是托管到专门的密钥管理服务然后应用侧仅通过环境变量注入不落盘。7.3 Spring Boot 3.x 下配置的新变化Spring Boot 3 基于 Jakarta EE、Spring Framework 6配置管理上也有一些小调整。比如spring.config.import成为标准机制spring.datasource.url和spring.datasource.username这些老属性依然保留但一些旧属性被清理掉。用 Spring Boot 2.5 之前写的老配置迁移到 3.x 时启动报Unknown property的概率不小——迁移前先去官方文档的 Configuration Changelog 里把涉及到的 key 过一遍能省下大量猜测时间。8. 结尾把配置当作工程问题而不是填空题Spring Boot 的数据库配置表面上看是一组 yaml 属性实际上背后是连接池生命周期、事务边界、部署环境和运维策略的博弈。写配置不难但让配置在各种极端条件下依然稳如磐石才是一个有经验的开发者真正要修炼的地方。我个人实际跑项目的心得是每上一个新服务第一周别急着加功能先花时间把数据源配置、连接池参数、监控指标、告警规则完整梳理一遍。这一周看清的底层情况比后面几个月踩坑省下的时间多得多。把连接池的每次超时、每一条连接泄漏、每一个启动报错都当成了解系统的入口而不是简单的修 bug你对自己的系统会有完全不一样的感觉。最后分享一个小技巧无论用什么连接池养成上线后定期看一下连接池监控面板的习惯重点关注activeConnections和pendingThreads的变化曲线。这两个指标能提前暴露数据源容量和业务增长的矛盾等用户开始投诉系统变慢再去看就晚了。