压测时看到一个很干脆的失败:把 hikari.maximum-pool-size 调到 2、connection-timeout 设成 1000 毫秒,同时发三个会占住连接 3 秒的请求,第四个请求立刻返回 HTTP 500。日志只有两行,第一行是 Could not open JDBC Connection for transaction,第二行是根因:HikariPool-1 - Connection is not available, request timed out after 1006ms (total=2, active=2, idle=0, waiting=1)。
这行日志把状态说得很清楚:池子里总共 2 个连接,2 个都在忙,空闲 0 个,还有 1 个请求在排队,等了 1006 毫秒还没等到,于是超时。连接池(connection pool)就是把已经建好的数据库连接存起来反复用的一小撮连接,省掉每次请求都握手的开销。池子满了不会让请求变慢,而是让它直接失败。
更极端的一次是把它设成 1。服务在启动阶段就挂了,报错发生在 Flyway 迁移那一环,日志是 HikariPool-1 - Connection is not available, request timed out after 1012ms (total=1, active=1, idle=0, waiting=0),随后进程退出。迁移自己要占一个连接,就没有任何余量留给别的初始化动作。这一篇从这两个现象出发,讲池子怎么定、迁移怎么管、事务放在哪一层。
为什么默认是 HikariCP
Spring Boot 的 jdbc starter 自带 HikariCP,不需要额外依赖,也不需要在代码里 new 一个数据源。它被选为默认实现的原因很实际:字节码小、获取连接快、配置项少。所谓「快」主要体现在高并发下拿连接的锁竞争,连接池本身的逻辑就是借出、归还、超时、保活这几件事,做得再复杂也绕不开。
自动配置的触发条件是 classpath 里有 DataSource 且容器里没有现成的数据源 bean。你只要配了 spring.datasource.url,它就会建一个 HikariDataSource,并从 spring.datasource.hikari.* 读参数。很多人把参数写在 spring.datasource.hikari 之外,比如自己造了个 hikari 前缀,结果不生效,池子还是默认的 10,压测时才发现数字对不上。
默认值里有两个值得记住:maximum-pool-size 默认 10,connection-timeout 默认 30 秒。30 秒意味着池子满时请求要卡半分钟才报错,在这半分钟里 Tomcat 线程一直被占着,很容易把整个服务拖死。生产上通常会把它降到 1 到 3 秒,快速失败比慢慢排队更可控。
这一篇用到的依赖只有三项,版本仍由父 pom 管理:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
</dependencies>
web 和 actuator 依赖沿用上一篇。注意 H2 是 runtime scope,Flyway 不写版本。启动命令不复杂,打包后直接跑 jar:
mvn -q -DskipTests package
java -jar target/demo-0.0.1.jar
池子开多大:公式、上限和实测
流传最广的经验公式是「连接数等于核心数乘 2 再加磁盘数」。四核加一块盘的机器算出来是 9,所以很多模板直接写 10。这个公式来自单机数据库的年代,前提是连接真的在干活。现在的请求大部分时间在等网络、等锁、等远程服务,连接并不总是忙,照搬公式往往开得过大。
真正该先看的是数据库那侧的上限。云数据库通常按套餐限制最大连接数,一个实例允许几十到几百不等,具体看规格。假设上限是 100,应用有 10 个实例,每个实例池子开 20,加起来就是 200,必然有一部分连不上。正确算法是先减去运维、迁移、监控占用的连接,再把余量按实例数平分,最后留一点给发布时的重叠期。
这台机器上的实测给了两个边界。池子 5 时,单个请求的写入和查询都正常;池子 2 时,三个慢请求就能把它打满,第四个在 1006 毫秒后失败;池子 1 时,连启动都过不去,因为 Flyway 迁移要先占一个。结论不是「越大越好」,而是「至少要比启动期同时需要的连接多,再按并发和数据库上限取一个保守值」。
一个可以直接用的起点是 5 到 10,然后看指标调整。Hikari 会通过 Micrometer 暴露 hikaricp.connections.active、idle、pending 这些值,接上 actuator 就能看到。判断标准是 pending 是否长期大于 0,以及 active 是否长期贴着上限。如果两者都成立,先查慢 SQL 和连接泄漏,再考虑加池子;如果 active 长期只有 1 到 2,说明池子开大了,纯属浪费数据库连接名额。
把这些参数落到配置文件里,就是下面这几行。这里把池子定在 5、超时定在 1 秒,正是后面能复现「第四个请求失败」的那组值:
spring:
datasource:
url: jdbc:h2:mem:app;DB_CLOSE_DELAY=-1
username: SA
password: ""
hikari:
maximum-pool-size: 5
connection-timeout: 1000
flyway:
locations: classpath:db/migration
参数名里的层级不能省。写成 spring.datasource.maximum-pool-size 不会生效,也没人告诉你,因为绑定失败只是忽略。验证办法是启动时看有没有 HikariPool-1 - Added connection 这行,再用 actuator 的 /actuator/metrics/hikaricp.connections.max 看实际值,别靠猜。
连接泄漏和池子满的表现很像,但方向相反:池子满通常有突发流量,泄漏则是 active 只增不减,重启后恢复。用 JdbcTemplate 一般不会泄漏,因为它把关闭放在 finally 里;自己 dataSource.getConnection() 又忘了 close,才会一天泄漏几个。看到这种曲线,直接搜代码里的手动获取连接。
Flyway:把表结构变更当代码管
Flyway 是一个数据库版本管理工具:把每次表结构变更写成一个带编号的 SQL 文件,应用启动时按编号顺序执行还没执行过的那些,并在数据库里记一张历史表。好处是任何环境都能从空库走到同一个结构,不用再靠「谁的电脑上手动执行过哪条 ALTER」这种口头传承。
文件放在 src/main/resources/db/migration,命名必须是 V编号__说明.sql,编号和说明之间是两个下划线。少一个下划线、用空格代替、编号写成 1.1,都会被判定为无效命名而跳过或报错。第一条迁移就叫 V1__init.sql:
create table items (
id bigint generated by default as identity primary key,
name varchar(100) not null
);
对应的配置是 spring.flyway.locations=classpath:db/migration,默认值其实就是这个路径,写出来是为了让后来的人一眼看到。启动日志会打出 Migrating schema "PUBLIC" to version "1 - init" 和 Successfully applied 1 migration to schema "PUBLIC", now at version v1,前者表示正在执行,后者表示执行成功并更新了版本。
最重要的一条纪律:已经上线的迁移脚本不能再改。Flyway 会把脚本内容的校验和记进历史表,改动一个空格都会导致下次启动报校验和不匹配,然后拒绝启动。要改结构就新增 V2__add_index.sql,让它在所有环境按顺序执行。开发库如果只有你自己,可以清库重来;共享的测试库和生产库,永远只往前加。
还有两个实际约束。第一,迁移在启动时执行,多个实例同时启动会抢同一把锁,后到的实例会等,等不到就失败,所以滚动发布时要么把迁移拆成独立的发布步骤,要么确认 Flyway 的锁等待时间够长。第二,迁移脚本要写成可重复执行的增量,避免「先删表再建表」这种会丢数据的写法,除非你明确就是要重置环境。
为什么不用手写 SQL 加人工执行?因为人工执行没有记录、没有顺序、没有回滚依据,三个人在三个环境执行的结果可能完全不同。Flyway 的代价是启动多了一步、脚本要遵守命名、改错要新增版本;换来的是环境可重建、变更可审计。项目超过两个人,这笔交换就划算。
JdbcTemplate:够用,但要看清列名
数据访问层先用 JdbcTemplate,它把 JDBC 那些重复的样板代码包掉:拿连接、建语句、设参数、关资源、处理异常。你只需要写 SQL 和取值。它不生成 SQL,也不管理实体关系,所以性能可预期,出问题能直接看到执行的那条语句。
目录按职责分成四块,迁移脚本单独放资源目录,跟 Java 代码一起进 jar:
package com.example.demo.repository;
import java.sql.PreparedStatement;
import java.util.List;
import java.util.Map;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.support.GeneratedKeyHolder;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.stereotype.Repository;
@Repository
public class ItemRepository {
private final JdbcTemplate jdbc;
public ItemRepository(JdbcTemplate jdbc) {
this.jdbc = jdbc;
}
public long insert(String name) {
KeyHolder keys = new GeneratedKeyHolder();
jdbc.update(con -> {
PreparedStatement ps = con.prepareStatement(
"insert into items(name) values (?)", new String[]{"id"});
ps.setString(1, name);
return ps;
}, keys);
return keys.getKey().longValue();
}
public List<Map<String, Object>> findAll() {
return jdbc.queryForList("select * from items order by id");
}
public Map<String, Object> findById(long id) {
List<Map<String, Object>> rows =
jdbc.queryForList("select * from items where id = ?", id);
return rows.isEmpty() ? null : rows.get(0);
}
}
服务层和控制器只做编排:插入返回主键,查询为空就抛 ItemNotFoundException,由上一篇的全局处理器转成 404。启动命令和前面一样,打包后 java -jar target/demo-0.0.1.jar,端口 8081。
curl -s -X POST 127.0.0.1:8081/api/items \
-H "Content-Type: application/json" -d '{"name":"widget"}'
{"name":"widget","id":1}
curl -s 127.0.0.1:8081/api/items/1
{"ID":1,"NAME":"widget"}
第二条返回的字段是大写的 ID 和 NAME,这不是接口写错,而是 H2 的默认行为:未加引号的列名会被转成大写。而 queryForList 直接拿结果集的列标签作为 Map 的键,于是原样返回。换成 PostgreSQL,同样的代码会返回小写的 id 和 name,因为它的默认规则是小写。
这个差异在开发用 H2、生产用 PostgreSQL 的组合里特别危险:前端按小写取值,联调时看着正常(如果本地用 PostgreSQL),一上生产就全变成 undefined。正确做法是不要用 select * 加 Map 返回给外部,改成显式列别名或映射到固定的返回对象,让接口契约与数据库方言无关。
select * 还有一个更隐蔽的问题:表加字段后查询结果会跟着变,接口响应体悄悄多出几列。如果其中包含手机号、内部备注这类字段,就等于无意中泄露。对外接口永远显式列出需要的列。写 SQL 时参数一律用问号占位,不要把用户输入拼进字符串。JdbcTemplate 的 update(sql, args...) 会做预编译和参数绑定,既防注入也省掉转义。拼接 SQL 的代码一旦出现在报表或搜索接口里,往往就是注入入口,而且这种写法在测试环境不会暴露,只有人故意构造输入时才会。
批量写入不要循环调用单条 insert。一千条数据循环插入就是一千次网络往返,即使连接池够用,耗时也会是批量的几十倍。batchUpdate 把多条语句一次发给驱动,代价是单批太大时数据库日志和锁持有时间变长,常见做法是每批五百到一千条,分批提交。
事务边界:放在 service,不要放在 controller
事务就是一组要么全部成功、要么全部失败的操作。转账扣款和加款必须在同一个事务里,只成功一半就是事故。Spring 的声明式事务靠 @Transactional 加代理实现:调用经过代理时,代理在方法前开启事务、方法后提交、抛异常时回滚。
边界应该放在 service 层,因为一个业务动作往往包含多次数据库写入,repository 的方法只是其中一步。放在 controller 里会导致事务范围过大,把参数校验、远程调用都包进去,事务持有连接的时间变长,池子更容易满。放在 repository 里又太细,两次 insert 各自提交,中间失败就无法回滚。
package com.example.demo.service;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class ItemService {
private final ItemRepository repository;
public ItemService(ItemRepository repository) {
this.repository = repository;
}
@Transactional
public void createPair(String first, String second) {
repository.insert(first);
repository.insert(second);
}
}
这里有个必须知道的坑:同类方法自调用时事务不生效。比如 outer() 里调用 this.inner(),inner() 上的 @Transactional 不会起作用,因为调用没有经过代理,直接走的是原始对象。表现是内层方法抛了异常,外层已经写入的数据没有回滚,而且日志里没有任何提示。
解决办法有三种:把内层方法挪到另一个 bean,让调用跨对象走代理;在类里注入自己(需要 @Lazy 避免循环依赖);或者干脆用 TransactionTemplate 显式写出事务范围。第三种最直白,适合逻辑复杂、需要精确控制提交时机的场景:
@Service
public class BatchService {
private final ItemRepository repository;
private final TransactionTemplate tx;
public BatchService(ItemRepository repository, TransactionTemplate tx) {
this.repository = repository;
this.tx = tx;
}
public void createPair(String first, String second) {
tx.executeWithoutResult(status -> {
repository.insert(first);
repository.insert(second);
});
}
}
还有两个默认规则要记:@Transactional 默认只对运行时异常回滚,受检异常不回滚;默认传播级别是 REQUIRED,外层有事务就加入,没有就新建。如果方法里 catch 了异常又没重新抛出,事务同样不会回滚,因为代理根本不知道出过事。这三种「看起来有注解、实际不回滚」的情况,占了事务问题的大半。
连接和事务出错时先看什么
下面这张表按现象查。第一列尽量写成日志里真实出现的那句话,第二列是根因,第三列是第一条命令或第一个位置。连接池的问题优先看 Hikari 那行括号里的四个数字。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| HTTP 500,日志 Could not open JDBC Connection for transaction | 池子被占满,等待超过 connection-timeout | Hikari 日志里的 total、active、idle、waiting |
| 启动阶段退出,迁移时报连接超时 | 池子太小,迁移和初始化抢同一个连接 | 看日志里 total=1、active=1 的那一行 |
| 接口字段变成大写 ID、NAME | H2 把未加引号的列名转成大写 | 确认数据库方言和 queryForList 的键来源 |
| 启动报 Flyway checksum mismatch | 改动了已经执行过的迁移脚本 | 看历史表记录和脚本文件的修改时间 |
| 异常发生了但数据没回滚 | 异常被 catch,或同类方法自调用绕过代理 | 搜 catch 和 this. 开头的方法调用 |
| 运行几天后池子慢慢满,重启就恢复 | 某处拿了连接没归还,典型是手工 getConnection | 看 active 是否只增不减,搜 getConnection |
| 多实例同时发布,部分实例起不来 | Flyway 迁移锁被别的实例占着 | 看日志里的 lock 等待和发布顺序 |
| 查询很慢,数据库 CPU 却不高 | 慢 SQL 占着连接,后面全在排队 | Hikari pending 指标加数据库慢查询日志 |
| 本地正常,生产插入报字段过长 | 两边列定义长度不一致,迁移没同步 | 对比 flyway_schema_history 的版本号 |
这张表里最容易被误判的是第三行。看到大写字段,很多人第一反应是「JSON 序列化配置错了」,去改 Jackson 的命名策略,结果只影响新增的接口,老接口还是大写。根因在数据库返回的列标签,要么改 SQL 用别名,要么换映射方式,序列化层不该背这个锅。
边界与代价
连接池不是越大越好,这一点在云数据库上尤其明显。池子开大只提升了「同时能有多少请求在等数据库」,并没有提升数据库的处理能力。数据库连接数上去后,每个连接的内存、上下文切换、锁竞争都会增加,整体吞吐反而下降。判断池子上限应该看数据库,不是看应用配置能写多大。
把超时调短是好事,但有代价:数据库短暂抖动时,原本等 3 秒就能拿到的请求会直接失败。这个取舍取决于接口能否重试。查询类的幂等接口可以短超时加一次重试;写接口不能盲目重试,否则会重复插入。给写接口配一个幂等键,比调超时更重要。
Flyway 的代价是启动耦合。应用启动必须等迁移完成,数据库不可用时服务也起不来。这其实是好事:结构不对就不该接流量。但它也意味着迁移必须快,几百万行的数据变更不能放在启动脚本里,应该拆成独立的运维任务,脚本只做结构变更。
什么时候该从 JdbcTemplate 换成 JPA?当实体关系复杂、需要大量按对象图查询、团队更熟悉 ORM 时,JPA 省的是映射代码。代价是 SQL 不透明,复杂查询要么写 JPQL 要么退回原生 SQL,性能问题更难定位。反过来说,报表、批量、复杂 SQL 为主的系统,JdbcTemplate 更合适。两者的选择看「查询复杂还是对象关系复杂」,不看流行度。
JdbcTemplate
SQL 完全可控,返回结构简单,排查直接看语句。适合查询逻辑多、需要精细控制、团队能写 SQL 的系统。代价是映射代码要自己写,字段改名要同步改多处。
JPA 与 Hibernate
对象与表映射自动,关联查询写起来快,适合领域模型复杂、以增删改查为主的系统。代价是生成的 SQL 不直观,懒加载容易触发额外查询,性能问题需要经验。
最后是规模边界。单库单表、连接数 10 以内、QPS 几百,这套组合非常稳。再往上,先做读写分离和索引优化,然后才是分库分表。分库分表会让「一个事务跨两个库」变成分布式事务,代价是整个一致性模型都要重做。没有到单表千万级、写入成为瓶颈之前,不要提前付这笔成本。
当天能自己验证的练习
- 把
maximum-pool-size改成 2、超时改成 1000,写一个 sleep 3 秒的接口,同时发三个请求再发第四个,抄下 Hikari 那行日志的四个数字。 - 把池子改成 1 重启,观察 Flyway 迁移阶段直接失败,记录
total=1, active=1和进程退出码。 - 新建
V2__add_index.sql,加一个索引,重启确认版本从 v1 走到 v2,再把 V1 改一个空格,看校验和报错。 - 在 service 里写
outer()调用带@Transactional的inner(),让 inner 抛异常,确认第一条插入没有回滚。 - 把查询改成显式别名
select id as id, name as name,对比 H2 返回的键,再解释为什么生产换库后行为会变。
小结
三句话收束:池子大小的上限由数据库给,不由应用配置给,先保证启动期够用,再用 active 和 pending 指标调;Flyway 的脚本只往前加,改历史脚本等于让服务起不来;事务边界放 service,自调用和吞异常是两个最常见的失效原因。
下一篇讲鉴权。数据层解决的是「谁能读到什么」,但前提是先知道「请求是谁发的」。那篇会从一条没有任何过期时间的令牌讲起,说明登录、令牌校验、权限判断分别该落在哪一层,以及为什么自己签令牌只适合过渡。