Java MyBatis 实战：如何通过 SQL 查询返回 List＜Map＞ 数据格式

1. 引言

在 Java 企业级开发中，MyBatis 作为一款优秀的持久层框架，以其灵活的 SQL 映射和强大的动态 SQL 功能而广受欢迎。虽然 MyBatis 推荐使用强类型的实体类（POJO）来接收查询结果，但在实际开发中，我们经常会遇到一些动态查询、结果集结构不固定或需要快速原型开发的场景。此时，直接返回 List<Map<String, Object>> 这种灵活的数据结构就变得非常有用。

本文将详细介绍如何在 MyBatis 中配置和执行 SQL，以返回 List<Map> 格式的数据，并探讨其适用场景、优缺点以及最佳实践。

2. 为什么需要返回 List？

2.1 适用场景

1. 动态查询结果：当查询的列名或数量在运行时才能确定时，无法预先定义对应的实体类。
2. 快速原型与调试：在开发初期或进行数据探查时，无需为每次查询都创建实体类，提升开发效率。
3. 多表关联查询（非一对一映射）：复杂的联表查询结果可能无法直接映射到某个现有的实体类，使用 Map 可以灵活地容纳所有字段。
4. 数据导出或转换：需要将查询结果直接转换为 JSON 或其他键值对格式进行传输或展示。

2.2 与实体类映射的对比

• 实体类（POJO）映射：类型安全、代码可读性强、便于 IDE 提示和重构，是 MyBatis 的推荐方式。
• Map 映射：灵活、无需预先定义结构、适合动态场景，但牺牲了类型安全和部分可读性。

3. 核心实现方式

MyBatis 默认支持将结果集自动映射到 List<Map<String, Object>>。其中，Map 的键（Key）是查询结果的列名（或别名），值（Value）是对应列的值。

3.1 Mapper XML 配置示例

以下是一个直接在 Mapper XML 文件中编写 SQL，并返回 List<Map> 的示例。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.DynamicQueryMapper">

    <!-- 返回 List<Map<String, Object>> -->
    <select id="selectUsersAsMap" resultType="java.util.Map">
        SELECT
            user_id as "userId",
            user_name as "userName",
            email,
            age,
            create_time as "createTime"
        FROM
            t_user
        WHERE
            status = 'ACTIVE'
        <!-- 可选：动态SQL -->
        <if test="minAge != null">
            AND age >= #{minAge}
        </if>
    </select>

    <!-- 更复杂的联表查询示例 -->
    <select id="selectUserOrderSummary" resultType="java.util.Map">
        SELECT
            u.user_id as "userId",
            u.user_name as "userName",
            COUNT(o.order_id) as "orderCount",
            SUM(o.amount) as "totalAmount"
        FROM
            t_user u
        LEFT JOIN
            t_order o ON u.user_id = o.user_id
        GROUP BY
            u.user_id, u.user_name
    </select>

</mapper>

关键点：

• resultType="java.util.Map"：这是告诉 MyBatis 将每一行结果包装成一个 Map。
• 列别名 ：建议为查询字段起一个清晰的别名（特别是数据库字段名是下划线风格，而希望 Map 的 key 是驼峰风格时）。例如 user_id as "userId"。MyBatis 会将别名作为 Map 的 Key。

3.2 Mapper 接口定义

对应的 Java Mapper 接口如下：

package com.example.mapper;

import org.apache.ibatis.annotations.Mapper;
import java.util.List;
import java.util.Map;

@Mapper
public interface DynamicQueryMapper {

    /**
     * 查询用户信息，返回 List<Map>
     * @param minAge 可选参数
     * @return List<Map<String, Object>>
     */
    List<Map<String, Object>> selectUsersAsMap(Integer minAge);

    /**
     * 查询用户订单汇总信息
     * @return List<Map<String, Object>>
     */
    List<Map<String, Object>> selectUserOrderSummary();

}

3.3 服务层调用示例

在 Service 中，你可以像使用其他返回实体类列表的方法一样调用它。

package com.example.service;

import com.example.mapper.DynamicQueryMapper;
import org.springframework.stereotype.Service;
import javax.annotation.Resource;
import java.util.List;
import java.util.Map;

@Service
public class UserService {

    @Resource
    private DynamicQueryMapper dynamicQueryMapper;

    public List<Map<String, Object>> getActiveUsers(Integer minAge) {
        // 直接调用，返回的就是 List<Map<String, Object>>
        return dynamicQueryMapper.selectUsersAsMap(minAge);
    }

    public void processUserData() {
        List<Map<String, Object>> userList = getActiveUsers(18);
        for (Map<String, Object> userMap : userList) {
            // 通过列名（或别名）获取值
            Long userId = (Long) userMap.get("userId");
            String userName = (String) userMap.get("userName");
            Integer age = (Integer) userMap.get("age");
            // ... 处理业务逻辑
            System.out.printf("用户ID: %d, 姓名: %s, 年龄: %d%n", userId, userName, age);
        }
    }
}

4. 注解方式实现

如果你更喜欢使用注解而非 XML，也可以轻松实现。

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import java.util.List;
import java.util.Map;

@Mapper
public interface DynamicQueryAnnotationMapper {

    @Select("SELECT user_id as userId, user_name as userName FROM t_user WHERE dept_id = #{deptId}")
    List<Map<String, Object>> selectUsersByDept(@Param("deptId") Long deptId);

}

5. 注意事项与最佳实践

5.1 类型转换与空值处理

• Map 中的 Object 值类型由 JDBC Driver 和 MyBatis 的类型处理器决定。例如，数据库的 BIGINT 可能被转为 Long，VARCHAR 转为 String。
• 获取值时需要进行强制类型转换，并注意处理 null 值。
• 可以使用 Map.getOrDefault(key, defaultValue) 或 Optional 来避免空指针。

String userName = Optional.ofNullable(userMap.get("userName")).map(Object::toString).orElse("未知");

5.2 键（Key）的大小写问题

• 默认情况下，MyBatis 返回的 Map 的 Key（列名）区分大小写，且通常与 SQL 中指定的列名或别名完全一致。
• 为了保持一致性，强烈建议在 SQL 中使用 as 为所有列指定明确的别名，并统一命名风格（如驼峰）。

5.3 性能考量

• 对于大数据量查询，返回 List<Map> 与返回 List<POJO> 的性能开销差异很小，主要开销在于结果集的映射和网络传输。
• 真正的性能瓶颈通常在于 SQL 本身和数据库索引。

5.4 可维护性建议

1. 限定使用场景 ：仅在确实需要动态性时使用 List<Map>，对于结构固定的业务模型，优先使用实体类。
2. 文档化：在方法注释或团队文档中明确说明返回的 Map 中包含哪些键及其对应的数据类型。
3. 提取常量：对于频繁使用的 Map Key，可以定义成常量类，避免硬编码字符串。

public class UserMapKeys {
    public static final String USER_ID = "userId";
    public static final String USER_NAME = "userName";
    // ...
}
// 使用时
Long userId = (Long) userMap.get(UserMapKeys.USER_ID);

6. 总结

List<Map<String, Object>> 是 MyBatis 提供的一种灵活的结果映射方式，非常适合处理动态查询、数据探查和快速开发场景。通过简单的 resultType="java.util.Map" 配置或在注解中直接定义返回类型即可使用。

然而，灵活性的代价是牺牲了编译时的类型安全和代码的可读性。因此，在项目实践中，应遵循"实体类优先"的原则，仅在合适的场景下谨慎选用 List<Map>，并辅以良好的别名规范和文档说明，这样才能在享受灵活性的同时，保持代码的健壮与可维护。

希望本文能帮助你在 MyBatis 项目中游刃有余地处理各种数据返回需求。