Spring Boot同名实体优先级配置：指定包实体覆盖其他包实体

当项目中存在同名@Entity类（如com.project.data.entity.User和com.project.data.domain.User），JPA会因实体名称唯一约束报错。由于Spring Boot通过@EntityScan扫描实体，ClassLoader层面的方案无法生效，以下是几种可行的解决方法：

方法一：精准扫描目标包，排除冲突包 #

如果只需要保留com.project.data.entity下的User，且冲突包没有其他需要扫描的实体，可以直接缩小@EntityScan的扫描范围：

@SpringBootApplication
@EnableJpaRepositories(basePackages = "com.project")
@EntityScan(basePackages = {"com.project.data.entity", "com.project.other.needed.packages"})
public class ProjectMain {
    public static void main(String[] args) {
        SpringApplication.run(ProjectMain.class, args);
    }
}

注：需手动列出所有包含需要扫描实体的包，避免遗漏其他业务实体。

方法二：使用excludeFilters排除特定冲突类 #

如果冲突包还有其他需要保留的实体，仅需排除其中的User类，可通过@EntityScan的excludeFilters精准过滤：

@SpringBootApplication
@EnableJpaRepositories(basePackages = "com.project")
@EntityScan(
    basePackages = "com.project",
    excludeFilters = @Filter(
        type = FilterType.ASSIGNABLE_TYPE,
        value = com.project.data.domain.User.class
    )
)
public class ProjectMain {
    public static void main(String[] args) {
        SpringApplication.run(ProjectMain.class, args);
    }
}

也可通过正则匹配类路径实现排除：

@Filter(
    type = FilterType.REGEX,
    pattern = "com\\.project\\.data\\.domain\\.User"
)

方法三：自定义过滤规则，优先保留指定包实体 #

如果需要更灵活的规则（如自动识别同名实体并优先保留指定包下的实例），可以自定义TypeFilter实现动态过滤：

1. 实现自定义过滤类 #

import jakarta.persistence.Entity;
import org.springframework.core.type.AnnotationMetadata;
import org.springframework.core.type.classreading.MetadataReader;
import org.springframework.core.type.classreading.MetadataReaderFactory;
import org.springframework.core.type.filter.TypeFilter;
import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider;
import org.springframework.core.type.filter.AnnotationTypeFilter;
import org.springframework.beans.factory.config.BeanDefinition;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;

public class PreferredEntityFilter implements TypeFilter {
    // 指定优先保留的包路径
    private final Set<String> preferredPackages = Set.of("com.project.data.entity");

    @Override
    public boolean match(MetadataReader metadataReader, MetadataReaderFactory metadataReaderFactory) throws IOException {
        String currentClassName = metadataReader.getClassMetadata().getClassName();
        AnnotationMetadata annotationMetadata = metadataReader.getAnnotationMetadata();

        // 仅处理@Entity注解的类
        if (!annotationMetadata.hasAnnotation(Entity.class.getName())) {
            return false;
        }

        // 获取实体名称（默认是类名）
        String entityName = (String) annotationMetadata.getAnnotationAttributes(Entity.class.getName())
                .getOrDefault("name", currentClassName.substring(currentClassName.lastIndexOf('.') + 1));

        // 查找所有同名的实体类
        List<String> sameNameEntities = findAllSameNameEntities(entityName, metadataReaderFactory);
        if (sameNameEntities.size() > 1) {
            // 如果当前类不在优先包中，则排除
            return !preferredPackages.stream().anyMatch(pkg -> currentClassName.startsWith(pkg));
        }

        // 无冲突或当前类在优先包中，不排除
        return false;
    }

    private List<String> findAllSameNameEntities(String entityName, MetadataReaderFactory readerFactory) throws IOException {
        ClassPathScanningCandidateComponentProvider scanner = new ClassPathScanningCandidateComponentProvider(false);
        scanner.addIncludeFilter(new AnnotationTypeFilter(Entity.class));
        Set<BeanDefinition> candidates = scanner.findCandidateComponents("com.project");

        List<String> result = new ArrayList<>();
        for (BeanDefinition bd : candidates) {
            String className = bd.getBeanClassName();
            MetadataReader reader = readerFactory.getMetadataReader(className);
            AnnotationMetadata annMeta = reader.getAnnotationMetadata();
            String name = (String) annMeta.getAnnotationAttributes(Entity.class.getName())
                    .getOrDefault("name", className.substring(className.lastIndexOf('.') + 1));

            if (entityName.equals(name)) {
                result.add(className);
            }
        }
        return result;
    }
}

2. 在@EntityScan中使用自定义过滤器 #

@SpringBootApplication
@EnableJpaRepositories(basePackages = "com.project")
@EntityScan(
    basePackages = "com.project",
    excludeFilters = @Filter(
        type = FilterType.CUSTOM,
        value = PreferredEntityFilter.class
    )
)
public class ProjectMain {
    public static void main(String[] args) {
        SpringApplication.run(ProjectMain.class, args);
    }
}

备选方案：修改冲突实体的名称 #

如果允许修改实体名称，可给冲突的User类指定唯一的实体名，避免冲突：

package com.project.data.domain;

import jakarta.persistence.Entity;

@Entity(name = "DomainUser")
public class User {
   // ...
}

此方法无需调整扫描规则，但会影响JPA查询时的实体引用（需使用DomainUser作为实体名）。

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