Resolving Duplicate Mapper Bean Warnings in Spring Boot 2.x with MyBatis‑Plus 3.4.1

Background

When using Spring Boot 2.x together with MyBatis‑Plus 3.4.1, the console prints many warn messages such as "Bean already defined with the same name" for XxxMapper , although the application still runs correctly.

2020-12-07 19:37:26.025  WARN 25756 --- [           main] o.m.s.mapper.ClassPathMapperScanner      : Skipping MapperFactoryBean with name 'roleMapper' and 'com.dunzung.java.spring.mapper.RoleMapper' mapperInterface. Bean already defined with the same name!

2020-12-07 19:37:26.025  WARN 25756 --- [           main] o.m.s.mapper.ClassPathMapperScanner      : Skipping MapperFactoryBean with name 'userMapper' and 'com.dunzung.java.spring.mapper.UserMapper' mapperInterface. Bean already defined with the same name!

These warnings do not affect program correctness but clutter the startup logs.

To eliminate them, the author investigated how MyBatis‑Plus initializes mapper objects.

Problem Analysis

Maven Dependencies

The project includes three MyBatis‑Plus related JARs:

mybatis-plus-boot-starter 3.4.1

mybatis-plus-extension 3.4.1

pagehelper-spring-boot-starter 1.2.10

The configuration classes for MyBatis‑Plus appear correct, so the issue is likely in the underlying libraries.

MyBatis‑Plus Configuration Class

@Configuration
@MapperScan(basePackages = "com.dunzung.**.mapper.**")
public class MybatisPlusConfiguration {
    @Bean
    public PaginationInterceptor paginationInterceptor() {
        PaginationInterceptor paginationInterceptor = new PaginationInterceptor();
        paginationInterceptor.setDbType(DbType.MYSQL);
        return paginationInterceptor;
    }
}

Service Class Definition

The custom service implementation extends MyBatis‑Plus's ServiceImpl and implements a generic MybatisService interface that extends IService :

/**
 * Custom Service interface base class
 */
public interface MybatisService
extends IService
{}

public interface RoleService extends MybatisService
{}

/**
 * Custom Service implementation base class
 */
public class MybatisServiceImpl
, T> extends ServiceImpl
implements MybatisService
{}

@Slf4j
@Service
public class RoleServiceImpl extends MybatisServiceImpl
implements RoleService {}

Mapper Interface

@Mapper
public interface RoleMapper extends DaoMapper
{}

Root Cause Investigation

Debugging shows that ClassPathMapperScanner logs the warning in its checkCandidate() method. The scanner is invoked twice during startup:

First, Spring Boot’s auto‑configuration registers a MapperScannerRegistrar via MybatisAutoConfiguration.AutoConfiguredMapperScannerRegistrar , which creates a ClassPathMapperScanner and calls doScan() .

Second, the MapperScannerConfigurer (brought in by MapperScans and @Import ) also creates a ClassPathMapperScanner and scans the same packages, causing the duplicate bean definition warning.

The duplication stems from inconsistent versions of the mybatis-spring library pulled in by two different dependencies:

mybatis-plus-extension depends on mybatis-spring 2.0.5 .

pagehelper-spring-boot-starter depends on mybatis-spring 1.3.2 .

Because the two versions register mapper scanners differently, the same mapper is scanned twice, triggering the warning.

Solution

Upgrade pagehelper-spring-boot-starter to version 1.3.0 , which aligns its mybatis-spring dependency with the version used by mybatis-plus-extension . After the upgrade, the duplicate warnings disappear.

Example Maven snippet for the corrected dependency:

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>1.3.0</version>
</dependency>

Conclusion

When upgrading open‑source frameworks, always verify the transitive dependency versions to avoid incompatibilities that can cause subtle issues such as duplicate bean registration. Consulting official upgrade guides or release notes helps prevent unnecessary trouble in production environments.