ResultType实战避坑：3分钟搞懂MyBatis映射
官方文档翻了三遍还是晕？别急，我在给劳务班组做嵌入式设备数据上报的实战项目里，就栽在 resultType 这个看似简单的属性上。今天不整虚的，直接带你拆穿它的原理，让你以后写 SQL 映射时不再靠猜。
1. 概念速懂：ResultType 到底在干嘛？
很多人以为 resultType 就是告诉 MyBatis “我要个 Java 对象”。没错，但更准确地说，它是告诉 MyBatis 数据库返回的每一行数据，该映射成哪种类型的 Java 对象。
想象一下，数据库吐出来的是扁平的表（Table），一行行数据；而 Java 里我们要的是一个个对象（Object）。resultType 就是那个“翻译官”。如果你查 select * from user，返回多行，resultType 设为 User.class，MyBatis 就会把每一行都变成一个 User 对象，最后打包成一个 ListUser 返回。
如果你查 select count(*) from user，只返回一个数字，resultType 设为 Integer.class 或 int.class，MyBatis 就直接返回一个整数。核心区别（划重点）：
resultType 处理的是简单映射，即数据库列名与 Java 属性名一致（或忽略大小写一致）的情况。
如果列名和属性名不一样，或者涉及一对多、多对多的复杂关系，你就得用 resultMap 了。resultType 干不了这个活。
2. 环境准备：别在垃圾堆上跳舞
在嵌入式开发场景下，资源有限，但代码规范不能丢。JDK 版本：建议 JDK 8 或 11。很多老旧的嵌入式网关还在用 JDK 8，MyBatis 3.5+ 都支持，没问题。依赖引入：
dependencygroupIdorg.mybatis/groupIdartifactIdmybatis/artifactIdversion3.5.13/version
/dependency数据库驱动：根据你用的数据库选。比如 MySQL 用 mysql-connector-java，PostgreSQL 用 postgresql。实体类准备：
假设我们有一个设备状态表 device_status，字段有 id, device_id, status_code, update_time。
public class DeviceStatus {private Integer id;private String deviceId;private Integer statusCode;private LocalDateTime updateTime;// Getter Setter 省略
}注意：MyBatis 默认通过反射获取属性，所以必须有对应的 Setter 方法。如果字段名和列名不一致（如 device_id 对应 deviceId），默认映射会失败，除非你开启驼峰命名转换（下文细说）。3. 核心语法：ResultType 的三种常见用法
3.1 查询单行数据
场景：根据设备 ID 查询最新状态。
Mapper 接口：
DeviceStatus selectByDeviceId(String deviceId);XML 配置：
select id=selectByDeviceId parameterType=String resultType=com.example.entity.DeviceStatusSELECT id, device_id, status_code, update_time FROM device_status WHERE device_id = #{deviceId} ORDER BY update_time DESC LIMIT 1
/select关键点：resultType 写全限定类名（包名+类名）。MyBatis 通过反射实例化对象，并将列值填入属性。
3.2 查询多行数据（List）
场景：查询所有离线设备。
Mapper 接口：
ListDeviceStatus selectOfflineDevices();XML 配置：
select id=selectOfflineDevices resultType=com.example.entity.DeviceStatusSELECT id, device_id, status_code, update_time FROM device_status WHERE status_code = 0
/select原理：MyBatis 内部会遍历 ResultSet，每读一行就 new 一个 DeviceStatus，最后 put 进 ArrayList。
3.3 查询简单类型（Integer/String/Boolean）
场景：统计在线设备数量。
Mapper 接口：
Integer countOnlineDevices();XML 配置：
select id=countOnlineDevices resultType=IntegerSELECT COUNT(*) FROM device_status WHERE status_code = 1
/select注意：这里 resultType 可以直接写基本类型或包装类的全限定名，如 java.lang.Integer，但通常简写 Integer 即可，MyBatis 能识别。
4. 完整代码示例：嵌入式网关数据上报模块
这是一个实战项目中的真实片段。我们的网关需要定期从本地 SQLite 读取设备心跳数据，并准备上报云端。
4.1 实体类（带构造器映射）
为了在嵌入式环境下节省内存，我们使用构造器注入，避免无参构造带来的临时对象开销。
public class DeviceHeartbeat {private String deviceId;private Long timestamp;private Integer signalStrength;// 无参构造（MyBatis 默认需要，除非配置 constructor）public DeviceHeartbeat() {}// 有参构造public DeviceHeartbeat(String deviceId, Long timestamp, Integer signalStrength) {this.deviceId = deviceId;this.timestamp = timestamp;this.signalStrength = signalStrength;}// Getters...
}4.2 Mapper XML：使用 ResultType 配合别名
在 mybatis-config.xml 中，我们通常会给实体类起别名，简化 XML 书写。
typeAliasespackage name=com.example.entity/
/typeAliases这样，resultType=DeviceHeartbeat 就等同于全限定名。
mapper namespace=com.example.mapper.DeviceMapper!-- 查询最近 1 分钟内的所有心跳记录注意：列名 device_id 与属性 deviceId 不一致，这里依赖 MyBatis 的驼峰命名转换--select id=selectRecentHeartbeats resultType=DeviceHeartbeatSELECT device_id, timestamp, signal_strength FROM device_heartbeat WHERE timestamp = #{oneMinuteAgo}ORDER BY timestamp ASC/select
/mapper关键配置：开启驼峰命名转换
如果没开这个，device_id 映射不到 deviceId，属性会为 null。
settings!-- 开启下划线到驼峰自动映射 --setting name=mapUnderscoreToCamelCase value=true/
/settings4.3 Service 层调用
@Service
public class DeviceService {@Autowiredprivate DeviceMapper deviceMapper;public ListDeviceHeartbeat getRecentHeartbeats() {// 计算 1 分钟前的时间戳long oneMinuteAgo = System.currentTimeMillis() - 60 * 1000;// 调用 MapperListDeviceHeartbeat heartbeats = deviceMapper.selectRecentHeartbeats(oneMinuteAgo);// 业务逻辑：过滤掉信号强度低于阈值的脏数据return heartbeats.stream().filter(h - h.getSignalStrength() 10).collect(Collectors.toList());}
}这段代码在实战中跑通了，关键在于 mapUnderscoreToCamelCase 配置。很多新手报错就是因为没开这个，导致查出来的对象全是 null。
5. 常见报错与避坑指南
5.1 报错：ReflectionException: There is no setter for property named 'xxx'
原因：数据库列名 user_name，实体类属性 userName，但没开驼峰转换，且没写 resultMap。
解决：开启 mapUnderscoreToCamelCase=true。
或者在 XML 中显式指定列别名：SELECT user_name AS userName ...（不推荐，耦合度高）。
或者使用 resultMap 手动映射。5.2 报错：TooManyResultsException: Expected one result (or null) to be returned by selectOne(), but found: 2
原因：Mapper 接口定义返回单个对象，但 SQL 查询结果有多行。
解决：检查 SQL 逻辑，确保唯一性（加 LIMIT 1 或唯一索引条件）。
如果确实需要多行，将返回类型改为 ListT。5.3 坑点：resultType 与 resultMap 混用
误区：有人觉得 resultType 不够用，就在 XML 里既写 resultType 又写 resultMap。
真相：两者互斥。写了 resultMap，resultType 会被忽略。如果 resultMap 没定义，会报错。
建议：简单查询用 resultType，复杂关联用 resultMap。保持清晰。
5.4 坑点：基本类型与包装类型的 NPE
场景：查询 select count(*)，返回类型设为 int。
风险：如果结果为 0，int 没问题。但如果查询结果为 NULL（比如 max(id) 无数据），设为 int 会抛 NPE（空指针异常），因为无法将 NULL 拆箱为 int。
建议：对于可能为空的查询结果，使用包装类型 Integer、Long 等。
6. 小结与进阶
resultType 是 MyBatis 中最基础也最易被忽视的映射方式。它的核心价值在于简洁和快速开发。适用场景：单表查询、列名与属性名一致（或可自动转换）、无关联关系。
不适用场景：多表关联、字段名差异大、需要嵌套对象。此时请果断切换 resultMap。在嵌入式开发中，性能敏感，但代码可读性同样重要。合理使用 resultType 可以减少 XML 配置量，降低维护成本。但切记，配置先行（如驼峰转换），类型安全（用包装类），边界清晰（单行 vs 多行）。
MDN Web Docs 虽然主要面向 Web，但其关于“数据绑定”和“反射”的底层逻辑与 Java 的 MyBatis 映射原理异曲同工，理解“如何将扁平数据绑定到结构化对象”是通用的。
你在项目里踩过这个坑吗？比如因为 resultType 设置错误导致数据全为 null，或者因为没开驼峰转换调试了一下午？评论区聊聊，咱们互相避坑。
