Spring Boot无法识别依赖项目中的实体类问题求助

实体类定义 #

基础实体类：

@MappedSuperclass
@EntityListeners({AuditingEntityListener.class})
public class BaseAuditEntity extends BaseEntity {
      ...
} 

依赖项目中的实体类：

package core.entities;
@Entity
public class Customer extends BaseAuditEntity {
    ...
}

查询代码与首次报错 #

使用Criteria Builder执行查询的代码：

CriteriaQuery<BaseIdCodeDto> query =
    getCriteriaBuilder().createQuery(BaseIdCodeDto.class);

Root<Customer> root = query.from(Customer.class);

报错信息：

org.springframework.dao.InvalidDataAccessApiUsageException: Not an
 entity: class core.entities.Customer; nested exception is
 java.lang.IllegalArgumentException: Not an entity:

后续尝试与二次报错 #

将Customer类复制到当前项目后，新报错：

Customer.customerChannel references an unknown entity: 
core.entities.CustomerChannel

注：Customer类位于另一个Maven依赖项目，已通过pom.xml引入；多个项目共用这些实体，无法全部复制到当前项目。

核心原因 #

Spring Boot默认仅扫描当前项目启动类所在包及其子包下的@Entity注解类，依赖项目中的实体不在默认扫描范围内，因此无法被JPA识别为合法实体。

具体解决办法 #

1. 用@EntityScan指定实体扫描路径 #

在Spring Boot启动类上添加@EntityScan注解，明确包含依赖项目的实体包路径：

@SpringBootApplication
@EntityScan(basePackages = {"com.your.current.project.entities", "core.entities"})
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

• 替换com.your.current.project.entities为当前项目自身的实体包，core.entities是依赖项目的实体包，多个包用逗号分隔。

2. 修正依赖项目的打包配置 #

如果依赖项目是Spring Boot项目，需避免将其打成可执行jar（可执行jar的类结构与普通jar不同，会导致依赖引用异常）。在依赖项目的pom.xml中修改打包插件：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <classifier>exec</classifier> <!-- 同时生成普通jar和可执行jar -->
            </configuration>
        </plugin>
    </plugins>
</build>

这样依赖项目会生成两个jar：一个普通jar供其他项目依赖，一个带exec后缀的可执行jar用于自身启动。

3. 检查实体注解的正确性 #

• 确认所有实体类都正确标注@Entity，无拼写错误。
• 确保@MappedSuperclass修饰的父类没有被误标为@Entity，避免干扰子类的实体识别。

4. 排查组件扫描冲突 #

如果当前项目使用了自定义@ComponentScan配置，需确保它没有覆盖@EntityScan的扫描范围；或者在@ComponentScan中同时包含依赖项目的包（更推荐用@EntityScan专门处理实体扫描）。

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