Hibernate查询参数占位符:#{#param}与:param的使用差异及适用场景

很多人写查询的时候传简单类型入参，会觉得两种写法跑出来的结果没区别，但二者的底层实现、能力边界完全不同，不存在“随便用哪个都一样”的场景。

1. 基础命名参数写法 :paramName #

这是JPA官方规范定义的标准参数绑定语法，也是最通用的实现：

• 执行逻辑：查询预编译阶段会直接把占位符和标注了@Param的方法入参做绑定，入参值会以预编译参数的形式直接传给数据库，全程不参与JPQL语句的表达式解析
• 兼容性：所有JPA实现（Hibernate、EclipseLink、OpenJPA）都原生支持，不依赖任何框架的额外能力
• 适用场景：90%以上的常规简单查询，尤其是直接传递Long、String、Date这类简单类型入参的场景，用这个写法语义最清晰、没有额外解析开销
• 能力边界：占位符本身不能做任何表达式运算、属性提取，比如你没法直接在占位符里写取入参对象嵌套属性、设默认值的逻辑，所有这些处理都必须提前在业务层做完，把最终要绑定的值传给方法

2. EL表达式参数写法 :#{#paramName} #

这是Spring Data JPA为了降低样板代码，在Hibernate查询能力之上拓展的SpEL（Spring表达式语言）嵌入能力：

• 执行逻辑：占位符内的内容会先交给SpEL引擎做表达式求值，拿到最终的求值结果后，再走和基础写法完全一致的参数绑定流程送到数据库
• 能力特性：
  • 支持从入参对象里直接提取嵌套属性：比如你的方法入参是一个SubmissionQuery封装对象，里面嵌套了dateRange.startTime字段，完全不用在Service层拆属性取值，直接在JPQL里写WHERE s.createTime >= :#{#query.dateRange.startTime}即可完成绑定
  • 支持入参默认值兜底：如果某个入参可能为null，不用在业务层写判空逻辑，直接在表达式里写WHERE s.status = :#{#status ?: 'ACTIVE'}，当传入status为null时会自动兜底用默认值ACTIVE做查询
  • 支持入参的轻量处理：比如做字符串匹配时需要先对入参做去空格、转大小写的处理，直接在表达式里写WHERE LOWER(s.title) = LOWER(:#{#searchTitle?.trim()})就行，不用把这类零散的处理逻辑散在业务层
• 适用边界：这种写法完全绑定Spring生态，脱离Spring Data JPA的环境（比如直接用原生Hibernate Session API写查询）根本无法运行；在传简单值的场景下，因为多了一层SpEL解析，会有可忽略不计的微小性能开销。

为什么简单入参场景下二者表现完全一致 #

当你用:#{#submissionId}直接传入一个Long类型的简单值时，SpEL对这个表达式的求值结果就是入参本身，后续的参数绑定、SQL执行流程和:submissionId没有任何区别，所以这种最朴素的用法下你感知不到差异。但一旦涉及嵌套属性提取、默认值兜底、入参轻量处理的需求，基础写法根本没法实现这类能力。

选型参考 #

• 常规简单参数的查询，优先使用:paramName的标准写法，兼容性更强、语义更清晰
• 当需要减少业务层重复的入参拆值、判空、格式转换的样板代码时，再使用:#{#paramName}的EL表达式写法

内容的提问来源于stack exchange，提问作者Alfred Kreuzer