简介一个基于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 后端这条路上待过三个月大概率会撞到 springboothibernatemysql 这组经典搭配。Spring Boot 把过去 XML 里那堆繁琐配置压缩成几十行 ymlHibernate 负责把 Java 对象自动映射成数据库表MySQL 在底下老老实实存数据。三样东西单独拎出来都不难但合在一起时启动报错、表建不出来、查询慢得出奇这三座大山几乎人人都会翻一次车。这篇文章不带你抄官方 Demo而是按一线落地的顺序把这个组合的边界讲透先弄清三者各自管什么再给出一份最小依赖和配置然后用实体类和仓库接口跑通 CRUD最后把配置玄学和查询性能上的坑逐个拆开。新手照着做能十分钟跑通熟手也能在参数和踩坑上找到想要的答案。2. 先搭骨架最小依赖与那份容易让人翻车的 application.yml 配置2.1 为什么 Spring Boot 官方默认选型就是 HibernateJPA 规范与实现的关系很多初学者先接触 MyBatis再来看 Spring Data JPA 时容易把 Hibernate 理解为“另一个 ORM 框架”。更准确地说Hibernate 是 JPAJakarta 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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependencyspring-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 ?createDatabaseIfNotExisttrue useSSLfalse serverTimezoneAsia/Shanghai characterEncodingutf8 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 个关键点逐个说清楚配置项作用我的建议createDatabaseIfNotExisttrue连接时若数据库不存在则自动创建本地开发方便生产环境删除serverTimezoneAsia/Shanghai指定时区防止驱动报时区错误必配否则大概率启动即报错characterEncodingutf8保证中文正常读写乱码时先检查这里ddl-autoupdate启动时按实体类自动更新表结构仅限开发环境生产别用open-in-viewfalse关闭视图层长时间占用数据库连接建议显式关闭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 JpaRepositoryUser, Long { OptionalUser findByUsername(String username); ListUser findByAgeGreaterThan(Integer age); ListUser 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 注解写 HQLHibernate 查询语言或者直接写原生 SQL。import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; public interface UserRepository extends JpaRepositoryUser, Long { Query(select u from User u where u.username :username and u.age :minAge) OptionalUser findActiveUser(Param(username) String username, Param(minAge) Integer minAge); }这段代码里的 HQL 是面向实体类写的User是实体名而不是表名。写 Query 的好处是你能精确控制查询逻辑坏处是它绕开了方法名派生查询的自动实现如果写错了字段名运行期才报错。配合 Spring Boot 配置里的spring.jpa.properties.hibernate.format_sqltrue可以在控制台看到格式化的 SQL 语句方便你核对生成的查询是否符合预期。3.3 从实体类到表结构Hibernate 自动建表的时机与验证方法很多人配置完 ddl-autoupdate 后启动项目发现数据库里没有表第一反应是配置写错了。多数情况下应用是启动成功的但表还没有创建因为 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 这次会话里的查询不需要开启写入事务能提交只读优化写操作的方法不标 readOnlyspring 默认开启读写事务。把事务放在 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 ListOrder orders new ArrayList(); // 其他字段省略 }上面的 orders 集合是懒加载的。当 Service 层的 findByUsername 方法返回 User 后事务已经提交Session 关闭。随后 Controller 把 User 交给 Jackson 做 JSON 序列化Jackson 尝试访问 orders 属性就会触发送给一个已关闭的 Session 的代理查询抛出 LazyInitializationException。解决这个问题的标准方式不是把 fetch 改成 EAGER。EAGER 虽然能在事务内把数据全查出来但会让每次查询 User 都连带查询 orders性能损耗非常大而且还会带来 N1 问题。正确做法是在返回给前端之前把实体转成 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-autoupdate 启动后数据库里没有表原因要从多个方向排查这也是新人最容易陷入死循环的地方。我见过不少项目半天都没有成果最后发现配置文件根本没被读取。Spring Boot 对 application.yml 的文件名和位置敏感多套环境的配置如果不小心写进了 application-prod.yml而启动时没有激活对应 profile那份配置就形同虚设。解决步骤是先在启动命令行里加--debug看控制台打印的数据源 url 到底连到哪个库。然后确认主配置文件和 profile 文件不要同时存在冲突项。若数据库连接正常但表没有生成检查实体类所在包是否被SpringBootApplication的默认扫描路径覆盖到。默认扫描当前包和子包如果实体放在别的包需要显式加EntityScan指定路径。5.2 现象单元测试或启动时弹出 Table doesnt exist 异常原因往往是 createDatabaseIfNotExist 参数没有配数据库本身不存在。Spring Boot 的连接池不会自动创建库MySQL 也不会因为一个连接串就建库。如果没有配 createDatabaseIfNotExist应用启动报错“Unknown database”这是最常见的新手问题。解决方式是先在 MySQL 客户端里手工建库CREATE DATABASE demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;同时把连接串里的 createDatabaseIfNotExist 参数保留。需要特别提醒的是生产环境不要依赖这个参数自动建库库表结构的变更应该走专门的数据库迁移脚本工具。5.3 现象N1 查询把接口响应时间拉高十几倍这是一个经典性能问题。看日志会发现查询 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应用侧连接串要带 characterEncodingutf8。有些老服务器把数据库字符集设成 latin1应用怎么做都还是会乱码。最稳妥的方式是建库时直接指定字符集字段级不单独指定让表继承库的字符集。时区错误在 MySQL 8.x 上尤其常见启动时报The server time zone value is unrecognized or represents more than one time zone。这个报错发生在 JDBC 驱动建立连接时需要连接串上有一个合法时区参数。我的习惯统一配serverTimezoneAsia/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_sqltrue打开实际 SQL 的打印。常见原因是 HQL 里的隐式 join 生成了 INNER JOIN而关联表没有匹配记录导致主表记录也被过滤掉。此时需要把JOIN显式改成LEFT JOIN并给出 join 条件。6. 从“能跑”到“敢上线”一份开发和测试用的验证清单到这一步你已经跑通了一个最小但完整的 springboothibernatemysql 例子。接下来我建议你用半小时过一遍下面的验证清单把“本地能跑”提升到“敢给别人部署”的水平。第一项验证是自定义查询方法是否真的生效。写一个测试接口分别调用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 在生产环境自动去改表结构。这种习惯让我吃过不少教训也希望帮你省下后面熬夜排查数据不一致的时间。希望帮到你。本文还有配套的精品资源点击获取