mybatis sql映射文件以为根元素，必须配置与mapper接口全限定名一致的namespace，并为每个sql标签（如）设置唯一id；需在mybatis-config.xml的中显式注册，支持resource、package或class三种方式，解析后封装为mappedstatement存入configuration单例。
MyBatis 的 SQL 映射文件（即 Mapper.xml）是连接 Java 方法与数据库操作的核心载体，它的配置和解析过程直接影响 SQL 执行的准确性与灵活性。关键在于两件事：一是 XML 文件本身怎么写、怎么挂载；二是 MyBatis 启动时如何识别、加载并转换成可执行对象。
SQL 映射文件的基本结构与配置要点
每个映射文件必须以 <mapper></mapper> 为根元素，并声明 namespace，该值需与对应 Mapper 接口的全限定名一致（如 com.example.mapper.UserMapper），否则动态代理无法绑定方法。
-
命名空间（namespace）不可省略：它是 MyBatis 查找 SQL 语句的唯一标识前缀，比如调用
userMapper.selectById(1)，实际匹配的是namespace="com.example.mapper.UserMapper"下id="selectById"的<select></select>标签 -
SQL 标签需有唯一 id：每个
<select></select>、<insert></insert>等标签必须带id，且在当前 namespace 内不重复 -
参数与结果类型要明确：可用
parameterType指定入参类型（支持别名如int、map或类全名），用resultType（简单类型或 POJO）或resultMap（复杂映射）声明返回结构 -
推荐使用 resultMap 而非 resultType：尤其当列名与属性名不一致（如数据库用下划线
user_name，Java 用驼峰userName），可通过<result property="userName" column="user_name"></result>显式映射
映射文件如何被 MyBatis 加载与注册
映射文件不会自动生效，必须在主配置文件 mybatis-config.xml 的 <mappers></mappers> 节点中显式引入。支持三种方式：
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
-
按资源路径引入：
<mapper resource="mapper/UserMapper.xml"></mapper>，路径基于 classpath，适用于单个文件管理 -
按包扫描注册：
<package name="com.example.mapper"></package>，要求接口与 XML 同名同包（如UserMapper.java和UserMapper.xml），MyBatis 会自动加载所有匹配文件 -
按类接口引入：
<mapper class="com.example.mapper.UserMapper"></mapper>，适合纯注解开发，但若同时存在同名 XML，仍会优先加载 XML 内容
加载过程由 XMLConfigBuilder 完成，在构建 SqlSessionFactory 阶段解析 <mappers></mappers>，将每个 SQL 片段封装为 MappedStatement 对象，存入全局 Configuration 单例中——后续执行时直接根据 namespace + id 查找，无需重复解析。
常见配置陷阱与验证建议
很多运行时错误（如 Invalid bound statement）都源于映射文件未正确加载或命名不匹配。排查时注意：
- 检查 XML 文件是否在编译后出现在
target/classes（Maven 项目）或输出目录中；若放在src/main/java下，需确认 IDE 或构建工具已将其纳入资源拷贝范围 - 确保
namespace与接口类名完全一致，包括大小写和包路径；接口中方法名必须与 XML 中id完全相同 - 使用
<where></where>、<set></set>等动态标签时，避免手写 SQL 拼接逻辑；它们会自动处理前置 AND/OR 或逗号，但前提是标签内至少有一个条件为 true - 启用 MyBatis 日志（如 log4j 配置
org.apache.ibatis=DEBUG），可看到每条 SQL 如何被解析、参数如何绑定、结果如何映射，是调试映射问题最直接的方式
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
