简介面向Spring Boot初学者的入门级项目实例以Hibernate整合MySQL实现简单的数据插入与查询操作。资源从实际工程出发覆盖项目依赖、实体映射、核心配置与JSP页面交互等环节适合正在学习Spring Boot数据持久化、希望快速跑通基础CRUD流程的开发者参考。压缩包共155个文件整体大小34.25MB其中包含64个jar依赖包、6个java源码文件、6个class编译文件、3个properties配置、2个JSP页面、2个XML配置以及1个SQL脚本从源码、配置、页面到数据库建表语句均已齐备无需额外搜索依赖或编写建表脚本创建对应数据库并执行SQL即可直接运行。已有1826人下载学习。借助该实例可直观理解Hibernate与Spring Boot的组合方式、SessionFactory或EntityManager的装配思路以及插入和查询操作的基础写法。工程目录结构完整可快速定位各层代码适合作为课程设计、毕业设计前的练手素材或自学参考。1. 这个组合意味着什么一个简单例子为什么会在你本地翻车如果你问一个常年写 Java 的人“Spring Boot Hibernate MySQL”最简示例怎么搭他通常会告诉你三分钟搞定加两个依赖写一个实体继承一个 JpaRepository然后启动就行。但到你手上一跑大概率会撞上时区报错、表没建出来、JSON 循环引用这类问题。这个组合真正跑通的最小闭环并不在启动那一下而在“实体、事务边界、建表策略”这三处你对底层机制的理解上。本文按照 Spring Boot 官方推荐的默认路径来落一个可运行的用户 CRUD 示例Spring Boot 负责自动装配Hibernate 作为 JPA 实现负责对象关系映射MySQL 负责存储。你不需要写任何 SQL 建表语句也不需要写复杂的 DAO只需要理解 Hibernate 在什么时机把实体翻译成 DDL以及事务边界在哪里。适合刚接触 Spring Boot 的 Java 开发者照着敲一遍也适合那种“从 Hibernate 配置地狱里逃出来但心里不踏实”的熟手快速核对参数与边界。2. 搭建最小可运行骨架依赖、数据源和实体三件套2.1 选依赖为什么只需 spring-boot-starter-data-jpa 和 mysql-connector-j常见做法是在spring-boot-starter-web之外再加一个spring-boot-starter-data-jpa。这个 starter 会把 Hibernate ORM、Spring Data JPA、JPA API 以及事务管理器一并拉进来。你不需要单独配 Hibernate 的 sessionFactorySpring Boot 的自动配置会在容器启动时自动为你创建LocalContainerEntityManagerFactoryBean和PlatformTransactionManager。这和你以前手写hibernate.cfg.xml的日子完全不同但底层机制还是同一个EntityManager 就是 Hibernate Session 的包装事务管理器最终控制 Session 的提交和回滚。MySQL 驱动在 Spring Boot 2.x 时代的名字是mysql-connector-javaSpring Boot 3 之后改为com.mysql:mysql-connector-j。如果你用的是最新的 Spring Boot 3.x写旧坐标反而拉不到正确版本。我建议直接写com.mysql:mysql-connector-j并且不显式指定版本让 Spring Boot 的依赖管理替你决定。以下是pom.xml的最小片段dependencies !-- Web 支持提供内嵌 Tomcat 和 Spring MVC -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 引入 Hibernate Spring Data JPA -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency !-- MySQL 驱动Spring Boot 管理版本 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies这里的逻辑是runtime作用域表示驱动只在运行期需要编译期不需要starter-data-jpa已经决定了 Hibernate 的版本策略你不需要自己声明hibernate-core。如果你之前在 Hibernate 官方文档里见过hibernate-entitymanager这种旧坐标在 Spring Boot 里是不需要的。选依赖的核心原则就是“让 Spring Boot 的 starter 决定 Hibernate 生态让依赖管理决定版本你的 pom 只表达业务需要什么而不是表达怎么组装”。2.2 数据源配置从 application.yml 到连接池参数新建src/main/resources/application.yml配置数据源、JPA 和 Hibernate 的关键行为。最常见的一个最小配置如下server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver jpa: hibernate: ddl-auto: update show-sql: true open-in-view: false properties: hibernate: format_sql: true dialect: org.hibernate.dialect.MySQL8Dialect每个参数都需要解释清楚。url里的serverTimezoneAsia/Shanghai是必须的否则 MySQL 8.x 驱动和 Hibernate 之间的时区判断会抛异常。driver-class-name写com.mysql.cj.jdbc.Driver注意这是 MySQL 8 的新驱动类名老项目里的com.mysql.jdbc.Driver在新版本中会提示已废弃。ddl-auto: update表示 Hibernate 在启动时对比实体类和已存在的表结构缺列补列缺表建表但不会删除数据。show-sql: true会在日志里打印 Hibernate 生成的 HQL 翻译后的 SQL。open-in-view我直接设成false这是 Spring Boot 默认true的一个隐藏陷阱。如果保留true每次请求都会占用一次数据库连接直到视图渲染完并发一高连接池就容易被打满。对于 REST API你根本不需要 Open Session In View果断关掉。dialect的作用是告诉 Hibernate 使用 MySQL 特有的分页语法和类型方言MySQL 8 就写MySQL8Dialect如果是 MySQL 5.7 则写MySQL5InnoDBDialect。写错版本会导致某些类型映射异常虽然大多数简单例子感知不到。2.3 实体与主键策略一张表最少要写什么实体就是一张表的对象化映射。Hibernate 通过注解解析你的字段类型生成对应的数据库列类型。下面这个User实体是最简但足够完整的模板package com.example.demo.entity; import jakarta.persistence.*; import java.time.LocalDateTime; Entity Table(name user_info) public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(name username, nullable false, unique true, length 50) private String username; Column(name email, length 100) private String email; Column(name created_at, updatable false) private LocalDateTime createdAt LocalDateTime.now(); // 必须提供无参构造Hibernate 内部靠它创建对象 public User() { } // getter 和 setter 省略 }解释一下几个容易忽略的点。Table(name user_info)把表名显式指定为user_info而不是默认的user因为user在部分 MySQL 环境里和系统表或语法发生冲突这个改法能省掉一次踩坑。GenerationType.IDENTITY让数据库自增主键这是 MySQL 最合适的策略AUTO在 MySQL 下会被 Hibernate 映射为identity或sequence行为不够直观。createdAt字段的LocalDateTime.now()是 Java 层面赋值所以不需要数据库默认值updatable false保证后续更新操作不会误改这个字段。User()无参构造是 JPA 规范强制要求的Hibernate 通过反射创建实例没有它会直接抛异常。这里还要提一个看起来很玄学的点Hibernate 默认使用的是字段访问还是属性访问。你在字段上标注解就是字段访问Hibernate 直接操作字段不经 getter。如果你把注解写到 getter 上就成了属性访问Hibernate 在实例化后调用 setter 填值。两种方式不能混用否则会出现“查询正常但插入时字段全空”的怪问题。我的习惯是全部写在字段上简单且不会因为 IDE 生成 getter 导致行为变化。3. 让 Hibernate 干活的三种方式Repository、EntityManager 和原生 SQL3.1 Spring Data JPA Repository最简单但别乱拖关联Spring Data JPA 的接口声明方式已经定义好了 Hibernate 的调用边界。你觉得只是写了一个接口它却在启动时为你生成一个代理实现类。以下是仓库接口package com.example.demo.repository; import com.example.demo.entity.User; import org.springframework.data.jpa.repository.JpaRepository; import java.util.List; public interface UserRepository extends JpaRepositoryUser, Long { // 按用户名精确查询 User findByUsername(String username); // 按邮箱模糊查询关键词包含 like ListUser findByEmailContaining(String keyword); }这种findByUsername的写法叫“查询方法”。Spring Data JPA 会解析方法名把Username映射到实体的username字段自动生成 JPQL 查询。你不需要写 SQL也不需要加Query。JpaRepositoryUser, Long已经提供了save、findById、findAll、delete等通用方法。注意方法名解析规则findBy后面跟属性名属性首字母大写如果有多个条件就用And或Or连接。findByEmailContaining会被翻译成where email like ?并自动添加%通配符。在使用上有一个常见认知错误Repository 方法默认跑在事务里但它只是单一查询事务。如果实体上有关联关系比如用户关联订单而你只在查询了 User 之后再去访问user.getOrders()这时 Session 已经关闭就会抛出懒加载异常。Repository 是“以简单查询为目的”的不是为了拖出整个对象图。涉及关联懒加载必须把查询放进 service 层的事务边界里后面我会单独讲。3.2 Query 与 EntityManager需要控制查询时怎么办方法名虽然方便但一旦查询变复杂比如多表 join 拼接动态条件方法名会变成一长串不可读的怪物。这时优先用Query注解在方法上写 JPQL 而不是原生 SQL。JPQL 操作的是实体类和属性名不需要关心数据表列名。例如public interface UserRepository extends JpaRepositoryUser, Long { // JPQL按创建时间倒序取前 10 个用户 Query(select u from User u order by u.createdAt desc) ListUser findLatestUsers(Pageable pageable); }注意Pageable参数。Spring Data 会把分页信息转换成数据库方言对应的分页 SQLMySQL 下就是limit ?。如果你想写原生 SQLQuery里加nativeQuery true但返回值映射会退化为数据库字段名和实体属性名的字面对齐一旦列名不一样就会出现映射空值。JPQL 是更安全的选择Hibernate 还允许你在复杂查询里调用join fetch一次把关联查出来避免懒加载问题。如果连 JPQL 都不够再考虑直接注入EntityManager。它更底层但也在某些场景里更灵活。通常我把它用在需要批量处理或 Entity graph 控制的场景package com.example.demo.service; import com.example.demo.entity.User; import jakarta.persistence.EntityManager; import jakarta.persistence.PersistenceContext; import org.springframework.stereotype.Service; import java.util.List; Service public class UserEntityManagerService { PersistenceContext private EntityManager entityManager; public ListUser findByEmailLike(String keyword) { return entityManager.createQuery(select u from User u where u.email like :kw, User.class) .setParameter(kw, % keyword %) .setMaxResults(20) .getResultList(); } }这里的重点是PersistenceContext注入的是“当前事务绑定的 EntityManager”它不像普通 Spring Bean 那样是单例共享的而是线程级事务绑定的。在外面看起来像一个对象实际每次调用都跟着事务走。setMaxResults(20)用来限制返回条数防止你查询条件写错把整表捞出来。三者的选择顺序应该是方法名查询能表达就用方法名表达不了用QueryJPQL再不行才用 EntityManager。3.3 事务到底在哪开Transactional 是 Hibernate 能懒加载的前提Hibernate 的 Session 生命周期和事务强绑定。Spring Data JPA 的 Repository 方法自带事务但那是只读查询事务方法一结束 Session 就关了。如果你在 Controller 里直接调用UserRepository.findById再访问该实体上懒加载的关联属性必然报LazyInitializationException。解决办法是把多个动作合并到一个事务里而这个事务必须放在 service 层。package com.example.demo.service; import com.example.demo.entity.User; import com.example.demo.repository.UserRepository; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository userRepository; } Transactional public User updateEmail(Long id, String newEmail) { User user userRepository.findById(id).orElseThrow( () - new RuntimeException(用户不存在 id) ); user.setEmail(newEmail); // 这里没有显式调用 save因为实体处于托管状态 // 事务提交时 Hibernate 会自动 flush 脏数据 return user; } }解释一下这个代码的内部机制。findById返回的是一个托管状态的实体它在 Hibernate 当前 Session 的持久化上下文里。修改了email后事务提交时 Hibernate 会做脏检查对比持久化上下文里的快照发现字段变了自动发出 update SQL。这就是“不需要 save 也能更新”的原理。如果你在Transactional外面做这套操作findById返回的实体在方法返回时就已经脱管了改动不会被识别整个操作会静默丢失。这个例子同时解释了什么是事务边界Transactional开在updateEmail方法上方法内所有数据库操作共享同一个 Session包括查询后修改再到提交。我一般会把事务放在 service 类的方法上避免在 Controller 层加事务因为 Controller 是 HTTP 层事务放这里会把 Session 拖到网络传输完成连接占用时间不可控。4. 把代码跑起来启动参数、建表策略和第一个 REST 接口4.1 ddl-auto 四档怎么选create、update、validate、noneddl-auto是 Hibernate 自动 DDL 行为的开关也是新手最容易随手一选就出事的配置。它有四个常用值create每次启动先删表再建表数据全部清空只适合本地实验update保留已有数据基础上补齐缺失列和表validate只校验实体和表结构是否一致不一致就启动失败不建表不删表none完全关闭自动 DDL建表交给外部脚本。你可以这样判断本地第一次学习用update项目要交付或环境要稳定用validate或none。spring: jpa: hibernate: ddl-auto: update有一个血泪经验是别在测试环境用update跑长期项目。它会默默新增列但不会删除列也不会改列类型。表结构变动一旦多起来你的数据库会累积一堆垃圾列而实体类早就把对应字段删了。测试环境数据丢不丢不是重点重点是测试验证不了数据库迁移脚本的可用性。所以我在简单示例里为了演示开update但立刻要讲清楚它的边界让你不至于带着这个配置上生产。4.2 第一个控制器和 JSON 循环问题现在我提供一个最小的 REST 控制器用来操作用户数据。这个控制器直接依赖 service而不是仓库。好处是事务边界清晰后续加权限校验或日志也方便package com.example.demo.controller; import com.example.demo.entity.User; import com.example.demo.service.UserService; import org.springframework.web.bind.annotation.*; import java.util.List; RestController RequestMapping(/users) public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService userService; } PostMapping public User create(RequestBody User user) { return userService.save(user); } GetMapping public ListUser list() { return userService.findAll(); } GetMapping(/{id}) public User detail(PathVariable Long id) { return userService.findById(id); } }这里有一个很容易翻车的地方如果实体之间有关联关系比如 User 里有个OneToMany的ListOrder orders而 Order 里又反向引用 UserSpring MVC 在把实体序列化成 JSON 时会无限递归要么报序列化异常要么返回巨慢。简单示例虽然没有关联但我建议从第一天起养成“不直接返回实体”的习惯。最轻量的做法是返回实体但配合JsonIgnore打断关联更稳的做法是直接返回 DTO让 JSON 结构由你掌控而不是由 Hibernate 的懒加载状态决定。在这个例子我们保持简单先返回实体但要意识到实体直接暴露给前端会带来字段冗余。4.3 验证链路从启动日志到 curl 长这样才算成功启动 Spring Boot 应用控制台会出现这个关键日志Hibernate: create table user_info (id bigint not null auto_increment, created_at datetime(6), email varchar(100), username varchar(50) not null, primary key (id)) engineInnoDB这说明 Hibernate 已经通过update创建了表。注意我提到的not null来自实体字段上的nullable falsevarchar(50)来自length 50engineInnoDB是 MySQL8Dialect 自动加的。这些细节都能反过来帮你检查实体注解是否生效。接下来用 curl 做链路验证。先创建用户curl -X POST http://localhost:8080/users \ -H Content-Type: application/json \ -d {username:zhangsan,email:zsexample.com}你应该能看到服务和数据库的往返过程里日志打印了带有参数占位符的 SQL返回 JSON 中带有自动生成的id和createdAt。然后查询列表curl http://localhost:8080/users返回的数组里只有一条记录。如果此时出现null的email回去检查请求体有没有传字段如果整个接口 500去日志找异常堆栈八成是ddl-auto建表失败或数据库连接时区问题。验证链路的关键是看三层请求是否到 Controller、service 是否拿到参数、SQL 是否发到 MySQL。少一层问题定位范围就大一圈。5. 避坑让新手 CV 过去就挂的 5 个常见问题5.1 现象启动报 “Unknown database” 或 “Connection refused”启动日志里出现Caused by: java.sql.SQLSyntaxErrorException: Unknown database demo_db或java.net.ConnectException: Connection refused原因通常很直接demo_db在 MySQL 里并不存在或者 MySQL 端口不是默认的 3306又或者服务没起来。Spring Boot 不会帮你创建数据库它只能在你指定的库里建表。我的解决步骤是先登录 MySQL 检查mysql -uroot -p -e CREATE DATABASE IF NOT EXISTS demo_db DEFAULT CHARSET utf8mb4;utf8mb4是为了支持中文和 emoji。如果报Connection refused检查 MySQL 是否监听在 3306用netstat -ano | findstr 3306Linux 上是ss -lntp | grep 3306确认。另外一个常见的坑是连接串里写成localhost而 MySQL 只监听127.0.0.1偶尔会导致连不上直接统一写127.0.0.1更稳妥。5.2 现象时区报错 serverTimezone 或一年差 8 小时启动日志报java.sql.SQLException: The server time zone value йʱ is unrecognized...原因是 MySQL 8 驱动在建立连接时校验服务端时区而你的 MySQL 使用时区SYSTEM系统时区是中文名或 UTC驱动无法解析。解决方式在 JDBC URL 里显式指定serverTimezoneAsia/Shanghai同时在 MySQL 里也可以执行SET GLOBAL time_zone 08:00。还有一个更隐蔽的现象连接不报错但查询LocalDateTime返回的结果比数据库里实际值早 8 小时。这是连接时区与 JVM 时区不一致导致。如果你用Asia/ShanghaiJVM 默认也是中国时区两者就对上了。顺手在启动类的 main 方法里不要手动TimeZone.setDefault那会绕过连接串时区造成二次混乱。5.3 现象Hibernate 一直打 SQL 但表没建出来show-sql: true下能看到 Hibernate 执行select语句但数据库里没有表。最常见原因是你配置了ddl-auto: validate或者none而表根本没建。validate只在实体和表匹配时通过不匹配就启动失败或查询抛异常none则完全交给你自己。另一个可能你开了ddl-auto: update但Entity注解没写Hibernate 根本不知道有这张表。扫描实体类是 Hibernate 启动阶段完成的漏了Entity它只会启动一个不扫描任何表的 SessionFactory。还有第三种可能也是我从同事的代码里见到的Table(name user_info)写的是复数表名但你代码里操作的是User实体映射的是一张不存在的表而update模式下 Hibernate 只对有实体的表建表如果注解写错它会按错的表名去建。检查方式很简单启动日志里搜create table看它到底打印了哪张表。5.4 现象REST 返回实体时无限循环或报序列化错误这个场景需要实体有关联关系时才出现。User 关联 OrderOrder 又关联 User返回findAll时 Jackson 序列化这个对象图发现user.orders里有order.userorder.user又回溯到user.orders于是无限递归最终抛StackOverflowError。解决路径有三条最简单的是在关联字段上标JsonIgnore打断双向引用如果你希望返回关联但不希望循环用JsonIdentityInfo让 Jackson 用 id 引用而不是嵌套对象更可控的是不要把实体直接返回而是转成 DTO。我倾向于第三种的长期价值更高因为实体类和数据库结构耦合前端字段需求变化频繁直接暴露实体等于让前端和数据库结构绑定后续改名表字段会连环改接口。5.5 现象懒加载时报 LazyInitializationException日志里出现org.hibernate.LazyInitializationException: failed to lazily initialize a collection of role: com.example.demo.entity.User.orders, could not initialize proxy - no Session原因是你在没有Transactional的地方访问了一个懒加载集合。findAll返回的实体里orders这个集合是一个 Hibernate 代理对象Session 关闭后代理无法再从数据库加载数据。很多人第一反应是给集合注解改成fetch FetchType.EAGER这能消除当前报错但代价是每次查 User 都会连表查全部订单性能隐患极大。正确做法是访问关联数据的动作必须发生在事务内。改法是在 service 层提供专门方法方法上加Transactional方法内先查询 User再触发user.getOrders()让 Hibernate 在同一事务内完成加载。也可以用 JPQL 里的join fetch一次性查出来但要注意fetch不能作用于ManyToOne关联返回多条记录的集合否则内存里会出现重复结果。这个坑只要记住一个原则就不会再犯实体和它的关联属性是同生共死的要么一起在事务里拿要么就接受它是不可脱管的对象。6. 进阶玩法从“简单例子”走出来先动这三处作为从“能跑”到“能交付”的分界线我会建议你按顺序做三个调整。第一把ddl-auto从update改成none引出一个像 Flyway 这样的版本化迁移工具来管理表结构。Flyway 会在启动时执行classpath:db/migration下的 SQL 脚本而实体类里删掉ddl-auto相关配置让 schema 变更记录在脚本里。这样团队每个人启动应用拿到的表结构都完全一致不会再出现“本地自动加了一列而测试环境没有”的漂移。一个最简单的迁移文件长这样CREATE TABLE user_info ( id BIGINT NOT NULL AUTO_INCREMENT, username VARCHAR(50) NOT NULL, email VARCHAR(100), created_at DATETIME(6), PRIMARY KEY (id), UNIQUE KEY uk_username (username) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;第二给实体到返回结构之间加一层 DTO。简单项目里一个UserResponse类只包含id、username、email三个字段用静态方法from(User user)做转换。这样实体上的关联懒加载失败不会波及接口表结构改字段时接口也不会跟着破。第三调整连接池和日志参数。Spring Boot 默认连接池是 HikariCP我一般会配一个最大连接数和超时时间避免高并发下默认配置把数据库打爆spring: datasource: hikari: maximum-pool-size: 20 connection-timeout: 30000 jpa: properties: hibernate: jdbc.batch_size: 30batch_size对批量插入有肉眼可见的提升但注意它和GenerationType.IDENTITY有些冲突MySQL 下 IDENTITY 策略会导致批量插入退化为逐条。所以如果你追求批量性能主键策略得改TABLE或重新评估架构。这条路我踩过为了性能把批量调到 50结果日志还是逐条 insert后来才发现是 IDENTITY 限制改成普通值插入后性能才真实提升。最后留一个验证习惯每次改动配置后我会把启动日志里Hibernate:开头的所有 SQL 抓出来和预期比对一次确认没有意外建表或意外删表。相比看一堆“起没起来”的状态直接看 SQL 更能让你确信 Hibernate 在做你让它做的事。这个习惯帮我挡住过多次配置复制粘贴带来的结构偏差希望帮到你。本文还有配套的精品资源点击获取