导入org.apache.ibatis.annotations.Mapper语句报错，@Mapper注解无法正常使用

核心原因梳理 #

• 版本适配问题
  org.apache.ibatis.annotations.Mapper注解是MyBatis 3.0及以上版本才新增的注解，若项目引入的MyBatis版本低于3.0，单独导入该类会直接抛出编译报错。使用通配符import org.apache.ibatis.annotations.*;时编译器不会显式抛出未找到类的错误，但注解本身不存在，自然无法生效。
• 依赖冲突问题
  项目中如果同时引入了多个不同版本的MyBatis依赖，或引入了MyBatis-Plus等二次封装的MyBatis相关依赖，会导致类路径下的@Mapper注解类加载冲突，出现单独导入报错、通配符导入后注解不生效的问题。
• SpringBoot场景下的依赖缺失
  如果是SpringBoot整合MyBatis的项目，仅引入原生MyBatis依赖无法让Spring容器识别@Mapper注解，必须引入mybatis-spring-boot-starter适配依赖，注解才能正常被扫描加载。

修复方案 #

1. 检查pom.xml（Maven）或build.gradle（Gradle）中的MyBatis版本，将版本升级至3.0及以上稳定版本，示例Maven配置如下：

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.13</version>
</dependency>

2. 排查依赖冲突：执行Maven命令mvn dependency:tree或Gradle命令gradle dependencies，排查所有MyBatis相关依赖，排除多余的低版本依赖。
3. SpringBoot项目额外引入适配依赖：

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>2.3.1</version>
</dependency>

同时可在启动类上添加@MapperScan("你的Mapper接口所在包全路径")注解，强制扫描所有Mapper接口，避免注解失效。
4. 若依赖配置确认无误仍有报错，可清理IDE缓存后重启项目，IDEA操作路径为：File -> Invalidate Caches -> 勾选对应清理选项后重启。

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