前言

作为互联网开发，你有没有过这样的经历：本地跑通的代码，一到测试环境就报 SQL 异常；明明 Mapper 文件里的字段和数据库对得上，却总提示 “列名无效”；甚至有时候，SQL 执行结果和预期差了十万八千里，盯着日志看半天也找不到问题在哪？

我前几天就遇到个同事小王，他调试一个 MyBatis 查询接口，卡了整整一下午。明明在 Navicat 里直接执行 SQL 能拿到数据，可通过代码调用就是返回空列表。最后我帮他看的时候发现，居然是因为他在 Mapper 的resultMap里，把column="user_id"写成了column="userId"—— 就因为一个大小写，白白耗了几小时。

其实不止小王，我接触过的 Java 后端开发里，至少有 70% 都在 MyBatis 调试上踩过坑。不是因为技术差，而是 MyBatis 的 “半自动化” 特性，让 SQL 和 Java 代码之间多了一层映射，一旦出问题，定位起来就像隔着一层雾。今天就用 “直接对话” 的方式，跟你聊聊怎么快速解决 MyBatis 调试的核心问题，帮你省下更多时间做更有价值的开发。

为什么 MyBatis 调试比普通 SQL 难？

在说解决方法前，咱们得先明白一个背景：MyBatis 调试难，根源不是你技术不行，而是它的 “工作流程” 藏了太多 “隐形操作”。

你平时在数据库工具里写 SQL，是 “写一句执行一句，报错直接看提示”，但 MyBatis 不一样，它要走 3 个关键步骤：

1. XML / 注解解析：MyBatis 会把你写在 Mapper.xml 里的 SQL（或者@Select注解里的 SQL）解析成 “可执行的 SQL 模板”，这个过程中会替换#{}占位符、处理if/foreach等动态标签；
2. 参数映射：它会把 Java 里的参数（比如User对象、Integer类型的id）转换成 SQL 能识别的格式，比如把LocalDateTime转成'2025-11-04 15:30:00'，把 List 转成(1,2,3)；
3. 结果映射：执行完 SQL 后，它还要把数据库返回的 “列名 - 值”（比如user_id:123）对应到 Java 对象的字段（比如userId:123）上，这个过程中还会处理关联查询、类型转换。

这三个步骤里，任何一个环节出问题，都会导致 “代码没报错，但结果不对”，或者 “报了错，但看不出在哪错”。比如动态 SQL 拼接错了、参数类型没匹配、结果映射字段不对应，这些问题在普通 SQL 调试里很少见，但在 MyBatis 里却是高频坑。

更麻烦的是，默认情况下 MyBatis 不会打印 “最终执行的 SQL”—— 你看到的日志里可能只有 “Preparing: SELECT * FROM user WHERE id = ?”，却看不到?到底被替换成了什么值，这就给定位问题增加了难度。

3 步解决 MyBatis 调试核心问题，亲测有效

针对上面说的这些痛点，我总结了一套 3 步调试法，不管是 “SQL 执行异常”“结果为空” 还是 “字段映射错”，都能快速定位。每个步骤都给你讲清楚 “怎么做”“为什么这么做”，你看完就能直接用。

第一步：先打印 “完整执行 SQL”，排除拼接和参数问题

90% 的 MyBatis 问题，其实都是 “SQL 拼接错了” 或者 “参数传错了”。比如你写了个动态 SQL：

<select id="getUser" resultType="User">
    SELECT * FROM user
    <where>
        <if test="id != null">AND id = #{id}</if>
        <if test="name != null">AND name = #{name}</if>
    </where>
</select>

本来想传id=1，结果不小心传成了id=null，这时候 SQL 就变成了 “SELECT * FROM user”，可能返回所有数据，也可能因为表数据多导致超时 —— 但如果没看到完整 SQL，你可能会以为是 “查询逻辑错了”，白费功夫。

所以第一步必须让 MyBatis 打印 “带真实参数的完整 SQL”，具体分 2 种场景配置：

场景 1：Spring Boot 项目（最常用）

直接在application.yml（或application.properties）里加 3 行配置：

mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 控制台打印SQL日志
logging:
  level:
    com.yourpackage.mapper: DEBUG  # 你的Mapper接口所在包，设为DEBUG级别

配置完重启项目，再执行接口，控制台会输出 3 类关键信息：

• Preparing: SELECT * FROM user WHERE id = ?（解析后的 SQL 模板）

• Parameters: 1(Integer)（传入的真实参数，?对应的具体值）

• Total: 1（查询返回的行数）

这时候你把 “SQL 模板” 里的?换成 “Parameters” 里的参数，就能得到 “最终执行的 SQL”，比如 “SELECT * FROM user WHERE id = 1”。把这句 SQL 复制到 Navicat、DBeaver 里执行，看能不能拿到正确结果：

• 如果执行报错：说明 SQL 本身有问题（比如表名错、字段名错），直接在数据库工具里改到能执行，再同步回 Mapper；

• 如果执行有结果，但代码返回空：说明问题在 “结果映射”，进入第二步；

• 如果执行没结果：说明参数传错了（比如传了id=100但数据库里没有），或者查询条件有问题，直接改参数逻辑就行。

场景 2：非 Spring Boot 项目（传统 SSM）

需要在mybatis-config.xml里配置日志实现：

<configuration>
    <settings>
        <!-- 配置日志输出，这里用Log4j2为例，也可以用StdOutImpl -->
        <setting name="logImpl" value="org.apache.ibatis.logging.log4j2.Log4j2Impl"/>
    </settings>
</configuration>

再在log4j2.xml里设置 Mapper 包的日志级别为 DEBUG，就能看到和 Spring Boot 一样的完整 SQL 日志。

第二步：用 “结果映射校验” 解决 “字段不匹配” 问题

如果完整 SQL 在数据库里执行有结果，但代码返回的User对象里，某些字段是null（比如userId是null，但数据库里user_id有值），那大概率是 “结果映射” 出了问题。

这种问题分 2 种情况，对应不同的解决方法：

情况 1：用resultType映射（简单查询）

如果你的 Mapper 里用的是resultType="
com.yourpackage.entity.User"，MyBatis 会默认 “按字段名大小写忽略匹配”—— 也就是说，数据库里的user_id会对应 Java 对象里的userId（驼峰命名），user_name对应userName。

但如果出现不匹配，比如数据库字段是userid（没有下划线），而 Java 对象是userId（有驼峰），这时候就会映射失败。解决方法有 2 个：

• 方法 A：在 SQL 里给字段起别名，比如SELECT userid AS userId, username AS userName FROM user；
• 方法 B：开启 MyBatis 的 “驼峰命名自动映射”，在配置文件里加一行：

mybatis:
  configuration:
    map-underscore-to-camel-case: true  # 下划线转驼峰，比如user_id→userId

开启后，只要数据库字段是 “下划线命名”，Java 对象是 “驼峰命名”，就能自动匹配，不用写别名。

情况 2：用resultMap映射（复杂查询，比如关联查询）

如果你的查询涉及多表关联，比如 “查用户的同时查他的订单”，会用resultMap手动配置映射关系：

<resultMap id="UserWithOrderMap" type="User">
    <id column="user_id" property="userId"/>  <!-- 主键映射 -->
    <result column="user_name" property="userName"/>  <!-- 普通字段映射 -->
    <!-- 关联订单列表 -->
    <collection property="orderList" ofType="Order">
        <id column="order_id" property="orderId"/>
        <result column="order_time" property="orderTime"/>
    </collection>
</resultMap>

这种情况下映射失败，90% 是因为column的值和 “完整 SQL 里的字段名” 不一致。比如你 SQL 里写的是o.id AS order_id，但resultMap里column写的是o_order_id，就会匹配不上。

解决方法很简单：拿第一步打印的 “完整 SQL” 去查数据库，看返回的 “列名” 到底是什么（比如用 Navicat 执行后看表头），再把resultMap里的column值改成和表头完全一致的名称（大小写也要注意，比如数据库是ORDER_ID，column就得写ORDER_ID）。

第三步：用 “断点调试” 定位动态 SQL 和逻辑问题

如果上面两步都没问题，但还是有问题（比如动态 SQL 没按预期拼接、参数被修改），就需要用 IDE 的断点调试，跟踪 MyBatis 的执行过程。这里以 IntelliJ IDEA 为例，教你 2 个关键断点位置：

断点 1：在 Mapper 接口方法上打断点

比如你的 Mapper 接口是UserMapper，方法是List<User> getUserList(UserQuery query);，直接在这个方法上点一下（行号左边出现红色圆点），然后 debug 运行。

当程序走到这个断点时，你可以先检查 “传入的参数query” 是不是正确的 —— 比如你想传name="张三"，结果query.getName()是null，那问题就出在 “调用 Mapper 之前的参数组装逻辑”，和 MyBatis 没关系。

断点 2：在 MyBatis 的MapperMethod类上打断点（进阶）

如果参数没问题，想跟踪 SQL 的拼接过程，可以在
org.apache.ibatis.binding.MapperMethod类的execute方法上打断点。这个方法是 MyBatis 执行 Mapper 方法的入口，在这里你能看到：

• sqlCommand：当前执行的 SQL 类型（SELECT/INSERT/UPDATE/DELETE）；
• param：最终传给 MyBatis 的参数对象；
• 执行到sqlSession.selectList(command.getName(), param)时，会进入 SQL 解析和执行流程。

如果还想更深入看动态 SQL 的拼接过程，可以在
org.apache.ibatis.scripting.xmltags.DynamicSqlSource类的getBoundSql方法上打断点 —— 这里会把你写的动态标签（if/foreach）解析成最终的 SQL 模板，你可以一步一步跟踪，看哪段动态逻辑没按预期执行（比如某个if条件本该成立却没成立）。

最后总结：记住 2 个原则，少踩 80% 的坑

今天跟你聊的 3 步调试法，其实核心就是 “把隐形的问题变显性”—— 通过打印完整 SQL，让 “拼接和参数问题” 显性化；通过校验结果映射，让 “字段匹配问题” 显性化；通过断点调试，让 “逻辑和解析问题” 显性化。

最后再给你 2 个原则，帮你少踩 MyBatis 的坑：

1. 写 SQL 时，先在数据库工具里跑通，再复制到 Mapper：很多人习惯直接在 Mapper 里写动态 SQL，写完就调用，出了问题不好定位。正确的做法是：先在 Navicat 里写好 “静态 SQL”（比如把foreach换成具体的(1,2,3)），跑通后再改成动态 SQL，这样能排除 “SQL 本身错误” 的干扰；
2. 遇到映射问题，先查 “数据库返回的列名”：别凭感觉猜列名，不管是resultType还是resultMap，column的值必须和 “数据库返回的列名” 完全一致（包括大小写）。第一步打印的完整 SQL，就是用来查这个列名的最好工具。

如果你今天用这个方法解决了之前卡了很久的 MyBatis 问题，欢迎在评论区分享你的经历；如果还有其他调试技巧，也可以留言告诉我 —— 技术分享就是这样，你一言我一语，大家才能一起进步。下次遇到 MyBatis 问题，别再瞎猜了，按这 3 步来，比同事快 10 倍定位问题！