jpa 规范不支持直接在单个 jpql 或 criteria 查询中关联不同物理数据库中的实体，这是导致 “not an entity” 错误的根本原因；正确做法是分库查询后在应用层聚合，或借助数据库级联邦能力（如 oracle db link）。
jpa 规范不支持直接在单个 jpql 或 criteria 查询中关联不同物理数据库中的实体，这是导致 “not an entity” 错误的根本原因；正确做法是分库查询后在应用层聚合，或借助数据库级联邦能力（如 oracle db link）。
在 Spring Boot + JPA 的多数据源项目中，开发者常期望像单库那样通过 CriteriaBuilder 跨实体（甚至跨库）构建关联查询。但您遇到的 Not an entity 错误并非配置疏漏，而是 JPA/Hibernate 的
设计约束
：query.from(C.class) 仅在当前 EntityManager 关联的持久化单元（即对应一个数据库）内有效。当 S 和 C 分属不同数据源（如不同 @Primary 与 @Secondary 配置的数据源），Hibernate 无法将 C 识别为当前 EntityManager 的托管实体，因此抛出该异常。
❌ 错误示例解析
您的 SSpecification.isNameLike() 方法试图在 S 的查询中引入 C 作为 Root：
即使两个类都标注了 @Entity，只要它们未被声明在同一个 persistence-unit（或 Spring Boot 的同一 LocalContainerEntityManagerFactoryBean）中，JPA 就拒绝将其纳入同一 Criteria 查询树。
✅ 可行的解决方案
方案一：应用层两阶段查询（推荐，通用性强）
先查 C 获取匹配的 ID 列表，再用这些 ID 查询 S：
对应 Repository 接口：
✅ 优势：完全兼容任意数据库组合（MySQL + PostgreSQL、Oracle + SQL Server 等），无需数据库特殊功能。
⚠️ 注意：需处理空列表、N+1 查询风险（此处已规避）、事务隔离级别（若需强一致性，考虑 @Transactional(propagation = Propagation.REQUIRES_NEW) 分开管理）。
方案二：数据库联邦查询（限特定 DB，性能更优）
若底层数据库支持跨库逻辑视图（如 Oracle DB Link、PostgreSQL Foreign Data Wrapper、SQL Server Linked Server），可将远程表映射为本地“伪实体”，再用原生 SQL 查询：
✅ 优势：一次网络往返，减少应用层数据搬运。
⚠️ 注意：依赖数据库能力，增加运维复杂度；JPA 无法校验跨库字段，易因 DDL 变更引发运行时错误。
方案三：统一数据服务层（中长期架构建议）
对高频跨库关联场景，可引入轻量级数据聚合服务（如 Spring Cloud Stream + Kafka 做变更捕获，或物化视图同步），将 C 的关键字段冗余至 S 所在库，转为单库查询。
总结
核心原则
：JPA 是 ORM 框架，不是分布式查询引擎。跨物理数据库的 JOIN 必须由数据库层或应用层承担，而非 JPA Criteria。
优先选择方案一
：清晰、可控、可测试，符合 Spring Boot 多数据源最佳实践。
避免陷阱
：不要尝试通过 @Secondary 注解混用 EntityManager，或强行注册跨库实体——这违反 JPA 规范，会导致不可预测行为。
调试提示
：启用 logging.level.org.hibernate.SQL=DEBUG 和 logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE，可快速确认实际执行的 SQL 是否符合预期。
遵循上述路径，您不仅能解决当前报错，还能构建出健壮、可维护的多数据源业务逻辑。
Root cRoot = query.from(C.class); // ⚠️ 失败：C 不属于当前 EntityManager 的实体上下文 @Service
public class SService {
@Autowired private SRepository sRepo;
@Autowired private CRepository cRepo; // 对应 secondary 数据源
public List findSByCName(String nameQuery) {
// Step 1: 查询 C 表中 name 匹配的 id 列表
List cIds = cRepo.findIdsByNameLike("%" + nameQuery + "%");
// Step 2: 查询 S 表中 cId 在该列表中的记录
return sRepo.findByCIdIn(cIds);
}
} // CRepository.java（secondary 数据源）
public interface CRepository extends JpaRepository {
@Query("SELECT c.id FROM C c WHERE c.name LIKE %:name%")
List findIdsByNameLike(@Param("name") String name);
}
// SRepository.java（primary 数据源）
public interface SRepository extends JpaRepository {
List findByCIdIn(List cIds);
} @Repository
public class SRepositoryCustomImpl implements SRepositoryCustom {
@PersistenceContext(unitName = "primaryPU")
private EntityManager em;
@Override
public List findSByCNameViaDBLink(String nameQuery) {
String sql = """
SELECT s.* FROM s
INNER JOIN c@remote_db_link c ON s.c_id = c.id
WHERE c.name LIKE ?
""";
return em.createNativeQuery(sql, S.class)
.setParameter(1, "%" + nameQuery + "%")
.getResultList();
}
}