Spring Data JPA 里最容易被高估的是方法名解析最容易被低估的就是 Query 注解。平时随便几个条件方法名解决起来又快又爽可一旦查询开始复杂——多表关联、报表统计、条件分支、批量更新——你会发现所有别扭的地方最后都得回到 Query 来兜底。这篇内容就是讲清楚 Query 的完整用法从最基础的 JPQL 写法到原生 SQL、参数绑定、SpEL 动态处理、配合 Modifying 做增删改再到常见异常和缓存不一致的排查每一块都会给可运行的代码和对应的避坑经验。适合两类人看一是刚开始接触 Spring Data JPA、对自定义查询没有头绪的同学二是已经写了很久 Repository 但一直在用方法名硬扛、想系统搞明白 Query 细节的开发者。1. 什么时候该用 Query先从方法名解析的边界说起1.1 方法名解析能做什么不能做什么Spring Data JPA 的方法名解析确实方便像findByNameAndEmail、findByAgeGreaterThan、findTop3ByOrderByCreateTimeDesc这种查询不写一行实现代码框架照着方法名就帮你拼出 SQL。我见过不少团队早期就靠这一招撑起整个数据层效率确实高。但方法名解析有一个隐藏问题它能表达的查询模式太固定了。简单等值、范围、排序、分页这些都没问题可一旦遇到多表 join、group by having、子查询、批量更新方法名的表达力就完全不够用。你很难想象findByUserIdAndOrderStatusAndGoodsIdInOrderByCreateTimeDesc这种四十几个字符的方法名能被团队里的新人一眼看懂更别说方法名解析天生不带group by和having复杂统计查询根本没有干净的表达方式。还有一点方法名生成的 SQL 是框架在运行时拼出来的你只能看到最终 SQL 长什么样中间没有代码层面的人工可控点出了问题反而不好定位。所以我的判断标准很简单查询条件超过两个、涉及多张表、需要自定义返回结构、或者要写 update/delete 的时候不要再折磨方法名了直接上 Query。它本身就是 Spring Data JPA 留给开发者接管查询的出口与其等到 SQL 复杂到失控不如从一开始就在方法上把查询逻辑写清楚。1.2 Query 真正解决的几类典型问题Query 能做的远不止是代替方法名。它最大的优势是让你在框架自动化和原生控制之间找到一个可控的落点。第一类典型问题是多表关联查询。比如订单和用户你想一次性把订单连同用户名称查出来避免循环查询造成 N1可以在 JPQL 里用 join fetch。这种写法在方法名解析里几乎没法优雅表达但在 Query 里就是一句话的事。Query(select distinct o from Order o left join fetch o.user where o.status :status) ListOrder findOrdersWithUser(Param(status) Integer status);第二类是聚合统计。按月统计订单数、按状态统计金额合计这类 SQL 说白了就是group by加几个聚合函数用 JPQL 写出来格式干净也还保留着实体映射的能力。第三类是批量更新和删除。Spring Data JPA 默认的save方法是一条条 SQL几百条数据还好几万条就要命了用 Query 写一条批量更新可以显著减少数据库往返。第四类是调用数据库特有函数比如 MySQL 的DATE_FORMAT、JSON_CONTAINSJPQL 里可以用function()透传原生 SQL 里更是直接写。1.3 什么时候反而不要用 QueryQuery 不是银弹我见过反面的滥用场景。如果查询条件组合特别多比如用户列表页有十几种筛选条件而且每次请求出现的组合都不一样你在 Query 里写死任何一种 SQL 都是错的做法拼接字符串又很快会变成灾难。这种情况应该考虑用 Specification 或者 QueryDSL让条件在业务层动态组装而不是硬塞进一个注解里。还有一种情况是简单查询也硬上 Query。findByName能解决的问题非要写成Query(select u from User u where u.name :name)代码并没有变好反而多了一行要维护的字符串方法名解析的语义优势也没了。我的经验是能用方法名说清楚的就不要动 Query否则查询逻辑会散落在注解字符串和业务代码之间可读性只会更差。2. Query 基本写法JPQL、原生 SQL 与返回值设计2.1 注解参数与最简示例先看 Query 注解的常用参数。在 Spring Data JPA 的源码里这个注解最核心的配置是value和nativeQueryvalue就是查询语句本身nativeQuery默认是 false也就是按 JPQL 解析设成 true 之后value里的内容按数据库原生 SQL 解析。另外还有countQuery、countProjection两个参数专门用来配合分页查询的 count 语句后面会展开。一个最基本的命名参数查询写起来长这样public interface UserRepository extends JpaRepositoryUser, Long { Query(select u from User u where u.email :email) OptionalUser findByEmail(Param(email) String email); }这里User是实体类名不是数据库表名u.email是实体的 Java 属性名不是数据库列名。JPQL 本质上是在跟实体模型打交道而不是直接跟表结构打交道这就是它和原生 SQL 最大的区别。如果你把这里写成select u from t_userHibernate 会直接抛出QuerySyntaxException: t_user is not mapped这类问题后面专门讲。2.2 JPQL 查询语句的核心写法JPQL 的语法和 SQL 非常像它支持select、where、order by、group by、having、join大部分情况下你可以在 SQL 和 JPQL 之间做一次近乎等价的翻译。区别在于你引用的对象JPQL 里写实体名和属性名SQL 里写表名和列名。实际项目中我最常用的 JPQL 写法是以下三种。第一种是简单条件查询控制在实体单表范围内第二种是分页查询直接往方法里加一个Pageable参数框架会自动拼接limit和 count 查询第三种是关联查询比如要拿到用户及其订单列表可以用left join fetch这能极大避免 N1。Query(select u from User u where u.age between :minAge and :maxAge) ListUser findUsersByAgeRange(Param(minAge) Integer minAge, Param(maxAge) Integer maxAge);Query(value select u from User u where u.status :status, countQuery select count(u) from User u where u.status :status) PageUser findUsersByStatus(Param(status) Integer status, Pageable pageable);第二段代码里的countQuery是很多人会忽略的。默认情况下 Spring Data 会尝试从你的查询中生成 count 语句简单查询没问题一旦查询里带了group by、distinct、多表 join自动生成的 count 可能统计错误或者性能极差。自己写 count 语句能保证总数的准确性也能把 count 的 SQL 调整到最轻量。这里建议直接数主表能不加 join 就不加 join。JPQL 里也支持case表达式、coalesce、nullif这些逻辑控制比如Query(select u.name, coalesce(u.phone, u.email) from User u) ListObject[] findContactInfo();2.3 原生 SQL 的正确姿势和坑当 JPQL 解决不了数据库方言特性时就轮到nativeQuery true出场。比如 MySQL 的DATE_FORMAT、GROUP_CONCAT或者某些报表 SQL 里复杂到让你怀疑人生的子查询嵌套这些在 JPQL 里写起来很别扭但原生 SQL 直接照抄数据库客户端的语句就行。Query(value select id, name, date_format(create_time, %Y-%m) as month from t_user where status :status, nativeQuery true) ListObject[] findUserSummary(Param(status) Integer status);原生 SQL 的坑主要在映射关系上。如果你返回的是实体类型比如ListUserSQL 里的列名必须能覆盖实体映射的字段否则 Hibernate 要么报找不到列的异常要么拷出大量 null 值。这里给个最稳的操作能select *就别手写列清单手写列清单时一定注意列别名要跟实体属性匹配得上。另一个常见问题是忘写nativeQuery truevalue里写的明明是数据库表名框架还是按 JPQL 去解析结果报一堆实体映射错误这种低级错误排查起来非常浪费时间。我平时写原生 SQL 的习惯是先在数据库客户端把 SQL 跑通确认结果没问题再粘贴到注解里然后立刻跑一个单元测试验证字段映射绝对不靠肉眼检查。2.4 返回值类型设计实体、DTO 投影与接口投影Query 的返回类型选择直接影响代码质量和查询性能这块值得单独花时间理清楚。最简单的是直接返回实体ListUser、OptionalUser这种适合查询字段和实体完全匹配的情况。但如果你只需要两三个字段也返回完整实体会产生不必要的字段映射开销而且容易误用实体携带的那些大字段。更合适的做法是用投影。接口投影是 Spring Data JPA 的一个特性在 Repository 里定义一个接口里面只声明需要的 getter框架会自动生成代理实现public interface UserNameView { String getName(); Integer getAge(); } Query(select u.name, u.age from User u where u.id :id) OptionalUserNameView findUserNameById(Param(id) Long id);这里有个细节JPQL 里的字段别名要和接口 getter 对应上写成select u.name as name之类的最保险。接口投影适合只读场景代码干净还不用维护额外 DTO。类投影则更适合在业务层传递结构化的数据对象写法是在 JPQL 里用new关键字Query(select new com.example.dto.UserBrief(u.id, u.name, u.email) from User u) ListUserBrief findBriefUsers();前提是UserBrief必须有一个入参完全匹配的构造函数。还有一种是返回ListMapString, Object用select new map(u.name as name, u.age as age)适合字段不固定的临时查询但类型不安全不太推荐在核心业务里用。3. 参数绑定的几种写法位置参数、命名参数与集合 IN3.1 位置参数与命名参数怎么选Query 支持两类参数绑定。位置参数写法是?1、?2按方法参数顺序自动匹配命名参数写法是:name配合Param(name)指定参数名。Query(select u from User u where u.age ?1 and u.status ?2) ListUser searchUsers(Integer minAge, Integer status); Query(select u from User u where u.name :name and u.status :status) ListUser searchUsers(Param(name) String name, Param(status) Integer status);我个人强烈推荐命名参数原因只有一个可读性和维护性。位置参数在参数少的时候没问题一旦查询涉及五六个参数你根本记不住第几个?对应哪个字段中间加一个参数还要回去数数。命名参数就没有这个问题参数名和属性名一一对应代码审查时一眼能看懂。另外有一个容易踩的版本坑Spring Boot 3 和 Spring Framework 6 默认开启了-parameters编译参数方法参数名会保留在字节码里所以Param在某些情况下可以省略。但为了兼容老项目、也为了显式表达意图建议始终写Param。你不写的话在旧的构建配置或某些代理模式下框架可能找不到参数名爆出Named parameter not found异常这种问题很难排查。3.2 集合参数处理 IN 查询在业务里「根据一组 ID 查数据」是极其常见的场景。方法名解析里可以用findByIdIn但如果你还带了其他条件或者这个查询本来就是 Query那直接用集合参数最方便Query(select u from User u where u.id in :ids) ListUser findUsersByIds(Param(ids) CollectionLong ids);这个写法的好处是框架会自动把集合展开成IN (?, ?, ?...)的绑定参数不用你手动拼逗号。但有一个隐藏问题如果传入的集合为空最终生成的 SQL 可能是in ()这在某些数据库上会直接报语法错误Hibernate 对空集合的处理也曾经在多个版本里出现过不一致。我的建议是在调用层做一次空集合判断为空直接返回空集合别把这个边界条件甩给 SQL 来处理。3.3 LIKE 模糊查询的安全写法模糊查询是 Query 新手翻车最频繁的地方。很多人一上来就写Query(select u from User u where u.name like %:keyword%) ListUser searchUsers(Param(keyword) String keyword);这个写法是错的而且错得很有迷惑性。:keyword会被当成一个参数名来解析但它的前后是单引号括起来的字符串内容Hibernate 会要求你给keyword赋值最终生成的 SQL 也不是你想要的那个模糊匹配语义大概率直接报参数绑定失败。正确的写法是用 JPA 内置函数concat拼接百分号Query(select u from User u where u.name like concat(%, :keyword, %)) ListUser searchUsers(Param(keyword) String keyword);也可以用另一种方式方法调用方传参时自己拼好%keyword%JPQL 里只写like :keyword。为什么不推荐用||拼接因为||在不同数据库方言里的连接语义不完全一致JPQL 的concat是规范内置的跨库更稳妥。如果你还要匹配%和_这类通配符那就得用ESCAPE子句自定义转义字符不然用户输入的%会被误当成通配符。3.4 分页与排序的正确配合Query 方法里加一个Pageable参数框架会自动处理分页逻辑这是 Spring Data JPA 很强大的地方。最小可行的例子Query(select u from User u where u.age :age) PageUser findUsersByAge(Param(age) Integer age, Pageable pageable);Pageable可以用PageRequest.of(page, size, sort)创建页码从 0 开始。多数时候你不需要自己写 limit也不需要关心 count 是怎么生成的。但有两种情况要注意。第一种是复杂查询里 count 可能不正确前面提过需要显式指定countQuery。第二种是join fetch集合关联的时候用PageHibernate 在底层可能被迫先把所有关联数据加载进内存做分页会出现一条警告firstResult/maxResults specified with collection fetch; applying in memory。这种查询量一大就会内存溢出我的解决套路是先分页查出主表 ID 列表再用 ID 列表 IN 查询关联数据最后在业务层组装等价于把分页和关联查询拆成两步性能反而更好。4. 动态场景的补位SpEL 表达式与统计查询实战4.1 用 SpEL 处理集合参数Spring Data JPA 在 Query 里支持 SpEL 表达式最常见的一个用途是对参数进行处理。比如你要兼容传空集合的情况或者想直接引用参数对象里的某个属性就可以用:#{}这种写法Query(select u from User u where u.id in :#{#ids}) ListUser findUsersByIds(Param(ids) CollectionLong ids);这个写法本质上和直接传集合参数一样但 SpEL 给你多了处理空间。你可以用?:空值合并、用? :条件判断比如给个默认集合Query(select u from User u where u.id in :#{#ids ! null ? #ids : { -1 }}) ListUser findUsersByIds(Param(ids) CollectionLong ids);这里把 null 集合替换成{ -1 }至少不会生成非法的空in ()。虽然这个技巧有点取巧但在快速迭代的项目里确实能少写很多判空逻辑。4.2 动态表名与可选条件的写法动态表名是 Query 的进阶用法。比如分表场景下每个月一张表方法参数里传入表名后缀JPQL 没法直接支持动态表名只能走原生 SQL 加 SpELQuery(value select * from #{#tableName} where status :status, nativeQuery true) ListMapString, Object findListByTable(Param(tableName) String tableName, Param(status) Integer status);需要特别强调表名不能作为预处理语句的占位符绑定只能用 SpEL 拼接。这意味着如果表名来源不可信这就是个 SQL 注入点。我在实际项目里只允许内部枚举出来的表名列表传进来任何来自前端参数的表名直接拒绝。可空条件的处理也是动态查询的一个经典难题。一个筛选列表名称可能为空、状态可能为空每次查询组合都不同。JPQL 里可以用is null or的模式Query(select u from User u where (:#{#name} is null or u.name :#{#name}) and (:#{#status} is null or u.status :#{#status})) ListUser searchUsers(Param(name) String name, Param(status) Integer status);这种写法虽然 SQL 里带or is null会让数据库优化器没那么高效但在多数金额级数据量的场景下足够用而且代码非常简单。数据量大、性能敏感的接口该上 Specification 就上不要硬扛。4.3 复杂统计查询的实践示例统计报表是我用 Query 最多的地方。比如按月份统计用户注册数量在 MySQL 下原生 SQL 这么好写select date_format(create_time, %Y-%m) as month, count(*) as cnt from t_user group by month order by month descJPQL 版本可以用function调用数据库函数Query(select function(date_format, u.createTime, %Y-%m) as month, count(u) from User u group by function(date_format, u.createTime, %Y-%m)) ListObject[] countUserByMonth();我个人的建议是这种统计 SQL 直接用原生 SQL 就好因为统计查询本身对数据库方言的依赖很强JPQL 翻译一层还可能改变 SQL 形态对排查不利。原生 SQL 的好处是你可以把数据库客户端验证过的语句原样贴进注解行为完全可预期。5. 增删改操作Modifying 的配套细节与常见坑5.1 更新与删除的基本写法Query 不只可以做查询还可以做更新和删除。但 Spring Data JPA 有明确限制非查询语句必须在方法上再加一个Modifying注解否则框架会因为执行了非 select 语句而抛异常。基本写法Modifying Query(update User u set u.email :email where u.id :id) int updateEmail(Param(id) Long id, Param(email) String email); Modifying Query(delete from User u where u.id :id) int deleteUserById(Param(id) Long id);返回值int表示受影响的行数可以用来判断更新是否真的命中。注意 JPQL 的批量更新里不能用单个实体引用比如不能写u.setEmail这种对象式写法它本质上是面向语句的不是面向对象的。5.2 事务、缓存与清缓存参数用 Query 写 update/delete 时事务是必须的。如果你不在 Service 层加Transactional运行时会报TransactionRequiredException。这个异常提示很友好但很多新手还是会在 Repository 层放了Modifying就以为万事大吉实际上一调用就炸。更隐蔽的是缓存问题。JPA 的一级缓存会缓存当前事务里查询过的实体。如果你在同一个事务里先查了一遍实体再执行 Modifying 批量更新然后又在同一个事务里查这个实体你拿到的可能是缓存里的旧值而不是更新后的值。解决方式就是设置两个参数Modifying(clearAutomatically true, flushAutomatically true) Query(update User u set u.status :status where u.id in :ids) int batchUpdateStatus(Param(ids) CollectionLong ids, Param(status) Integer status);clearAutomatically true会在执行更新后清空持久化上下文保证后续查询能拿到数据库的最新值flushAutomatically true则会在执行更新前自动 flush 未保存的实体变更避免更新的结果被本地未提交数据覆盖。我建议查询更新混用的方法都加上这两个参数代价最多是多一次 flush但能避免无数诡异的结果不一致问题。5.3 批量操作的几个隐蔽问题批量操作里还有三个坑是我实测踩过的。第一个是生命周期回调失效JPQL 批量更新和删除不会触发PreUpdate、PreRemove这类实体回调方法。如果你的业务依赖实体的审计字段自动填充批量操作会静默跳过需要手动在语句里维护这些字段。第二个是乐观锁失效Version 字段在批量更新里默认不会被框架自动处理你得自己在 set 子句里写版本号加一否则并发场景下可能丢失更新保护。第三个是关联删除问题。用 JPQL 批量删除父实体不会自动级联删除子实体除非数据库外键本身配置了级联删除。我处理这类需求时如果关联关系复杂宁可先查出父实体 ID 列表再按子先后顺序分多条 SQL 处理图省事直接 delete 父表大概率留下悬挂数据后面查关联的时候一堆空引用。6. 翻车记录高频异常、缓存问题与排查思路6.1 高频异常与对应原因速查下面这张表是我在实际排查 Query 问题时最常遇到的情况一条条对照能省不少时间异常信息根本原因解决方式QuerySyntaxException: xxx is not mappedJPQL 里写了表名而不是实体名或实体类名拼错检查引用的名称JPQL 用实体名Invalid path: u.emial实体属性名拼写错误或路径写错核对实体 Java 字段名大小写敏感Named parameter not foundParam(xxx)和方法实际参数名不一致或忘了加 Param统一参数名与 Param 的值in ()语法报错传入的集合参数为空业务层判空或用 SpEL 给默认集合Not supported by JpaQueryExecution方法上有 Query 但没有 Modifying 却执行了 update/delete给语句加上 ModifyingTransactionRequiredException更新/删除方法没有运行在事务中Service 层加 Transactionalnative 查询列映射报错原生 SQL 的列名和实体属性无法对应改为select *或使用投影返回6.2 查询结果与缓存不一致问题缓存不一致是我见过最磨人的问题表现为同一份数据前一次查询和后一次查询结果不一样而且重启服务又好了。排查思路要分成两层。第一层是一级缓存。前面说过Modifying 更新后没有清空 EntityManager 缓存同事务内再次查询会命中旧对象。这种情况的典型特征是在同一个事务里一次查询一次更新一次查询第二次查询结果不对但事务结束后新事务查询结果正常。解决办法就是给 Modifying 加上clearAutomatically true。第二层是二级缓存。如果你的实体上配置了CacheableSpring Data JPA 的二级缓存会整体缓存整个查询结果集。执行批量 update 后即使一级缓存清了二级缓存里的数据也可能还是旧的而且这个数据会在缓存失效前一直误导你。排查这个问题的快捷手段是禁用二级缓存跑一遍测试如果结果恢复正常那基本就实锤了。线上改起来没那么快项目中可以执行完批量操作后手动调用缓存清理方法或者在 Modifying 后对相关实体做一次缓存驱逐。6.3 排查工具与调试建议遇到 Query 问题第一件事永远是打开 SQL 日志。Spring Boot 项目里在配置文件加一段logging: level: org.hibernate.SQL: debug org.hibernate.orm.jdbc.bind: traceSQL: debug会打印 Hibernate 实际发送到数据库的 SQLorm.jdbc.bind: trace会打印每个占位符绑定的具体参数值。这两个日志一开百分之八十的问题当场就能看出来是参数绑错了还是 SQL 本身生成了非预期形态。除此之外我给 Query 方法写单元测试时习惯用真实数据库而不是 H2 内存库尤其是原生 SQL 涉及数据库特有函数时H2 的方言模拟效果和线上差距很大。一个 DataJpaTest 注解连上本地开发库每个查询方法都验证一遍返回结构和条数看起来麻烦但一旦遇到 SQL 跑在测试环境正常、到线上就挂的情况你会感谢这些测试。还有一个小技巧写 JPQL 之前先按同样的逻辑写一版原生 SQL 到数据库客户端里跑通然后对照着翻译成 JPQL。这样做能让你更快定位问题到底是「业务逻辑写错」还是「SQL 映射出错」不用在注解字符串和数据库报错之间反复折腾。最后分享一下我自己的经验组合简单查询用方法名写起来快中复杂度查询用 Query逻辑看得清动态筛选组合用 Specification可扩展性强批量更新和统计查询提前想好缓存和事务边界。把 Query 当成一把趁手的工具而不是一个装 SQL 的字符串容器你的数据访问层会舒服很多。 
长河君 · 2026/10/17 9:54:20 · 阅读 1.2k Spring Data JPA @Query 注解全解析：从基础到避坑实践
Spring Data JPA 里最容易被高估的是方法名解析最容易被低估的就是 Query 注解。平时随便几个条件方法名解决起来又快又爽可一旦查询开始复杂——多表关联、报表统计、条件分支、批量更新——你会发现所有别扭的地方最后都得回到 Query 来兜底。这篇内容就是讲清楚 Query 的完整用法从最基础的 JPQL 写法到原生 SQL、参数绑定、SpEL 动态处理、配合 Modifying 做增删改再到常见异常和缓存不一致的排查每一块都会给可运行的代码和对应的避坑经验。适合两类人看一是刚开始接触 Spring Data JPA、对自定义查询没有头绪的同学二是已经写了很久 Repository 但一直在用方法名硬扛、想系统搞明白 Query 细节的开发者。1. 什么时候该用 Query先从方法名解析的边界说起1.1 方法名解析能做什么不能做什么Spring Data JPA 的方法名解析确实方便像findByNameAndEmail、findByAgeGreaterThan、findTop3ByOrderByCreateTimeDesc这种查询不写一行实现代码框架照着方法名就帮你拼出 SQL。我见过不少团队早期就靠这一招撑起整个数据层效率确实高。但方法名解析有一个隐藏问题它能表达的查询模式太固定了。简单等值、范围、排序、分页这些都没问题可一旦遇到多表 join、group by having、子查询、批量更新方法名的表达力就完全不够用。你很难想象findByUserIdAndOrderStatusAndGoodsIdInOrderByCreateTimeDesc这种四十几个字符的方法名能被团队里的新人一眼看懂更别说方法名解析天生不带group by和having复杂统计查询根本没有干净的表达方式。还有一点方法名生成的 SQL 是框架在运行时拼出来的你只能看到最终 SQL 长什么样中间没有代码层面的人工可控点出了问题反而不好定位。所以我的判断标准很简单查询条件超过两个、涉及多张表、需要自定义返回结构、或者要写 update/delete 的时候不要再折磨方法名了直接上 Query。它本身就是 Spring Data JPA 留给开发者接管查询的出口与其等到 SQL 复杂到失控不如从一开始就在方法上把查询逻辑写清楚。1.2 Query 真正解决的几类典型问题Query 能做的远不止是代替方法名。它最大的优势是让你在框架自动化和原生控制之间找到一个可控的落点。第一类典型问题是多表关联查询。比如订单和用户你想一次性把订单连同用户名称查出来避免循环查询造成 N1可以在 JPQL 里用 join fetch。这种写法在方法名解析里几乎没法优雅表达但在 Query 里就是一句话的事。Query(select distinct o from Order o left join fetch o.user where o.status :status) ListOrder findOrdersWithUser(Param(status) Integer status);第二类是聚合统计。按月统计订单数、按状态统计金额合计这类 SQL 说白了就是group by加几个聚合函数用 JPQL 写出来格式干净也还保留着实体映射的能力。第三类是批量更新和删除。Spring Data JPA 默认的save方法是一条条 SQL几百条数据还好几万条就要命了用 Query 写一条批量更新可以显著减少数据库往返。第四类是调用数据库特有函数比如 MySQL 的DATE_FORMAT、JSON_CONTAINSJPQL 里可以用function()透传原生 SQL 里更是直接写。1.3 什么时候反而不要用 QueryQuery 不是银弹我见过反面的滥用场景。如果查询条件组合特别多比如用户列表页有十几种筛选条件而且每次请求出现的组合都不一样你在 Query 里写死任何一种 SQL 都是错的做法拼接字符串又很快会变成灾难。这种情况应该考虑用 Specification 或者 QueryDSL让条件在业务层动态组装而不是硬塞进一个注解里。还有一种情况是简单查询也硬上 Query。findByName能解决的问题非要写成Query(select u from User u where u.name :name)代码并没有变好反而多了一行要维护的字符串方法名解析的语义优势也没了。我的经验是能用方法名说清楚的就不要动 Query否则查询逻辑会散落在注解字符串和业务代码之间可读性只会更差。2. Query 基本写法JPQL、原生 SQL 与返回值设计2.1 注解参数与最简示例先看 Query 注解的常用参数。在 Spring Data JPA 的源码里这个注解最核心的配置是value和nativeQueryvalue就是查询语句本身nativeQuery默认是 false也就是按 JPQL 解析设成 true 之后value里的内容按数据库原生 SQL 解析。另外还有countQuery、countProjection两个参数专门用来配合分页查询的 count 语句后面会展开。一个最基本的命名参数查询写起来长这样public interface UserRepository extends JpaRepositoryUser, Long { Query(select u from User u where u.email :email) OptionalUser findByEmail(Param(email) String email); }这里User是实体类名不是数据库表名u.email是实体的 Java 属性名不是数据库列名。JPQL 本质上是在跟实体模型打交道而不是直接跟表结构打交道这就是它和原生 SQL 最大的区别。如果你把这里写成select u from t_userHibernate 会直接抛出QuerySyntaxException: t_user is not mapped这类问题后面专门讲。2.2 JPQL 查询语句的核心写法JPQL 的语法和 SQL 非常像它支持select、where、order by、group by、having、join大部分情况下你可以在 SQL 和 JPQL 之间做一次近乎等价的翻译。区别在于你引用的对象JPQL 里写实体名和属性名SQL 里写表名和列名。实际项目中我最常用的 JPQL 写法是以下三种。第一种是简单条件查询控制在实体单表范围内第二种是分页查询直接往方法里加一个Pageable参数框架会自动拼接limit和 count 查询第三种是关联查询比如要拿到用户及其订单列表可以用left join fetch这能极大避免 N1。Query(select u from User u where u.age between :minAge and :maxAge) ListUser findUsersByAgeRange(Param(minAge) Integer minAge, Param(maxAge) Integer maxAge);Query(value select u from User u where u.status :status, countQuery select count(u) from User u where u.status :status) PageUser findUsersByStatus(Param(status) Integer status, Pageable pageable);第二段代码里的countQuery是很多人会忽略的。默认情况下 Spring Data 会尝试从你的查询中生成 count 语句简单查询没问题一旦查询里带了group by、distinct、多表 join自动生成的 count 可能统计错误或者性能极差。自己写 count 语句能保证总数的准确性也能把 count 的 SQL 调整到最轻量。这里建议直接数主表能不加 join 就不加 join。JPQL 里也支持case表达式、coalesce、nullif这些逻辑控制比如Query(select u.name, coalesce(u.phone, u.email) from User u) ListObject[] findContactInfo();2.3 原生 SQL 的正确姿势和坑当 JPQL 解决不了数据库方言特性时就轮到nativeQuery true出场。比如 MySQL 的DATE_FORMAT、GROUP_CONCAT或者某些报表 SQL 里复杂到让你怀疑人生的子查询嵌套这些在 JPQL 里写起来很别扭但原生 SQL 直接照抄数据库客户端的语句就行。Query(value select id, name, date_format(create_time, %Y-%m) as month from t_user where status :status, nativeQuery true) ListObject[] findUserSummary(Param(status) Integer status);原生 SQL 的坑主要在映射关系上。如果你返回的是实体类型比如ListUserSQL 里的列名必须能覆盖实体映射的字段否则 Hibernate 要么报找不到列的异常要么拷出大量 null 值。这里给个最稳的操作能select *就别手写列清单手写列清单时一定注意列别名要跟实体属性匹配得上。另一个常见问题是忘写nativeQuery truevalue里写的明明是数据库表名框架还是按 JPQL 去解析结果报一堆实体映射错误这种低级错误排查起来非常浪费时间。我平时写原生 SQL 的习惯是先在数据库客户端把 SQL 跑通确认结果没问题再粘贴到注解里然后立刻跑一个单元测试验证字段映射绝对不靠肉眼检查。2.4 返回值类型设计实体、DTO 投影与接口投影Query 的返回类型选择直接影响代码质量和查询性能这块值得单独花时间理清楚。最简单的是直接返回实体ListUser、OptionalUser这种适合查询字段和实体完全匹配的情况。但如果你只需要两三个字段也返回完整实体会产生不必要的字段映射开销而且容易误用实体携带的那些大字段。更合适的做法是用投影。接口投影是 Spring Data JPA 的一个特性在 Repository 里定义一个接口里面只声明需要的 getter框架会自动生成代理实现public interface UserNameView { String getName(); Integer getAge(); } Query(select u.name, u.age from User u where u.id :id) OptionalUserNameView findUserNameById(Param(id) Long id);这里有个细节JPQL 里的字段别名要和接口 getter 对应上写成select u.name as name之类的最保险。接口投影适合只读场景代码干净还不用维护额外 DTO。类投影则更适合在业务层传递结构化的数据对象写法是在 JPQL 里用new关键字Query(select new com.example.dto.UserBrief(u.id, u.name, u.email) from User u) ListUserBrief findBriefUsers();前提是UserBrief必须有一个入参完全匹配的构造函数。还有一种是返回ListMapString, Object用select new map(u.name as name, u.age as age)适合字段不固定的临时查询但类型不安全不太推荐在核心业务里用。3. 参数绑定的几种写法位置参数、命名参数与集合 IN3.1 位置参数与命名参数怎么选Query 支持两类参数绑定。位置参数写法是?1、?2按方法参数顺序自动匹配命名参数写法是:name配合Param(name)指定参数名。Query(select u from User u where u.age ?1 and u.status ?2) ListUser searchUsers(Integer minAge, Integer status); Query(select u from User u where u.name :name and u.status :status) ListUser searchUsers(Param(name) String name, Param(status) Integer status);我个人强烈推荐命名参数原因只有一个可读性和维护性。位置参数在参数少的时候没问题一旦查询涉及五六个参数你根本记不住第几个?对应哪个字段中间加一个参数还要回去数数。命名参数就没有这个问题参数名和属性名一一对应代码审查时一眼能看懂。另外有一个容易踩的版本坑Spring Boot 3 和 Spring Framework 6 默认开启了-parameters编译参数方法参数名会保留在字节码里所以Param在某些情况下可以省略。但为了兼容老项目、也为了显式表达意图建议始终写Param。你不写的话在旧的构建配置或某些代理模式下框架可能找不到参数名爆出Named parameter not found异常这种问题很难排查。3.2 集合参数处理 IN 查询在业务里「根据一组 ID 查数据」是极其常见的场景。方法名解析里可以用findByIdIn但如果你还带了其他条件或者这个查询本来就是 Query那直接用集合参数最方便Query(select u from User u where u.id in :ids) ListUser findUsersByIds(Param(ids) CollectionLong ids);这个写法的好处是框架会自动把集合展开成IN (?, ?, ?...)的绑定参数不用你手动拼逗号。但有一个隐藏问题如果传入的集合为空最终生成的 SQL 可能是in ()这在某些数据库上会直接报语法错误Hibernate 对空集合的处理也曾经在多个版本里出现过不一致。我的建议是在调用层做一次空集合判断为空直接返回空集合别把这个边界条件甩给 SQL 来处理。3.3 LIKE 模糊查询的安全写法模糊查询是 Query 新手翻车最频繁的地方。很多人一上来就写Query(select u from User u where u.name like %:keyword%) ListUser searchUsers(Param(keyword) String keyword);这个写法是错的而且错得很有迷惑性。:keyword会被当成一个参数名来解析但它的前后是单引号括起来的字符串内容Hibernate 会要求你给keyword赋值最终生成的 SQL 也不是你想要的那个模糊匹配语义大概率直接报参数绑定失败。正确的写法是用 JPA 内置函数concat拼接百分号Query(select u from User u where u.name like concat(%, :keyword, %)) ListUser searchUsers(Param(keyword) String keyword);也可以用另一种方式方法调用方传参时自己拼好%keyword%JPQL 里只写like :keyword。为什么不推荐用||拼接因为||在不同数据库方言里的连接语义不完全一致JPQL 的concat是规范内置的跨库更稳妥。如果你还要匹配%和_这类通配符那就得用ESCAPE子句自定义转义字符不然用户输入的%会被误当成通配符。3.4 分页与排序的正确配合Query 方法里加一个Pageable参数框架会自动处理分页逻辑这是 Spring Data JPA 很强大的地方。最小可行的例子Query(select u from User u where u.age :age) PageUser findUsersByAge(Param(age) Integer age, Pageable pageable);Pageable可以用PageRequest.of(page, size, sort)创建页码从 0 开始。多数时候你不需要自己写 limit也不需要关心 count 是怎么生成的。但有两种情况要注意。第一种是复杂查询里 count 可能不正确前面提过需要显式指定countQuery。第二种是join fetch集合关联的时候用PageHibernate 在底层可能被迫先把所有关联数据加载进内存做分页会出现一条警告firstResult/maxResults specified with collection fetch; applying in memory。这种查询量一大就会内存溢出我的解决套路是先分页查出主表 ID 列表再用 ID 列表 IN 查询关联数据最后在业务层组装等价于把分页和关联查询拆成两步性能反而更好。4. 动态场景的补位SpEL 表达式与统计查询实战4.1 用 SpEL 处理集合参数Spring Data JPA 在 Query 里支持 SpEL 表达式最常见的一个用途是对参数进行处理。比如你要兼容传空集合的情况或者想直接引用参数对象里的某个属性就可以用:#{}这种写法Query(select u from User u where u.id in :#{#ids}) ListUser findUsersByIds(Param(ids) CollectionLong ids);这个写法本质上和直接传集合参数一样但 SpEL 给你多了处理空间。你可以用?:空值合并、用? :条件判断比如给个默认集合Query(select u from User u where u.id in :#{#ids ! null ? #ids : { -1 }}) ListUser findUsersByIds(Param(ids) CollectionLong ids);这里把 null 集合替换成{ -1 }至少不会生成非法的空in ()。虽然这个技巧有点取巧但在快速迭代的项目里确实能少写很多判空逻辑。4.2 动态表名与可选条件的写法动态表名是 Query 的进阶用法。比如分表场景下每个月一张表方法参数里传入表名后缀JPQL 没法直接支持动态表名只能走原生 SQL 加 SpELQuery(value select * from #{#tableName} where status :status, nativeQuery true) ListMapString, Object findListByTable(Param(tableName) String tableName, Param(status) Integer status);需要特别强调表名不能作为预处理语句的占位符绑定只能用 SpEL 拼接。这意味着如果表名来源不可信这就是个 SQL 注入点。我在实际项目里只允许内部枚举出来的表名列表传进来任何来自前端参数的表名直接拒绝。可空条件的处理也是动态查询的一个经典难题。一个筛选列表名称可能为空、状态可能为空每次查询组合都不同。JPQL 里可以用is null or的模式Query(select u from User u where (:#{#name} is null or u.name :#{#name}) and (:#{#status} is null or u.status :#{#status})) ListUser searchUsers(Param(name) String name, Param(status) Integer status);这种写法虽然 SQL 里带or is null会让数据库优化器没那么高效但在多数金额级数据量的场景下足够用而且代码非常简单。数据量大、性能敏感的接口该上 Specification 就上不要硬扛。4.3 复杂统计查询的实践示例统计报表是我用 Query 最多的地方。比如按月份统计用户注册数量在 MySQL 下原生 SQL 这么好写select date_format(create_time, %Y-%m) as month, count(*) as cnt from t_user group by month order by month descJPQL 版本可以用function调用数据库函数Query(select function(date_format, u.createTime, %Y-%m) as month, count(u) from User u group by function(date_format, u.createTime, %Y-%m)) ListObject[] countUserByMonth();我个人的建议是这种统计 SQL 直接用原生 SQL 就好因为统计查询本身对数据库方言的依赖很强JPQL 翻译一层还可能改变 SQL 形态对排查不利。原生 SQL 的好处是你可以把数据库客户端验证过的语句原样贴进注解行为完全可预期。5. 增删改操作Modifying 的配套细节与常见坑5.1 更新与删除的基本写法Query 不只可以做查询还可以做更新和删除。但 Spring Data JPA 有明确限制非查询语句必须在方法上再加一个Modifying注解否则框架会因为执行了非 select 语句而抛异常。基本写法Modifying Query(update User u set u.email :email where u.id :id) int updateEmail(Param(id) Long id, Param(email) String email); Modifying Query(delete from User u where u.id :id) int deleteUserById(Param(id) Long id);返回值int表示受影响的行数可以用来判断更新是否真的命中。注意 JPQL 的批量更新里不能用单个实体引用比如不能写u.setEmail这种对象式写法它本质上是面向语句的不是面向对象的。5.2 事务、缓存与清缓存参数用 Query 写 update/delete 时事务是必须的。如果你不在 Service 层加Transactional运行时会报TransactionRequiredException。这个异常提示很友好但很多新手还是会在 Repository 层放了Modifying就以为万事大吉实际上一调用就炸。更隐蔽的是缓存问题。JPA 的一级缓存会缓存当前事务里查询过的实体。如果你在同一个事务里先查了一遍实体再执行 Modifying 批量更新然后又在同一个事务里查这个实体你拿到的可能是缓存里的旧值而不是更新后的值。解决方式就是设置两个参数Modifying(clearAutomatically true, flushAutomatically true) Query(update User u set u.status :status where u.id in :ids) int batchUpdateStatus(Param(ids) CollectionLong ids, Param(status) Integer status);clearAutomatically true会在执行更新后清空持久化上下文保证后续查询能拿到数据库的最新值flushAutomatically true则会在执行更新前自动 flush 未保存的实体变更避免更新的结果被本地未提交数据覆盖。我建议查询更新混用的方法都加上这两个参数代价最多是多一次 flush但能避免无数诡异的结果不一致问题。5.3 批量操作的几个隐蔽问题批量操作里还有三个坑是我实测踩过的。第一个是生命周期回调失效JPQL 批量更新和删除不会触发PreUpdate、PreRemove这类实体回调方法。如果你的业务依赖实体的审计字段自动填充批量操作会静默跳过需要手动在语句里维护这些字段。第二个是乐观锁失效Version 字段在批量更新里默认不会被框架自动处理你得自己在 set 子句里写版本号加一否则并发场景下可能丢失更新保护。第三个是关联删除问题。用 JPQL 批量删除父实体不会自动级联删除子实体除非数据库外键本身配置了级联删除。我处理这类需求时如果关联关系复杂宁可先查出父实体 ID 列表再按子先后顺序分多条 SQL 处理图省事直接 delete 父表大概率留下悬挂数据后面查关联的时候一堆空引用。6. 翻车记录高频异常、缓存问题与排查思路6.1 高频异常与对应原因速查下面这张表是我在实际排查 Query 问题时最常遇到的情况一条条对照能省不少时间异常信息根本原因解决方式QuerySyntaxException: xxx is not mappedJPQL 里写了表名而不是实体名或实体类名拼错检查引用的名称JPQL 用实体名Invalid path: u.emial实体属性名拼写错误或路径写错核对实体 Java 字段名大小写敏感Named parameter not foundParam(xxx)和方法实际参数名不一致或忘了加 Param统一参数名与 Param 的值in ()语法报错传入的集合参数为空业务层判空或用 SpEL 给默认集合Not supported by JpaQueryExecution方法上有 Query 但没有 Modifying 却执行了 update/delete给语句加上 ModifyingTransactionRequiredException更新/删除方法没有运行在事务中Service 层加 Transactionalnative 查询列映射报错原生 SQL 的列名和实体属性无法对应改为select *或使用投影返回6.2 查询结果与缓存不一致问题缓存不一致是我见过最磨人的问题表现为同一份数据前一次查询和后一次查询结果不一样而且重启服务又好了。排查思路要分成两层。第一层是一级缓存。前面说过Modifying 更新后没有清空 EntityManager 缓存同事务内再次查询会命中旧对象。这种情况的典型特征是在同一个事务里一次查询一次更新一次查询第二次查询结果不对但事务结束后新事务查询结果正常。解决办法就是给 Modifying 加上clearAutomatically true。第二层是二级缓存。如果你的实体上配置了CacheableSpring Data JPA 的二级缓存会整体缓存整个查询结果集。执行批量 update 后即使一级缓存清了二级缓存里的数据也可能还是旧的而且这个数据会在缓存失效前一直误导你。排查这个问题的快捷手段是禁用二级缓存跑一遍测试如果结果恢复正常那基本就实锤了。线上改起来没那么快项目中可以执行完批量操作后手动调用缓存清理方法或者在 Modifying 后对相关实体做一次缓存驱逐。6.3 排查工具与调试建议遇到 Query 问题第一件事永远是打开 SQL 日志。Spring Boot 项目里在配置文件加一段logging: level: org.hibernate.SQL: debug org.hibernate.orm.jdbc.bind: traceSQL: debug会打印 Hibernate 实际发送到数据库的 SQLorm.jdbc.bind: trace会打印每个占位符绑定的具体参数值。这两个日志一开百分之八十的问题当场就能看出来是参数绑错了还是 SQL 本身生成了非预期形态。除此之外我给 Query 方法写单元测试时习惯用真实数据库而不是 H2 内存库尤其是原生 SQL 涉及数据库特有函数时H2 的方言模拟效果和线上差距很大。一个 DataJpaTest 注解连上本地开发库每个查询方法都验证一遍返回结构和条数看起来麻烦但一旦遇到 SQL 跑在测试环境正常、到线上就挂的情况你会感谢这些测试。还有一个小技巧写 JPQL 之前先按同样的逻辑写一版原生 SQL 到数据库客户端里跑通然后对照着翻译成 JPQL。这样做能让你更快定位问题到底是「业务逻辑写错」还是「SQL 映射出错」不用在注解字符串和数据库报错之间反复折腾。最后分享一下我自己的经验组合简单查询用方法名写起来快中复杂度查询用 Query逻辑看得清动态筛选组合用 Specification可扩展性强批量更新和统计查询提前想好缓存和事务边界。把 Query 当成一把趁手的工具而不是一个装 SQL 的字符串容器你的数据访问层会舒服很多。