数据源配置

约 1210 字大约 4 分钟

布欧-Lewyon

2026-05-15

Spring Boot 通过 spring-boot-starter-jdbc 或 spring-boot-starter-data-jpa 自动配置数据源和连接池。

起步依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

spring-boot-starter-data-jpa 已包含 spring-boot-starter-jdbc，不需要重复引入。

数据源配置

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: db_user
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver

PostgreSQL 驱动坐标：

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

内嵌数据库（开发/测试）

Spring Boot 自动配置 H2、HSQLDB、Derby 等内嵌数据库。只需引入依赖并留空连接池配置：

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

不加 spring.datasource.url 时，Spring Boot 自动使用 jdbc:h2:mem:testdb。

HikariCP 连接池

Spring Boot 默认使用 HikariCP 作为连接池实现，零配置即可工作。常见调优参数：

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      idle-timeout: 300000
      connection-timeout: 30000
      max-lifetime: 1800000

参数	说明	默认值
`maximum-pool-size`	最大连接数	10
`minimum-idle`	最小空闲连接数	10
`connection-timeout`	等待连接超时（毫秒）	30000
`idle-timeout`	空闲连接最大存活时间（毫秒）	600000
`max-lifetime`	连接最大寿命（毫秒）	1800000

连接池不是越大越好。对于常见业务，10-20 个连接通常足够；过大反而增加数据库负载。从默认值开始，通过压测逐步调整。

进阶阅读：HikariCP 连接池内部结构

初学者了解基础配置即可跳过。

HikariCP 是 Spring Boot 默认的连接池实现，其核心设计围绕极致性能展开。理解其内部结构有助于精准调优：

ConcurrentBag 算法：HikariCP 的无锁设计大幅减少了 CAS 竞争，这也是为什么 maximum-pool-size=10 时表现优于传统加锁池的 20 个连接。

这种设计的优势：无锁路径（步骤 1）在低竞争下无 CAS 开销，吞吐量显著高于传统 synchronized 连接池。这也是为什么 HikariCP 在 maximum-pool-size=10 时表现优于其他池的 20 个连接——因为无锁让每个连接利用率更高。

生产意识：HikariCP 的关键调优参数不是 maximum-pool-size，而是 maxLifetime。默认 maxLifetime=1800000ms（30 分钟） 是基于 MySQL 的 wait_timeout 默认 8 小时设计的折中值。如果你的数据库（如 AWS Aurora / RDS Proxy）有更短的连接超时，需要相应调整 maxLifetime（建议比数据库侧超时短 5-10 秒）。另外，leak-detection-threshold 参数可以在连接被借用超过指定毫秒时打印告警日志——设置 spring.datasource.hikari.leak-detection-threshold=60000（60 秒）可以有效发现连接泄露。

多数据源（进阶）

当需要连接多个数据库时，手动声明多个 DataSource Bean：

@Configuration
public class DataSourceConfig {

    @Primary
    @Bean(name = "primaryDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean(name = "secondaryDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }
}

多数据源会显著增加配置复杂度（需要为每个数据源绑定 JdbcTemplate、TransactionManager、JPA 的 EntityManagerFactory 等），建议在明确需求时再引入。

小结

spring-boot-starter-jdbc 自动配置 HikariCP + DataSource。
配置方式：spring.datasource.url / username / password。
内嵌 H2 数据库适合开发与测试，生产使用 PostgreSQL / MySQL 等。
HikariCP 参数按需调整，从默认值开始。
易错：生产环境务必配置 password（用环境变量注入）。driver-class-name 对于主流数据库（PostgreSQL、MySQL、H2）可以省略——Spring Boot 会根据 JDBC URL 自动推断。

生产意识：连接池泄露是线上最常见的数据库问题之一。场景：业务代码中拿到 Connection 后执行了某些远程调用（RPC、HTTP），远程调用超时阻塞了线程，导致 Connection 一直被占用不归还——最终池子被耗尽，所有请求排队等待，服务雪崩。连接池超时 (connection-timeout) 一定要小于上游 RPC 超时，让数据库请求先超时释放连接，而不是让连接被线程持有到天荒地老。建议在运维层面配合 HikariCP 的 pool-name 区分不同数据源，便于从 JStack 或监控平台识别连接归属。

思考任务：在 application-dev.yml 中配置 H2 内存数据库，在 application-prod.yml 中配置 PostgreSQL，用 Profile 切换。

上一节：Springdoc OpenAPI 3

下一节：JdbcTemplate