本文详解如何在 JPA Repository 方法命名中安全使用含 SQL 保留字（如 And、Or、Order 等）的实体属性名，避免因 PropertyPath 解析歧义导致的 IllegalArgumentException，并提供命名规范、@Query 替代方案及最佳实践。
本文详解如何在 jpa repository 方法命名中安全使用含 sql 保留字（如 `and`、`or`、`order` 等）的实体属性名，避免因 `propertypath` 解析歧义导致的 `illegalargumentexception`，并提供命名规范、`@query` 替代方案及最佳实践。
在 Spring Data JPA 中，Repository 接口支持通过方法名自动解析查询逻辑（如 findByUsernameAndStatus()），其底层依赖 PropertyPath 类对方法名进行分词与属性映射。但当实体字段名本身包含 And、Or、Between、OrderBy 等关键字时（例如 dateAndTimeOfEstimation），PropertyPath 会错误地将 And 视为逻辑连接符而非字段名的一部分，导致解析中断——它仅截取 date 作为属性名，进而抛出 PropertyReferenceException: No property date found for type XxxEntity。
✅ 正确解决方案
方案一：使用下划线命名 + @Column(name = "...") 显式映射（推荐）
遵循 Java 命名规范的同时规避解析歧义，将驼峰字段转为下划线风格，并通过 @Column 明确指定数据库列名：
@Entity
public class Estimation {
@Column(name = "date_and_time_of_estimation")
private LocalDateTime dateAndTimeOfEstimation;
// getter/setter...
}此时可安全定义 Repository 方法：
public interface EstimationRepository extends JpaRepository<Estimation, Long> {
List<Estimation> findAllByDateAndTimeOfEstimation(LocalDateTime dateTime);
// ✅ 解析成功：PropertyPath 将整个 "dateAndTimeOfEstimation" 视为单一属性名
}⚠️ 注意：该方案生效的前提是 字段名中不出现连续大写字母触发误切分（如 XMLData 可能被切为 XML + Data）。若存在此类情况，建议改用方案二。
方案二：显式声明 JPQL 查询（最稳妥）
彻底绕过方法名解析机制，使用 @Query 注解编写类型安全的 JPQL：
public interface EstimationRepository extends JpaRepository<Estimation, Long> {
@Query("SELECT e FROM Estimation e WHERE e.dateAndTimeOfEstimation = :dateTime")
List<Estimation> findAllByDateAndTimeOfEstimation(@Param("dateTime") LocalDateTime dateTime);
// 或使用原生 SQL（需注意数据库兼容性）
@Query(value = "SELECT * FROM estimation WHERE date_and_time_of_estimation = ?", nativeQuery = true)
List<Estimation> findAllByDateAndTimeOfEstimationNative(LocalDateTime dateTime);
}方案三：使用 @NamedQuery（适合复用复杂查询）
在实体类中定义命名查询，保持 Repository 接口简洁：
@Entity
@NamedQuery(
name = "Estimation.findByDateAndTimeOfEstimation",
query = "SELECT e FROM Estimation e WHERE e.dateAndTimeOfEstimation = :dateTime"
)
public class Estimation { /* ... */ }public interface EstimationRepository extends JpaRepository<Estimation, Long> {
List<Estimation> findByDateAndTimeOfEstimation(@Param("dateTime") LocalDateTime dateTime);
// Spring Data 会自动匹配 @NamedQuery 名称（去掉前缀 "Estimation."）
}? 关键注意事项
- ❌ 避免在方法名中强行使用 And/Or 作为字段一部分（如 findByDateAndTimeOfEstimation）而不做适配——这是设计陷阱，非临时 workaround。
- ✅ 始终优先采用方案一（下划线映射），它兼顾可读性、约定一致性与零额外开销。
- ? 调试技巧：在 PropertyPath.from(String, TypeInformation<?>) 处设置断点，观察实际解析出的属性路径，验证是否符合预期。
- ? 若项目已上线且列名不可变更，方案二（@Query）是最安全、可立即落地的选择。
综上，JPA 方法名解析的“保留字冲突”本质是命名约定与解析器能力的边界问题。通过合理设计实体字段名、善用注解或显式查询，即可在保持代码清晰的同时，完全规避这一常见障碍。
