SpringCloud集成Mybatis-Plus与Xstream时Bean定义冲突的解决方法

问题 #

项目集成SpringCloud Eureka与Mybatis-Plus后启动失败，抛出ConflictingBeanDefinitionException异常，具体栈信息如下：

org.springframework.context.annotation.ConflictingBeanDefinitionException: Annotation-specified bean name 'mapper' for bean class [com.thoughtworks.xstream.mapper.Mapper] conflicts with existing, non-compatible bean definition of same name and class [com.baomidou.mybatisplus.core.mapper.Mapper]
    at org.springframework.context.annotation.ClassPathBeanDefinitionScanner.checkCandidate(ClassPathBeanDefinitionScanner.java:349) ~[spring-context-5.3.18.jar:5.3.18]
    at org.mybatis.spring.mapper.ClassPathMapperScanner.checkCandidate(ClassPathMapperScanner.java:310) ~[mybatis-spring-2.0.6.jar:2.0.6]
    at org.springframework.context.annotation.ClassPathBeanDefinitionScanner.doScan(ClassPathBeanDefinitionScanner.java:287) ~[spring-context-5.3.18.jar:5.3.18]
    at org.mybatis.spring.mapper.ClassPathMapperScanner.doScan(ClassPathMapperScanner.java:204) ~[mybatis-spring-2.0.6.jar:2.0.6]
    at org.springframework.context.annotation.ClassPathBeanDefinitionScanner.scan(ClassPathBeanDefinitionScanner.java:254) ~[spring-context-5.3.18.jar:5.3.18]
    at org.mybatis.spring.mapper.MapperScannerConfigurer.postProcessBeanDefinitionRegistry(MapperScannerConfigurer.java:375) ~[mybatis-spring-2.0.6.jar:2.0.6]
    at io.choerodon.mybatis.spring.CommonMapperScannerConfigurer.postProcessBeanDefinitionRegistry(CommonMapperScannerConfigurer.java:79) ~[hzero-starter-mybatis-mapper-1.9.0.RELEASE.jar:1.9.0.RELEASE]
    at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanDefinitionRegistryPostProcessors(PostProcessorRegistrationDelegate.java:311) ~[spring-context-5.3.18.jar:5.3.18]
    at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:142) ~[spring-context-5.3.18.jar:5.3.18]
    at org.springframework.context.support.AbstractApplicationContext.invokeBeanFactoryPostProcessors(AbstractApplicationContext.java:746) ~[spring-context-5.3.18.jar:5.3.18]
    at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:564) ~[spring-context-5.3.18.jar:5.3.18]
    at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.5.12.jar:2.5.12]
    at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:775) [spring-boot-2.5.12.jar:2.5.12]
    at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:448) [spring-boot-2.5.12.jar:2.5.12]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:339) [spring-boot-2.5.12.jar:2.5.12]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1365) [spring-boot-2.5.12.jar:2.5.12]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1354) [spring-boot-2.5.12.jar:2.5.12]
    at com.anker.ipd.basis.IPDBasisApplication.main(IPDBasisApplication.java:23) [classes/:na]

已通过mvn dependency:tree排查依赖冲突，寻求解决方法。

解决方法 #

1. 精准限定Mapper扫描路径 #

异常核心原因是MyBatis的Mapper扫描器误扫到XStream的Mapper类，导致Bean命名冲突。需明确指定扫描范围：

• 注解配置：在启动类的@MapperScan中指定项目自身的Mapper包路径，如@MapperScan("com.anker.ipd.basis.mapper")，避免使用com这类宽泛根包。
• XML配置：在MapperScannerConfigurer中设置basePackage为项目Mapper所在的具体包。

2. 排除XStream冲突依赖 #

若项目无需XStream组件，通过mvn dependency:tree定位引入XStream的依赖，在Maven中排除该模块：

<dependency>
    <!-- 替换为实际引入XStream的依赖，比如SpringCloud Eureka相关依赖 -->
    <groupId>xxx</groupId>
    <artifactId>xxx</artifactId>
    <version>xxx</version>
    <exclusions>
        <exclusion>
            <groupId>com.thoughtworks.xstream</groupId>
            <artifactId>xstream</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 自定义Bean命名策略 #

修改MyBatis的Mapper扫描Bean命名规则，避免重名。自定义BeanNameGenerator给Mapper添加唯一前缀：

public class CustomMapperBeanNameGenerator extends DefaultBeanNameGenerator {
    @Override
    public String generateBeanName(BeanDefinition definition, BeanDefinitionRegistry registry) {
        return "mybatisMapper_" + super.generateBeanName(definition, registry);
    }
}

在@MapperScan中指定该生成器：@MapperScan(basePackages = "com.anker.ipd.basis.mapper", nameGenerator = CustomMapperBeanNameGenerator.class)

4. 调整依赖版本兼容性 #

检查XStream与MyBatis-Plus、MyBatis-Spring的版本匹配度，尝试升级或降级其中一方版本。例如升级MyBatis-Spring至更高版本，新版本可能优化了扫描逻辑，减少冲突概率。

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