企业官网建设流程全解析

最近又有人在群里问 MyBatis 的@Result注解：说想在用户列表里嵌套查询每个用户的订单，结果子查询老是拿不到参数，要么是 null，要么直接报Parameter 'xxx' not found。其实这个问题十有八九出在column参数的传递时机和写法上。很多人只记住了@Result(column="xxx", property="yyy")是列映射，却没搞懂一旦配合@One/@Many做子查询，column的值会被原封不动地拿去做子查询方法的入参。今天就把这个点彻底讲透，包括单列传递、多列传递、参数名匹配，以及那些我实际踩过的坑。

这个知识点最典型的应用场景就是：主查询返回一批用户，需要额外加载每个用户的订单列表；或者主查询返回订单，需要关联查询下单用户的信息。用注解方式写@Results+@Many/@One是最常见的做法。适合正在用 MyBatis 注解开发、对 resultMap 和嵌套查询一知半解的开发者，也适合被column传参坑过、想搞清底层逻辑的同学。

1. 先搞懂@Result里column的双重身份

1.1 列名到属性的映射：column 的第一层作用

@Result最普通的用法是：

@Results(value = { @Result(id = true, column = "id", property = "id"), @Result(column = "username", property = "username") }) @Select("SELECT id, username FROM user WHERE id = #{id}") User findUser(Long id);

这里的column="id"、column="username"负责把查询结果集里的列名，映射到实体类User的id、username属性上。它和 XML 里<resultMap>的<result column="id" property="id"/>是完全等价的。这个阶段，column只关心“查询结果集里的哪一列”，和 Java 方法参数没有任何关系。

很多人在这一步没什么问题，真正迷糊的是下面这种写法。

1.2 嵌套查询时 column 从“列映射”变成了“参数源”

当@Result里同时出现many = @Many(select = "...")或one = @One(select = "...")时，column的含义就变了：

@Results(value = { @Result(id = true, column = "id", property = "id"), @Result(column = "username", property = "username"), @Result(property = "orders", column = "id", many = @Many(select = "com.example.mapper.OrderMapper.selectByUserId")) }) @Select("SELECT id, username FROM user WHERE id = #{id}") User findUserWithOrders(Long id);

此时column="id"不再是简单地把id列映射到orders属性上（orders是List<Order>，也不可能做普通映射）。MyBatis 会把它解析成：从父查询的结果集中取出id这一列的值，作为参数传给com.example.mapper.OrderMapper.selectByUserId这个方法。

这就像是主查询拿到一行数据后，抽出其中一个字段，转身塞给了另一个查询方法。property只是告诉你“查出来的结果要装到哪个属性里”，真正决定子查询怎么拿参数的，是column。

1.3 为什么 column 里写的是列名，不是主查询的方法参数

这是一个特别容易混淆的点。很多人会误以为column可以把父查询方法的入参传给子查询，例如：

User findUserWithOrders(@Param("id") Long id);

然后想当然地在@Result里写column="id"。如果父查询的表里恰好也有id字段，那没问题；但如果你传入的id和查询结果集里的id不是同一个东西，就会出问题。column引用的永远是“SQL 查询结果集中的列名”或“别名”，而不是 Java 方法的参数名。

如果你确实想把父查询方法的某个入参传给子查询，正确做法是让这个入参出现在父查询的结果集里，比如：

@Select("SELECT #{id} AS user_id, username FROM user WHERE id = #{id}") @Results(value = { @Result(column = "user_id", property = "userId"), @Result(property = "orders", column = "user_id", many = @Many(select = "...")) }) User findUserWithOrders(@Param("id") Long id);

这里#{id}会先被替换成 SQL 参数，查询返回时给它起个别名user_id，然后column="user_id"才能把这个值传给子查询。这是很多老手也容易绕进去的细节，记住“先成为结果集的一列，才能被 column 引用”。

2. 单列传递：最常用也最容易想当然的写法

2.1 一个“用户-订单”的实际场景

先看一个完整的最小示例。假设有两张表：

• user：id、username
• order：id、user_id、amount

实体类：

public class User { private Long id; private String username; private List<Order> orders; } public class Order { private Long id; private Long userId; private BigDecimal amount; }

需求很简单：根据用户 id 查用户信息，同时把该用户的所有订单查出来。

Mapper 接口：

public interface UserMapper { @Select("SELECT id, username FROM user WHERE id = #{id}") @Results(id = "userResult", value = { @Result(id = true, column = "id", property = "id"), @Result(column = "username", property = "username"), @Result(property = "orders", column = "id", many = @Many(select = "com.example.mapper.OrderMapper.selectByUserId")) }) User findUserWithOrders(Long id); } public interface OrderMapper { @Select("SELECT id, user_id, amount FROM `order` WHERE user_id = #{userId}") List<Order> selectByUserId(Long userId); }

findUserWithOrders执行后，MyBatis 先执行SELECT id, username FROM user WHERE id = #{id}，拿到一行 User 数据。随后发现orders属性配置了@Many，于是取出这一行id列的值，把它作为参数去调用selectByUserId。

执行日志会有两条 SQL：

==> Preparing: SELECT id, username FROM user WHERE id = ? ==> Parameters: 1(Long) <== Columns: id, username <== Row: 1, test_user ====> Preparing: SELECT id, user_id, amount FROM `order` WHERE user_id = ? ====> Parameters: 1(Long) <== Total: 3

这里selectByUserId的列user_id和传入的id列名不同，但没关系，MyBatis 是按“值”传递的，不是按“列名”匹配的。子查询方法里的参数名userId实际上不影响传值过程，因为单参数的情况下，MyBatis 只要有一个值，就能调用这个方法。

2.2 子查询方法的参数签名怎么配合

单列传递时，子查询方法最推荐写成单个参数，省心：

List<Order> selectByUserId(Long userId);

也可以写成@Param形式：

List<Order> selectByUserId(@Param("userId") Long userId);

都没问题。真正需要注意的是：不要写成这样：

List<Order> selectByUserId(Long userId, String flag);

为什么？因为父查询只传了一个值过来，MyBatis 尝试调用两个参数的方法，没有@Param时它没法把唯一的值塞进userId和flag两个坑位，会直接抛BindingException。就算你用了@Param("userId") Long userId, @Param("flag") String flag，父查询传一个值也匹配不上两个参数。除非用多列传递，也就是下一节的主角。

2.3 单列传递时的隐式规则

实测下来，单列传递有几个隐含规则值得记一下：

• 父查询中的列值如果为null，子查询依然会执行，只是传入的参数为null。如果你的子查询 SQL 是WHERE user_id = #{userId}，参数为 null 时查不到数据，但不会报错。只有当 SQL 里写了#{userId, jdbcType=OTHER}等特殊写法时，才可能出现类型转换异常。
• 子查询方法的返回类型如果是List，用@Many；如果是单个对象，用@One。column的传递机制一样，没有区别。
• 同一个@Results可以被多个查询方法复用，通过@ResultMap("userResult")引用。但如果某个查询方法查询的列结构变了，column指向的列名可能就不存在了，复用时要格外小心。

3. 多列传递：用{key=column}告别参数缺失

3.1 业务场景：子查询需要两个以上条件

单列传递应付不了复杂子查询。举个例子：订单表里冗余了一个用户等级字段user_level，需求是查出用户列表，同时查出该用户下“用户等级匹配”的订单（比如订单上的 user_level 必须和 user 表的 level 一致）。

父查询：

@Select("SELECT id, username, level FROM user WHERE id = #{id}")

子查询要接收两个值：用户 ID 和用户等级。SQL 大致是：

SELECT * FROM `order` WHERE user_id = #{userId} AND user_level = #{userLevel}

这你就没法用column="id"一笔带过了。MyBatis 官方提供了一种特殊写法，在column中使用花括号包起来：

@Result(property = "orders", column = "{userId=id, userLevel=level}", many = @Many(select = "com.example.mapper.OrderMapper.selectByUserIdAndLevel"))

3.2{userId=id, userLevel=level}到底怎么读

这个字符串的格式是：

{子查询参数名 = 父查询列名, 子查询参数名 = 父查询列名, ...}

注意等号两边的含义：

• 等号左边是子查询方法中参数的名称（对应@Param的值，或 Map 的 key）
• 等号右边是父查询结果集中的列名或别名

所以{userId=id, userLevel=level}意思是：从父查询结果集中取出id列的值，命名为userId；再取出level列的值，命名为userLevel。然后 MyBatis 会把这两个值组装成一个参数集合传给子查询方法。

对应子查询 Mapper：

@Select("SELECT id, user_id, user_level, amount FROM `order` " + "WHERE user_id = #{userId} AND user_level = #{userLevel}") List<Order> selectByUserIdAndLevel(@Param("userId") Long userId, @Param("userLevel") Integer userLevel);

注意@Param里的名字必须和{}左边保持一致。如果写成了@Param("id")，MyBatis 就会拿着userId去参数映射表里找，找不到就报：

Parameter 'userId' not found. Available parameters are [userLevel, userId, param1, param2]

这个报错信息很有用，它会把你实际可用的参数名列出来。严格来说，@Param不写也能应对很多情况，但为了稳妥，我建议多参数一律写上@Param，省得和编译参数名解析打架。

3.3 子查询方法接收参数的三种方式

第一种是标准的@Param：

List<Order> selectByUserIdAndLevel(@Param("userId") Long userId, @Param("userLevel") Integer userLevel);

第二种是用Map接收：

@Select("SELECT id, user_id, user_level, amount FROM `order` " + "WHERE user_id = #{userId} AND user_level = #{userLevel}") List<Order> selectByUserIdAndLevel(Map<String, Object> params);

这种写法的好处是，column花括号里的 key 会自动变成 Map 的 key，MyBatis 会帮你组装好。对于参数特别多的场景挺省事，缺点是参数类型安全没了，SQL 里写错 key 要等运行时才能发现。

第三种是直接用下标名：

List<Order> selectByUserIdAndLevel(@Param("userId") Long userId, @Param("userLevel") Integer userLevel);

如果完全不用@Param，方法签名是：

List<Order> selectByUserIdAndLevel(Long userId, Integer userLevel);

那么 MyBatis 能拿到的参数名就取决于是否开启useActualParamName（默认 true）以及编译时是否加了-parameters参数。如果你在 IDE 里没配置这个编译选项，实际参数名很可能被抹掉，变成arg0、arg1或param1、param2。这时候column="{userId=id}"就会报找不到。所以再次建议：多列传参时，方法参数务必用@Param显式命名。

XML 里的对应写法也给一下，方便大家对照：

<resultMap id="userResult" type="com.example.entity.User"> <id property="id" column="id"/> <result property="username" column="username"/> <collection property="orders" column="{userId=id, userLevel=level}" select="com.example.mapper.OrderMapper.selectByUserIdAndLevel"/> </resultMap>

3.4 容易混淆的 key 和列名顺序

有些同学会把column的格式和@Results里的普通列映射搞混，写成：

@Result(column = "id=userId", property = "orders", ...)

这种写法是不合法的。多列传参必须用花括号包起来，而且key=column的顺序是先子查询参数名，再父查询列名。我刚开始也写反过，等号左边的id是父查询列名，结果怎么调试都报Parameter 'id' not found。后来改成{userId=id}，立刻就好了。

还有一点：父查询结果集中如果用了别名，column右侧要写别名。比如：

@Select("SELECT id AS user_id, level AS user_level FROM user WHERE id = #{id}")

那column要写{userId=user_id, userLevel=user_level}，不要写原来的列名。因为 MyBatis 是根据 ResultSet 的元数据取列的。

4. 高频报错与排查心得

4.1 子查询参数始终是 null，问题不在 SQL

一次很常见的现场：父查询 SQL 没问题，子查询 SQL 也没问题，但子查询参数打出来就是null。多半是因为column写的列名在父查询结果集里不存在。

比如父查询是：

@Select("SELECT id, username FROM user WHERE id = #{id}")

你在@Result里写column="user_id"，可是user表根本没有user_id列。MyBatis 取不到值，却不会报一个明确的“列不存在”，因为 ResultSet 的findColumn("user_id")在某些数据库驱动下会抛异常，有些则返回 0，最终体现为参数为 null。

排查方法很简单：把父查询改成SELECT *，对比一下column是否真的匹配；或者直接看日志里父查询返回的Columns行。如果列不存在，加别名即可。

4.2 报“Parameter 'xxx' not found”优先查 @Param

如果你用了多列传递，并且日志里抛：

Parameter 'userId' not found. Available parameters are [param1, param2, ...]

那基本是参数命名没对上。先看子查询方法上有没有@Param("userId")，再看column="{userId=id}"里的左值是否和@Param一致。注意 MyBatis 对大小写敏感，@Param("userid")和column="{userId=id}"也是不同的。

如果没有@Param，可以临时用param1、param2命名，或者干脆改成 Map 接收，这样 Key 就是column花括号里的左值，不会走参数名解析。

4.3 懒加载导致子查询“延迟”不执行

如果在mybatis-config.xml里开启了：

<setting name="lazyLoadingEnabled" value="true"/>

那么@Many子查询不会在主查询返回时立即执行，而是等到你调用user.getOrders()时才触发。这本身不是 bug，但会带来两个体验问题：

• 如果子查询 SQL 有误，错误不会在调用主方法时抛出，而是在后续某个调用点突然爆出来，容易误导排查方向。
• 如果开了aggressiveLazyLoading，即使你只调用getUsername()，也可能把orders的子查询一并触发，性能反而更差。

需要调试嵌套查询时，可以先临时把懒加载关掉，确认子查询逻辑没问题后，再按需开启。

4.4 N+1 查询怎么权衡

嵌套查询本质上是 N+1 查询：主查询返回 N 条记录，子查询就执行 N 次。用户量很小的时候无感，一旦用户量上千，数据库可能瞬间被打爆。

如果要优化，可以改用 join 结果映射：

@Select("SELECT u.id, u.username, o.id AS order_id, o.amount " + "FROM user u LEFT JOIN `order` o ON u.id = o.user_id " + "WHERE u.id = #{id}") @Results(value = { @Result(id = true, column = "id", property = "id"), @Result(column = "username", property = "username"), @Result(property = "orders", column = "order_id", many = @Many(...)) })

但注意，join 结果映射的@Many并不一样，它不是在子查询中传参，而是把同一行里order_id列映射到集合里。这里需要重新理顺property、column和 Java 属性之间的关系，不是把select去掉那么简单。如果不深究，还是老老实实接受 N+1，但一定要限制主查询的条数，并且给子查询的user_id建索引，这样单次查询也在可接受范围。

5. 一点实操总结与最后的建议

我把@Result的column传参总结成一句话：column是父查询结果集到子查询方法入参之间的“数据管道”，单列直接写列名，多列用{key=column}，key对应子查询参数名，column对应父查询列名。理解了这个，再看各种嵌套查询的写法就不会发怵。

开发中我的习惯是这样：能用 XML 的resultMap就用 XML，因为一眼能看清column和select的对应关系；如果项目统一用注解，那么多列传参一定要在子查询方法上写完整的@Param，并且保持和column花括号里的 key 一致。遇到稀奇古怪的参数问题，先开 MyBatis 的 SQL 日志，看父查询返回的列名，再看子查询打印的Parameters，一步步排除，基本都能定位。

这个知识点还有一个可以深入的方向：结合@ConstructorArgs做构造函数映射，或者在多级嵌套（用户 -> 订单 -> 订单明细）时把三层@Result串起来。多级嵌套时column的传递链路更长，任何一层的列名不对，都会往下一层传一个 null。后续有机会我再专门写一篇多级嵌套的实战，欢迎一起交流。