压测时看到一个很干脆的失败:把 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:

controller:接收请求,调用 service
service:业务规则与事务边界
repository:SQL 与结果映射
config:数据源与迁移相关装配
resources/db/migration:V1、V2 等迁移脚本
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-timeoutHikari 日志里的 total、active、idle、waiting
启动阶段退出,迁移时报连接超时池子太小,迁移和初始化抢同一个连接看日志里 total=1、active=1 的那一行
接口字段变成大写 ID、NAMEH2 把未加引号的列名转成大写确认数据库方言和 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 几百,这套组合非常稳。再往上,先做读写分离和索引优化,然后才是分库分表。分库分表会让「一个事务跨两个库」变成分布式事务,代价是整个一致性模型都要重做。没有到单表千万级、写入成为瓶颈之前,不要提前付这笔成本。

当天能自己验证的练习

  1. 把 maximum-pool-size 改成 2、超时改成 1000,写一个 sleep 3 秒的接口,同时发三个请求再发第四个,抄下 Hikari 那行日志的四个数字。
  2. 把池子改成 1 重启,观察 Flyway 迁移阶段直接失败,记录 total=1, active=1 和进程退出码。
  3. 新建 V2__add_index.sql,加一个索引,重启确认版本从 v1 走到 v2,再把 V1 改一个空格,看校验和报错。
  4. 在 service 里写 outer() 调用带 @Transactional 的 inner(),让 inner 抛异常,确认第一条插入没有回滚。
  5. 把查询改成显式别名 select id as id, name as name,对比 H2 返回的键,再解释为什么生产换库后行为会变。

小结

三句话收束:池子大小的上限由数据库给,不由应用配置给,先保证启动期够用,再用 active 和 pending 指标调;Flyway 的脚本只往前加,改历史脚本等于让服务起不来;事务边界放 service,自调用和吞异常是两个最常见的失效原因。

下一篇讲鉴权。数据层解决的是「谁能读到什么」,但前提是先知道「请求是谁发的」。那篇会从一条没有任何过期时间的令牌讲起,说明登录、令牌校验、权限判断分别该落在哪一层,以及为什么自己签令牌只适合过渡。