企业官网建设流程全解析

1. 先搞清楚：Spring Data JPA 到底解决什么问题

我见过不少刚接触 Spring Data JPA 的同事，第一个反应是：“Repository 接口里明明没写实现，为什么调用 findAll 就能拿到数据？”这个疑问很正常，它背后并不是魔法，而是 Spring 在启动时根据接口自动生成了一套实现。这篇内容我按自己上手时的顺序来写，从环境搭建、实体映射、Repository 机制，到分页查询和常见坑，适合刚接触 JPA 的 Java 开发，也适合已经用了很久但经常被懒加载和 N+1 问题折腾的人。如果你之前在 MyBatis 和 JPA 之间反复横跳，应该能理解这种割裂感：一边是 SQL 全掌握，一边是对象导航很爽但出了问题难排查。这篇文章不会替你做选型，但会把 Spring Data JPA 的关键机制讲透，让你无论是写新项目还是接手老代码，都能快速定位问题。

1.1 从 JDBC 到 ORM：为什么需要 JPA

如果回到十几年前写 Java 后端，最常见的做法是 JDBC 加手动拼 SQL。你要自己获取 Connection、创建 PreparedStatement、执行查询、遍历 ResultSet，再把每一列塞进对象里。数据表一多，这些样板代码会占掉大量开发时间，而且很容易出现资源泄漏、字段错位这类低级问题。ORM 的出现就是为了把“表记录”和“Java 对象”之间的转换，从手工操作变成自动化机制。

JPA 全称是 Java Persistence API，它只是一套规范，定义了你该怎么映射实体、怎么管理 EntityManager、怎么描述查询。真正干活的是实现框架，最常见的就是 Hibernate。Hibernate 在 JPA 规范之上还提供了一些增强功能，但如果你只依赖标准注解，项目在将来切换实现时会轻松不少。用生活化的方式理解：JPA 是“约定”，Hibernate 是“按照约定干活的工人”，而 Spring Data JPA 则是把“安排工人干活”这件事也帮你包了。

用一张表可以直观看出三层的关系：

Spring Data JPA 之所以能让你“只写接口不写实现”，是因为它在应用启动时扫描 Repository 接口，解析方法名，再基于 Hibernate 生成一个运行时实现。所以你在代码里看到的是一个空接口，跑起来却真实存在功能完整的 Bean。这正是很多初学者觉得它“玄”的地方，其实背后就是一套成熟的接口代理生成机制。

1.2 Spring Data JPA 在技术栈里的位置

很多项目里会有这样的分层：Controller 接收请求，Service 处理业务，Repository 负责持久化。Spring Data JPA 主要替代的是传统 DAO 里那些重复的增删改查代码。你不需要写一个 UserDaoImpl，再手写一堆 getUserById、saveUser、deleteUser，只要定义一个接口继承 JpaRepository，常用方法就都有了。

举一个很具体的例子。以前用 Spring JDBC 写一个查询用户的方法，需要写 SQL、传参数、指定行映射器，逻辑一旦复杂起来，代码量会明显膨胀。用 Spring Data JPA 之后，同样是查用户，接口里声明一行方法就够了。两种写法放在一起对比，差别非常直观：

// 旧方式：Spring JDBC public User findById(Long id) { String sql = "select * from user_info where id = ?"; return jdbcTemplate.queryForObject(sql, new BeanPropertyRowMapper<>(User.class), id); }

// Spring Data JPA 方式 public interface UserRepository extends JpaRepository<User, Long> { }

这里不需要任何实现类，JpaRepository 已经提供了findById、findAll、save、deleteById等一批方法。如果后续需要按用户名查，只需要在接口里加一个方法声明findByUsername。Spring 会解析这个方法名，自动生成对应的查询逻辑，不需要你亲自写实现。

这种设计带来两个直接收益。第一，简单 CRUD 的逻辑不再散落在 DAO 类里，Repository 接口本身就是数据访问契约。第二，查询方法的命名带有强约束，团队看代码时能直接从方法名推断 SQL 意图。缺点是方法名太长时很难看，所以 Spring Data JPA 也提供了@Query注解让你写 JPQL 或原生 SQL，这一点后面会单独讲。

1.3 什么时候该选它，什么时候别用它

选型问题我再多说一句。Spring Data JPA 适合业务模型相对清晰、实体关系较多的项目，尤其是领域驱动设计风格的代码库，因为它能把持久化和领域模型结合得很好。如果团队里 Java 基础扎实、对对象建模有感觉，用 JPA 写 CRUD 和维护关系会比 MyBatis 省很多事。

但如果你负责的是报表中心这类重 SQL 场景，或者业务上大量依赖复杂动态查询、多表聚合、存储过程，那 Spring Data JPA 不一定是首选。虽然它也能写原生 SQL，但到了那个程度，MyBatis 对 SQL 的掌控和调试体验会更直接。更常见的是两种框架同时存在，比如主业务用 JPA，报表查询用 MyBatis，这在很多中大型项目里很常见。坦白说，框架之间没有绝对的好坏，关键在于是否匹配你的业务形态和团队能力。

2. 搭好基础工程：依赖和配置要一次弄对

入门阶段最能看到 JPA 优势的地方在于：一个最小项目只需要很少的配置就能跑通。但配置虽少，几个关键参数如果理解不到位，上线之后很容易踩坑。这一节我把依赖、配置和实体映射一起讲，照着做就能把第一个 Repository 跑起来。

2.1 最小依赖配置

如果你用的是 Spring Boot，依赖非常简单。一个spring-boot-starter-data-jpa就会把所有核心库带进来，包括 Spring Data、Hibernate 和事务支持。再按实际数据库加一个驱动即可。比如本地开发用 H2，测试和部署用 MySQL，可以这样加：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>

这里要提醒一个很多新手会犯的错：不要手动去引入 Hibernate 的版本。Spring Boot 的依赖管理已经帮你锁好了 Hibernate 与 Spring Data JPA 的兼容版本。如果你在 pom 里额外加了别版本的 hibernate-core，运行时会遇到各种 NoSuchMethodError 或 SessionFactory 初始化失败，这类问题排查起来非常浪费时间。入门阶段出现这种问题，大概率都是依赖版本冲突导致的，先检查是不是重复引用了 Hibernate。

2.2 配置文件里的几个关键参数

一个典型的 application.yml 配置如下：

spring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: root jpa: hibernate: ddl-auto: update show-sql: true open-in-view: false properties: hibernate: format_sql: true

ddl-auto是最容易让人困惑的参数。它有四个主要值：none表示不自动改表结构；update表示启动时根据实体变化增加表字段；create表示启动时删表再建表；create-drop会在关闭时把表也删掉。个人建议开发环境用update，本地临时项目可以用create，但生产环境必须设置为none或validate，并且表结构通过专门的数据库迁移工具管理。否则某次误启动带update的应用，可能导致线上表结构被自动修改，而这种修改往往不会被纳入代码评审流程。

注意：ddl-auto不是数据库迁移工具，它只是 Hibernate 的建表辅助开关。生产环境请使用 Flyway、Liquibase 这类方案管理表结构。

show-sql: true在开发阶段很有用，能帮你直接看到 Hibernate 生成的 SQL。配合format_sql: true，输出会更好读。不过生产环境不要开，既浪费日志空间，也可能把敏感查询打到日志里。open-in-view: false这一项后面讲懒加载时会详说，简单说它控制的是 Web 请求期间是否保持数据库会话打开，默认是 true，关了能避免很多连接资源被无谓占用。

2.3 第一个实体类的映射

实体类是与数据库表对应的 Java 对象，最基础的长这样：

@Entity @Table(name = "user_info") public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(nullable = false, unique = true, length = 50) private String username; @Column(name = "nick_name") private String nickName; private Integer status; protected User() { } // getter / setter }

@Entity标记这是一个 JPA 实体，@Table指定表名。如果你不写@Table，Hibernate 会拿类名当表名，默认把User变成user，但很多业务表名不是这个规则，所以建议显式声明。@Id和@GeneratedValue表示主键自增，使用IDENTITY策略时依赖数据库的自增列，适合 MySQL。如果切到 Oracle 或 PostgreSQL，可能需要换成SEQUENCE。

关于字段映射，默认命名策略是驼峰转下划线，所以nickName会被自动映射到nick_name列，不写@Column(name = "nick_name")也能正常工作。但当你需要指定长度、唯一约束或列允许为空时，@Column就派上用场了。@Column(nullable = false)会影响建表语句，但如果ddl-auto设为none，这个属性并不会真正给数据库列加约束，需要数据库中已经存在对应约束。

写实体类时还要注意无参构造。JPA 规范要求实体类提供一个 protected 或 public 的无参构造，Hibernate 在反射创建对象时会用到。很多开发工具生成的实体类自带无参构造，但如果手动写实体，很容易漏掉这个细节，运行时会遇到HibernateException: No default constructor for entity这样的错误。

3. Repository 层：接口方法的魔法与限制

Repository 层是 Spring Data JPA 最容易上手也最容易误解的部分。理解它的运行机制，比背下一个方法命名清单更有用，因为你以后会遇到无数个自定义查询场景，光靠背是背不完的。

3.1 Repository 接口是怎么一回事

定义 Repository 接口时，通常有两种继承选择。简单 CRUD 可以用Repository<T, ID>，但它提供的默认方法很少；多数项目会直接继承JpaRepository<T, ID>，它集合了CrudRepository、PagingAndSortingRepository和QueryByExampleExecutor的能力，方法最全，也省得以后补。

public interface UserRepository extends JpaRepository<User, Long> { }

当你启动 Spring Boot 时，框架会扫描@EnableJpaRepositories配置的包路径，找到所有继承 Repository 的接口，然后为它们生成 Bean。所以你在 Service 里可以直接注入UserRepository，而不需要写任何实现类。接口方法在执行时会被解析成查询或操作，这就是“接口的魔法”。

有个小细节值得注意：不要为了省事把 Repository 接口都放在根包之外，也不要自己实现一个同名类去覆盖框架生成的 Bean。我见过有人想给save方法加日志，直接在接口里定义了一个默认方法，结果和已有的save方法冲突，运行时报Invalid derived query。遇到这类需求，正确做法是定义一个叫saveWithAudit的方法，或者用事件监听器，不要在接口里重新声明已有方法。

3.2 方法名派生查询的规则

Spring Data JPA 有三类查询方式：方法名派生、@Query注解、Specification 或 QueryDSL。入门阶段最重要的是方法名派生，因为它零额外配置，直接看方法名就知道在查什么。

List<User> findByUsernameAndStatus(String username, Integer status); List<User> findByNickNameContaining(String keyword); List<User> findByStatusIn(Collection<Integer> statuses); List<User> findByCreatedAtBetween(LocalDateTime start, LocalDateTime end); Optional<User> findByUsername(String username);

这些方法名看起来像语法糖，但内部有一套解析器。findBy之后跟着属性路径，属性名必须和实体里的字段名对应，可以用And、Or拼接多个条件，用Containing、Between、In、IsNull等关键字表达具体语义，最后还可以用OrderBy控制排序。整体规则不复杂，常见查询都能表达。

需要注意的坑是：方法名里的属性名写错时，Spring 启动阶段就会失败，报错信息会告诉你找不到对应属性。这其实是好事，问题在启动时就暴露了，而不是查询时才发现。另一个坑是方法名过长可读性下降，比如findByCreatedAtBetweenAndStatusInAndUsernameContaining这种方法，已经很难一眼看懂。所以我个人的习惯是，单个方法名超过五个条件就改用@Query注解，或者使用命名参数，宁可多写几行代码也要保持接口可读。

3.3 @Query 写自定义查询

当方法名派生已经撑不住复杂查询时，用@Query注解。它支持两种写法：JPQL 和原生 SQL。JPQL 针对的是实体对象，写的不是表名和列名，而是类名和属性名；原生 SQL 则直接写数据库方言，灵活但失去了跨数据库迁移的便利。

public interface UserRepository extends JpaRepository<User, Long> { @Query("select u from User u where u.nickName = :nickName") List<User> findByNickName(@Param("nickName") String nickName); @Query(value = "select * from user_info where nick_name = ?1", nativeQuery = true) List<User> findByNickNameNative(String nickName); }

这里有几个容易踩的细节。JPQL 的参数绑定推荐用:name形式，在方法参数上配合@Param注解，写起来清晰且不容易错。原生 SQL 里的?1表示第一个参数，和 JPQL 的:name不一样，不要混用。还有一个常见的坑：原生 SQL 查询返回的字段如果和实体映射不一致，Hibernate 会尝试按列名映射，缺字段时可能返回 null 甚至报错。建议优先用 JPQL，只有 JPQL 表达不了或性能要求极限优化时才用原生 SQL。

@Query方法同样支持更新和删除操作，但需要加上事务注解。默认情况下，Repository 的查询方法是只读的，但修改操作必须在一个事务里执行。你可以在接口方法上直接标注@Transactional，也可以把事务边界放在 Service 层。个人建议事务边界放在 Service 层，Repository 只管数据访问，业务上的多表一致性由 Service 把握。

4. 分页、排序与动态查询：别每次接口都写一堆 if

分页和排序是 Web 项目里再常见不过的需求。Spring Data JPA 对这块的封装做得不错，理解Pageable和Page之后，大多数分页场景都能靠框架自带能力解决，不需要手写 SQL。

4.1 Pageable 与 Page 的实际使用

先看一个最典型的分页例子：

@Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository = userRepository; } public Page<User> page(int pageNo, int pageSize) { Pageable pageable = PageRequest.of(pageNo, pageSize, Sort.by(Sort.Direction.DESC, "createdAt")); return userRepository.findAll(pageable); } }

PageRequest.of的三个参数分别是页码、每页大小和排序规则。注意页码是从 0 开始的，也就是说前端传过来的第 1 页，在后端代码里要减 1。很多联调问题都出在这里：后端按 0 起始设计，前端按 1 起始传参，结果第二页数据一直不对。

Page<T>接口里除了包含当前页的数据getContent()，还有getTotalElements()总记录数、getTotalPages()总页数，这些信息可以直接组装成前端需要的分页结果。如果查询不需要总数，比如移动端下拉加载，可以用Slice接口，它只判断有没有下一页，性能上会好一点。

分页时的另一个典型问题是排序字段不能由用户随意传。如果你直接把前端传的排序字段拼进Sort.by("createdAt")，一旦用户传入一个不存在的属性名，运行时会报PropertyNotFoundException。更危险的是，如果你拼接原生 SQL，还可能引入注入风险。建议在服务端维护一个白名单 Map，把允许排序的字段名做映射，不允许的都过滤掉。

4.2 Specification 处理动态条件

动态查询是很多人的痛点。用户查询列表时可能传用户名、状态、时间范围，可能只传其中几个。用@Query写死条件很难覆盖所有组合。Spring Data JPA 对此提供了JpaSpecificationExecutor接口，配合Specification使用。

先让 Repository 继承扩展接口：

public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> { }

然后写一个动态查询方法：

public List<User> search(UserQuery query) { Specification<User> spec = (root, criteriaQuery, builder) -> { List<Predicate> predicates = new ArrayList<>(); if (query.getUsername() != null && !query.getUsername().isBlank()) { predicates.add(builder.like(root.get("username"), "%" + query.getUsername() + "%")); } if (query.getStatus() != null) { predicates.add(builder.equal(root.get("status"), query.getStatus())); } if (query.getStartTime() != null) { predicates.add(builder.greaterThanOrEqualTo(root.get("createdAt"), query.getStartTime())); } return builder.and(predicates.toArray(new Predicate[0])); }; return userRepository.findAll(spec); }

这种方式比字符串拼接 SQL 规范得多，条件组合灵活，也避免了 SQL 注入风险。需要说明的是，Specification的写法有点繁琐，条件多时 lambda 会变得很长。可以考虑把 Predicate 的拼接抽成工具方法，比如hasText、eqIfNotNull这类辅助函数，让主查询代码更清爽。如果项目里查询条件特别多，也可以引入 QueryDSL，但那是另一个话题，入门阶段先把 Specification 用好就够了。

4.3 排序参数容易被忽略的细节

排序看起来简单，但实际开发中翻车概率不低。首先是多字段排序的语义。Sort.by("name", "age")表示先按 name 排序，如果相同再按 age 排序，而不是各自独立的排序规则。如果你想 name 升序、age 降序，要这么写：

Sort sort = Sort.by( Sort.Order.asc("name"), Sort.Order.desc("age") );

其次是排序字段和数据表列名的关系。Spring Data JPA 中Sort.by用的是实体属性名，不是数据库列名。也就是说实体里写了nickName，你在排序时就得写nickName，写成nick_name会报错。如果你通过@Column(name = "nick_name")指定了列名，排序时依然用属性名。

还有一个比较隐蔽的问题：当实体属性名恰好是 SQL 关键字，比如order、group，生成的 SQL 可能有问题。Hibernate 通常会做转义，但如果你直接用原生 SQL 语法写@Query，就不一定了。这类字段命名最好一开始就避开关键字。

5. 事务和懒加载：JPA 的隐藏开关

很多使用 Spring Data JPA 一段时间后开始迷茫的开发者，往往不是卡在查询写法上，而是卡在事务和对象状态上。这两个机制理解不到位，写出来的代码时好时坏，还会出现各种莫名其妙的异常。这一节把最关键的点讲清楚。

5.1 @Transactional 的默认行为和坑

Spring 的@Transactional默认使用代理机制来实现事务。它的意思是方法进入时开启事务，方法正常退出时提交，抛出运行时异常时回滚。注意是运行时异常，而不是受检异常。如果你在事务方法里抛了一个 Exception 对象，默认情况下事务不会回滚，这是很多财务类功能出问题的根源。解决方法是在注解上声明回滚规则：

@Transactional(rollbackFor = Exception.class) public void createUserAndOrder(User user, Order order) { userRepository.save(user); orderRepository.save(order); }

另一个更隐蔽的坑是自调用。同一个类里，一个方法调用另一个@Transactional方法，事务不会生效。因为 Spring 的事务是靠着代理生成的，自调用走的是 this 对象，代理逻辑没有介入。例如：

public void outer() { this.inner(); // @Transactional 不生效 } @Transactional public void inner() { }

解决办法是把内部方法放到另一个 Service 类中，或者注入自己。这个问题的排查往往不明显，因为业务没有报错，只有出现异常时才会发现数据没有回滚。

5.2 懒加载与一级缓存

JPA 的加载策略分为EAGER和LAZY。@ManyToOne默认EAGER，@OneToMany默认LAZY。懒加载意思是关联对象并不会立即查询，而是在第一次访问时才触发查询。这个设计能减少不必要的关联查询，但也带来了“懒加载必须发生在会话内”的限制。

最常见的问题是控制器里直接返回实体，JSON 序列化时访问到了懒加载属性，抛出LazyInitializationException。造成这个异常的原因通常不是 Spring Data JPA 本身，而是事务已经结束、会话已关闭。有些团队为了省事会开启open-in-view: true，让整个 Web 请求期间都开着会话，这样懒加载在控制器里也能工作。但这个方案会让数据库连接在整个请求周期内被占用，高并发时连接池很容易耗尽，不建议作为常规做法。

我的建议是三层都明确边界：Controller 只接收参数和返回 DTO，Service 负责事务和初始化需要的关联数据，Repository 只做查询。需要返回前端的数据，在 Service 内用 DTO 组装完成，尽量不让实体直接出现在 Controller 层。这样既避免了懒加载异常，也让 API 的响应结构更可控。

Hibernate 还有一级缓存，默认在 Session 范围内生效。同一个事务里，如果根据同一个 id 查询多次，第二次不会真正执行 SQL，而是从一级缓存返回同一个对象。这个机制能避免重复查询，但也带来一个注意点：如果你在同一事务里先用findById查到对象，再在外面修改对象的某些属性，事务提交时会自动执行 update。这也就是为什么明明没有调用save，数据库却更新了。

5.3 对象状态修改为什么不用 update 方法

很多从 MyBatis 转过来的人，看到新增有save，下意识以为修改也要写update。实际上 JPA 没有单独的 update 方法，因为 JPA 管理的是对象状态。实体对象在持久化上下文中处于托管状态时，事务提交前 Hibernate 会做脏检查，发现字段值变了，就自动发 update 语句。

@Transactional public void changeStatus(Long id, Integer status) { User user = userRepository.findById(id).orElseThrow(...); user.setStatus(status); // 没有调用 save，事务提交时会自动 update }

这也意味着你不应该先 new 一个 User、set 好 id 再调用save。因为这样做 Hibernate 会认为这是一个游离对象，执行 merge 逻辑，先发送 select 查询数据库，再合并属性，最后 update。一次无用查询加一次更新，批量操作时损耗很明显。正确的做法是让实体在同一个事务里被查询出来，再修改属性。

6. 实战中绕不开的常见问题

框架用久了，每个人都会积累一份属于自己的避坑清单。我把这几年遇到的高频问题整理成一个速查表，每个问题都给出了定位思路和解决方向，希望能帮你少走弯路。

6.1 N+1 查询问题的定位与解决

所谓 N+1，是指先查了 N 条主记录，再访问每条记录的关联对象时，各自触发一次查询，导致整体执行 1+N 条 SQL。日志里会看到这种特征：第一条 select 查列表，后面 N 条 select 查关联表。这在对象导航式写法里非常容易出现，因为访问user.getOrders()的代码看起来很正常，底层却在偷偷查询。

解决 N+1 最常用的手段是@EntityGraph或 JPQL 的join fetch。例如：

public interface UserRepository extends JpaRepository<User, Long> { @EntityGraph(attributePaths = "orders") @Query("select u from User u") List<User> findAllWithOrders(); }

@EntityGraph会生成一个带 join 的查询，一次性把关联对象查出来。要注意，如果是一对多关联，join 会让主记录的行数变多，同名结果会出现重复，所以查询返回集合时要加distinct。用 JPQL 时可以在select distinct u from User u join fetch u.orders。加了 fetch 之后，如果还要配合分页，很可能 Hibernate 在统计总数时也会携带关联表，导致 count 查询报错，这时候你可能需要同时指定 countQuery。

6.2 懒加载序列化异常处理

前面提到，控制器直接返回实体时，Jackson 序列化会碰触懒加载属性。最常见的异常是LazyInitializationException。除了用 DTO 方案，还有几个补救办法，但优先级不一样。

如果实体关系里有不需要返回前端的集合，可以加@JsonIgnore，让序列化时直接跳过。但要注意，这只解决了“看不到”的问题，如果后续别的接口需要这个数据，又要另想办法。更通用的是在 Service 内使用Hibernate.initialize(user.getOrders())，在事务内主动初始化。这种方法适合简单场景，但要注意它会绕过懒加载的初衷，该限流还是得限流。

还有一个增强方案是 Jackson 的@JsonIdentityInfo，或者用 MapStruct 把实体映射成 DTO。我的经验是，能 DTO 就 DTO。实体和 API 响应解耦之后，不仅懒加载问题少了，字段变化也不会影响接口契约。

6.3 批量插入慢的优化思路

批量保存数据是很多业务都会遇到的需求。直接用saveAll看起来很方便，但性能并不总是好，尤其是在 MySQL 且主键策略为IDENTITY时，Hibernate 很难利用 JDBC 批处理，因为每条记录都需要先获取生成的主键。

改善批量插入性能有几个方向。第一，如果数据库支持，可以改用SEQUENCE主键生成策略，比如 PostgreSQL、Oracle，或者使用TABLE策略，然后配置 Hibernate 的batch_size：

spring: jpa: properties: hibernate: jdbc: batch_size: 50

第二，MySQL 可以在 JDBC URL 上加rewriteBatchedStatements=true，配合批处理能显著减少执行时间。第三，数据量特别大时，可以考虑用原生 SQL 的INSERT INTO ... VALUES ...，或者干脆用数据库的 load data 工具。这里需要记住：saveAll不是银弹，批量性能要看主键策略、JDBC 驱动和 Hibernate 配置三者是否配合。

最后说一点个人习惯。我用了几年 Spring Data JPA，最深的体会是：不要把它当成自动生成 SQL 的工具，而要当成对象模型落地的手段。遇到性能问题先别急着骂框架，先看自己的实体关系、抓取策略、事务边界是否合理。大多数时候问题出在建模和查询方式上，而不是 JPA 本身。如果你刚从 CRUD 阶段切换到 JPA，建议先老老实实地用 Repository 自带的简单方法，等理解了实体状态和懒加载机制，再逐步使用@EntityGraph、Specification 和原生 SQL。这套东西一旦走上正轨，写业务代码的速度会明显提升，排查问题时的思路也会更清晰。