MyBatis 核心属性详解笔记（由浅入深）

MyBatis 核心属性详解笔记（由浅入深）

MyBatis 作为半ORM框架，核心是通过映射配置将 Java 对象与数据库表/字段关联，而映射配置中的各类属性是实现这一关联的"桥梁"。掌握这些属性的含义和使用场景，能避免类型转换错误、参数缺失异常、SQL 执行失败等问题，让 MyBatis 配置更规范、更健壮。本文从基础高频属性 到进阶场景属性，由浅入深拆解核心属性。

一、基础篇：日常开发高频属性

这部分是你日常写 Mapper 映射文件时最常接触的属性，是 MyBatis 映射的"基本功"。

1.1 property & column：映射的基础核心

• 是什么 ：
  • column：数据库表的字段名（或 SQL 查询的列名）；
  • property：Java 实体类（POJO）的属性名。
• 什么时候用 ：只要涉及"数据库列 ↔ Java 对象属性"映射（如 resultMap、#{参数}、parameterMap），必须用这对属性（或隐式关联）。
• 作用：建立数据库字段和 Java 属性的一一对应关系，是 MyBatis 映射的底层基础。
• 示例：

<!-- 基础resultMap映射：数据库列 → Java实体属性 -->
<resultMap id="UserResultMap" type="com.example.entity.User">
  <id column="id" property="id"/> <!-- 主键映射：id列 → User.id属性 -->
  <result column="user_name" property="userName"/> <!-- 普通字段：user_name列 → User.userName属性 -->
  <result column="age" property="age"/>
</resultMap>

1.2 javaType：指定 Java 端类型

• 是什么 ：明确参数/返回值对应的Java 类型 （如 String、Integer、Date、自定义实体类）。
• 什么时候用 ：
  1. 大多数场景 MyBatis 能通过反射自动推断（比如传入 Integer 类型参数，自动识别）；
  2. 需显式指定的场景：泛型场景（如 List<User>）、类型模糊（Object 类型参数）、复杂嵌套映射（如 association/collection）。
• 作用：避免 MyBatis 类型推断错误，确保 Java 类型与数据库类型的正确映射。
• 示例：

<resultMap id="UserResultMap" type="com.example.entity.User">
  <id column="id" property="id" javaType="Long"/> <!-- 显式指定Long类型 -->
  <!-- 完整类名/简写都支持，推荐简写（更简洁） -->
  <result column="create_time" property="createTime" javaType="java.util.Date"/>
</resultMap>

1.3 jdbcType：指定数据库 JDBC 类型

• 是什么 ：对应 java.sql.Types 中的常量，是 Java 类型与数据库字段类型的"中间桥梁"（如 VARCHAR、INTEGER、DATE、BIGINT）。
• 什么时候用 ：
  1. 处理NULL 值 时（核心场景！）：MyBatis 对 NULL 值的处理必须知道对应的 JDBC 类型，否则会抛 Invalid column type 异常；
  2. 数据库字段类型与 Java 类型映射不明确时（如 Java 的 Double 对应数据库的 DECIMAL/DOUBLE）。
• 作用：明确 Java 类型到数据库类型的转换规则，解决 NULL 值处理异常，避免类型转换错误。
• 示例：

<!-- 插入语句：处理可能为NULL的参数，必须指定jdbcType -->
<insert id="insertUser">
  INSERT INTO user (user_name, age, create_time) 
  VALUES (
    #{userName,javaType=String,jdbcType=VARCHAR},
    #{age,javaType=Integer,jdbcType=INTEGER},
    #{createTime,javaType=Date,jdbcType=DATETIME}
  )
</insert>

二、进阶篇：特定场景必备属性

这部分属性不常用，但在特定场景（如存储过程、自定义类型转换）是"刚需"，掌握后能解决复杂场景的映射问题。

2.1 mode：存储过程参数传递模式

• 是什么 ：指定参数的传递模式，仅用于调用数据库存储过程/函数。
• 什么时候用 ：开发中需要调用数据库存储过程（需设置 statementType="CALLABLE"）时。
• 作用：区分参数是"输入给数据库""从数据库返回"还是"既输入又返回"，是存储过程参数配置的核心。
• 取值 ：
  • IN：输入参数（默认值，普通 SQL 的参数都是 IN 模式）；
  • OUT：输出参数（从存储过程返回的参数）；
  • INOUT：输入输出参数（既传值给存储过程，又接收返回值）。
• 示例：

<!-- 调用存储过程，获取用户总数（OUT模式） -->
<select id="getUserCount" statementType="CALLABLE">
  CALL proc_get_user_count(#{count,mode=OUT,jdbcType=INTEGER})
</select>

2.2 defaultValue：参数默认值

• 是什么：参数的兜底值，当传入的参数为 NULL 或未传递时，MyBatis 自动使用该值填充。
• 什么时候用 ：
  1. 参数非必传，但希望未传时用默认值（如状态字段默认 0 表示"未激活"）；
  2. 配置 <parameterMap> 时（MyBatis 3.x 中 parameterMap 使用较少，注解开发建议代码层处理）。
• 作用：避免参数缺失导致 SQL 执行错误，简化参数校验逻辑。
• 示例：

<parameterMap id="UserParamMap" type="com.example.entity.User">
  <!-- 未传status则默认填充0 -->
  <parameter property="status" javaType="Integer" defaultValue="0"/>
  <parameter property="userName" javaType="String" jdbcType="VARCHAR"/>
</parameterMap>

2.3 required：参数必传校验

• 是什么 ：标记参数是否必须传入，取值 true/false。
• 什么时候用 ：配置 <parameterMap> 时，需要强制校验参数是否传递（普通 #{参数} 或 @Param 注解需手动校验）。
• 作用 ：MyBatis 自动校验，若 required="true" 但参数为 NULL/未传递，直接抛 Parameter 'xxx' is not present 异常，提前发现参数缺失问题。
• 示例：

<parameterMap id="UserParamMap" type="com.example.entity.User">
  <parameter property="id" javaType="Long" required="true"/> <!-- id必须传，否则抛异常 -->
  <parameter property="userName" javaType="String" required="false"/> <!-- 可选传 -->
</parameterMap>

2.4 typeHandler：自定义类型转换

• 是什么 ：自定义 Java 类型与 JDBC 类型的转换规则（MyBatis 内置了常用类型处理器，如 String↔VARCHAR）。
• 什么时候用 ：
  1. 自定义类型（如枚举、自定义日期格式、JSON 字符串 ↔ Java 对象）；
  2. 内置类型处理器无法满足需求时（如 Java 的 LocalDateTime ↔ 数据库的 DATETIME）。
• 作用：实现自定义的类型转换逻辑，解决特殊类型的映射问题。
• 示例：

<!-- 映射枚举类型，指定自定义TypeHandler -->
<resultMap id="UserResultMap" type="com.example.entity.User">
  <result column="user_status" property="status" 
          javaType="com.example.enums.UserStatus"
          typeHandler="com.example.handler.UserStatusTypeHandler"/>
</resultMap>

2.5 resultType & parameterType：简化映射的快捷属性

• 是什么 ：
  • resultType：指定查询结果的 Java 类型（直接映射，无需写 resultMap）；
  • parameterType：指定传入参数的 Java 类型（MyBatis 3.x 可自动推断，通常省略）。
• 什么时候用 ：
  1. 简单映射场景（如查询单字段、简单 POJO，字段名与属性名完全一致）；
  2. 不想写复杂 resultMap 时。
• 作用：简化配置，减少代码量。
• 示例：

<!-- 简单查询，用resultType替代resultMap -->
<select id="getUserById" resultType="com.example.entity.User">
  SELECT id, user_name AS userName, age FROM user WHERE id = #{id}
</select>

<!-- 指定参数类型（可省略，MyBatis自动推断） -->
<insert id="insertUser" parameterType="com.example.entity.User">
  INSERT INTO user (user_name, age) VALUES (#{userName}, #{age})
</insert>

三、实战避坑：关键注意事项

1. jdbcType 仅在处理 NULL 值时必须显式指定，非 NULL 场景可省略；
2. parameterType 在 MyBatis 3.x 中几乎无需显式指定，MyBatis 能自动推断；
3. defaultValue 和 required 仅在 <parameterMap> 中生效，注解开发建议在代码层处理默认值/必传校验；
4. 自定义 typeHandler 需继承 BaseTypeHandler，并重写 setNonNullParameter、getNullableResult 等核心方法；
5. 字段名与属性名不一致时，优先用 resultMap（或别名 AS），而非强行依赖类型推断。

总结

1. 基础核心：property/column 是映射的基础，javaType/jdbcType 解决类型映射问题（NULL 值必指定 jdbcType）；
2. 简化配置：resultType/parameterType 适用于简单映射场景，减少配置量；
3. 特定场景：mode 用于存储过程，typeHandler 处理自定义类型转换，defaultValue/required 用于参数兜底/校验；
4. 使用原则：简单场景用快捷属性（resultType），复杂/特殊场景用精准配置（resultMap+显式类型指定）。