MyBatisXML与注解混合使用教程

MyBatis 支持 XML 与注解混合配置，但绝非随意混搭——XML 具有绝对优先级，一旦接口方法在 XML 中定义了同名语句，对应注解将被完全忽略；成功混用的关键在于清晰划分职责边界：简单 CRUD 用注解（尤其是 `@SelectProvider` 处理轻量动态SQL），复杂多表、嵌套条件等强逻辑必须交由 XML 承担，同时严格确保 namespace 与接口全限定名一致、XML 路径正确加载、参数命名精准匹配，否则极易陷入“语句未找到”“值为 null”“修改不生效”等隐蔽陷阱——混用不是为了省事，而是用对的地方，让结构更清晰、维护更可控、性能更稳定。

MyBatis XML 和注解能混用吗？能，但得守规矩

能混用，但不是随便在同一个 Mapper 接口里一会儿写 @Select，一会儿又配 selectById 在 XML 里——MyBatis 会直接忽略注解，只认 XML。根本原因是：一旦为某个接口方法找到了对应的 XML 中的 <select id="xxx">，它就不再扫描该方法上的注解。

• XML 优先级高于注解，只要命名空间（namespace）+ 方法名匹配上，注解自动失效
• 想混用，得按「功能域」切分：比如通用 CRUD 用注解（@SelectProvider 或简单 @Select），动态 SQL 复杂逻辑（多表嵌套、条件分支多）全扔 XML
• 别在同一个模块里反复横跳——新人容易把 UserMapper.java 和 UserMapper.xml 同时改，结果 XML 没刷新、IDE 缓存没清，死活不生效

mybatis-config.xml 里怎么让 XML 和注解同时被扫到？

不用特别“开启”注解支持——只要用了 SqlSessionFactoryBean（Spring）或 SqlSessionFactoryBuilder（原生），注解默认就可用。真正要检查的是 XML 的加载路径和命名空间是否对齐。

• 里必须显式引入 XML 文件，例如：；光有接口类没用
• XML 的 namespace 必须严格等于接口全限定名，比如 namespace="com.example.mapper.UserMapper"，少个包名或大小写错，整个 XML 就白配
• Spring Boot 用户注意：mybatis.mapper-locations 配置项只管 XML 路径，不影响注解；注解靠 classpath 扫描，所以接口得在 @MapperScan 范围内

Mapper 接口方法签名和 XML 中的 id 不一致会怎样？

会报 Invalid bound statement (not found) 错误，而且这个错误不提示具体缺哪个，只说找不到 com.example.mapper.UserMapper.selectById —— 实际可能是拼写错、参数类型不匹配、甚至 XML 文件没被 Maven 打进 jar。

• 检查点顺序建议：先确认 XML 文件在 target/classes 下存在 → 再核对 namespace → 最后逐字比对 <select id="selectById"> 和接口方法名
• 参数名不一致也会触发该错误：XML 里用 #{id}，但接口是 selectById(@Param("uid") Long id)，那得写成 #{uid}，否则取不到值，还可能静默为 null
• Spring Boot + MyBatis 3.4.6+ 可开启 mybatis.configuration.use-generated-keys=true，但跟混用无关，别误以为开了就能绕过命名约束

为什么 @SelectProvider 写着写着就变慢了？

因为每次调用都会反射执行 provider 类里的方法生成 SQL 字符串，如果 provider 方法里做了 IO、循环拼接或未缓存 StringBuilder，性能损耗明显。它适合“SQL 结构固定、仅参数动态”的场景，不适合替代 XML 做复杂逻辑。

• 避免在 provideSql() 里查数据库、读配置文件、调远程服务
• 字符串拼接务必用 StringBuilder，别用 +；条件分支多时，提前 return，别堆满 if-else
• 如果发现 @SelectProvider 方法开始做 if (user.getRole() != null) sql.append(" AND role = #{role}") 这种事，说明该挪回 XML 了——XML 的 是预编译优化过的，更稳

混用本身不难，难的是边界感：XML 管结构，注解管简单即席查询，Provider 管轻量动态拼装。越想一把梭哈，越容易掉进命名冲突、缓存失效、调试黑盒的坑里。

今天关于《MyBatisXML与注解混合使用教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！