MyBatis类型映射失败导致查询结果为空？

Question

在使用MyBatis进行数据库查询时，常因实体类字段与数据库列的类型映射不匹配导致查询结果为空。例如，数据库中为`VARCHAR`类型的字段被映射到Java实体类的`Integer`类型属性，MyBatis在自动映射过程中无法完成类型转换，字段值将被置为`null`，严重时致使整个对象构建失败，返回空结果集。此类问题多发于驼峰命名转换未开启、resultMap配置缺失或使用了不兼容的数据类型（如LocalDateTime与Date混用）。尤其在无显式resultMap的情况下，MyBatis依赖自动映射，一旦类型不一致便容易静默失败，难以排查。建议启用日志输出SQL及结果、合理配置typeHandlers，并通过resultMap明确字段映射关系，避免类型映射错误引发空结果问题。

Answer 1

一、问题背景与常见现象

在使用 MyBatis 进行数据库操作时，开发者常遇到查询结果为空或部分字段为 null 的情况。尽管 SQL 执行正常且数据库中存在数据，但最终 Java 实体对象却未能正确填充。

典型场景如下：

• 数据库列类型为 VARCHAR，Java 实体类中对应字段定义为 Integer。
• 日期字段数据库使用 DATETIME，Java 使用 LocalDateTime 但未配置 typeHandler。
• 字段命名风格不一致（如数据库为下划线命名，Java 为驼峰命名），且未开启自动映射策略。
• 未定义 <resultMap>，依赖 MyBatis 自动映射机制。

这些问题往往不会抛出明显异常，而是“静默失败”，导致调试困难，严重影响开发效率和系统稳定性。

二、MyBatis 映射机制解析

MyBatis 提供两种映射方式：自动映射（auto-mapping）和手动映射（resultMap）。其行为受配置项影响：

配置项	默认值	说明
mapUnderscoreToCamelCase	false	是否开启下划线转驼峰命名
autoMappingBehavior	PARTIAL	控制自动映射范围（NONE, PARTIAL, FULL）
defaultEnumTypeHandler	-	全局枚举处理器配置

当 autoMappingBehavior=PARTIAL 时，MyBatis 仅对无嵌套结果的简单属性进行自动映射。若类型不兼容（如字符串转整数），则跳过该字段赋值，置为 null。

三、类型不匹配的典型场景分析

1. VARCHAR → Integer：数据库存储 "123" 字符串，Java 属性为 Integer id，MyBatis 无法自动转换，返回 null。
2. CHAR(1) → Boolean：用 'Y'/'N' 表示布尔值，需自定义 TypeHandler<Boolean>。
3. DATETIME → java.util.Date / LocalDateTime：JDBC 驱动可识别，但若缺少对应 typeHandler 或版本冲突，可能出现转换异常或空值。
4. DECIMAL → Double 精度丢失：虽能映射，但可能引发金融计算误差。
5. JSON 字段 → POJO 对象：MySQL 中 JSON 类型需通过自定义 TypeHandler 解析为 Java Bean。
6. 枚举类型映射错误：数据库存码值（如 1），Java 使用 enum，未配置 handler 则无法实例化。
7. BLOB → byte[]：二进制字段需确保 JDBC 类型与 Java 类型匹配。
8. 字段名大小写敏感：Oracle 默认大写，MySQL 默认小写，Java 字段小写易造成映射断开。
9. 复合主键映射缺失：多个列组合成一个嵌套对象时，必须使用 <association> 明确声明。
10. 继承结构映射混乱：父类字段未在 resultMap 中包含，导致子类对象字段为空。

四、解决方案与最佳实践

为避免因类型映射错误导致空结果集，应采取以下措施：

<settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
    <setting name="autoMappingBehavior" value="FULL"/>
    <setting name="logImpl" value="STDOUT_LOGGING"/>
</settings>

启用日志输出后，可在控制台查看实际执行的 SQL 及返回结果集，便于排查字段映射问题。

推荐使用显式的 <resultMap> 定义映射关系：

<resultMap id="UserResultMap" type="com.example.User">
    <id property="userId" column="user_id"/>
    <result property="userName" column="user_name"/>
    <result property="status" column="status" typeHandler="com.example.enums.StatusEnumHandler"/>
    <result property="createTime" column="create_time" javaType="LocalDateTime"/>
</resultMap>

<select id="selectUserById" resultMap="UserResultMap">
    SELECT user_id, user_name, status, create_time
    FROM users WHERE user_id = #{id}
</select>

五、自定义 TypeHandler 实现灵活转换

对于特殊类型转换，可通过实现 TypeHandler 接口完成定制逻辑。

public class YesNoBooleanTypeHandler implements TypeHandler<Boolean> {
    @Override
    public void setParameter(PreparedStatement ps, int i, Boolean parameter, JdbcType jdbcType) throws SQLException {
        ps.setString(i, parameter != null && parameter ? "Y" : "N");
    }

    @Override
    public Boolean getResult(ResultSet rs, String columnName) throws SQLException {
        return "Y".equals(rs.getString(columnName));
    }

    @Override
    public Boolean getResult(ResultSet rs, int columnIndex) throws SQLException {
        return "Y".equals(rs.getString(columnIndex));
    }

    @Override
    public Boolean getResult(CallableStatement cs, int columnIndex) throws SQLException {
        return "Y".equals(cs.getString(columnIndex));
    }
}

注册方式：

<typeHandlers>
    <typeHandler handler="com.example.type.YesNoBooleanTypeHandler" javaType="boolean"/>
</typeHandlers>

六、可视化流程：MyBatis 映射处理过程

graph TD
            A[执行SQL查询] --> B{是否存在resultMap?}
            B -- 是 --> C[按resultMap规则映射]
            B -- 否 --> D{开启autoMapping?}
            D -- 是 --> E[尝试自动映射所有列]
            E --> F{类型是否兼容?}
            F -- 是 --> G[成功赋值]
            F -- 否 --> H[字段设为null]
            C --> I[调用TypeHandler进行转换]
            I --> J{转换成功?}
            J -- 是 --> K[完成字段填充]
            J -- 否 --> L[抛出异常或设为null]
            G --> M[构建完整Java对象]
            K --> M
            M --> N[返回结果集]