Spring MVC 4迁移至Spring MVC 6启动报错：MyBatis Mapper配置异常

迁移Spring MVC 4到Spring MVC 6时启动报错，无法确定是Mapper XML路径配置还是MapperConfig.xml内容问题，错误信息如下：

06-Sep-2024 16:01:21.184 SEVERE [main] org.apache.catalina.core.StandardContext.listenerStart Exception sending context initialized event to listener instance of class [org.springframework.web.context.ContextLoaderListener]
    org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'AuthService': Unsatisfied dependency expressed through field 'personMapper': Error creating bean with name 'personMapper' defined in file [C:\Program Files\Apache Software Foundation\Tomcat 10.1\webapps\codereaper\WEB-INF\classes\com\empirestateids\dao\PersonMapper.class]: Unsatisfied dependency expressed through bean property 'sqlSessionFactory': Error creating bean with name 'sqlSessionFactory' defined in class path resource [atlas-dao-context.xml]: Failed to parse config resource: class path resource [MapperConfig.xml]

当前配置内容 #

atlas-dao-context.xml中的Bean定义（JNDI配置成功，sqlSessionFactory创建失败） #

<bean id="dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="java:comp/env/jdbc/CodereaperDB"/>
</bean>

<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <property name="mapperLocations" value="classpath:/mapper/*.xml" />
    <property name="configLocation" value="classpath:MapperConfig.xml" />
</bean>

<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource" />
</bean>

<tx:annotation-driven transaction-manager="transactionManager" />

<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate">
    <constructor-arg index="0" ref="sqlSessionFactory" />
</bean> 
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="com.empirestateids.dao" />
</bean>  

MapperConfig.xml内容 #

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd" >
<configuration >

  <mappers >
    <mapper resource="mapper/UsersMapper.xml" />
    <mapper resource="mapper/GroupMemberMapper.xml" />
    <mapper resource="mapper/PhoneMapper.xml" />
    <mapper resource="mapper/PersonMapper.xml" />
    <mapper resource="mapper/RegistrationMapper.xml" />
    <mapper resource="mapper/AddressMapper.xml" />
    <mapper resource="mapper/LookupMapper.xml" />
    <mapper resource="mapper/LoincMapper.xml" />
    <mapper resource="mapper/ContactMapper.xml" />
    <mapper resource="mapper/PersonMapper.xml" />
    <mapper resource="mapper/EmailMapper.xml" />
    <mapper resource="mapper/GroupAuthorityMapper.xml" />
    <mapper resource="mapper/GroupsMapper.xml" />
    <mapper resource="mapper/PersistentLoginsMapper.xml" />
    <mapper resource="mapper/UsersMapper.xml" />
    <mapper resource="mapper/IpowerliftIdMapper.xml" />
    <mapper resource="mapper/ProductListMapper.xml" />
    <mapper resource="mapper/PaypalEnvMapper.xml" />
    <mapper resource="mapper/LoincMapper.xml" />
    <mapper resource="mapper/CvxCatalogsMapper.xml" />
    <mapper resource="mapper/CvxCataAttributesMapper.xml" />
    <mapper resource="mapper/CvxParentMapper.xml" />
    <mapper resource="mapper/GroupMemberMapper.xml" />
    <mapper resource="mapper/Icd10Mapper.xml" />
    <mapper resource="mapper/Icd11Mapper.xml" />
    <mapper resource="mapper/RxNormCodesMapper.xml" />
    <mapper resource="mapper/SnomedEntityMapper.xml" />
  </mappers>
</configuration>

XML映射文件位于类路径下的mapper目录中。

问题分析与解决步骤 #

核心问题 #

错误栈明确指向Failed to parse config resource: class path resource [MapperConfig.xml]，说明MyBatis解析MapperConfig.xml时失败，主要原因集中在以下几点：

1. 重复注册Mapper：MapperConfig.xml中存在大量重复的<mapper>标签（比如PersonMapper.xml、UsersMapper.xml等重复出现），适配Spring 6的新版本MyBatis对重复注册的兼容性更严格，会导致解析失败。
2. Mapper注册方式冲突：sqlSessionFactory中配置了mapperLocations自动扫描所有mapper文件，同时MapperConfig.xml又手动注册所有mapper，两种方式重复触发解析，引发冲突。
3. 依赖版本不兼容：Spring MVC 6对应Spring 6框架，需要搭配兼容版本的MyBatis和MyBatis-Spring，旧版本依赖会导致配置解析失败。
4. DTD地址协议问题：MapperConfig.xml中使用的HTTP协议DTD地址，部分环境下可能无法访问或被拦截，导致XML解析失败。

解决步骤 #

1. 清理重复的Mapper注册

删除MapperConfig.xml中所有重复的<mapper>标签，保留每个Mapper文件仅一次注册，比如删除重复的PersonMapper.xml、UsersMapper.xml等条目。

2. 统一Mapper注册方式

选择以下两种方式之一，避免冲突：

• 方式一：保留自动扫描（推荐）
  删除MapperConfig.xml中的<mappers>节点，仅保留sqlSessionFactory中的mapperLocations配置，让MyBatis自动扫描类路径下mapper目录的所有XML文件。
• 方式二：保留手动注册
  删除sqlSessionFactory中的mapperLocations配置，仅通过MapperConfig.xml的<mappers>节点手动注册所有Mapper文件。

3. 确保依赖版本兼容

更新pom.xml（或gradle配置）中的MyBatis及MyBatis-Spring版本，适配Spring 6：

<!-- MyBatis -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.15</version>
</dependency>
<!-- MyBatis-Spring -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>3.0.3</version>
</dependency>

4. 修正DTD地址协议

将MapperConfig.xml中的DTD地址改为HTTPS协议，避免HTTP访问问题：

<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "https://mybatis.org/dtd/mybatis-3-config.dtd">

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