本文详解 Spring Boot（含 3.x）中如何正确配置以在控制台输出 SQL 语句及参数值，涵盖 show-sql、format_sql、日志级别设置等关键配置，并指出 Spring Boot 2.7 与 3.x 的兼容性注意事项。
本文详解 spring boot（含 3.x）中如何正确配置以在控制台输出 sql 语句及参数值，涵盖 `show-sql`、`format_sql`、日志级别设置等关键配置，并指出 spring boot 2.7 与 3.x 的兼容性注意事项。
在 Spring Boot 应用中调试 JPA 操作时，实时查看执行的 SQL 语句（尤其是带实际参数的语句）是开发和排错的关键环节。但许多开发者发现，即使按常见教程配置了 spring.jpa.properties.hibernate.show_sql=true，控制台仍无 SQL 输出——这通常源于配置项失效、日志级别不匹配或版本兼容性问题。
✅ 正确配置：三步到位
1. 启用基础 SQL 输出（必需）
Spring Boot 提供了更直接的属性 spring.jpa.show-sql=true（注意：不是 spring.jpa.properties.hibernate.show_sql）。该属性由 Spring Boot 自动注入到 Hibernate 配置中，且在 Spring Boot 2.7+ 和 3.x 中均有效：
# application.properties spring.jpa.show-sql=true
⚠️ 注意：spring.jpa.show-sql 是 Spring Boot 的第一层开关，若为 false（默认），后续所有 Hibernate 日志配置均不会生效。
2. 格式化 SQL 并显示参数值
仅开启 show-sql 只能打印简化 SQL（无换行、无参数），需配合以下两项实现可读性强的完整日志：
# 格式化 SQL（缩进、换行） spring.jpa.properties.hibernate.format_sql=true # 输出绑定参数值（如：binding parameter [1] as [VARCHAR] - "Alice"） logging.level.org.hibernate.type.descriptor.sql=trace
✅ logging.level.org.hibernate.type.descriptor.sql=trace 是 Spring Boot 2.5+ 推荐方式（替代已废弃的 org.hibernate.type=trace），在 Spring Boot 3.x 中完全兼容。
3. 完整推荐配置（application.properties）
# 数据源（H2 示例） spring.datasource.url=jdbc:h2:mem:testdb spring.datasource.driver-class-name=org.h2.Driver spring.datasource.username=sa spring.jpa.database-platform=org.hibernate.dialect.H2Dialect # ✅ 关键：启用 SQL 打印 spring.jpa.show-sql=true # ✅ 关键：格式化 + 参数日志 spring.jpa.properties.hibernate.format_sql=true logging.level.org.hibernate.type.descriptor.sql=trace # 可选：提升 Hibernate 日志可见性（便于排查其他问题） logging.level.org.hibernate.SQL=debug logging.level.org.hibernate.orm.jdbc.bind=trace # H2 控制台（辅助验证） spring.h2.console.enabled=true spring.h2.console.path=/h2-ui
? 常见失败原因与修复
❌ 错误配置 spring.jpa.properties.hibernate.show_sql=true 却遗漏 spring.jpa.show-sql=true
→ 在 Spring Boot 2.7+ 中，hibernate.show_sql 已被 Spring Boot 忽略，必须使用 spring.jpa.show-sql。❌ 日志级别未设为 trace
org.hibernate.type.descriptor.sql 默认日志级别为 warn，需显式设为 trace 才输出参数绑定详情。❌ 使用了过时的包名（Spring Boot 3 已迁移日志包）
❌ logging.level.org.hibernate.type=trace（旧版，Spring Boot 3 不再识别）
✅ logging.level.org.hibernate.type.descriptor.sql=trace（Spring Boot 2.5+ / 3.x 标准）-
❌ pom.xml 中 Spring Boot 版本与配置不匹配
你当前使用的是 2.7.10（非 Spring Boot 3），但问题标题提及 “Spring Boot 3”。若升级至 Spring Boot 3.x，请确保：- spring-boot-starter-parent 版本 ≥ 3.0.0
- java.version ≥ 17
- h2 依赖建议升级至 2.2.224+（兼容 JDK 17+）
? 补充：YAML 格式参考（application.yml）
spring:
jpa:
show-sql: true
properties:
hibernate:
format_sql: true
logging:
level:
org.hibernate.SQL: debug
org.hibernate.type.descriptor.sql: trace
org.hibernate.orm.jdbc.bind: trace
✅ 验证方法
启动应用后，执行一条 JPA 操作（如 userRepository.save(new User("Alice"))），控制台应输出类似内容：
Hibernate:
insert
into
user
(id, name)
values
(?, ?)
TRACE o.h.t.d.s.BasicBinder - binding parameter [1] as [BIGINT] - [1]
TRACE o.h.t.d.s.BasicBinder - binding parameter [2] as [VARCHAR] - [Alice]
✅ 至此，SQL 语句、格式化结构、参数值均已清晰可见，满足调试与性能分析需求。
总结：Spring Boot 中 SQL 日志的核心在于 spring.jpa.show-sql=true 开关 + logging.level.org.hibernate.type.descriptor.sql=trace 参数日志，二者缺一不可；避免使用已弃用的配置项，并确保日志框架（Logback/Log4j2）未全局抑制 TRACE 级别输出。
