企业官网建设流程全解析

我记得第一次在项目里看到有人往 Mapper 接口里塞了六七个参数，心里就冒出一个念头：这段代码迟早要出问题。结果没过多久，同事就拿着一个BindingException的报错来找我，日志里写着Parameter 'name' not found. Available parameters are [arg1, arg0, param1, param2]。这种报错对刚接触 MyBatis 的人来说几乎是必经之路，而它的根子往往不在 SQL 写错，而在于传参方式没选对、没讲透。

这篇文章我想把 MyBatis Mapper 传递参数这件事从头到尾盘一遍。从单参数直接传、@Param注解、POJO 对象、Map、集合数组到混合传参，再把背后的参数解析链路翻出来看一眼，最后说清楚哪些坑我在生产环境里真实踩过。如果你是刚入门的 Java 开发，看完可以直接照着用；如果你已经写了两三年 MyBatis，我相信里面那些排查思路和选型规范也能给你一些参考。

1. 传参方式这么多，为什么值得单独梳理一篇

1.1 一个高频报错引出的核心问题

先看那个报错。方法签名长这样：

User findByNameAndPwd(String name, String pwd);

XML 里写的是：

<select id="findByNameAndPwd" resultType="User"> select * from t_user where name = #{name} and pwd = #{pwd} </select>

一运行，直接抛异常。原因很简单：Java 方法定义了两个参数，MyBatis 在解析#{name}时，并不知道name对应的是哪个参数。它只认自己构建出的参数映射，默认情况下你能用的 key 是arg0、arg1这种位置索引，或者param1、param2这种兼容别名。你写#{name}，它当然找不到。

这种问题之所以高频，本质上是因为 MyBatis 的传参有一套自己的约定，它不完全等同于 Java 方法的参数语义。你不主动告诉它"name 就是第一个参数"，它就只能按位置猜。猜不到，就报错。

1.2 传参方式直接影响代码的可维护性

有人可能会觉得，不就是传个参嘛，写法能有多大差别？在只有一两个参数的简单查询里，确实差别不大。可一旦进入真实业务，条件查询、批量操作、分页组合、复杂更新，这些场景对传参方式的要求就完全不一样了。

我见过一个项目，某个统计报表的 Mapper 方法签名字面是：

List<Map<String, Object>> queryReport(Map<String, Object> params);

写的时侯确实爽，啥条件都能往里塞。几个月后要加一个查询维度，接手的人打开 XML 一看，十几个<if test="xxx != null">，完全不知道哪些 key 是必需的、哪些是可选，更不知道这些 key 在什么时候被赋值。最后只能一层层往调用处追，追了半小时才定位到 Key 在某个 Service 里拼错了。Map 传参看起来灵活，但它的"灵活"是用可读性和类型安全换来的。

相反，如果一开始就把查询条件封装成一个 DTO 对象，参数名、类型、默认值全都有迹可循，后面即使换人维护，也只需要看一眼 DTO 的字段定义，就能把 XML 里的引用全部对应上。传参方式的选择，从来不只是"能不能跑通"的问题，而是"后续好不好维护"的问题。

1.3 面试里也常考，理解背后原理才算真会

传参方式还是 MyBatis 面试题里的常客。常见的问法是："MyBatis Mapper 接口有哪些传参方式？各有什么优缺点？"以及"不写@Param会怎么样？"。

这类问题其实是在考察两个层面：第一，面试者有没有写过足够多的 MyBatis 代码，对各种场景都有感知；第二，面试者有没有读过源码，理解参数解析的机制。只背答案的人通常会卡在"单参数为什么不写@Param也能跑通"上，因为这个问题光靠经验很难想明白，得看过ParamNameResolver和DefaultParameterHandler才能说清楚。所以这篇文章后面专门留了一节讲链路，帮大家把这层窗户纸捅破。

2. 六种传参姿势逐个拆解：用法与适用边界

2.1 单参数直接传：最简单的路径，但有两个隐藏规则

这是最省事的一种写法：

User findById(Long id);

<select id="findById" resultType="User"> select * from t_user where id = #{id} </select>

这里有两个新手不太清楚的规则。

第一，如果参数是简单类型（String、Integer、Long 等），#{}里写什么名字都能取到值。你可以写#{id}，也可以手滑写成#{abc}，运行都不会报错。因为 MyBatis 在绑定参数时发现 parameterObject 本身就有对应的 TypeHandler，就直接把这个对象当成了参数值，不会再拿花括号里的名字去反射。当然，我强烈建议你老老实实写语义化的名字，写#{abc}虽然能跑，但对读代码的人来说是一种精神污染。

第二，如果参数是一个普通 Java 对象，#{}里写的必须是它的属性名：

User insertUser(User user);

<insert id="insertUser"> insert into t_user (name, age, email) values (#{name}, #{age}, #{email}) </insert>

在这里，#{name}等价的不是"参数变量 user"，而是user.getName()。MyBatis 通过反射去读取这个属性。如果字段名拼错，比如写成#{nmae}，运行时会抛出常见的ReflectionException，告诉你没有这个属性。拼写错误能直接暴露，这反而是好事。

2.2 @Param 注解：多参数场景的主力方案

一旦方法里有多个参数，最规范的做法就是用@Param显式声明参数名：

User findByUsernameAndAge(@Param("username") String username, @Param("age") Integer age);

<select id="findByUsernameAndAge" resultType="User"> select * from t_user where username = #{username} and age = #{age} </select>

@Param是告诉 MyBatis：这个参数在 SQL 环境里的引用名是什么。加了注解之后，#{}里就只能用注解值，不能用 Java 方法里的变量名去期待它自动匹配，两者其实不一定同名，比如：

User findByUsername(@Param("name") String username);

只有#{name}有效，#{username}反而报错。所以这个注解相当于一种"重命名映射"。

为什么多参数必须用它？因为 MyBatis 对多参数有一个默认兜底机制，会生成param1、param2这类序列 key。你不用@Param也能通过#{param1}、#{param2}取到值，可用这种方法写出来的 SQL 毫无可读性，参数一多基本分不清谁是谁。显式@Param后，SQL 看着就像在用真实业务字段，可读性大幅提升。

2.3 POJO 对象传参：让参数有归属感

当参数超过三个，而且这些参数表达的是同一个业务概念时，就应该把它们封装成一个对象：

public class UserQuery { private String username; private Integer minAge; private Integer maxAge; private String email; // getter / setter }

List<User> searchUser(UserQuery query);

<select id="searchUser" resultType="User"> select * from t_user <where> <if test="username != null and username != ''"> and username like concat('%', #{username}, '%') </if> <if test="minAge != null"> and age &gt;= #{minAge} </if> <if test="maxAge != null"> and age &lt;= #{maxAge} </if> <if test="email != null"> and email = #{email} </if> </where> </select>

这种写法的最大优势是把散落的参数收拢成一个"查询上下文"。测试、复用、扩展都比散装参数方便。比如后期要加一个status筛选条件，只需要在UserQuery里加一个字段，再在 XML 里对应加一段<if>，调用方想传就传，不传也不会破坏现有逻辑。

它也有自己需要注意的点：第一，对象里的字段不要拆成两个用途，比如同一个字段既当过滤条件又当排序字段，会让 XML 的<if>逻辑变复杂；第二，传给 Mapper 的对象不要复用 Controller 层的 VO，因为接口语义随时可能变，Controller VO 是面向视图的，和持久层的查询条件往往不是一回事。

2.4 Map 传参：灵活是优点，失控是代价

Map 传参在 MyBatis 里同样很常见：

List<User> searchByMap(Map<String, Object> params);

<select id="searchByMap" resultType="User"> select * from t_user <where> <if test="username != null"> and username = #{username} </if> <if test="minAge != null"> and age &gt;= #{minAge} </if> </where> </select>

调用时：

Map<String, Object> params = new HashMap<>(); params.put("username", "张三"); params.put("minAge", 18); mapper.searchByMap(params);

Map 的好处在于，key 名和 XML 里的引用直接对应，几乎没有学习成本，动态查询要加条件时，也不用改动方法签名。这对于字段非常不固定的统计报表类需求尤其好用。

但它的问题我也在前面说过：key 拼错不报编译错误，只会在运行时得到错误结果；Map 里所有 value 都是 Object，根本没有类型约束，传错了类型（比如 Integer 传成 String）也是到了数据库层才可能暴露。这种"事事需要自律"的风格，在多人协作的中大型项目里很容易失控。我的建议是：Map 可以用于少数几个明确定位的场景（比如动态报表），但不要让它成为整个持久层的主流传参方式。

2.5 集合与数组传参：批量 SQL 的必经之路

批量查询或批量插入，最常见的写法是传入一个集合：

List<User> findByIds(@Param("ids") List<Long> ids);

<select id="findByIds" resultType="User"> select * from t_user where id in <foreach collection="ids" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>

用@Param("ids")后，foreach的collection属性就写ids，这个值是显式定义的，没有任何歧义。

如果你不打算写@Param：

List<User> findByIds(List<Long> ids);

那么foreach的collection有三种选择：list、collection或array。规则是这样的：

• 传入List实例时，MyBatis 会往参数 Map 中放入list和collection两个 key，所以collection="list"或collection="collection"都行；
• 传入数组时，放入的 key 是array，所以collection="array"；
• 传入Set等其他 Collection 子类时，只有collection可用。

这里有个很容易让人困惑的点：如果你传的是数组，却写成collection="list"，MyBatis 会直接报参数找不到。相反，传List却写collection="array"，也一样报错。批量场景里最常见的异常就是这一处名字写错。为了避免团队里各自猜，我建议统一用@Param显式定义集合名，别去依赖list、array这类默认 key。

2.6 混合传参：对象 + 基础参数的组合技巧

还有一些场景，既有一个查询条件对象，又需要分页参数、排序参数这类独立基础参数。这时可以把两者混搭：

List<User> searchWithPage( @Param("query") UserQuery query, @Param("offset") Integer offset, @Param("limit") Integer limit);

<select id="searchWithPage" resultType="User"> select * from t_user <where> <if test="query.username != null and query.username != ''"> and username = #{query.username} </if> <if test="query.minAge != null"> and age &gt;= #{query.minAge} </if> </where> limit #{offset}, #{limit} </select>

注意两个细节。

第一，访问对象里的属性时要写成#{query.username}，MyBatis 支持这种嵌套属性路径，它会自动调用query.getUsername()。<if>里的 test 同样可以写query.username != null。

第二，如果我把参数顺序打乱成：

List<User> searchWithPage( Integer offset, @Param("query") UserQuery query, Integer limit);

那 XML 里#{offset}和#{limit}还能不能直接用？可以，但有个前提——这些没有@Param的参数会被 MyBatis 按位置规则处理。因为方法里存在一个有@Param的参数，整个方法会走"命名参数"路线，没有@Param的参数依然会生成arg0、arg1、param2这类位置 key。如果 XML 里写#{offset}，抱歉，还是不行。这就引出一个非常重要的结论：想用语义化引用名，就得给每个参数都加@Param，不要混着写。最稳妥的方案是上面那种，所有参数全部加注解，谁也不依赖默认行为。

3. 揭开传参链路的面纱：ParamNameResolver 与 ParameterHandler 的协作

3.1 Mapper 接口调用到参数解析，中间发生了什么

面试官爱问，"MyBatis 底层是怎么把 Mapper 接口方法参数和 SQL 里的#{}关联起来的？"这个问题的答案藏在几个核心类里。

当你调用userMapper.findByUsernameAndAge("张三", 18)时，实际执行的链路是：

MapperProxy拦截方法调用，组装一个MapperMethod，然后由SqlSession调用对应的 executor。在MapperMethod内部，有一个重要步骤：用ParamNameResolver解析参数数组，得到一个"参数映射容器"。

ParamNameResolver做的事情可以理解为"翻译官"：

1. 遍历方法的所有参数位；
2. 如果某个参数标了@Param("xxx")，就把该位置的 key 记为xxx；
3. 如果没有标@Param，默认用位置名（比如arg0、arg1，也可能因编译参数配置而显示成真实参数名）；
4. 为了让旧版本兼容，它还会额外把param1、param2加入容器，指向同一批参数；
5. 如果只有一个参数且没有@Param，而且它又不是集合或数组，就直接返回这个参数对象本身，不去做包装。

所以前面的报错日志里会出现[arg1, arg0, param1, param2]这种列表，其实就是ParamNameResolver把能用的 key 都列出来给你看了。你写#{name}找不到，因为它只有name这个业务名之外的"位置名"。

3.2 单参数不写 @Param 为什么也能跑通

回到那个关键问题：单参数时，MyBatis 为什么不要求@Param？

因为ParamNameResolver的第三步明确写了一条规则：无注解且只有一个参数时，直接返回该参数对象本身，不包装成 Map。既然是对象本身，DefaultParameterHandler在处理#{}时有两条路径：

• 参数对象本身就是简单类型，并且注册过 TypeHandler，那直接用对象本身作为参数值；
• 参数对象是 POJO，通过MetaObject按属性路径去取字段值。

如果强制包装成 Map，反而会多一层 key 映射，单参数场景完全没有必要。这个设计是性能与易用性的折中，也解释了为什么#{value}、#{id}、#{anything}在单简单类型参数下都能取到同一个值。

但要注意，单参数场景也有例外。如果这个参数是个集合或数组，ParamNameResolver会额外包装一层，放入list、collection或array这些 key。这就是为什么foreach批量查询要区分list和array的根源。也就是说，单参数的"免注解"规则，对集合和数组并不完全适用。

3.3 ParameterHandler 与 typeHandler 的隐藏作用

参数映射容器构造好之后，SQL 最终还是需要设置到PreparedStatement上，这一步交给DefaultParameterHandler处理。它遍历BoundSql里每个ParameterMapping，按顺序处理占位符对应的值。

取值环节有一套优先级逻辑，我简化后是这样的：

1. 如果参数映射来自动态 SQL 的额外参数（比如foreach里的 item 变量），从BoundSql.additionalParameters中拿；
2. 如果参数对象本身为 null，value 直接置 null；
3. 如果参数对象类型能直接匹配某个 TypeHandler（常见于 String、数字这类简单类型），整个参数对象就是 value；
4. 否则，通过MetaObject反射从参数对象上取属性值。

取到 value 后，还需要把它塞进 JDBC 的PreparedStatement，这就是 TypeHandler 的职责。根据 value 的 Java 类型，MyBatis 会选择对应的 TypeHandler，比如StringTypeHandler、LongTypeHandler。如果 value 是 null，它会依据配置的jdbcTypeForNull来设置 JDBC 的 NULL 类型。

这节可能读起来偏理论，但它能解释很多实战问题。比如为什么Map里 key 写错结果会静默变成 null？因为MetaObject对一个不存在的 key 取不到值，返回 null 后 MyBatis 照样执行ps.setNull()，SQL 不会报错，只是查询条件变了。这类"不报错的异常"往往最难排查，理解了取值链路，排查方向就会清晰很多。

4. 踩坑实录：传参环节最常见的五类问题与排查链路

4.1 多参数没加 @Param：从报错信息反推可用参数

我在文章开头提到的报错，实际排查过程其实不难。假设你有如下代码：

List<User> findByNameAndEmail(String name, String email);

<select id="findByNameAndEmail" resultType="User"> select * from t_user where name = #{name} and email = #{email} </select>

报错是：

org.apache.ibatis.binding.BindingException: Parameter 'name' not found. Available parameters are [arg1, arg0, param1, param2]

翻译成人话就是：MyBatis 说"你要的name不在我手里的参数列表里，我能用的 key 是 arg1、arg0、param1、param2"。

正确的排查顺口溜是：报错里 Available parameters 列了哪些 key，就把#{}改成哪个 key，但同时要想办法把 key 稳定成业务名。最直接的修复是加注解：

List<User> findByNameAndEmail(@Param("name") String name, @Param("email") String email);

改完重启再试，问题消失。如果当时很急，临时用#{arg0}、#{arg1}也能跑通，但这种写法可读性太差，Java 编译器对参数名的处理结果也有可能随构建工具配置变化，今天能跑，换个环境可能又崩了。所以，@Param才是根治方案。

4.2 foreach 的 collection 写错：list、array、param1 的庐山真面目

这原本是一个很简单的需求，批量查询用户 ID 列表，方法签名：

List<User> findByIds(Long[] ids);

同事的 XML 写的是：

<foreach collection="list" item="id" ...>

结果报Parameter 'list' not found. Available parameters are [array, arg0, param1]。原因现在很好理解了：参数是数组，ParamNameResolver在单参数集合/数组场景只注入了array这个 key，list当然不存在。

排查这类问题，第一件事是看清楚调用方传的到底是数组还是List，再回来看 XML 的collection属性。这里最容易踩的坑是，接口定义里写了@Param("ids") List<Long> ids，但 XML 里foreach却沿用了之前某段代码的collection="list"，导致参数解析时ids存在、list不存在，报错和上一种情况几乎一模一样。

我建议，在代码评审阶段就统一规则：涉及集合、数组的 Mapper 方法参数，一律写@Param("xxx")，XML 的foreach里只写这个自定义名。直接废除list、collection、array三种默认写法在团队里的使用，一劳永逸。

4.3 插入 null 值时 JDBC 类型报错：jdbcType 与 null 参数的纠缠

这个坑和传参方式也有关系。几年前我在做用户信息导入时，遇到一个诡异的问题：批量插入用户，只要某个用户没有手机号（传入 null），就会抛类似：

JDBC exception on H2/MySQL ... Error setting null for parameter #3 with JdbcType OTHER

严格来说，这是参数绑定环节的典型问题。MyBatis 会为 null 值调用ps.setNull(parameterIndex, jdbcType)，而 JDBC 驱动在未知 JdbcType（默认 OTHER）下，部分数据库无法正确处理。

解决办法有两种：

第一种，在 SQL 的占位符上显式指定：

insert into t_user (name, phone) values (#{name}, #{phone, jdbcType=OTHER})

第二种，在 MyBatis 全局配置里把 null 值的默认 JDBC 类型改成允许的类型：

mybatis: configuration: jdbc-type-for-null: 'NULL'

这种问题在 MySQL 下通常不发作，但在 Oracle、PostgreSQL 某些驱动版本下很常见。排查时要记得看异常栈里是setNull还是setString，如果卡在setNull，八九不离十就是 JdbcType 的问题，跟传参方式是"Map 还是 POJO"没有直接关系。

4.4 Map 传参 key 写错：不报错的异常比报错更危险

有的坑会让你夜不能寐，因为它不报错，只是结果不对。Map 传参就是典型。

有一次同事做查询导出，方法：

List<ReportData> exportReport(Map<String, Object> params);

调用方写的 key 是userId，XML 里判断和引用的却是uid：

<if test="uid != null"> and user_id = #{uid} </if>

因为 Map 里确实没有uid这个 key，test 判断恒为 false，整个条件被跳过，SQL 变成全表查询。功能看起来"没坏"，数据却全错了。这类问题在报表、筛选条件很多的场景里尤其危险，因为老板一眼就能看出数字不对，但排查起来要翻 Service、XML、Map 的 put 逻辑三层。

如果说 POJO 传参拼错字段名会立即抛异常，Map 传参拼错 key 则倾向于"安静地失败"。这也是我不主张在核心业务里大量使用 Map 传参的最大原因。如果非要用 Map，至少让 XML 里引用的 key 统一集中在一个常量类里管理，而不是散落在 Service 层随手写的字符串里。

4.5 动态 SQL 判空失效：问题不一定出在传参方式

还有一种状况，参数传了，但<if>判断怎么都不进。很多人以为是传参方式不对，其实要分两种看。

第一种，多参数没加@Param，test 引用名和参数名对不上，导致判断恒 false。这个跟 4.1 是同一个根因，加@Param就好。

第二种，参数对象里的某个字段永远是 null，因为调用方根本没给它赋值。比如前端没传status，后端直接拿一个刚 new 出来的 DTO 去查询，status当然是 null，<if>不进入，SQL 条件就少了。这不是 MyBatis 传参方式能解决的，而是数据准备层的逻辑问题。排查时不要只盯着 Mapper 层，先确认调用方到底有没有把值塞进参数对象。

判断问题范围的技巧很简单：在 MyBatis 配置文件里打开日志（比如log-impl: org.apache.ibatis.logging.stdout.StdOutImpl），让 MyBatis 打印最终执行 SQL 和参数绑定日志。一眼就能看出传进去的参数是不是 null、参数个数对不对。排查传参问题，日志永远是最快的手段。

5. 项目实战中的选型建议与团队规范

5.1 按场景选型：一张表理清什么时候用哪种

写代码不是"哪个流行用哪个"，而是针对场景选合适的工具。我总结了下面这张表，基本覆盖日常开发里最常见的传参场景：

这里没有"银弹"方案。单参数场景非去封装一个 DTO，是过度设计；复杂查询场景硬拆散装参数，是自找麻烦。关键看参数之间的关联程度和变化频率。关联度高、变化频繁的条件，适合收敛成对象；关联低、独立性强的基础参数，用@Param单独传就行。

5.2 从散装参数到查询对象的演进思路

很多 P0/P1 项目都是从小接口起步的，一开始只有两三个查询条件，大家图省事全写在方法签名里。后来需求迭代，条件越加越多，方法签名变成一长串，各种@Param满天飞，XML 里 test 判断又臭又长。等到这一步，就该做查询对象重构了。

我推荐的做法是：新建一个XxxQuery类，把散装参数按业务维度收进去，同时加上默认值和校验注解。比如用户查询：

public class UserQuery { private String username; private Integer minAge; private Integer maxAge; private Integer status; private String orderColumn; private String orderDirection; // 构造、getter、setter }

重构成查询对象后，方法签名变成：

List<User> searchUser(UserQuery query);

XML 里的<if>判断跟着变得规整起来，每个字段对应一段独立判断。新增条件时只需要在 Query 类加字段、在 XML 加段落，不需要改动 Mapper 接口方法签名，也就不需要动调用方传入参数的形状。数据库索引也能根据这些条件做针对性优化。

这个过程我一般建议分成三步走：第一步，把散装参数在 Service 层组装成 Query 对象，XML 不动；第二步，把 Mapper 方法签名从多参数改为对象参数，同时把 XML 里的#{param}改成#{object.field}；第三步，清理掉不再使用的旧方法。每一步都能独立测试，降低重构风险。

5.3 我在团队里定的三条传参规约

在团队协作里，传参方式如果各写各的，代码评审时会很痛苦。我自己在项目里定过三条规约，简单务实：

第一，多参数方法必须全部加@Param，不允许出现"部分注解、部分不注解"的混搭。理由前面已经说过，混搭时会有一部分参数退回位置名，XML 里的引用名必然会乱。

第二，Repository/Mapper 层对外暴露的方法，参数类型优先是业务对象或基础简单类型，禁用裸 Map 作为公共核心方法入参。报表等少数动态场景可以例外，但要限定在独立的 Mapper 模块里，且 XML 里的 key 尽量集中定义，避免随手 put 字符串。

第三，批量方法的集合参数一律用@Param显式命名，XMLforeach的 collection 属性只写注解值。不依赖list/array/collection默认 key，从根源上消灭那类"Available parameters are [array, arg0, param1]"的报错。

这三条规约本身没有太高深的技术含量，但执行下来，我看到的效果是：MyBatis 相关的传参问题几乎只剩业务逻辑本身的问题，像"参数到底传没传""这个 key 从哪来的"这类无谓争论基本消失了。

回到文章开头那个BindingException，其实等到你把日志打开、把可用参数列表看清、再对照这几种传参方式一一排查，你会发现 MyBatis 传参并没有那么玄乎。它的规则无非是：单参数直接拿对象，多参数要么自己声明名字、要么接受位置名。真正影响项目质量的，不是能不能跑通，而是你选择哪种方式去承载那些会持续演变的业务参数。

最后分享一个小技巧：如果你用的是 Spring Boot，除了开启 MyBatis 日志，还可以在开发环境的application.yml里把 mapper 接口上下文的参数映射打印出来。配合StdOutImpl，每次 SQL 执行都会输出类似于==> Parameters: 张三(String), 18(Integer)的行，一眼能核对所有参数绑定顺序和值。排查传参问题时，这个输出比单纯看 SQL 文本有用得多。