MyBatis 动态 SQL 中 ORA-00913 值过多报错的排查与规避

1. 这个报错到底在说什么

ORA-00913: 值过多，第一次看到这个提示的时候，很多人会下意识地去数SQL里VALUES后面到底跟了几个值，然后跟前面列的数量对一遍，发现“好像没错啊”。这个报错在Oracle+MyBatis的组合里出现，十有八九不是你真的多写了一个值，而是MyBatis在拼接SQL的时候，把你没打算传进去的东西也塞进去了。

先把结论摆在前面：这个错误的本质是SQL语句中某处“值的数量”超过了数据库期望的数量。在Oracle里，它最常出现在两个位置——INSERT语句的VALUES子句，以及SELECT语句的查询列表与UNION、子查询的列数不匹配。而在MyBatis场景下，绝大多数情况是第一种，并且根源往往藏在动态SQL标签、<foreach>循环、或者参数映射的细节里。

这篇文章面向的是正在用MyBatis操作Oracle、被这个报错卡住的开发者。不管你是刚接触MyBatis的新手，还是用了几年但一直没深究过动态SQL拼接机制的老手，我都会从报错的触发原理讲起，把常见的几种“值过多”场景一个个拆开，给出可以直接对照排查的方法，最后再分享几个我在实际项目里踩过的坑和总结出来的规避套路。看完之后，你应该能做到看到这个报错就知道往哪个方向查，而不是盲目地改SQL。

2. 报错背后的SQL拼接逻辑

2.1 Oracle为什么对“值的数量”这么敏感

Oracle在执行一条SQL之前，会先做语法解析和语义校验。对于INSERT INTO table (col1, col2) VALUES (v1, v2)这样的语句，数据库会严格比对括号里列的数量和值的数量，一旦不相等就直接抛出ORA-00913（值过多）或者ORA-00947（值太少）。这是硬性规则，没有商量余地。

关键在于，Oracle看到的SQL是MyBatis最终拼接完成的那条字符串，而不是你在Mapper XML里写的那个“看起来没问题”的模板。你在XML里写的动态标签、#{}占位符、<foreach>循环，经过MyBatis的解析引擎处理后，会变成一条完整的、带?占位符的PreparedStatement SQL。如果这个拼接过程中多出来一个逗号、一个多余的列、或者循环多跑了一次，Oracle看到的SQL就是错的。

举个最简单的例子。你写了一个插入语句：

<insert id="insertUser"> INSERT INTO user_info (id, name, age) VALUES (#{id}, #{name}, #{age}) </insert>

这条语句本身没问题。但如果你在age后面不小心多写了一个#{email}，而列清单里没有email，那就变成了3列对4个值，Oracle立刻报ORA-00913。这种情况肉眼容易发现，真正麻烦的是动态SQL拼接出来的“隐形多余值”。

2.2 MyBatis动态标签是怎么“偷偷”多加值的

MyBatis的动态SQL能力很强，<if>、<choose>、<foreach>、<trim>这些标签让SQL可以根据参数灵活变化。但灵活的另一面就是拼接结果不可控。我见过最多的场景是这样的：

<insert id="batchInsert"> INSERT INTO order_detail (order_id, product_id, quantity <if test="remark != null">, remark</if> ) VALUES <foreach collection="list" item="item" separator=","> (#{item.orderId}, #{item.productId}, #{item.quantity} <if test="item.remark != null">, #{item.remark}</if> ) </foreach> </insert>

这段代码的意图是：如果某条记录有备注就带上remark列，没有就不带。看起来逻辑没问题对吧？但问题在于，<if>判断的是当前循环项的remark，而列清单部分的<if>判断的是外层参数的remark。如果外层remark不为空（列清单里加了remark列），但某条循环项的remark为空（值列表里没加对应的值），那么这条记录的列数是4，值数却是3——这会导致ORA-00947（值太少）。反过来，如果外层remark为空但某个循环项有remark，就变成了列数3、值数4，直接触发ORA-00913。

这种“列和值分别判断”的写法是动态SQL里最经典的坑。正确的做法是让列清单和值列表使用完全一致的判断条件，或者干脆统一用<trim>标签来管理前后缀，避免手动拼接逗号带来的数量错位。

2.3 参数映射中的隐性多值问题

除了动态标签，还有一种情况容易被忽略：MyBatis的参数映射机制。当你传入一个Java对象作为参数时，MyBatis会通过反射读取属性值。如果Mapper接口的方法签名和XML里引用的属性名对不上，有时候不会直接报“找不到属性”，而是产生一些意料之外的行为。

比如你定义了一个UserDTO，里面有id、name、age三个字段，但XML里写的是#{userName}而不是#{name}。在某些MyBatis版本和配置下，这不会报错，而是把null塞进去，导致值的数量和预期不一致。更隐蔽的是，当你使用@Param注解或者Map作为参数时，属性引用的层级如果写错了，也可能导致MyBatis把整个对象当成一个值来处理，从而多出一个值。

还有一种情况是存储过程调用。Oracle的存储过程如果带有IN OUT参数，MyBatis在映射时可能会把同一个参数计算两次，导致值过多。这种问题在普通的增删改查里不常见，但一旦涉及存储过程调用，就需要特别留意参数的模式声明。

3. 五类高频场景逐一拆解

3.1 INSERT语句列与值不匹配

这是最直接的一类。表现就是INSERT INTO table (a, b, c) VALUES (?, ?, ?, ?)——四个问号对三列。排查方法很简单：把MyBatis打印出来的SQL复制到Oracle客户端里执行一遍，看看是不是真的多了一个值。

但难的是找到“为什么多了一个”。我总结下来主要有三个原因：

第一个原因是手写SQL时的笔误。比如复制粘贴了一行，忘了删掉末尾的逗号或者某个#{}。这种靠肉眼审查就能发现。

第二个原因是动态标签的<if>条件写反了。比如你写的是<if test="name != null">, name</if>，但实际传参时name是一个空字符串而不是null，条件成立，列清单里加了name，但值列表里可能因为另一个判断条件没加，导致数量对不上。

第三个原因是**<foreach>的separator用错了位置**。比如在批量插入时，separator应该放在每条记录的括号之间，而不是括号内部。如果放错了位置，就会在某个括号里多出一个逗号，Oracle解析时会把逗号后面的内容当成额外的值。

3.2 批量插入中foreach的陷阱

批量插入是ORA-00913的重灾区。我见过一个典型的错误写法：

<insert id="batchInsert"> INSERT INTO t_user (id, name, age) VALUES <foreach collection="list" item="item" separator=","> (#{item.id}, #{item.name}, #{item.age},) </foreach> </insert>

注意看，每个括号里最后多了一个逗号。这个逗号会让Oracle认为你试图插入四个值，但列只有三个，于是报ORA-00913。这种错误在代码格式化之后特别容易被忽略，因为逗号藏在括号里面，不仔细看根本发现不了。

正确的写法应该是：

<foreach collection="list" item="item" separator=","> (#{item.id}, #{item.name}, #{item.age}) </foreach>

另外，批量插入时还要注意Oracle对IN子句的参数数量限制。虽然这不会直接导致ORA-00913，但如果你的<foreach>用在IN条件里，参数过多时Oracle会报另一个错误。这个限制在Oracle 11g及以前是1000个，12c以后有所放宽，但实际项目中还是建议分批处理。

3.3 SELECT子查询列数不一致

ORA-00913不只在INSERT里出现。当你写SELECT语句时，如果主查询和子查询的列数不匹配，也会触发这个错误。比如：

SELECT id, name, age FROM user_info WHERE id IN (SELECT user_id, user_name FROM order_info)

这里子查询返回了两列，但IN只期望一列，Oracle就会报ORA-00913。在MyBatis里，这种错误通常是因为子查询的SELECT列表被动态标签影响了。比如你写了一个<sql>片段，本意是查一列，但某个<if>条件成立时多带了一列出来。

还有一种情况是UNION操作。UNION要求前后两个查询的列数完全一致，如果第一个查询有三列，第二个查询因为动态条件变成了四列，同样会报这个错。排查时重点看UNION两边的SELECT列表是否严格对齐。

3.4 存储过程与函数调用的参数错位

调用Oracle存储过程时，MyBatis的<select>标签需要指定statementType="CALLABLE"。如果参数映射写错了，比如把一个IN参数写成了OUT，或者参数的顺序和存储过程定义的不一致，就可能出现值过多的情况。

我遇到过一个案例：存储过程定义了三个IN参数和一个OUT参数，但MyBatis的XML里写了五个#{ }，多出来的那个是之前调试时留下的，忘了删。结果每次调用都报ORA-00913。这种问题的排查方法是：把存储过程的参数定义和XML里的参数列表并排放在一起，逐个核对数量和模式。

3.5 动态SQL中trim标签的误用

<trim>标签是MyBatis里处理前后缀的利器，但用不好也会导致值过多。比如：

<trim prefix="(" suffix=")" suffixOverrides=","> <if test="id != null">id,</if> <if test="name != null">name,</if> <if test="age != null">age,</if> </trim>

这段代码用于生成列清单，suffixOverrides=","会去掉末尾多余的逗号，看起来没问题。但如果值列表部分没有用同样的逻辑，而是手动写了逗号，就可能出现列清单有3列、值列表有4个值的情况。<trim>的正确用法是列清单和值列表成对出现，要么都用<trim>，要么都不用，不要混着来。

4. 一套可复用的排查流程

4.1 第一步：拿到最终执行的SQL

排查任何MyBatis的SQL错误，第一步永远是看到最终执行的SQL。MyBatis提供了日志功能，你可以在配置文件里把日志级别调到DEBUG：

logging: level: com.example.mapper: debug

或者在MyBatis的配置文件里：

<settings> <setting name="logImpl" value="STDOUT_LOGGING"/> </settings>

开启之后，控制台会打印出MyBatis拼接完成的SQL和对应的参数。把这条SQL复制出来，这是你排查的起点。

提示：如果日志里看到的是带?的PreparedStatement SQL，还需要把参数值手动填进去，或者在日志配置里开启参数打印。有些连接池或框架会拦截日志输出，导致看不到完整的SQL，这时候可以临时把日志级别调到TRACE。

4.2 第二步：在Oracle客户端里复现

拿到SQL之后，不要直接在代码里改，先把它放到Oracle客户端（比如SQL Developer或者命令行）里执行一遍。如果客户端里也报ORA-00913，说明SQL本身确实有问题，跟MyBatis的参数映射无关。如果客户端里能执行成功，那问题就出在MyBatis的参数传递或者类型处理上。

这一步能帮你快速区分“SQL写错了”和“参数传错了”两种情况，避免在错误的方向上浪费时间。

4.3 第三步：逐段注释动态标签

如果SQL在客户端里执行没问题，但MyBatis执行就报错，那基本可以确定是动态标签拼接的问题。这时候最有效的办法是逐段注释掉动态标签，看看注释到哪一段的时候错误消失。

具体操作是：先把所有的<if>、<foreach>、<trim>都注释掉，只保留最基本的SQL骨架，确认能执行。然后一个一个地把标签加回来，每加一个就执行一次，直到错误复现。这样就能精确定位到是哪个标签、哪个条件导致了值过多。

这个方法听起来笨，但实际用起来非常高效。我处理过的ORA-00913问题里，有八成都是靠这个方法在十分钟内定位到根源的。

4.4 第四步：核对参数数量与类型

定位到具体的标签之后，接下来要核对的是参数的数量和类型。重点看这几个地方：

• <foreach>的collection属性是否指向了正确的集合
• <if>的判断条件是否和实际传参一致
• #{}里的属性名是否和Java对象的字段名完全匹配
• 是否有多个参数但没有用@Param注解

特别是当Mapper接口有多个参数时，MyBatis默认会把它们命名为param1、param2或者arg0、arg1。如果你在XML里直接写#{name}，而接口方法没有用@Param("name")，MyBatis可能找不到对应的值，从而产生意料之外的行为。

5. 常见问题速查表

注意：这个表格里的“解决方案”都是治标的办法。真正要避免这个问题，还是要从写动态SQL的习惯入手，下面我会详细说。

6. 我踩过的坑和总结的经验

6.1 逗号位置比你想的更重要

刚用MyBatis那会儿，我总觉得逗号这种东西随便放放就行，反正SQL解析器能看懂。后来被ORA-00913教做人之后才明白，在动态SQL里，逗号的位置直接决定了值的数量。一个逗号放错地方，Oracle就会认为你多给了一个值。

我的习惯是：在写动态SQL时，永远用<trim>来管理逗号，不要手动在<if>里面写逗号。比如列清单这样写：

<trim prefix="(" suffix=")" suffixOverrides=","> <if test="id != null">id,</if> <if test="name != null">name,</if> <if test="age != null">age,</if> </trim>

值列表也这样写：

<trim prefix="VALUES (" suffix=")" suffixOverrides=","> <if test="id != null">#{id},</if> <if test="name != null">#{name},</if> <if test="age != null">#{age},</if> </trim>

这样列和值的判断条件完全一致，逗号由<trim>统一处理，不会出现数量错位。

6.2 批量插入时先验证单条

批量插入的SQL比单条插入复杂得多，一旦出错，排查起来也更麻烦。我的做法是：先用单条插入验证SQL逻辑，确认没问题之后再改成批量。单条插入能跑通，说明列和值的对应关系是对的，这时候再套<foreach>，出问题的概率就小很多。

另外，批量插入时建议在<foreach>外面包一层<trim>，用来处理整体SQL的前后缀。比如：

<insert id="batchInsert"> INSERT INTO t_user (id, name, age) <trim prefix="VALUES" suffixOverrides=","> <foreach collection="list" item="item" separator=","> (#{item.id}, #{item.name}, #{item.age}) </foreach> </trim> </insert>

这样即使<foreach>的separator出了问题，<trim>也能兜底去掉多余的逗号。

6.3 日志一定要开，但别一直开

MyBatis的SQL日志是排查问题的利器，但生产环境一直开着DEBUG级别会严重影响性能，日志量也大得吓人。我的建议是：开发和测试环境默认开启，生产环境按需开启。如果生产环境出了问题需要排查，可以通过动态调整日志级别的方式临时开启，排查完立刻关掉。

另外，有些团队会用MyBatis的拦截器或者插件来记录慢SQL，这个跟DEBUG日志是两回事。慢SQL日志记录的是执行时间超过阈值的SQL，而DEBUG日志记录的是所有SQL。排查ORA-00913这种语法错误，需要的是DEBUG日志。

6.4 参数命名要统一

MyBatis的参数映射有一个很容易被忽略的细节：当Mapper接口有多个参数时，MyBatis默认的参数名是param1、param2或者arg0、arg1。如果你在XML里写#{name}，但接口方法没有用@Param("name")注解，MyBatis可能找不到这个属性，从而产生一些奇怪的行为。

我的习惯是：只要Mapper接口的方法有多个参数，就给每个参数加@Param注解。这样XML里的#{}引用就永远有明确的对应关系，不会因为参数名的问题导致值过多或值太少。

@Insert("...") int insertUser(@Param("id") Long id, @Param("name") String name, @Param("age") Integer age);

6.5 用测试用例覆盖动态SQL的边界情况

动态SQL的问题往往在特定参数组合下才会暴露。比如某个<if>条件在参数为null时成立，在参数不为null时不成立，如果你只测了参数不为null的情况，就发现不了问题。

我的做法是：为每个动态SQL写至少三个测试用例——全参数、部分参数为null、全部参数为null。这样能覆盖大部分边界情况，提前发现列和值数量不一致的问题。虽然写测试用例花时间，但比起在生产环境排查ORA-00913，这点时间花得值。

7. 从根源上避免值过多

7.1 列清单和值列表必须同源

这是最核心的一条原则：列清单和值列表的判断条件必须来自同一个数据源。不要一个判断外层参数，一个判断循环项；不要一个用<if>，一个用<choose>。只有判断条件完全一致，才能保证列和值的数量永远匹配。

如果业务逻辑确实需要列和值分别判断，那就把判断逻辑抽成一个<sql>片段，两边都引用这个片段。这样修改的时候只需要改一处，不会出现两边不一致的情况。

7.2 优先用注解而不是XML

对于简单的增删改查，MyBatis的注解方式（@Insert、@Select等）比XML更直观，也更不容易出错。因为注解里的SQL是直接写在Java代码里的，没有动态标签的拼接过程，列和值的对应关系一目了然。

当然，复杂的动态SQL还是得用XML。但我的建议是：能用注解就用注解，注解搞不定的再用XML。这样能减少很多因为动态标签拼接导致的问题。

7.3 用代码生成器减少手写SQL

现在有很多MyBatis的代码生成器（比如MyBatis Generator），可以根据数据库表结构自动生成实体类、Mapper接口和XML文件。自动生成的SQL通常不会出现列和值数量不匹配的问题，因为它是根据表结构严格生成的。

如果你的项目里大量使用手写SQL，可以考虑引入代码生成器来处理基础的增删改查，把精力集中在复杂的业务查询上。这样既能减少ORA-00913这类低级错误，也能提高开发效率。

7.4 建立SQL审查清单

最后分享一个我们团队在用的SQL审查清单，每次提交涉及SQL的代码时，对照这个清单过一遍：

• 列清单和值列表的数量是否一致
• 动态标签的判断条件是否两边一致
• <foreach>的separator位置是否正确
• 批量插入的括号是否配对
• 子查询是否只返回一列
• UNION两边的列数是否一致
• 存储过程的参数数量和模式是否匹配

这个清单看起来简单，但能拦住大部分ORA-00913的问题。我们团队自从用了这个清单之后，这类报错的出现频率下降了八成以上。

8. 一个完整的排查实例

8.1 问题现场

某天下午，测试同学反馈说批量导入用户数据的功能报错了，错误信息就是java.sql.SQLSyntaxErrorException: ORA-00913: 值过多。这个功能之前一直是好的，最近改了一版代码，加了一个“备注”字段，然后就挂了。

8.2 排查过程

第一步，打开DEBUG日志，拿到最终执行的SQL。日志里显示的是：

INSERT INTO t_user (id, name, age, remark) VALUES (?, ?, ?, ?), (?, ?, ?, ?), (?, ?, ?)

注意看，前两条记录有四个问号，第三条记录只有三个问号。这就是问题所在——第三条记录的remark字段没有值，但列清单里有remark列，导致列数4、值数3。等等，列数4、值数3应该是ORA-00947（值太少）才对，为什么报的是ORA-00913（值过多）？

再仔细看，第三条记录的括号里是(?, ?, ?)，但列清单是四列。Oracle在解析时，会把整个VALUES子句当成一个整体来处理。当它发现前两条记录是四个值、第三条是三个值时，会以第一个括号里的值数量为基准，认为后面的括号“值过多”或者“值太少”。具体报哪个错，取决于Oracle的解析顺序。在这个案例里，它报的是ORA-00913。

8.3 根因定位

问题出在XML的写法上。原来的代码是这样的：

<insert id="batchInsert"> INSERT INTO t_user (id, name, age <if test="remark != null">, remark</if> ) VALUES <foreach collection="list" item="item" separator=","> (#{item.id}, #{item.name}, #{item.age} <if test="item.remark != null">, #{item.remark}</if> ) </foreach> </insert>

列清单的<if>判断的是外层参数remark，值列表的<if>判断的是循环项item.remark。当外层remark不为null时，列清单里加了remark列，但某条循环项的remark为null时，值列表里没加对应的值，导致数量不匹配。

8.4 修复方案

修复的方法很简单：把列清单的<if>判断也改成基于循环项，或者干脆去掉列清单的动态判断，让remark列始终存在，值列表里用#{item.remark}直接传值（null也没关系，Oracle会插入空值）。

最终的写法：

<insert id="batchInsert"> INSERT INTO t_user (id, name, age, remark) VALUES <foreach collection="list" item="item" separator=","> (#{item.id}, #{item.name}, #{item.age}, #{item.remark}) </foreach> </insert>

这样列清单固定四列，值列表固定四个值，不管remark是否为null，数量永远匹配。问题解决。

8.5 经验总结

这个案例给我的教训是：动态SQL里的“动态”要尽量少用。能用固定列解决的问题，就不要用<if>去动态增减列。因为每多一个动态判断，就多一个数量不匹配的风险点。如果确实需要动态列，那就确保列和值的判断条件完全一致，并且用<trim>来统一管理逗号。

另外，这个案例也说明了一个问题：ORA-00913和ORA-00947有时候会“互换”。你以为值太少会报ORA-00947，但Oracle可能报ORA-00913。所以排查的时候不要只盯着错误代码的字面意思，要看最终执行的SQL到底长什么样。

9. 几个容易忽略的细节

9.1 空字符串和null的区别

在Oracle里，空字符串''和null是等价的。但在MyBatis的<if>判断里，name != null和name != ''是两个不同的条件。如果传参时name是空字符串，name != null成立，但name != ''不成立。这个差异在动态SQL里可能导致列和值的数量不一致。

我的建议是：在<if>判断里同时判断null和空字符串，比如<if test="name != null and name != ''">。这样能避免因为空字符串导致的判断偏差。

9.2 基本类型和包装类型

如果Java对象的字段是基本类型（比如int、long），那它永远不可能为null，<if test="age != null">永远成立。这本身不是问题，但如果你期望某个字段为null时不参与SQL拼接，就要用包装类型（Integer、Long）。

这个细节在ORA-00913的排查里容易被忽略，因为问题往往出在“你以为某个字段为null，但实际上它不是null”这种情况上。

9.3 数据库字段的默认值

有些数据库字段有默认值，比如create_time默认SYSDATE。如果你在INSERT语句里不写这个字段，Oracle会自动填默认值。但如果你在列清单里写了这个字段，值列表里却没给值，就会报ORA-00913。

所以，列清单里只写你确实要传值的字段，不要把所有字段都列上去然后指望数据库填默认值。数据库的默认值只在字段不出现在INSERT语句里时才生效。

9.4 MyBatis版本差异

不同版本的MyBatis在处理动态SQL时有一些细微差异。比如某些版本对<foreach>的separator处理方式不同，某些版本对#{}和${}的解析顺序不同。如果你在网上搜到的解决方案在你这里不生效，可能是版本不匹配。

排查的时候，先确认你用的MyBatis版本，然后去官方文档或者GitHub的issue列表里搜一下，看看有没有相关的已知问题。

10. 写在最后

ORA-00913这个报错本身不复杂，复杂的是MyBatis动态SQL的拼接过程。你看到的XML和Oracle看到的SQL之间，隔着一层解析引擎，这层引擎会根据参数的不同生成不同的SQL。一旦参数组合超出了你测试过的范围，就可能出现列和值数量不匹配的情况。

我的核心建议就三条：列和值的判断条件保持一致，逗号交给<trim>管理，批量插入前先验证单条。做到这三点，大部分ORA-00913的问题都能避免。剩下的那些，靠DEBUG日志和逐段注释的方法，也能在十分钟内定位到根源。

最后再分享一个小技巧：如果你实在搞不定动态SQL的拼接，可以先把参数拼成一个完整的SQL字符串，用<select>标签的statementType="STATEMENT"方式执行（注意这种方式有SQL注入风险，只适合调试）。这样你能看到最终执行的SQL长什么样，排查起来会直观很多。调试完之后再改回正常的#{}方式。

这个内容后续还可以这样扩展：如果你用的是MyBatis-Plus，它提供了InsertBatchSomeColumn之类的批量插入方法，底层也是拼SQL，但封装得更好，出问题的概率更低。如果你的项目允许，可以考虑用MyBatis-Plus来替代手写批量插入的XML，能省不少心。