JAR包中JPA实体无法识别：Not a managed type错误解决

问题场景 #

我创建了包含2个Entity的JAR包，其中Car类代码如下：

package com.jdm.legends.common.dto;

import com.jdm.legends.common.enums.CarColor;
import com.jdm.legends.common.enums.CarCompany;
import com.jdm.legends.common.enums.CarFuelType;
import com.jdm.legends.common.enums.CarTransmissionType;
import jakarta.persistence.*;

import lombok.*;

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

import static jakarta.persistence.CascadeType.ALL;
import static jakarta.persistence.EnumType.STRING;
import static jakarta.persistence.GenerationType.IDENTITY;

@Entity(name = "cars")
@Table
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Car {
    @Id
    @GeneratedValue(strategy = IDENTITY)
    private Long id;

    private String carName;

    @Enumerated(STRING)
    private CarColor carColor;

    @Enumerated(STRING)
    private CarTransmissionType carTransmissionType;

    @Enumerated(STRING)
    private CarCompany carCompany;

    @Enumerated(STRING)
    private CarFuelType carFuelType;

    private int km;

    private int productionYear;

    private BigDecimal initialPrice;

    private int hp;

    private boolean damaged;

    private int quantityInStock;

    @OneToMany(cascade = ALL, mappedBy = "car")
    private List<HistoryBid> historyBidList = new ArrayList<>();

    private LocalDateTime startDateCarPostedOnline;
    private LocalDateTime deadlineCarToSell;
}

在另一个微服务中通过pom.xml引入该JAR依赖：

<dependencies>
        <dependency>
            <groupId>com.jdm.legends.common</groupId>
            <artifactId>jdm-legends-commons</artifactId>
            <version>0.0.5</version>
        </dependency>
</dependencies>

并编写了CarRepository接口：

@Repository
public interface CarRepository extends JpaRepository<Car, Long> {
    @Query(value = "SELECT hb.id AS id, hb.bid_value AS bidValue FROM history_bid hb INNER JOIN cars c on hb.car_id = c.id " +
            "WHERE c.id = :id ORDER BY hb.bid_value DESC LIMIT 7;", nativeQuery = true)
    List<HistoryBidInterface> getBiggestHistoryBidByCarID(Long id);
}

启动微服务时抛出错误：

Caused by: java.lang.IllegalArgumentException: Not a managed type: class com.jdm.legends.common.dto.Car

尝试过使用@EntityScan、@ComponentScan注解，但问题仍未解决，请问该如何解决？

解决方案 #

以下是几个精准排查和解决的方向：

• 确保@EntityScan配置正确的包路径
  多数情况是注解的包范围未覆盖JAR中的实体类。需要在微服务的启动类上，明确指定JAR中实体类所在的包，同时保留本地实体包路径：

  @SpringBootApplication
  @EntityScan(basePackages = {"com.jdm.legends.common.dto", "你的本地实体类根包路径"})
  public class YourMicroserviceApplication {
      public static void main(String[] args) {
          SpringApplication.run(YourMicroserviceApplication.class, args);
      }
  }
  

• 检查JAR包的完整性与依赖引入

  1. 打开本地Maven仓库中的jdm-legends-commons-0.0.5.jar，确认com/jdm/legends/common/dto/Car.class文件存在；
  2. 若JAR为本地构建，检查其pom.xml配置，确保实体类未被打包规则排除。

• 对齐JPA相关依赖版本
  检查微服务与JAR包中JPA、Spring Data JPA的版本是否一致，版本差异可能导致@Entity注解无法被正确识别。优先使用Spring Boot的依赖管理统一版本。

• 验证实体类注解规范
  确认Car类的@Entity、@Table注解来自jakarta.persistence包（而非旧的javax.persistence），Spring Boot 3.x及以上版本默认采用Jakarta EE规范，旧javax注解会被忽略。

• 排查依赖冲突
  执行Maven命令查看依赖树，排查重复或冲突的JPA相关依赖：

  mvn dependency:tree
  

  若发现版本冲突，在微服务pom.xml中显式指定统一版本。

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