【源码解读之 Mybatis】【核心篇】–第7篇：ParameterHandler参数处理机制

技术分享 5个月前 (10-25) 0 999+

关注

第7篇：ParameterHandler参数处理机制

1. 学习目标确认

1.0 第6篇思考题解答

在深入学习ParameterHandler参数处理机制之前，让我们先回顾并解答第6篇中提出的思考题，这将帮助我们更好地理解ParameterHandler在整个执行流程中的关键作用。

思考题1：为什么MyBatis要设计RoutingStatementHandler？直接使用具体的StatementHandler不行吗？

答案要点：

统一入口：RoutingStatementHandler提供统一的创建入口，屏蔽了具体实现的复杂性
策略模式：根据StatementType动态选择合适的处理器，实现了策略模式
扩展性：便于添加新的StatementHandler类型，不影响现有代码
简化调用：Executor只需要与RoutingStatementHandler交互，不需要关心具体类型
插件支持：为插件拦截提供统一的拦截点

与ParameterHandler的关系：每种StatementHandler都需要ParameterHandler来设置SQL参数，RoutingStatementHandler确保了参数处理的一致性。

思考题2：PreparedStatementHandler相比SimpleStatementHandler有什么优势？为什么是默认选择？

答案要点：

安全优势：支持参数绑定，有效防止SQL注入攻击
性能优势：SQL预编译，相同SQL结构可以复用执行计划，减少10-20%的SQL解析时间（视数据库实现）
类型安全：通过TypeHandler进行类型转换，确保类型安全
维护性：参数与SQL分离，代码结构更清晰
功能丰富：支持主键生成、批量操作等高级功能

ParameterHandler的重要性：PreparedStatementHandler的核心优势来自于ParameterHandler的参数绑定机制。

思考题3：CallableStatementHandler如何处理存储过程的输出参数？与普通查询有什么区别？

答案要点：

参数注册：需要预先注册输出参数的类型和位置
参数模式：支持IN、OUT、INOUT三种参数模式
结果获取：通过CallableStatement.getXxx()方法获取输出参数值
处理时机：在SQL执行完成后处理输出参数
类型转换：输出参数也需要进行类型转换
多结果集支持：复杂存储过程可能返回多个结果集，需通过ResultSetHandler.handleMultipleResults()方法处理

存储过程多结果集处理示例：

// 调用存储过程，处理多个结果集和输出参数 CallableStatement cs = connection.prepareCall("{call getUserOrders(?, ?)}");  // 注册输出参数 cs.setLong(1, userId);  // 输入参数：用户ID cs.registerOutParameter(2, Types.INTEGER);  // 输出参数：订单总数  // 执行存储过程 cs.execute();  // 处理第一个结果集（用户信息） ResultSet rs1 = cs.getResultSet(); while (rs1.next()) {     System.out.println("用户: " + rs1.getString("name")); }  // 切换到下一个结果集（订单列表） if (cs.getMoreResults()) {     ResultSet rs2 = cs.getResultSet();     while (rs2.next()) {         System.out.println("订单: " + rs2.getString("order_no"));     } }  // 获取输出参数 int totalOrders = cs.getInt(2); System.out.println("订单总数: " + totalOrders);

ParameterHandler的扩展：CallableStatementHandler需要扩展ParameterHandler来处理输出参数的注册和获取。

思考题4：StatementHandler与ParameterHandler、ResultSetHandler是如何协作的？

答案要点：

组合模式：StatementHandler通过组合包含ParameterHandler和ResultSetHandler
职责分工：StatementHandler负责Statement管理，ParameterHandler负责参数设置，ResultSetHandler负责结果处理
执行流程：prepare() → parameterize() → execute() → handleResults()
统一管理：StatementHandler统一协调三者的执行时序

核心协作流程：

StatementHandler.prepare()     // 创建Statement ↓ ParameterHandler.setParameters() // 设置参数 ↓ Statement.execute()            // 执行SQL ↓ ResultSetHandler.handleResultSets() // 处理结果

1.1 本篇学习目标

通过本文你将能够:

深入理解ParameterHandler参数处理器的设计思想和核心职责
掌握DefaultParameterHandler的实现机制和参数设置流程
理解参数映射(ParameterMapping)的配置和使用方式
掌握TypeHandler类型处理器与参数处理的协作关系
了解不同参数类型(基本类型、对象、集合)的处理策略
理解额外参数(AdditionalParameter)的生成与使用机制
掌握参数验证和性能优化策略
具备自定义ParameterHandler扩展开发的能力

2. ParameterHandler参数处理器体系总览

还记得第6篇我们说StatementHandler是"SQL执行的总指挥"吗?那ParameterHandler就是这位总指挥手下最得力的"后勤部长"——专门负责把我们Java代码里的参数"翻译"成数据库能听懂的话。

想象一下,你要给外国朋友寄包裹,得先把中文地址翻译成英文对吧?ParameterHandler做的就是这个活儿:把 User user = new User("张三", 18)这样的Java对象,翻译成 ps.setString(1, "张三"); ps.setInt(2, 18)这样的JDBC调用。比如将 #{user.name}转换为 ps.setString(1, "张三")这样神奇的操作!

2.1 参数处理器继承关系图

classDiagram class ParameterHandler { <<interface>> +getParameterObject() Object +setParameters(PreparedStatement) void } class DefaultParameterHandler { -typeHandlerRegistry TypeHandlerRegistry -mappedStatement MappedStatement -parameterObject Object -boundSql BoundSql -configuration Configuration +DefaultParameterHandler(MappedStatement, Object, BoundSql) +getParameterObject() Object +setParameters(PreparedStatement) void } class ParameterMapping { -property String -mode ParameterMode -javaType Class -jdbcType JdbcType -typeHandler TypeHandler -numericScale Integer -resultMapId String -jdbcTypeName String -expression String } class TypeHandler { <<interface>> +setParameter(PreparedStatement, int, T, JdbcType) void +getResult(ResultSet, String) T +getResult(ResultSet, int) T +getResult(CallableStatement, int) T } class LanguageDriver { <<interface>> +createParameterHandler(MappedStatement, Object, BoundSql) ParameterHandler } class XMLLanguageDriver { +createParameterHandler(MappedStatement, Object, BoundSql) ParameterHandler } ParameterHandler <|.. DefaultParameterHandler LanguageDriver <|.. XMLLanguageDriver DefaultParameterHandler --> ParameterMapping : uses DefaultParameterHandler --> TypeHandler : delegates to XMLLanguageDriver --> DefaultParameterHandler : creates

2.2 参数处理器职责分工

组件	核心职责	主要功能	性能特点
ParameterHandler	参数处理接口	定义参数设置规范	统一入口,零性能损耗
DefaultParameterHandler	默认参数处理实现	参数值获取、类型转换、参数设置	内置优先级策略,高效稳定
ParameterMapping	参数映射配置	参数属性、类型、模式配置	建造者模式,减少对象创建开销
TypeHandler	类型转换处理	Java类型与JDBC类型互转	TypeHandler缓存可提升5-10%参数设置效率
LanguageDriver	语言驱动器	创建ParameterHandler实例	动态选择实现,支持多种SQL方言

2.3 参数处理流程图

sequenceDiagram participant SH as StatementHandler participant PH as ParameterHandler participant PM as ParameterMapping participant TH as TypeHandler participant PS as PreparedStatement SH->>PH: setParameters(ps) Note over PH: MetaObject缓存反射结果<br/>优化复杂对象处理 loop 遍历参数映射 PH->>PM: getProperty() PH->>PH: getPropertyValue() alt 额外参数 PH->>PH: boundSql.getAdditionalParameter() else 基本类型 PH->>PH: parameterObject直接使用 else 复杂对象 Note over PH: 使用MetaObject反射<br/>性能开销较大 PH->>PH: metaObject.getValue() end PH->>TH: setParameter(ps, index, value, jdbcType) TH->>PS: setXxx(index, value) end PS-->>SH: 参数设置完成

3. ParameterHandler接口定义

3.1 接口源码分析

ParameterHandler接口非常简洁，只定义了两个核心方法：

package org.apache.ibatis.executor.parameter;  import java.sql.PreparedStatement; import java.sql.SQLException;  /**  * 参数处理器接口  * 负责为PreparedStatement设置参数  *   * @author Clinton Begin  */ public interface ParameterHandler {      /**      * 获取参数对象      * @return 参数对象,可能为null、基本类型(如Long、String)、复杂对象(如User)或集合(如List<User>)      *       * 示例返回值:      * - 基本类型:Long id = 123L      * - 复杂对象:User user = new User()      * - 集合类型:List<Long> ids = Arrays.asList(1L, 2L, 3L)      * - 空值:null(无参数方法)      */     Object getParameterObject();        // 使用示例     // Object param = handler.getParameterObject();     // 可能是 Long、User、List<User> 或 null      /**      * 为PreparedStatement设置参数      * 这是ParameterHandler的核心方法，负责：      * 1. 获取参数值      * 2. 进行类型转换      * 3. 调用PreparedStatement的setXxx方法设置参数      *       * @param ps PreparedStatement对象      * @throws SQLException 参数设置过程中的SQL异常      */     void setParameters(PreparedStatement ps) throws SQLException; }

3.2 接口设计特点

简洁得让人惊讶：

就两个方法！getParameterObject()和setParameters()，简单到你都怀疑"这就完了？"
但别小看它，MyBatis的"单一职责原则"在这儿体现得淋漓尽致

扩展性拉满：

想加个参数加密？写个实现类就行
想做参数校验？也是写个实现类
这就是面向接口编程的魅力啊！

团队协作能手：

跟TypeHandler配合："兄弟，这个Date类型你来转一下"
跟StatementHandler配合："老大，参数我都设置好了，可以执行了！"

4. DefaultParameterHandler默认实现

4.1 核心源码分析

DefaultParameterHandler是ParameterHandler的默认实现，承担了参数处理的核心逻辑：

package org.apache.ibatis.scripting.defaults;  import org.apache.ibatis.executor.ErrorContext; import org.apache.ibatis.executor.parameter.ParameterHandler; import org.apache.ibatis.mapping.BoundSql; import org.apache.ibatis.mapping.MappedStatement; import org.apache.ibatis.mapping.ParameterMapping; import org.apache.ibatis.mapping.ParameterMode; import org.apache.ibatis.reflection.MetaObject; import org.apache.ibatis.session.Configuration; import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.TypeException; import org.apache.ibatis.type.TypeHandler; import org.apache.ibatis.type.TypeHandlerRegistry;  import java.sql.PreparedStatement; import java.sql.SQLException; import java.util.List;  /**  * 默认参数处理器实现  * 负责将Java参数对象转换为PreparedStatement的参数  *   * @author Clinton Begin  * @author Eduardo Macarron  */ public class DefaultParameterHandler implements ParameterHandler {      // 类型处理器注册表，用于获取对应的TypeHandler     private final TypeHandlerRegistry typeHandlerRegistry;        // SQL映射语句，包含参数映射配置     private final MappedStatement mappedStatement;        // 参数对象，可能是null、基本类型、Map、POJO等     private final Object parameterObject;        // 绑定SQL对象，包含参数映射列表     private final BoundSql boundSql;        // MyBatis全局配置对象     private final Configuration configuration;      /**      * 构造方法      * 初始化参数处理器所需的核心组件      *       * @param mappedStatement SQL映射语句，包含参数映射配置      * @param parameterObject 参数对象，可能为null、基本类型、复杂对象或集合      * @param boundSql 绑定SQL对象，包含参数映射列表和额外参数      */     public DefaultParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql) {         this.mappedStatement = mappedStatement;         this.configuration = mappedStatement.getConfiguration();         this.typeHandlerRegistry = mappedStatement.getConfiguration().getTypeHandlerRegistry();         this.parameterObject = parameterObject;         this.boundSql = boundSql;     }      @Override     public Object getParameterObject() {         return parameterObject;     }      /**      * 设置PreparedStatement参数的核心方法      * 遍历所有参数映射,为每个参数设置值      *       * 核心处理流程(伪代码):      * for (ParameterMapping pm : boundSql.getParameterMappings()) {      *     Object value = getPropertyValue(pm, metaObject);  // 优先级策略获取值      *     TypeHandler th = pm.getTypeHandler();           // 获取类型处理器      *     th.setParameter(ps, index++, value, pm.getJdbcType()); // 设置参数      * }      *       * MetaObject缓存优化: MetaObject内部使用Reflector缓存属性元数据(getter/setter方法、字段类型等),      * 避免重复反射解析,显著减少复杂对象处理的反射开销      */     @Override     public void setParameters(PreparedStatement ps) throws SQLException {         // 设置错误上下文，便于问题定位         ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());                // 获取参数映射列表         List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();                if (parameterMappings != null) {             MetaObject metaObject = null;                        // 遍历每个参数映射             for (int i = 0; i < parameterMappings.size(); i++) {                 ParameterMapping parameterMapping = parameterMappings.get(i);                                // 跳过输出参数（OUT参数用于存储过程）                 if (parameterMapping.getMode() != ParameterMode.OUT) {                     Object value;                     String propertyName = parameterMapping.getProperty();                                        // 参数值获取的优先级策略                     if (boundSql.hasAdditionalParameter(propertyName)) {                         // 1. 优先从额外参数中获取（如foreach生成的参数）                         value = boundSql.getAdditionalParameter(propertyName);                     } else if (parameterObject == null) {                         // 2. 参数对象为null                         value = null;                     } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {                         // 3. 参数对象是基本类型（有对应的TypeHandler）                         value = parameterObject;                     } else {                         // 4. 参数对象是复杂类型，通过反射获取属性值                         // MetaObject使用Reflector缓存属性元数据，减少反射开销                         if (metaObject == null) {                             metaObject = configuration.newMetaObject(parameterObject);                         }                         value = metaObject.getValue(propertyName);                     }                                        // 获取对应的类型处理器                     TypeHandler typeHandler = parameterMapping.getTypeHandler();                     JdbcType jdbcType = parameterMapping.getJdbcType();                                        // 处理null值的JDBC类型                     if (value == null && jdbcType == null) {                         jdbcType = configuration.getJdbcTypeForNull();                     }                                        try {                         // 使用TypeHandler设置参数                         typeHandler.setParameter(ps, i + 1, value, jdbcType);                     } catch (TypeException | SQLException e) {                         // 封装异常信息，便于问题定位                         throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);                     }                 }             }         }     } }

4.2 参数值获取策略

DefaultParameterHandler获取参数值可不是瞎猜的，人家有一套严格的"优先级规则"，就像你找东西一样——先找最有可能的地方：

// 第一优先级：额外参数（最高优先级） if (boundSql.hasAdditionalParameter(propertyName)) {     // "哎，这个参数是foreach动态生成的，我先用这个！"     value = boundSql.getAdditionalParameter(propertyName); } else if (parameterObject == null) {     // 第二优先级：参数对象是null     // "啊？你啥参数都没给我？那我也没办法，只能是null了"     value = null; } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {     // 第三优先级：基本类型     // "哦，你就传了个Long/String？那我直接用就行了"     value = parameterObject; } else {     // 第四优先级：复杂对象（最低优先级）     // "嗯？User对象？我得反射一下拿到user.getName()这些属性值"     if (metaObject == null) {         metaObject = configuration.newMetaObject(parameterObject);     }     value = metaObject.getValue(propertyName); }

为什么要这样设计？

额外参数优先：动态SQL（像foreach）会生成临时参数，这些肯定是最新的，当然要先用
null处理：空指针异常是程序员的噩梦，先判断null能避免很多问题
基本类型直接用：Long id = 123L这种，还反射个啥？直接用多省事
复杂对象才反射：User、Order这些对象，没办法，只能用反射了（虽然慢点，但准确啊）

4.3 类型处理器协作

DefaultParameterHandler跟TypeHandler的配合就像是"翻译官"和"专业术语顾问"的关系：

内置TypeHandler全家桶：

StringTypeHandler：String ↔ VARCHAR，这个最常用
IntegerTypeHandler：Integer ↔ INTEGER，处理数字的
DateTypeHandler：Date ↔ TIMESTAMP，时间类型专用
EnumTypeHandler：枚举 ↔ VARCHAR，枚举值的好帮手

它俩怎么配合的？

// 获取类型处理器 TypeHandler typeHandler = parameterMapping.getTypeHandler(); JdbcType jdbcType = parameterMapping.getJdbcType();  // 处理null值的JDBC类型 if (value == null && jdbcType == null) {     jdbcType = configuration.getJdbcTypeForNull(); }  try {     // 委托给TypeHandler进行具体的参数设置     // TypeHandler会根据Java类型和JDBC类型进行转换     typeHandler.setParameter(ps, i + 1, value, jdbcType); } catch (TypeException | SQLException e) {     throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e); }

协作示例: 当参数类型为 String 时,StringTypeHandler 会调用 PreparedStatement.setString(index, value) 设置参数。

内置TypeHandler使用示例:

// StringTypeHandler 处理字符串参数 TypeHandler<String> stringHandler = new StringTypeHandler(); stringHandler.setParameter(ps, 1, "张三", JdbcType.VARCHAR);  // IntegerTypeHandler 处理整数参数 TypeHandler<Integer> intHandler = new IntegerTypeHandler(); intHandler.setParameter(ps, 2, 25, JdbcType.INTEGER);  // DateTypeHandler 处理日期参数 TypeHandler<Date> dateHandler = new DateTypeHandler(); dateHandler.setParameter(ps, 3, new Date(), JdbcType.TIMESTAMP);

自定义TypeHandler示例：

/**  * 自定义日期类型处理器  * 将Java Date转换为JDBC Timestamp  */ public class CustomDateTypeHandler implements TypeHandler<Date> {        @Override     public void setParameter(PreparedStatement ps, int i, Date parameter, JdbcType jdbcType) throws SQLException {         if (parameter == null) {             ps.setNull(i, Types.TIMESTAMP);         } else {             ps.setTimestamp(i, new Timestamp(parameter.getTime()));         }     }        @Override     public Date getResult(ResultSet rs, String columnName) throws SQLException {         Timestamp timestamp = rs.getTimestamp(columnName);         return timestamp != null ? new Date(timestamp.getTime()) : null;     }        @Override     public Date getResult(ResultSet rs, int columnIndex) throws SQLException {         Timestamp timestamp = rs.getTimestamp(columnIndex);         return timestamp != null ? new Date(timestamp.getTime()) : null;     }        @Override     public Date getResult(CallableStatement cs, int columnIndex) throws SQLException {         Timestamp timestamp = cs.getTimestamp(columnIndex);         return timestamp != null ? new Date(timestamp.getTime()) : null;     } }  // 注册自定义TypeHandler configuration.getTypeHandlerRegistry().register(Date.class, JdbcType.TIMESTAMP, new CustomDateTypeHandler());

5. ParameterMapping参数映射配置

5.1 参数映射核心属性

ParameterMapping定义了参数的映射配置信息：

package org.apache.ibatis.mapping;  import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.TypeHandler;  /**  * 参数映射配置类  * 包含参数的详细映射信息  */ public class ParameterMapping {      private Configuration configuration;        // 参数属性名称（在参数对象中的属性名）     private String property;        // 参数模式：IN(输入)、OUT(输出)、INOUT(输入输出)     private ParameterMode mode;        // Java类型     private Class<?> javaType = Object.class;        // JDBC类型     private JdbcType jdbcType;        // 数字精度（用于NUMERIC和DECIMAL类型）     // 例如：BigDecimal类型的小数位数，price字段精度为2表示保留两位小数     // 应用场景：处理金额、汇率等需要精确小数的数值     private Integer numericScale;        // 类型处理器     private TypeHandler<?> typeHandler;        // 结果映射ID（用于复杂类型）     private String resultMapId;        // JDBC类型名称     private String jdbcTypeName;        // 表达式（用于动态参数）     private String expression;      // 构造方法和Getter/Setter略...        /**      * 参数映射建造器      * 使用建造者模式构建ParameterMapping对象      */     public static class Builder {         private ParameterMapping parameterMapping = new ParameterMapping();          public Builder(Configuration configuration, String property, TypeHandler<?> typeHandler) {             parameterMapping.configuration = configuration;             parameterMapping.property = property;             parameterMapping.typeHandler = typeHandler;         }          public Builder mode(ParameterMode mode) {             parameterMapping.mode = mode;             return this;         }          public Builder javaType(Class<?> javaType) {             parameterMapping.javaType = javaType;             return this;         }          public Builder jdbcType(JdbcType jdbcType) {             parameterMapping.jdbcType = jdbcType;             return this;         }          public Builder numericScale(Integer numericScale) {             parameterMapping.numericScale = numericScale;             return this;         }          public Builder resultMapId(String resultMapId) {             parameterMapping.resultMapId = resultMapId;             return this;         }          public Builder jdbcTypeName(String jdbcTypeName) {             parameterMapping.jdbcTypeName = jdbcTypeName;             return this;         }          public Builder expression(String expression) {             parameterMapping.expression = expression;             return this;         }          public ParameterMapping build() {             resolveTypeHandler();             validate();             return parameterMapping;         }          private void resolveTypeHandler() {             if (parameterMapping.typeHandler == null && parameterMapping.javaType != null) {                 Configuration configuration = parameterMapping.configuration;                 TypeHandlerRegistry typeHandlerRegistry = configuration.getTypeHandlerRegistry();                 parameterMapping.typeHandler = typeHandlerRegistry.getTypeHandler(parameterMapping.javaType, parameterMapping.jdbcType);             }         }          private void validate() {             if (parameterMapping.typeHandler == null) {                 throw new BuilderException("Type handler was null on parameter mapping for property '"                     + parameterMapping.property + "'. It was either not specified and/or could not be found for the javaType ("                     + parameterMapping.javaType.getName() + ") : jdbcType (" + parameterMapping.jdbcType + ") combination.");             }         }     } }

5.2 参数映射创建流程

参数映射通过SqlSource解析过程创建，支持在XML或注解中配置精度：

XML配置示例（指定DECIMAL精度）：

<!-- 指定DECIMAL类型的精度 --> <select id="findByPrice" resultType="Product">     SELECT * FROM product      WHERE price = #{price, javaType=BigDecimal, jdbcType=DECIMAL, numericScale=2} </select>  <!-- 批量插入时指定精度 --> <insert id="batchInsert" parameterType="list">     INSERT INTO product (name, price) VALUES     <foreach collection="list" item="item" separator=",">         (#{item.name}, #{item.price, javaType=BigDecimal, jdbcType=DECIMAL, numericScale=2})     </foreach> </insert>

参数映射构建代码：

<!-- 指定DECIMAL类型的精度 --> <select id="findByPrice" resultType="Product">     SELECT * FROM product      WHERE price = #{price, javaType=BigDecimal, jdbcType=DECIMAL, numericScale=2} </select>

参数映射构建代码：

// 在XMLScriptBuilder或AnnotationBuilder中创建ParameterMapping public ParameterMapping buildParameterMapping(Class<?> parameterType, String property, Class<?> javaType, JdbcType jdbcType) {     // 解析参数类型     if (javaType == null) {         if (JdbcType.CURSOR.equals(jdbcType)) {             javaType = java.sql.ResultSet.class;         } else if (Map.class.isAssignableFrom(parameterType)) {             javaType = Object.class;         } else {             MetaClass metaClass = MetaClass.forClass(parameterType, configuration.getReflectorFactory());             javaType = metaClass.getGetterType(property);         }     }        // 获取类型处理器     TypeHandler<?> typeHandler = configuration.getTypeHandlerRegistry().getTypeHandler(javaType, jdbcType);        // 构建ParameterMapping     return new ParameterMapping.Builder(configuration, property, typeHandler)         .javaType(javaType)         .jdbcType(jdbcType)         .build(); }

6. 不同参数类型的处理策略

6.1 基本类型参数处理

/**  * 基本类型参数处理示例  * 当参数是基本类型时，直接使用parameterObject作为参数值  */ public class BasicParameterExample {        /**      * 单个基本类型参数      * SQL: SELECT * FROM user WHERE id = ?      */     @Test     public void testSingleBasicParameter() throws SQLException {         // 参数对象就是基本类型值         Object parameterObject = 123L;                // MyBatis会检测到Long类型有对应的TypeHandler         boolean hasTypeHandler = typeHandlerRegistry.hasTypeHandler(parameterObject.getClass());         System.out.println("Long类型有TypeHandler: " + hasTypeHandler);                // 直接使用parameterObject作为参数值         if (hasTypeHandler) {             Object value = parameterObject; // 123L             System.out.println("参数值: " + value);         }     }        /**      * 多个基本类型参数      * SQL: SELECT * FROM user WHERE id = ? AND status = ?      * MyBatis会自动包装为Map      */     @Test     public void testMultipleBasicParameters() {         // MyBatis自动包装：{arg0=123, arg1="ACTIVE", param1=123, param2="ACTIVE"}         Map<String, Object> parameterObject = new HashMap<>();         parameterObject.put("arg0", 123L);         parameterObject.put("arg1", "ACTIVE");         parameterObject.put("param1", 123L);         parameterObject.put("param2", "ACTIVE");                // 通过属性名获取值         Object value1 = ((Map) parameterObject).get("arg0"); // 123L         Object value2 = ((Map) parameterObject).get("arg1"); // "ACTIVE"                System.out.println("第一个参数: " + value1);         System.out.println("第二个参数: " + value2);     } }

6.2 复杂对象参数处理

/**  * 复杂对象参数处理示例  * 当参数是POJO对象时，通过MetaObject反射获取属性值  */ public class ComplexParameterExample {        /**      * POJO对象参数      * SQL: INSERT INTO user (name, email, age) VALUES (?, ?, ?)      */     @Test     public void testPojoParameter() {         // 参数对象是User POJO         User parameterObject = new User();         parameterObject.setName("张三");         parameterObject.setEmail("zhangsan@example.com");         parameterObject.setAge(25);                // MyBatis检测User类型没有内置TypeHandler         boolean hasTypeHandler = typeHandlerRegistry.hasTypeHandler(parameterObject.getClass());         System.out.println("User类型有TypeHandler: " + hasTypeHandler); // false                if (!hasTypeHandler) {             // 创建MetaObject进行反射操作             MetaObject metaObject = configuration.newMetaObject(parameterObject);                        // 通过属性名获取值             Object nameValue = metaObject.getValue("name");       // "张三"             Object emailValue = metaObject.getValue("email");     // "zhangsan@example.com"             Object ageValue = metaObject.getValue("age");         // 25                        System.out.println("name属性值: " + nameValue);             System.out.println("email属性值: " + emailValue);             System.out.println("age属性值: " + ageValue);         }     }        /**      * 嵌套对象参数      * SQL: SELECT * FROM order WHERE user.id = ? AND user.name = ?      */     @Test     public void testNestedObjectParameter() {         // 创建嵌套对象         User user = new User();         user.setId(123L);         user.setName("张三");                Order parameterObject = new Order();         parameterObject.setUser(user);                // 通过MetaObject访问嵌套属性         MetaObject metaObject = configuration.newMetaObject(parameterObject);                Object userId = metaObject.getValue("user.id");     // 123L         Object userName = metaObject.getValue("user.name"); // "张三"                System.out.println("嵌套属性user.id: " + userId);         System.out.println("嵌套属性user.name: " + userName);     } }

6.3 集合类型参数处理

/**  * 集合类型参数处理示例  * MyBatis通过动态SQL和额外参数处理集合  */ public class CollectionParameterExample {        /**      * List参数处理      * SQL: SELECT * FROM user WHERE id IN <foreach collection="list" item="id" open="(" separator="," close=")">#{id}</foreach>      */     @Test     public void testListParameter() {         // 参数是List集合         List<Long> parameterObject = Arrays.asList(1L, 2L, 3L);                // MyBatis会将List包装为Map: {"list": [1L, 2L, 3L]}         Map<String, Object> wrappedParam = new HashMap<>();         wrappedParam.put("list", parameterObject);                // 在foreach处理过程中，会生成额外参数         BoundSql boundSql = new BoundSql(configuration, "SELECT * FROM user WHERE id IN (?, ?, ?)",              Arrays.asList(                 createParameterMapping("__frch_id_0", Long.class),                 createParameterMapping("__frch_id_1", Long.class),                 createParameterMapping("__frch_id_2", Long.class)             ), wrappedParam);                    // 设置额外参数         boundSql.setAdditionalParameter("__frch_id_0", 1L);         boundSql.setAdditionalParameter("__frch_id_1", 2L);         boundSql.setAdditionalParameter("__frch_id_2", 3L);                // 获取额外参数（最高优先级）         Object value1 = boundSql.getAdditionalParameter("__frch_id_0"); // 1L         Object value2 = boundSql.getAdditionalParameter("__frch_id_1"); // 2L         Object value3 = boundSql.getAdditionalParameter("__frch_id_2"); // 3L                System.out.println("foreach生成的参数1: " + value1);         System.out.println("foreach生成的参数2: " + value2);         System.out.println("foreach生成的参数3: " + value3);     }        /**      * Map参数处理      * SQL: SELECT * FROM user WHERE name = #{name} AND age = #{age}      */     @Test     public void testMapParameter() {         // 参数是Map         Map<String, Object> parameterObject = new HashMap<>();         parameterObject.put("name", "张三");         parameterObject.put("age", 25);                // Map类型没有内置TypeHandler，但Map实现了特殊处理         // Map参数可以直接从boundSql.getAdditionalParameter获取         // 或通过MetaObject的MapWrapper获取         MetaObject metaObject = configuration.newMetaObject(parameterObject);                // 通过Map的key获取值         Object nameValue = metaObject.getValue("name"); // "张三"         Object ageValue = metaObject.getValue("age");   // 25                System.out.println("Map参数name: " + nameValue);         System.out.println("Map参数age: " + ageValue);                // Map作为参数的特殊处理         // 当参数是Map时，MyBatis会将其包装为ParamMap         // SQL中的#{name}会直接从Map中通过"name"键获取值         System.out.println("Map参数直接映射: #{name} -> " + parameterObject.get("name"));     }        /**      * Map参数实际应用示例      */     @Test     public void testMapParameterInAction() {         Map<String, Object> params = new HashMap<>();         params.put("id", 1L);         params.put("name", "张三");         params.put("age", 25);                // 对应的Mapper方法         // List<User> findByMap(Map<String, Object> params);         // SQL: SELECT * FROM user WHERE id = #{id} AND name = #{name} AND age = #{age}                // 实际应用场景:Map参数适合动态条件查询,无需创建专门的参数对象         // MyBatis会直接从Map中获取键对应的值(如id、name、age),         // 并通过MetaObject包装后按属性名访问                System.out.println("使用Map参数查询: " + params);     } }

7. 实践案例：自定义参数处理器

7.1 参数加密处理器

让我们创建一个参数加密处理器，自动对敏感参数进行加密：

package com.example.parameter;  import org.apache.ibatis.executor.parameter.ParameterHandler; import org.apache.ibatis.mapping.BoundSql; import org.apache.ibatis.mapping.MappedStatement; import org.apache.ibatis.mapping.ParameterMapping; import org.apache.ibatis.mapping.ParameterMode; import org.apache.ibatis.reflection.MetaObject; import org.apache.ibatis.scripting.defaults.DefaultParameterHandler; import org.apache.ibatis.session.Configuration; import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.TypeHandler; import org.apache.ibatis.type.TypeHandlerRegistry;  import javax.crypto.Cipher; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.sql.PreparedStatement; import java.sql.SQLException; import java.util.Base64; import java.util.HashSet; import java.util.List; import java.util.Set;  /**  * 参数加密处理器  * 对指定的敏感参数进行自动加密  */ public class EncryptionParameterHandler implements ParameterHandler {        private final DefaultParameterHandler delegate;     private final Configuration configuration;     private final TypeHandlerRegistry typeHandlerRegistry;     private final MappedStatement mappedStatement;     private final Object parameterObject;     private final BoundSql boundSql;        // 需要加密的字段名集合     private static final Set<String> ENCRYPT_FIELDS = new HashSet<>();        // AES加密密钥（实际应用中应从配置文件读取）     private static final String ENCRYPT_KEY = "MyBatis123456789"; // 16位密钥        static {         // 配置需要加密的字段         ENCRYPT_FIELDS.add("password");         ENCRYPT_FIELDS.add("idCard");         ENCRYPT_FIELDS.add("phone");         ENCRYPT_FIELDS.add("email");     }        public EncryptionParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql) {         this.delegate = new DefaultParameterHandler(mappedStatement, parameterObject, boundSql);         this.configuration = mappedStatement.getConfiguration();         this.typeHandlerRegistry = configuration.getTypeHandlerRegistry();         this.mappedStatement = mappedStatement;         this.parameterObject = parameterObject;         this.boundSql = boundSql;     }        @Override     public Object getParameterObject() {         return delegate.getParameterObject();     }        @Override     public void setParameters(PreparedStatement ps) throws SQLException {         System.out.println("=== 使用加密参数处理器 ===");                List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();                if (parameterMappings != null) {             MetaObject metaObject = null;                        for (int i = 0; i < parameterMappings.size(); i++) {                 ParameterMapping parameterMapping = parameterMappings.get(i);                                if (parameterMapping.getMode() != ParameterMode.OUT) {                     Object value;                     String propertyName = parameterMapping.getProperty();                                        // 获取原始参数值（使用与DefaultParameterHandler相同的逻辑）                     if (boundSql.hasAdditionalParameter(propertyName)) {                         value = boundSql.getAdditionalParameter(propertyName);                     } else if (parameterObject == null) {                         value = null;                     } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {                         value = parameterObject;                     } else {                         if (metaObject == null) {                             metaObject = configuration.newMetaObject(parameterObject);                         }                         value = metaObject.getValue(propertyName);                     }                                        // 对敏感字段进行加密                     if (needEncryption(propertyName, value)) {                         String originalValue = (String) value;                         value = encryptValue(originalValue);                         System.out.println(String.format("字段 [%s] 加密: %s -> %s",                              propertyName, originalValue, value));                     }                                        // 设置参数                     TypeHandler typeHandler = parameterMapping.getTypeHandler();                     JdbcType jdbcType = parameterMapping.getJdbcType();                                        if (value == null && jdbcType == null) {                         jdbcType = configuration.getJdbcTypeForNull();                     }                                        try {                         typeHandler.setParameter(ps, i + 1, value, jdbcType);                     } catch (Exception e) {                         throw new SQLException("Could not set parameter: " + e.getMessage(), e);                     }                 }             }         }     }        /**      * 判断是否需要加密      */     private boolean needEncryption(String propertyName, Object value) {         return value instanceof String &&                 ENCRYPT_FIELDS.contains(propertyName) &&                 !((String) value).isEmpty();     }        /**      * AES加密      */     private String encryptValue(String value) {         try {             SecretKeySpec secretKey = new SecretKeySpec(ENCRYPT_KEY.getBytes(StandardCharsets.UTF_8), "AES");             Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");             cipher.init(Cipher.ENCRYPT_MODE, secretKey);                        byte[] encryptedBytes = cipher.doFinal(value.getBytes(StandardCharsets.UTF_8));             return Base64.getEncoder().encodeToString(encryptedBytes);         } catch (Exception e) {             throw new RuntimeException("参数加密失败: " + e.getMessage(), e);         }     }        /**      * 添加加密字段      */     public static void addEncryptField(String fieldName) {         ENCRYPT_FIELDS.add(fieldName);     }        /**      * 移除加密字段      */     public static void removeEncryptField(String fieldName) {         ENCRYPT_FIELDS.remove(fieldName);     } }

7.2 自定义LanguageDriver

创建自定义的LanguageDriver来使用我们的加密参数处理器：

package com.example.parameter;  import org.apache.ibatis.executor.parameter.ParameterHandler; import org.apache.ibatis.mapping.BoundSql; import org.apache.ibatis.mapping.MappedStatement; import org.apache.ibatis.mapping.SqlSource; import org.apache.ibatis.parsing.XNode; import org.apache.ibatis.scripting.LanguageDriver; import org.apache.ibatis.scripting.xmltags.XMLLanguageDriver; import org.apache.ibatis.session.Configuration;  /**  * 加密语言驱动器  * 创建加密参数处理器  */ public class EncryptionLanguageDriver extends XMLLanguageDriver implements LanguageDriver {        @Override     public ParameterHandler createParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql) {         // 根据配置决定是否使用加密处理器         Configuration configuration = mappedStatement.getConfiguration();                // 检查是否启用加密（可以通过配置或注解控制）         if (isEncryptionEnabled(mappedStatement)) {             System.out.println("创建加密参数处理器 for: " + mappedStatement.getId());             return new EncryptionParameterHandler(mappedStatement, parameterObject, boundSql);         } else {             // 使用默认参数处理器             return super.createParameterHandler(mappedStatement, parameterObject, boundSql);         }     }        /**      * 判断是否启用加密      * 可以根据MappedStatement的ID、配置等进行判断      */     private boolean isEncryptionEnabled(MappedStatement mappedStatement) {         String statementId = mappedStatement.getId();                // 示例：对包含"User"的Mapper启用加密         return statementId.contains("User");     } }

7.3 配置使用

插件注册方式

自定义ParameterHandler通常通过MyBatis插件机制注册,在 mybatis-config.xml中配置:

<plugins>     <!-- 参数验证拦截器 -->     <plugin interceptor="com.example.ValidationParameterInterceptor"/>     <!-- 参数加密拦截器 -->     <plugin interceptor="com.example.EncryptionParameterInterceptor"/> </plugins>

语言驱动器配置

<configuration>     <!-- 注册自定义语言驱动器 -->     <typeAliases>         <typeAlias alias="encryptionLanguageDriver" type="com.example.parameter.EncryptionLanguageDriver"/>     </typeAliases>        <!-- 设置默认语言驱动器 -->     <settings>         <setting name="defaultScriptingLanguage" value="encryptionLanguageDriver"/>     </settings>        <!-- 或者在特定的Mapper方法上使用 --> </configuration>

在Mapper接口中使用：

package com.example.mapper;  import org.apache.ibatis.annotations.*; import com.example.parameter.EncryptionLanguageDriver;  public interface UserMapper {        /**      * 使用默认语言驱动器（会自动加密password字段）      */     @Insert("INSERT INTO user (username, password, email) VALUES (#{username}, #{password}, #{email})")     int insertUser(User user);        /**      * 显式指定语言驱动器      */     @Lang(EncryptionLanguageDriver.class)     @Update("UPDATE user SET password = #{password} WHERE id = #{id}")     int updatePassword(@Param("id") Long id, @Param("password") String password); }

完整测试代码：

package com.example;  import org.apache.ibatis.io.Resources; import org.apache.ibatis.session.SqlSession; import org.apache.ibatis.session.SqlSessionFactory; import org.apache.ibatis.session.SqlSessionFactoryBuilder; import com.example.mapper.UserMapper; import com.example.entity.User;  import java.io.InputStream;  /**  * 加密参数处理器测试  * 演示自定义ParameterHandler的完整使用流程  */ public class EncryptionParameterTest {        public static void main(String[] args) {         SqlSessionFactory factory = MyBatisUtils.getSqlSessionFactory();                testEncryptionParameterHandler(factory);     }        /**      * 测试参数加密功能      */     private static void testEncryptionParameterHandler(SqlSessionFactory factory) {         System.out.println("=== 测试参数加密功能 ===");                try (SqlSession session = factory.openSession()) {             UserMapper mapper = session.getMapper(UserMapper.class);                        // 创建用户对象             User user = new User();             user.setUsername("testuser");             user.setPassword("mypassword123");      // 敏感信息，会被加密             user.setEmail("test@example.com");      // 敏感信息，会被加密                        System.out.println(">>> 插入用户前");             System.out.println("原始密码: " + user.getPassword());             System.out.println("原始邮箱: " + user.getEmail());                        // 插入用户（password和email字段会自动加密）             int result = mapper.insertUser(user);                        System.out.println(">>> 插入结果: " + result);                        // 更新密码测试             System.out.println(">>> 更新密码测试");             String newPassword = "newpassword456";             System.out.println("新密码: " + newPassword);                        int updateResult = mapper.updatePassword(1L, newPassword);             System.out.println("更新结果: " + updateResult);                        session.commit();         }     } }

7.4 参数验证处理器

再创建一个参数验证处理器：

package com.example.parameter;  import org.apache.ibatis.executor.parameter.ParameterHandler; import org.apache.ibatis.mapping.BoundSql; import org.apache.ibatis.mapping.MappedStatement; import org.apache.ibatis.mapping.ParameterMapping; import org.apache.ibatis.mapping.ParameterMode; import org.apache.ibatis.reflection.MetaObject; import org.apache.ibatis.scripting.defaults.DefaultParameterHandler; import org.apache.ibatis.session.Configuration; import org.apache.ibatis.type.TypeHandlerRegistry;  import java.sql.PreparedStatement; import java.sql.SQLException; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.function.Predicate; import java.util.regex.Pattern;  /**  * 参数验证处理器  * 在设置参数前进行数据验证  */ public class ValidationParameterHandler implements ParameterHandler {        private final DefaultParameterHandler delegate;     private final Configuration configuration;     private final TypeHandlerRegistry typeHandlerRegistry;     private final MappedStatement mappedStatement;     private final Object parameterObject;     private final BoundSql boundSql;        // 验证规则映射     private static final Map<String, Predicate<Object>> VALIDATION_RULES = new HashMap<>();        static {         // 邮箱格式验证         VALIDATION_RULES.put("email", value -> {             if (value == null) return true;             String email = value.toString();             return Pattern.matches("^[A-Za-z0-9+_.-]+@([A-Za-z0-9.-]+\.[A-Za-z]{2,})$", email);         });                // 手机号格式验证         VALIDATION_RULES.put("phone", value -> {             if (value == null) return true;             String phone = value.toString();             return Pattern.matches("^1[3-9]\d{9}$", phone);         });                // 用户名长度验证         VALIDATION_RULES.put("username", value -> {             if (value == null) return false;             String username = value.toString();             return username.length() >= 3 && username.length() <= 20;         });                // 密码强度验证         VALIDATION_RULES.put("password", value -> {             if (value == null) return false;             String password = value.toString();             // 至少8位，包含字母和数字             return password.length() >= 8 &&                     Pattern.matches(".*[A-Za-z].*", password) &&                     Pattern.matches(".*\d.*", password);         });     }        public ValidationParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql) {         this.delegate = new DefaultParameterHandler(mappedStatement, parameterObject, boundSql);         this.configuration = mappedStatement.getConfiguration();         this.typeHandlerRegistry = configuration.getTypeHandlerRegistry();         this.mappedStatement = mappedStatement;         this.parameterObject = parameterObject;         this.boundSql = boundSql;     }        @Override     public Object getParameterObject() {         return delegate.getParameterObject();     }        @Override     public void setParameters(PreparedStatement ps) throws SQLException {         System.out.println("=== 使用验证参数处理器 ===");                // 首先进行参数验证         validateParameters();                // 验证通过后，委托给默认处理器         delegate.setParameters(ps);     }        /**      * 验证所有参数      */     private void validateParameters() {         List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();                if (parameterMappings != null) {             MetaObject metaObject = null;                        for (ParameterMapping parameterMapping : parameterMappings) {                 if (parameterMapping.getMode() != ParameterMode.OUT) {                     Object value;                     String propertyName = parameterMapping.getProperty();                                        // 获取参数值                     if (boundSql.hasAdditionalParameter(propertyName)) {                         value = boundSql.getAdditionalParameter(propertyName);                     } else if (parameterObject == null) {                         value = null;                     } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {                         value = parameterObject;                     } else {                         if (metaObject == null) {                             metaObject = configuration.newMetaObject(parameterObject);                         }                         value = metaObject.getValue(propertyName);                     }                                        // 执行验证                     validateParameter(propertyName, value);                 }             }         }     }        /**      * 验证单个参数      */     private void validateParameter(String propertyName, Object value) {         Predicate<Object> validator = VALIDATION_RULES.get(propertyName);                if (validator != null) {             boolean isValid = validator.test(value);                        if (!isValid) {                 String message = String.format("参数验证失败: %s = %s", propertyName, value);                 System.err.println(message);                 throw new IllegalArgumentException(message);             } else {                 System.out.println(String.format("参数验证通过: %s = %s", propertyName, value));             }         }     }        /**      * 添加验证规则      */     public static void addValidationRule(String propertyName, Predicate<Object> validator) {         VALIDATION_RULES.put(propertyName, validator);     }        /**      * 移除验证规则      */     public static void removeValidationRule(String propertyName) {         VALIDATION_RULES.remove(propertyName);     } }

8. 源码调试指导

8.1 关键断点位置

DefaultParameterHandler断点：

DefaultParameterHandler.setParameters() - 参数设置入口
参数值获取的优先级判断逻辑
typeHandler.setParameter() - 类型处理器设置参数

ParameterMapping断点：

ParameterMapping.Builder.build() - 参数映射构建
resolveTypeHandler() - 类型处理器解析

MetaObject断点：

MetaObject.getValue() - 反射获取属性值
嵌套属性访问逻辑

8.2 调试技巧

工具建议：

使用IDEA的条件断点，表达式：parameterObject.getClass().getSimpleName().equals("User")
使用IDEA的字段监视（Field Watchpoint）观察 parameterObject的变化
启用MyBatis日志：<setting name="logImpl" value="STDOUT_LOGGING"/>

观察参数类型判断：

// 在setParameters方法中观察类型判断逻辑 if (boundSql.hasAdditionalParameter(propertyName)) {     System.out.println("使用额外参数: " + propertyName); } else if (parameterObject == null) {     System.out.println("参数对象为null"); } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {     System.out.println("参数是基本类型: " + parameterObject.getClass().getSimpleName()); } else {     System.out.println("参数是复杂对象: " + parameterObject.getClass().getSimpleName()); }

观察参数映射：

// 观察参数映射配置 for (ParameterMapping pm : boundSql.getParameterMappings()) {     System.out.println(String.format("参数映射: property=%s, javaType=%s, jdbcType=%s",          pm.getProperty(), pm.getJavaType().getSimpleName(), pm.getJdbcType())); }

观察类型处理器选择逻辑：

// 在TypeHandlerRegistry.getTypeHandler方法设置断点 // 观察类型处理器的匹配过程 TypeHandler typeHandler = parameterMapping.getTypeHandler(); System.out.println("使用的TypeHandler: " + typeHandler.getClass().getSimpleName());  // 观察TypeHandler的选择逻辑 TypeHandler<?> handler = typeHandlerRegistry.getTypeHandler(     parameterMapping.getJavaType(),      parameterMapping.getJdbcType() ); System.out.println(String.format("类型匹配: javaType=%s, jdbcType=%s -> %s",      parameterMapping.getJavaType().getSimpleName(),     parameterMapping.getJdbcType(),     handler.getClass().getSimpleName()));

9. 易错与排错清单

9.1 常见问题

问题	原因	解决方案
参数设置失败	ParameterMapping配置错误	检查参数映射的javaType和jdbcType
类型转换异常	TypeHandler选择不当	确认类型处理器配置
参数值为null	属性名拼写错误或对象为null	检查属性名和参数对象
反射失败	私有属性无getter方法	确保属性有对应的getter方法
嵌套属性访问失败	中间对象为null	检查嵌套对象的初始化
参数名不可靠	无@Param且未开启-parameters编译选项	使用@Param注解或启用编译参数保留
动态SQL参数错误	`<foreach>`的collection配置错误导致参数缺失	检查collection属性与实际参数类型匹配(list/array/map key),使用@Param明确命名避免歧义

9.2 性能优化建议

复用TypeHandler:为常用类型注册TypeHandler,避免每次查询都创建新实例
避免过度反射:复杂对象参数尽量使用字段直接访问,减少getter调用。MetaObject缓存可减少10-15%反射开销,通过 Reflector缓存属性元数据避免重复解析
批量操作优化:使用 executorType="BATCH"配合 addBatch,减少参数设置次数
参数命名规范:避免使用过长的嵌套属性(如 user.address.city.name),层级过深会增加反射开销