简介：一个基于Spring Boot与Hibernate连接MySQL的学习型项目，面向初学Java后端、想弄懂ORM框架与Spring Boot如何整合的开发者。项目围绕数据插入和简单查询两个基础操作，覆盖依赖配置、数据源连接、实体映射等关键环节，可作为课程设计或入门练手的参考。资源包共155个文件，压缩包约34.25MB，内含64个依赖jar包、Java源码及编译后的class文件，另有properties和xml配置文件、jsp演示页面、sql建表脚本，以及Eclipse工程文件（.project/.classpath），整体结构清晰，便于导入IDE后快速还原可运行环境。目前已有1826人学习/下载，适合作为一个起步阶段的参考项目。使用时先按sql脚本创建数据库和表，再借助包内jar依赖直接启动，即可完成插入与查询操作，省去手动查找依赖和建表的时间。
1. Spring Boot + Hibernate + MySQL 这个“简单例子”到底在解决什么问题
只要你在 Java 后端这条路上待过三个月，大概率会撞到 springboot+hibernate+mysql 这组经典搭配。Spring Boot 把过去 XML 里那堆繁琐配置压缩成几十行 yml，Hibernate 负责把 Java 对象自动映射成数据库表，MySQL 在底下老老实实存数据。三样东西单独拎出来都不难，但合在一起时，启动报错、表建不出来、查询慢得出奇，这三座大山几乎人人都会翻一次车。
这篇文章不带你抄官方 Demo，而是按一线落地的顺序把这个组合的边界讲透：先弄清三者各自管什么，再给出一份最小依赖和配置，然后用实体类和仓库接口跑通 CRUD，最后把配置玄学和查询性能上的坑逐个拆开。新手照着做能十分钟跑通，熟手也能在参数和踩坑上找到想要的答案。
2. 先搭骨架：最小依赖与那份容易让人翻车的 application.yml 配置
2.1 为什么 Spring Boot 官方默认选型就是 Hibernate：JPA 规范与实现的关系
很多初学者先接触 MyBatis，再来看 Spring Data JPA 时，容易把 Hibernate 理解为“另一个 ORM 框架”。更准确地说，Hibernate 是 JPA（Jakarta Persistence API）规范的一个实现，而 Spring Boot 的 spring-boot-starter-data-jpa 依赖里默认打包的就是 Hibernate。所以你在大多数 Spring Boot 项目里写的javax.persistence.Entity或jakarta.persistence.Entity注解，底层由 Hibernate 来执行。
这种设计带来的直接好处是：你的代码面向 JPA 规范写，不绑定具体实现。将来想从 Hibernate 切换到 EclipseLink，理论上是替换依赖而不是改业务代码。不过现实中很少有人这么干，因为 Hibernate 的生态最成熟、资料最多，Spring Boot 官方对它的支持也最深入。做这个组合的落地项目，先把这层关系记在心里，后面遇到“注解不生效”“继承的方法突然变慢”这类问题，你能更快定位到是规范层面的问题还是 Hibernate 实现层面的问题。
2.2 最小依赖清单：三个 starter 加起来不超过十行
打开一个空白的 Spring Boot 项目，只需要三个核心依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency>spring-boot-starter-data-jpa 会连带把 Hibernate Core、Hibernate 的 Jakarta Persistence API 实现和 Spring Data JPA 一起拉进来。starter-web 负责提供 REST 接口能力，包含内嵌的 Tomcat 和 Spring MVC。mysql-connector-j 是 MySQL 官方 JDBC 驱动，只在运行时需要，所以 scope 选择 runtime。
这里还有一个容易忽略的细节：如果你用的是 Spring Boot 3.x，依赖坐标里写的是com.mysql:mysql-connector-j，而不是老项目里常见的mysql:mysql-connector-java。后者在新版本里已经改名了，照抄老博客容易在启动时直接报找不到驱动类。
2.3 application.yml 的 5 个关键配置项与作用
依赖准备好了，最大的坑往往出在配置文件上。下面是一份我常用的最小配置：
spring: datasource: url: jdbc:mysql://localhost:3306/demo ?createDatabaseIfNotExist=true &useSSL=false &serverTimezone=Asia/Shanghai &characterEncoding=utf8 username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver jpa: hibernate: ddl-auto: update show-sql: true open-in-view: false配置里的 5 个关键点，逐个说清楚：
| 配置项 | 作用 | 我的建议 |
|---|---|---|
| createDatabaseIfNotExist=true | 连接时若数据库不存在则自动创建 | 本地开发方便，生产环境删除 |
| serverTimezone=Asia/Shanghai | 指定时区，防止驱动报时区错误 | 必配，否则大概率启动即报错 |
| characterEncoding=utf8 | 保证中文正常读写 | 乱码时先检查这里 |
| ddl-auto=update | 启动时按实体类自动更新表结构 | 仅限开发环境，生产别用 |
| open-in-view=false | 关闭视图层长时间占用数据库连接 | 建议显式关闭 |
ddl-auto的值有 none、validate、update、create 和 create-drop 这几种，很多人不知道该怎么选。本地开发用 update，启动时发现实体类字段变了会自动加列；但到了生产环境，我一般切到 validate，让应用启动时校验表结构是否和实体一致，不一致直接报错，防止 Hibernate 自行改表带来不可控的变更。create-drop 只在单元测试里偶偶用一下，它会在会话结束时把表删掉。
open-in-view这个参数值得单独强调。Spring Boot 默认把它设为 true，意味着一个 HTTP 请求的整个生命周期，从 Controller 到模板渲染完，数据库连接都一直被占着。如果你没有用视图模板，接口只返回 JSON，这个默认行为除了浪费连接池资源外，还会掩盖懒加载异常。把它关掉之后，才能在第一时间暴露出事务边界的问题。
3. 用实体和仓库接口跑通 CRUD：简单背后是约定优于配置的设计
3.1 @Entity 与@Id 注解：从 Java 类到 MySQL 表的映射规则
依赖和配置就位后，项目还跑不起来，因为还差一张表和能操作表的代码。在 JPA 的世界里，你不需要先写 CREATE TABLE 语句，而是先写一个实体类，Hibernate 会根据注解自动建表。新手最容易卡在这一步：不知道字段类型如何映射，也不知道表名和字段名怎么生成。
import jakarta.persistence.*; @Entity @Table(name = "app_user") public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(nullable = false, unique = true, length = 50) private String username; @Column(nullable = false) private String passwordHash; @Column(name = "real_age") private Integer age; // 无参构造函数必须存在，Hibernate 反射时需要用到 public User() { } // 省略 getter / setter }这个实体类对应的建表逻辑值得拆开讲。@Table(name = "app_user")指定表名为 app_user，如果你不写这个注解，Hibernate 默认按类名 User 映射为 user 表。问题是 user 在 MySQL 里是保留字，直接建表执行时可能报语法错误，所以表名尽量别用保留字，或者显式指定一个安全的名字。
字段映射上，id 用了GenerationType.IDENTITY，这意味着主键由 MySQL 自增生成，Hibernate 插入时会把生成的主键回填到对象的 id 属性上。username 字段上的@Column(nullable = false, unique = true, length = 50)会翻译成数据库层的“非空约束、唯一索引、varchar(50)”。年龄字段用了@Column(name = "real_age")，如果 Java 属性名和数据库字段名不一致，就得做这种显式映射。
3.2 继承 JpaRepository 之后，你白拿了多少现成能力
实体类写好后，接下来是仓库接口。这一步可能是整个上手过程里最让人惊艳的地方：写一个空接口继承 JpaRepository，就自动获得了插入、更新、按主键查询、分页、删除等二十多个方法。
import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.stereotype.Repository; import java.util.List; import java.util.Optional; @Repository public interface UserRepository extends JpaRepository<User, Long> { Optional<User> findByUsername(String username); List<User> findByAgeGreaterThan(Integer age); List<User> findByAgeBetween(Integer minAge, Integer maxAge); }接口里条件查询的方法名就是查询语句，Spring Data JPA 会根据方法名自动生成实现，不需要写任何 SQL。findByUsername等价于 SQL 里的SELECT * FROM app_user WHERE username = ?，返回 Optional 表示可能查不到。findByAgeGreaterThan对应WHERE age > ?，findByAgeBetween对应WHERE age BETWEEN ? AND ?。
这套命名规则叫方法名派生查询，它能识别 findBy、existsBy、countBy、deleteBy 这几个开头，后面跟条件属性名，再配合 And、Or、Between、LessThan、GreaterThan、OrderBy 这些关键词。不过我也建议你别全靠方法名硬拼，复杂一点多条件动态查询时，方法名会膨胀到看不清属性名之间的边界，这时候就该换 @Query 注解写 HQL（Hibernate 查询语言），或者直接写原生 SQL。
import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; public interface UserRepository extends JpaRepository<User, Long> { @Query("select u from User u where u.username = :username and u.age > :minAge") Optional<User> findActiveUser(@Param("username") String username, @Param("minAge") Integer minAge); }这段代码里的 HQL 是面向实体类写的，User是实体名而不是表名。写 @Query 的好处是你能精确控制查询逻辑，坏处是它绕开了方法名派生查询的自动实现，如果写错了字段名，运行期才报错。配合 Spring Boot 配置里的spring.jpa.properties.hibernate.format_sql=true，可以在控制台看到格式化的 SQL 语句，方便你核对生成的查询是否符合预期。
3.3 从实体类到表结构：Hibernate 自动建表的时机与验证方法
很多人配置完 ddl-auto=update 后，启动项目发现数据库里没有表，第一反应是配置写错了。多数情况下，应用是启动成功的，但表还没有创建，因为 Hibernate 的 DDL 执行发生在实体类扫描完成之后、第一个连接从连接池取出之前。
这时最直接的验证方法是打开启动日志，搜索ddl或create table关键字。不过更省事的方式是写一个简单的测试，用ApplicationRunner在启动时执行一次查询，强制触发建表和连接初始化：
import org.springframework.boot.ApplicationRunner; import org.springframework.boot.ApplicationArguments; import org.springframework.stereotype.Component; @Component public class StartupRunner implements ApplicationRunner { private final UserRepository userRepository; public StartupRunner(UserRepository userRepository) { this.userRepository = userRepository; } @Override public void run(ApplicationArguments args) { long count = userRepository.count(); System.out.println("用户总数：" + count); } }如果 count() 能正常返回，说明表已经建好，连接池和仓库接口都可用。如果这里抛异常说表不存在，说明 ddl-auto 没起作用，优先排查配置文件是不是没被加载，或者数据源 url 指向的库和实体所在包没被扫描到。
4. 从 REST 接口到数据库表：完整链路与事务边界
4.1 控制层、服务层、仓库层各管什么
实体类和仓库接口齐了，但它们还不能直接被前端调用。需要一层 REST 接口对外部暴露 HTTP 能力，这个过程中最常见的问题是把业务逻辑堆在 Controller 里，导致事务边界混乱。
import org.springframework.transaction.annotation.Transactional; import org.springframework.stereotype.Service; @Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository = userRepository; } @Transactional(readOnly = true) public User findByUsername(String username) { return userRepository.findByUsername(username) .orElseThrow(() -> new RuntimeException("用户不存在")); } @Transactional public User createUser(String username, String passwordHash, Integer age) { if (userRepository.findByUsername(username).isPresent()) { throw new RuntimeException("用户名已存在"); } User user = new User(); user.setUsername(username); user.setPasswordHash(passwordHash); user.setAge(age); return userRepository.save(user); } }Service 层用 @Transactional 声明事务边界，这是整个链条里的核心。readOnly = true告诉 Hibernate 这次会话里的查询不需要开启写入事务，能提交只读优化；写操作的方法不标 readOnly，spring 默认开启读写事务。
把事务放在 Service 层而不是 Repository 层是关键。如果事务边界放在每个仓库方法上，那么一个业务逻辑里调用多个仓库方法时，它们各自独立提交，一旦中间一步失败，前面的修改已经落库，无法回滚，这也就是常说的“部分成功”状态。放在 Service 层之后，整个方法体内所有数据库操作共享一个事务，任何一步抛异常，全部回滚。
import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/users") public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } @PostMapping public User create(@RequestBody CreateUserRequest request) { return userService.createUser( request.getUsername(), request.getPasswordHash(), request.getAge() ); } @GetMapping("/by-username") public User getByUsername(@RequestParam String username) { return userService.findByUsername(username); } }Controller 不写事务，不直接操作仓库，只负责参数解析、调用 Service、包装 HTTP 响应。这样做的原因是事务注解在 Spring 里通过 AOP 代理生效，如果 Controller 直接调用仓库方法，事务注解写在哪都别扭，而且 Controller 被代理的边界不容易控制。保持 Controller 干净、Service 持事务，是这组技术栈最不容易出错的写法。
4.2 懒加载与序列化：为什么接口返回实体类会捅出 LazyInitializationException
上面代码里直接把 User 实体作为 Controller 的返回对象，简单是简单了，但这一步是懒加载异常的高发区。当一个实体类里有 @OneToMany、@ManyToOne 这类关联关系时，Hibernate 默认使用 Lazy（懒加载）策略，只在访问关联属性的那一刻才去数据库查。
import jakarta.persistence.*; import java.util.List; @Entity @Table(name = "app_user") public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY) private List<Order> orders = new ArrayList<>(); // 其他字段省略 }上面的 orders 集合是懒加载的。当 Service 层的 findByUsername 方法返回 User 后，事务已经提交，Session 关闭。随后 Controller 把 User 交给 Jackson 做 JSON 序列化，Jackson 尝试访问 orders 属性，就会触发送给一个已关闭的 Session 的代理查询，抛出 LazyInitializationException。
解决这个问题的标准方式不是把 fetch 改成 EAGER。EAGER 虽然能在事务内把数据全查出来，但会让每次查询 User 都连带查询 orders，性能损耗非常大，而且还会带来 N+1 问题。正确做法是在返回给前端之前，把实体转成 DTO，或者在事务内手动初始化需要的关联集合，然后再返回。
import org.springframework.transaction.annotation.Transactional; @Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository = userRepository; } @Transactional(readOnly = true) public UserDto getUserWithOrders(Long userId) { User user = userRepository.findById(userId).orElseThrow(); user.getOrders().size(); // 在事务内初始化懒加载集合 return UserDto.from(user); } }user.getOrders().size()这行看起来很怪，但它的作用是强制触发懒加载集合的初始化，让数据在事务内被真实查出。之后实体转为 DTO，事务提交，关联数据已经放在内存里，序列化自然安全。很多人一遇到懒加载异常就想着调全局配置，其实治本的办法是理清哪里需要在事务内把数据拿全。
5. 避坑与排查：Hibernate 联合 MySQL 最常翻车的几个场景
5.1 现象：ddl-auto=update 启动后数据库里没有表
原因要从多个方向排查，这也是新人最容易陷入死循环的地方。我见过不少项目半天都没有成果，最后发现配置文件根本没被读取。Spring Boot 对 application.yml 的文件名和位置敏感，多套环境的配置如果不小心写进了 application-prod.yml，而启动时没有激活对应 profile，那份配置就形同虚设。
解决步骤是先在启动命令行里加--debug，看控制台打印的数据源 url 到底连到哪个库。然后确认主配置文件和 profile 文件不要同时存在冲突项。若数据库连接正常但表没有生成，检查实体类所在包是否被@SpringBootApplication的默认扫描路径覆盖到。默认扫描当前包和子包，如果实体放在别的包，需要显式加@EntityScan指定路径。
5.2 现象：单元测试或启动时弹出 Table doesn't exist 异常
原因往往是 createDatabaseIfNotExist 参数没有配，数据库本身不存在。Spring Boot 的连接池不会自动创建库，MySQL 也不会因为一个连接串就建库。如果没有配 createDatabaseIfNotExist，应用启动报错“Unknown database”，这是最常见的新手问题。
解决方式是先在 MySQL 客户端里手工建库，CREATE DATABASE demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;，同时把连接串里的 createDatabaseIfNotExist 参数保留。需要特别提醒的是，生产环境不要依赖这个参数自动建库，库表结构的变更应该走专门的数据库迁移脚本工具。
5.3 现象：N+1 查询把接口响应时间拉高十几倍
这是一个经典性能问题。看日志会发现，查询 10 条用户记录后，又跟了 10 条查询用户订单的 SQL。问题出在关联关系默认的懒加载策略加上了循环访问。
举个例子，列表展示需要同时显示用户和每个用户的订单数量，代码写成：
users.forEach(user -> System.out.println(user.getOrders().size()));遍历 10 个用户时，每个用户访问 orders，懒加载触发一条 SQL，加上主查询一共 11 条。如果在事务外访问还可能直接抛连接关闭异常。
解决这个问题的两个方向：一是用一个 @Query 把关联数据用 join fetch 一次性查出，二是写 DTO 专用查询，用 HQL 直接查出需要的数据。两种方式都远比逐条访问懒加载集合要好。优先推荐 DTO 方式，因为它彻底避免把实体关联关系暴露到外部。
5.4 现象：数据写入后中文乱码，或者报时区错误
乱码问题可以从两个层面排查。MySQL 侧的库、表、字段字符集需要是 utf8mb4，应用侧连接串要带 characterEncoding=utf8。有些老服务器把数据库字符集设成 latin1，应用怎么做都还是会乱码。最稳妥的方式是建库时直接指定字符集，字段级不单独指定，让表继承库的字符集。
时区错误在 MySQL 8.x 上尤其常见，启动时报The server time zone value is unrecognized or represents more than one time zone。这个报错发生在 JDBC 驱动建立连接时，需要连接串上有一个合法时区参数。我的习惯统一配serverTimezone=Asia/Shanghai，不要依赖 MySQL 服务器的默认时区。如果服务器在国外，库里的时间和你本地时间对不上，优先改连接串时区让 JDBC 驱动做转换，而不是改服务器系统时区。
5.5 现象：save 之后查出来的主键 id 是 null，或者 list 方法返回空
第一种主键为 null 的情况，多数是 GenerationType 策略选错。比如用了GenerationType.AUTO在某些 MySQL 方言下可能退化成 TABLE 生成器，需要额外建一张 hibernate_sequence 表，如果 Hibernate 没有权限建表，主键自然拿不到。建议统一使用GenerationType.IDENTITY，简单可靠。
第二种 list 方法返回空，情况要复杂一些。如果实体类之间有关联关系，数据其实存在但查询结果为空，可以用spring.jpa.properties.hibernate.format_sql=true打开实际 SQL 的打印。常见原因是 HQL 里的隐式 join 生成了 INNER JOIN，而关联表没有匹配记录，导致主表记录也被过滤掉。此时需要把JOIN显式改成LEFT JOIN，并给出 join 条件。
6. 从“能跑”到“敢上线”：一份开发和测试用的验证清单
到这一步，你已经跑通了一个最小但完整的 springboot+hibernate+mysql 例子。接下来我建议你用半小时过一遍下面的验证清单，把“本地能跑”提升到“敢给别人部署”的水平。
第一项验证是自定义查询方法是否真的生效。写一个测试接口，分别调用findByUsername和findByAgeGreaterThan，确认返回结果符合预期。同时打开 show-sql 日志，观察生成的 SQL 有没有把整个表的数据拉出来再过滤。findByUsername的 SQL 如果打印出where u.username = ?，说明派生查询正确，否则说明方法名拼写有误。
第二项验证是事务回滚。在 createUser 方法里故意在最后抛一个异常，调用接口后回到数据库看那条用户数据是否还在。如果不存在，说明事务注解生效；如果写进去了，说明事务边界没有覆盖到那个写入操作。
第三项验证是懒加载相关配置。把 open-in-view 设为 false 后，访问一个带有订单列表的接口，观察是否会抛 LazyInitializationException。异常出现说明事务边界过窄，按 4.2 的方式把关联初始化挪进 Service 方法内，而不是改回 true 把问题掩盖掉。
第四项验证是给表加上合理的索引。实体类里被 where 条件频繁使用的字段，仅凭@Column注解不会自动建索引。username字段有 unique 约束所以已经有索引，如果 age 字段需要做范围查询，写上@Table(name = "app_user", indexes = @Index(name = "idx_age", columnList = "real_age"))。
最后一件事，是整理一份实体类变更的记录习惯。表结构在开发和联调阶段频繁变化是常态，我会在每次改完实体类后，同步记录当时的表结构快照。等到了要上线的阶段，拿出这套对应关系的最终版，用原生 SQL 建表或交给专业的数据库迁移工具管理，而不是依赖 Hibernate 在生产环境自动去改表结构。这种习惯让我吃过不少教训，也希望帮你省下后面熬夜排查数据不一致的时间。希望帮到你。
本文还有配套的精品资源，点击获取
