Spring Data PropertyReferenceException排查：Auth微服务Jar包引入HRMS项目后自定义Native Query方法无法被识别

这个问题我之前也碰到过——单独运行的微服务一切正常，打包成Jar引入其他项目后，Spring就好像“看不到”XML里的命名查询了，转而瞎解析方法名，最后抛出PropertyReferenceException。别慌，我们一步步来排查解决：

核心根因 #

当Auth作为Jar包被HRMS引入时，Spring默认只会扫描HRMS自身类路径下的资源文件，不会自动加载Jar包中的jpa-named-sql.xml。这就导致Repository上的@Query(name=...)注解被忽略，Spring Data JPA退而尝试通过方法名推导查询条件，而你的方法名里的userId并不属于RoleModulePermissionMapping实体，所以抛出了那个异常。

分步解决方案 #

1. 让HRMS扫描所有类路径下的命名查询文件 #

修改HRMS项目的配置，确保JPA能找到Jar包中的XML文件。在application.yml或application.properties中添加配置：

如果是YAML格式：

spring:
  jpa:
    mapping-resources: classpath*:jpa-named-sql.xml

如果是Properties格式：

spring.jpa.mapping-resources=classpath*:jpa-named-sql.xml

这里的关键是用classpath*:而不是classpath:——前者会扫描所有类路径（包括依赖Jar包）中的匹配文件，后者只扫描当前项目的类路径。

2. 验证Auth Jar包是否正确包含了XML文件 #

解压你的Auth Jar包，检查BOOT-INF/classes/目录下是否存在jpa-named-sql.xml。如果没有，说明Auth项目的构建配置有问题：

• 对于Maven项目，确保XML文件放在src/main/resources目录下，pom.xml中没有排除资源文件的配置。
• 对于Gradle项目，确认sourceSets.main.resources包含该文件。

3. 确保命名查询的名称完全匹配 #

检查XML文件中的<named-native-query>的name属性，必须和Repository方法上@Query(name=...)的值完全一致（包括实体类名+方法名的格式）：

<named-native-query name="RoleModulePermissionMapping.getAllNavigationMenuPermissionsByUserId" resultClass="com.yourpackage.IUserRoleDTO">
    <query>
        <!-- 你的原生SQL语句 -->
    </query>
</named-native-query>

注意：resultClass要指定正确的DTO全类名，否则查询结果映射也会出问题。

4. 确认HRMS扫描了Auth的Repository包 #

如果HRMS的Spring配置只扫描自己的Repository，Auth的Repository不会被正确初始化。在HRMS的主配置类上修改@EnableJpaRepositories：

@EnableJpaRepositories(basePackages = {
    "com.yourauthpackage.repository", // Auth的Repository包
    "com.yourhrmspackage.repository"  // HRMS自身的Repository包
})

为什么单独运行Auth没问题？ #

单独运行Auth时，Spring Boot会自动扫描自身src/main/resources下的所有资源文件，包括jpa-named-sql.xml，所以命名查询能被正确加载并关联到Repository方法。但当作为依赖Jar引入HRMS后，HRMS的默认配置不会主动扫描Jar中的资源，必须显式配置classpath*:才能让Spring找到这些文件。

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