JPA的命名查询（Named Query）是把JPQL语句提前定义好并放到实体类上的一种查询方式，编译期就能校验语法，执行时也不用重复解析，性能和可维护性都不错。但很多初学者在实际使用时，往往被参数绑定这一步卡住：明明语句写对了，一传参数就报类型不匹配，或者日期参数查出来的结果永远是空。这篇文章就围绕命名查询中参数类型的各种用法，配上完整示例把细节讲透。
什么是命名查询，参数有哪两种写法
命名查询通过@NamedQuery注解定义在实体类上，比如在一个User实体上定义一个根据用户名查用户的查询。JPQL语句中的参数占位符有两种写法：一种是位置参数，用问号加数字表示，比如?1、?2；另一种是命名参数，用冒号开头，比如:username、:age。两种写法各有优劣，位置参数写起来短，但参数多了以后可读性差，顺序一旦搞混就很麻烦；命名参数虽然多写几个字符，但含义明确，后期维护时一眼就能看出每个参数是什么作用，实际项目中更推荐命名参数。
定义好命名查询后，执行时通过EntityManager的createNamedQuery方法拿到Query对象，再用setParameter把实际值绑到占位符上。需要注意的是，绑定命名参数时参数名要和JPQL里写的完全一致，冒号在setParameter中不需要再写，直接写username而不是:username，这是初学者最常犯的低级错误之一。
常见参数类型的绑定示例
整数和字符串是最基础的类型。假设实体User有字段id（Long类型）和username（String类型），可以这样定义查询：
@NamedQuery(name = "User.findByCondition", query = "SELECT u FROM User u WHERE u.username = :username AND u.age = :age")
执行时依次绑定：query.setParameter("username", "张三").setParameter("age", 25)。这里传的Java类型要和实体字段类型对应，age字段如果定义的是Integer，就不要传Long进去，虽然数值相同，某些JPA实现（比如Hibernate的严格模式下）会直接抛出IllegalArgumentException。
日期类型是最容易出问题的。JPQL中对日期字段做等值查询、范围查询时，建议直接传java.util.Date或者java.time包下的类型。如果字段用了@Temporal(TemporalType.DATE)标注，传参时只比较日期部分；如果是TIMESTAMP，就要精确到时分秒。很多人用new Date()当参数查当天数据查不到，就是因为时间戳精确到了毫秒，数据库里的值和传入值对不上。正确做法是用范围查询，或者提前把日期截断到零点。Java 8之后的LocalDate、LocalDateTime在Hibernate 5以上版本可以直接传参，不需要额外转换，比老日期类型省心不少。
BigDecimal类型常用于金额字段，绑定时要特别注意精度。如果数据库字段是DECIMAL(10,2)，查询时传new BigDecimal("100.00")和new BigDecimal("100")在等值查询时某些数据库会认为不同，建议构造时就保持和数据库精度一致。布尔类型比较简单，直接传Boolean即可，但要确认实体字段映射的是数据库的什么类型，MySQL的tinyint(1)和Oracle的number(1)都能正常映射。
枚举类型的绑定容易被忽视。实体字段如果标注了@Enumerated(EnumType.STRING)，那么查询参数也要传枚举常量本身，比如setParameter("status", OrderStatus.PAID)，JPA会自动把它转成字符串去比较。如果字段没有标注@Enumerated，默认按ORDINAL存的是序号，这时传枚举常量同样可以，但强烈建议用STRING方式存储，否则枚举顺序一变，历史数据就全乱了。
集合参数与IN查询
当查询条件是一个列表时，比如查出所有id在某个集合里的用户，JPQL可以写成"WHERE u.id IN :ids"。这时setParameter传入的可以直接是一个List，JPA会自动展开。有个别老版本实现要求在参数名外加括号，写成IN (:ids)，为了兼容性可以保留括号写法。需要注意的是集合不能为空，传空集合会生成非法SQL，最好在代码里先判断一下，为空时直接跳过查询返回空结果。
常见疑问与踩坑解答
第一个常见问题：参数值为null怎么办？如果某个条件可能为空，比如用户没填年龄就查全部，直接setParameter("age", null)往往会报错或者查出空结果。解决方案是动态拼查询，用Criteria API，或者在JPQL里写"(:age IS NULL OR u.age = :age)"这种防御式写法，Hibernate对这种写法支持良好。
第二个问题：位置参数和命名参数能混用吗？答案是不行，同一条JPQL语句里只能选一种，混用会在启动校验阶段就报错。要么全部用?1这种形式，要么全部用:name这种形式，建议统一用命名参数。
第三个问题：为什么我的查询结果一直是空但不报错？大概率是类型不匹配但恰好能隐式转换，最典型的是日期。另外字段名和表列名也要分清，JPQL里写的是实体属性名而不是数据库列名，把u.user_name写进去会直接提示路径错误。还有一点，@NamedQuery的name属性建议带上实体名前缀，比如"User.findByUsername"，这样全局唯一，不容易和其他实体的查询重名冲突。
操作要点小结
总结一下核心要点：优先使用命名参数而不是位置参数；参数Java类型必须和实体字段类型严格一致；日期查询注意精度问题，能截断就截断；枚举字段建议用STRING方式存储；IN查询的集合参数要判空；可空条件用防御式写法或动态查询。把这些细节掌握了，命名查询用起来会顺畅很多，编译期校验的优势才能真正发挥出来。