Spring Boot datasource 配置补全与校验指南

整理数据源基础配置、连接池参数、profile 覆盖和启动验证方法。

撰写与维护： ErickPang · 更新于：

整理 Spring Boot 数据源配置的常见 key、YAML/Properties 写法、连接池配置和启动验证方法。

基础 datasource 配置

数据源配置是 Spring Boot 项目最常见也最容易影响启动的问题之一。连接外部数据库时至少应明确 url，并根据数据库认证方式提供 username 和 password。Spring Boot 通常可以从 JDBC URL 推断驱动类，只有自动推断失败或需要指定实现时才设置 driver-class-name。

补全工具能帮助输入 spring.datasource 前缀下的常见 key，但无法判断真实数据库是否可达。配置写完后仍需要通过启动日志、连接池初始化结果或简单查询进行验证。

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app
    password: secret
    driver-class-name: org.postgresql.Driver

连接池配置

多数 Spring Boot 项目默认使用 HikariCP。连接池参数不宜盲目复制生产值到本地环境。本地开发可以使用较小的 maximum-pool-size，生产环境则需要结合数据库容量、服务副本数和请求峰值评估。

如果连接池配置不合理，可能表现为启动慢、连接耗尽或数据库压力过大。建议把连接池配置和业务并发、部署副本数一起评审。

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000

验证方法

启动应用后先确认没有 Bean 创建失败、驱动类缺失或认证失败。再使用一个最小查询验证连接是否可用。对于多 profile 项目，要确认当前 profile 使用的是预期数据库地址。

不要把生产数据库地址写入本地默认配置。更稳妥的方式是通过环境变量或 profile 文件注入，并在提交前检查敏感信息。

  • 确认数据库驱动依赖已加入
  • 确认 URL、用户名、密码和数据库可达
  • 确认 active profile 没有覆盖 datasource
  • 确认连接池参数适合当前环境

先验证依赖，再调整连接池

配置正确但驱动不在运行时 classpath 时，应用仍然无法创建 DataSource。使用 spring-boot-starter-jdbc 或 spring-boot-starter-data-jpa 时通常会自动引入 HikariCP，但 PostgreSQL、MySQL 等数据库驱动仍需单独声明，并选择与 Java 和数据库版本兼容的驱动。

不要用增大 maximum-pool-size 掩盖连接泄漏或慢查询。估算连接上限时要把单实例连接数乘以服务副本数，并为迁移任务、管理工具和其他服务预留数据库容量。connection-timeout 只决定等待连接的时长，不能修复不可达地址或错误凭据。

  • No suitable driver：检查 JDBC 驱动依赖和 URL 前缀
  • Connection refused：检查主机、端口、网络和数据库监听状态
  • Authentication failed：检查凭据来源及 active profile
  • Connection is not available：检查池上限、连接泄漏和慢查询

用环境变量隔离凭据

共享配置文件可以保留变量名称和非敏感默认值，但不应提交真实生产密码。部署环境负责注入 DB_URL、DB_USERNAME 和 DB_PASSWORD；本地开发通过未提交的环境文件或 IDE Run Configuration 提供。

提交前同时搜索 application-*.yml、application-*.properties、启动脚本和 CI 配置。删除 Git 中的明文并不等于凭据已经安全，发生泄露时还需要在数据库侧轮换。

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: ${DB_POOL_SIZE:10}

官方依据与相关文章

Spring Boot SQL Databases 文档说明 spring.datasource.* 的标准配置、驱动推断和连接池选择顺序。具体 HikariCP 参数的单位与含义可能随依赖版本变化，调整前应核对当前 Spring Boot 管理的 HikariCP 版本。

相关文章

本站由 ErickPang 独立维护，与 Spring、JetBrains 或 Broadcom 无官方关联。