三亚市网站建设_网站建设公司_悬停效果_seo优化

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

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

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

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

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

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

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

1.2 javaType：指定 Java 端类型

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

<resultMapid="UserResultMap"type="com.example.entity.User"><idcolumn="id"property="id"javaType="Long"/><!-- 显式指定Long类型 --><!-- 完整类名/简写都支持，推荐简写（更简洁） --><resultcolumn="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 --><insertid="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模式） --><selectid="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 执行错误，简化参数校验逻辑。
• 示例：

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

2.3 required：参数必传校验

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

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

2.4 typeHandler：自定义类型转换

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

<!-- 映射枚举类型，指定自定义TypeHandler --><resultMapid="UserResultMap"type="com.example.entity.User"><resultcolumn="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 --><selectid="getUserById"resultType="com.example.entity.User">SELECT id, user_name AS userName, age FROM user WHERE id = #{id}</select><!-- 指定参数类型（可省略，MyBatis自动推断） --><insertid="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+显式类型指定）。