MyBatis源码解析：从 Mapper 接口到 SQL 执行的完整链路

MyBatis 的底层本质是对 JDBC 的封装，因此建议忘记 JDBC 执行流程的同砚回首相干知识。可参考这篇文章：【JDBC 核心执行流程详解】
在 MyBatis 中，常用的查询方式是通过 Mapper 接口署理实现，而非直接调用 sqlSession.selectList 例如：

1. // Mapper 接口定义
2. public interface UserMapper {
3.     List<User> selectUser(@Param("name") String name, @Param("age") Integer age);
4. }
6. // 应用层调用（通过代理对象执行）
7. UserMapper mapper = sqlSession.getMapper(UserMapper.class);
8. List<User> users = mapper.selectUser("coderzpw", 18); // 核心：代理对象处理方法调用

复制代码

接下来文章内容主要围绕上述代码的底层源码逻辑展开讲解
一、Mapper 署理对象的创建：sqlSession.getMapper(UserMapper.class)

当调用 sqlSession.getMapper(UserMapper.class) 时，MyBatis 通过 MapperProxyFactory 创建动态署理对象，涉及到源码如下：

1. // DefaultSqlSession.java
2. public <T> T getMapper(Class<T> type) {
3.   return configuration.<T>getMapper(type, this);
4. }

复制代码

1. // Configuration.java
2. public <T> T getMapper(Class<T> type, SqlSession sqlSession) {
3.   return mapperRegistry.getMapper(type, sqlSession);
4. }

复制代码

1. // MapperRegistry.java
2. public <T> T getMapper(Class<T> type, SqlSession sqlSession) {
3.   // 从已知的Mapper映射中查找对应的Mapper代理工厂
4.   final MapperProxyFactory<T> mapperProxyFactory = (MapperProxyFactory<T>) knownMappers.get(type);
5.   // 如果找不到对应的Mapper代理工厂，抛出绑定异常
6.   if (mapperProxyFactory == null) {
7.     throw new BindingException("Type " + type + " is not known to the MapperRegistry.");
8.   }
9.   try {
10.     // 使用代理工厂创建Mapper代理实例
11.     return mapperProxyFactory.newInstance(sqlSession);
12.   } catch (Exception e) {
13.     throw new BindingException("Error getting mapper instance. Cause: " + e, e);
14.   }
15. }

复制代码

1. // MapperProxyFactory.java
3. public T newInstance(SqlSession sqlSession) {
4.   // 创建Mapper代理处理器，它实现了InvocationHandler接口
5.   // 参数1：当前SqlSession，用于执行SQL语句
6.   // 参数2：Mapper接口类型
7.   // 参数3：方法缓存，用于缓存Mapper方法对应的SQL语句
8.   final MapperProxy<T> mapperProxy = new MapperProxy<T>(sqlSession, mapperInterface, methodCache);
9.   return newInstance(mapperProxy);
10. }
12. protected T newInstance(MapperProxy<T> mapperProxy) {
13.   // 使用JDK动态代理创建代理对象
14.   // 参数1：类加载器，使用Mapper接口的类加载器
15.   // 参数2：代理对象要实现的接口，这里就是Mapper接口
16.   // 参数3：代理对象的调用处理器，负责处理代理对象方法的调用
17.   return (T) Proxy.newProxyInstance(mapperInterface.getClassLoader(), new Class[] { mapperInterface }, mapperProxy);
18. }

复制代码

梳理源码逻辑后，执行到 UserMapper mapper = sqlSession.getMapper(UserMapper.class) 时，MyBatis 通过动态署理为 UserMapper 接口生成署理对象，该对象会在后续数据访问中把接口方法调用转为 SQL 执行流程。
二、接口方法的执行：mapper.selectUser(“coderzpw”, 18)

2.1 四大核心组件解析

后续查询由 MyBatis 四大核心组件协同完成：

• Executor（执行器）：控制整体查询流程
  
• StatementHandler（语句处理器）：准备并执行 SQL
  
• ParameterHandler（参数处理器）：处理 SQL 参数设置
  
• ResultSetHandler（结果集处理器）：将查询结果映射为 Java 对象
  

2.1.1 Executor（执行器）：流程控制核心

类层级：

1. Executor（接口）
2. ├─ BaseExecutor（抽象类，实现一级缓存 + 事务管理）
3. │  ├─ SimpleExecutor（默认执行器，每次创建新 Statement）
4. │  ├─ ReuseExecutor（复用 Statement，基于 SimpleExecutor 扩展）
5. │  └─ BatchExecutor（批量执行，基于 SimpleExecutor 扩展）
6. └─ CachingExecutor（二级缓存装饰器，包装 Executor 实现缓存）

复制代码

关键方法：query（处理查询）、update（处理更新）
核心源码片段（BaseExecutor）：

1. public abstract class BaseExecutor implements Executor {
2.     // 一级缓存（本地缓存）
3.     private final PerpetualCache localCache = new PerpetualCache("LocalCache");
4.     // 占位符对象，用于标记正在执行的查询
5.     private static final Object EXECUTION_PLACEHOLDER = new Object();
7.     @Override
8.     public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) {
9.         BoundSql boundSql = ms.getBoundSql(parameter);
10.         // 生成缓存键（基于 SQL、参数、RowBounds 等）
11.         CacheKey key = createCacheKey(ms, parameter, rowBounds, boundSql);
12.         return query(ms, parameter, rowBounds, resultHandler, key, boundSql);
13.     }
15.     public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
16.             // ...
17.             List<E> list;
18.             try {
19.              
20.               queryStack++;
21.              
22.               // 从本地缓存获取结果
23.               list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
24.               // 如果缓存命中，处理本地缓存的输出参数（如存储过程的OUT参数）
25.               if (list != null) {
26.                 handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
27.               } else {
28.                 // 缓存未命中，从数据库查询并缓存结果
29.                 list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
30.               }
31.             } finally {
32.               queryStack--;
33.             }
34.             // ...
35.             // 返回查询结果列表
36.             return list;
37.         }
39.     private <E> List<E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) {
40.         List<E> list;
41.         // 先在缓存中放入占位符，标记该查询正在执行
42.         localCache.putObject(key, EXECUTION_PLACEHOLDER);
43.         try {
44.             // 执行实际的数据库查询
45.             list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
46.         } finally {
47.             // 移除占位符
48.             localCache.removeObject(key);
49.         }
50.         // 将实际查询结果存入缓存
51.         localCache.putObject(key, list);
52.         
53.         // 处理存储过程的输出参数（本文示例不涉及）
54.         if (ms.getStatementType() == StatementType.CALLABLE) {
55.             localOutputParameterCache.putObject(key, parameter);
56.         }
57.         return list;
58.     }
60.           
61.         // 子类实现具体执行逻辑（如 SimpleExecutor 的 doQuery）
62.         protected abstract <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException;
63. }

复制代码

2.1.2 StatementHandler（语句处理器）：JDBC 操纵封装

类层级：

1. StatementHandler（接口）
2. ├─ BaseStatementHandler（抽象类，实现公共逻辑）
3. │  ├─ SimpleStatementHandler（处理普通 Statement，无参数）
4. │  ├─ PreparedStatementHandler（处理预编译 PreparedStatement，带参数）
5. │  └─ CallableStatementHandler（处理存储过程 CallableStatement）
6. └─ RoutingStatementHandler（路由类，不直接处理 SQL，仅根据 StatementType 选择具体实现）

复制代码

关键方法：prepare（创建 Statement）、parameterize（设置参数）、query（执行查询）
核心源码片段（BaseExecutor）：

1. public class PreparedStatementHandler extends BaseStatementHandler {
2.     public PreparedStatementHandler(Executor executor, MappedStatement ms,
3.                                     Object parameter, RowBounds rowBounds,
4.                                     ResultHandler resultHandler, BoundSql boundSql) {
5.         super(executor, ms, parameter, rowBounds, resultHandler, boundSql);
6.     }
8.     // 创建预编译 Statement
9.     @Override
10.     protected Statement instantiateStatement(Connection connection) throws SQLException {
11.         String sql = boundSql.getSql();
12.         
13.         // 处理需要返回自动生成键的情况（如INSERT语句）
14.         if (mappedStatement.getKeyGenerator() instanceof Jdbc3KeyGenerator) {
15.             String[] keyColumnNames = mappedStatement.getKeyColumns();
16.             if (keyColumnNames == null) {
17.                     // 如果没有指定主键列名，使用默认方式返回所有生成的键
18.                 return connection.prepareStatement(sql, PreparedStatement.RETURN_GENERATED_KEYS);
19.             } else {
20.                 // 如果指定了主键列名，只返回这些列的生成键
21.                 return connection.prepareStatement(sql, keyColumnNames);
22.             }
23.         }
24.         
25.         // 处理需要指定结果集类型的情况
26.         else if (mappedStatement.getResultSetType() != null) {
27.             return connection.prepareStatement(
28.                 sql,
29.                 mappedStatement.getResultSetType().getValue(),
30.                 ResultSet.CONCUR_READ_ONLY  // 设置结果集为只读
31.             );
32.         }
33.         
34.         // 默认情况，使用标准的PreparedStatement
35.         else {
36.             return connection.prepareStatement(sql);
37.         }
38.     }
40.     // 执行查询并处理结果集
41.     @Override
42.     public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
43.         PreparedStatement ps = (PreparedStatement) statement;
44.         // 执行 SQL
45.         ps.execute();
46.         // 委托 ResultSetHandler 处理结果集
47.         return resultSetHandler.handleResultSets(ps);
48.     }
49. }

复制代码

2.1.3 ParameterHandler（参数处理器）：参数解析与绑定

实现类：DefaultParameterHandler
关键逻辑：将方法参数（如 name 和 age）映射到 SQL 占位符（?），通过 TypeHandler 转换范例
核心源码片段：

1. public void setParameters(PreparedStatement ps) {
2.   // 设置错误上下文，记录当前活动为"设置参数"，并关联到对应的参数映射ID
3.   ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());
4.   
5.   // 获取SQL语句中的参数映射列表
6.   List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
7.   
8.   // 遍历参数映射列表，为每个参数设置值
9.   if (parameterMappings != null) {
10.     for (int i = 0; i < parameterMappings.size(); i++) {
11.       ParameterMapping parameterMapping = parameterMappings.get(i);
12.       
13.       // 仅处理输入参数(IN或INOUT)，忽略输出参数(OUT)
14.       if (parameterMapping.getMode() != ParameterMode.OUT) {
15.         Object value;
16.         String propertyName = parameterMapping.getProperty();
17.         
18.         // 1. 首先检查是否为额外参数(如动态SQL中定义的参数)
19.         if (boundSql.hasAdditionalParameter(propertyName)) {
20.           value = boundSql.getAdditionalParameter(propertyName);
21.         }
22.         // 2. 检查参数对象是否为null
23.         else if (parameterObject == null) {
24.           value = null;
25.         }
26.         // 3. 检查参数对象是否可以直接使用类型处理器处理(如基本类型)
27.         else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
28.           value = parameterObject;
29.         }
30.         // 4. 对于复杂对象，使用MetaObject反射获取属性值
31.         else {
32.           MetaObject metaObject = configuration.newMetaObject(parameterObject);
33.           value = metaObject.getValue(propertyName);
34.         }
35.         
36.         // 获取参数的类型处理器和JDBC类型
37.         TypeHandler typeHandler = parameterMapping.getTypeHandler();
38.         JdbcType jdbcType = parameterMapping.getJdbcType();
39.         
40.         // 处理null值的JDBC类型
41.         if (value == null && jdbcType == null) {
42.           jdbcType = configuration.getJdbcTypeForNull();
43.         }
44.         
45.         try {
46.           // 使用类型处理器将Java对象转换为JDBC参数并设置到PreparedStatement中
47.           // 注意：JDBC参数索引从1开始，而不是从0开始
48.           typeHandler.setParameter(ps, i + 1, value, jdbcType);
49.         } catch (TypeException e) {
50.           throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
51.         } catch (SQLException e) {
52.           throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
53.         }
54.       }
55.     }
56.   }
57. }

复制代码

2.1.4 ResultSetHandler（结果集处理器）：对象映射引擎

实现类：DefaultResultSetHandler
关键逻辑：将 ResultSet 逐行映射为 Java 对象，支持 ResultMap 设置的字段到属性映射
核心源码片段：

1. public List<Object> handleResultSets(Statement stmt) throws SQLException {
2.     // 存储所有结果
3.     List<Object> results = new ArrayList<>();
4.    
5.     // 获取第一个结果集
6.     ResultSetWrapper rsw = getFirstResultSet(stmt);
7.     List<ResultMap> resultMaps = mappedStatement.getResultMaps();
8.    
9.     // 处理主结果集
10.     for (ResultMap resultMap : resultMaps) {
11.         if (rsw == null) break;
12.         handleResultSet(rsw, resultMap, results, null);
13.         rsw = getNextResultSet(stmt);
14.         // ...清理资源
15.     }
16.    
17.     // 处理命名结果集（如存储过程返回的多个结果集）
18.     String[] resultSets = mappedStatement.getResultSets();
19.     if (resultSets != null) {
20.         for (String resultSet : resultSets) {
21.             if (rsw == null) break;
22.             ResultMapping mapping = nextResultMaps.get(resultSet);
23.             if (mapping != null) {
24.                 ResultMap nestedMap = configuration.getResultMap(mapping.getNestedResultMapId());
25.                 handleResultSet(rsw, nestedMap, null, mapping);
26.             }
27.             rsw = getNextResultSet(stmt);
28.             // ...清理资源
29.         }
30.     }
31.    
32.     // 整理结果
33.     return collapseSingleResultList(results);
34. }
36. private void handleResultSet(ResultSetWrapper rsw, ResultMap resultMap, List<Object> multipleResults, ResultMapping parentMapping) throws SQLException {
37.    try {
38.        // 处理嵌套结果映射（如一对多关系）
39.        if (parentMapping != null) {
40.            handleRowValues(rsw, resultMap, null, RowBounds.DEFAULT, parentMapping);
41.        }
42.        // 处理普通结果集
43.        else {
44.            // 使用默认结果处理器收集结果
45.            if (resultHandler == null) {
46.                DefaultResultHandler defaultHandler = new DefaultResultHandler(objectFactory);
47.                handleRowValues(rsw, resultMap, defaultHandler, rowBounds, null);
48.                multipleResults.add(defaultHandler.getResultList());
49.            }
50.            // 使用自定义结果处理器
51.            else {
52.                handleRowValues(rsw, resultMap, resultHandler, rowBounds, null);
53.            }
54.        }
55.    } finally {
56.        // 关闭结果集
57.        closeResultSet(rsw.getResultSet());
58.    }
59. }

复制代码

2.2 源码解析-完整调用链路：从 Mapper 方法到结果集的全流程

接下来聚焦 List<User> users = mapper.selectUser("coderzpw", 18) 调用，执行时通过署理对象触发 MapperProxy 的 invoke 方法，进而调用 MapperMethod 的 execute 方法，MyBatis 会依方法签名和参数确定并转换 SQL。
2.2.1 调用链路步调分解

1. Mapper接口方法调用（如UserMapper.selectUser(name, age)）
2. ├─ 【MapperProxy（代理对象）】
3. │   ├─ 拦截接口方法调用，触发 invoke() 方法
4. │   ├─ 从缓存中获取对应的 MapperMethod 对象
5. │   └─ 调用 mapperMethod.execute(sqlSession, args)
6. │
7. ├─ 【MapperMethod】
8. │   ├─ 根据方法类型（SELECT/INSERT/UPDATE/DELETE）选择执行策略
9. │   ├─ 解析方法参数，构建参数对象
10. │   └─ 调用 sqlSession 对应方法（如 selectList/selectOne/insert 等）
11. │
12. ├─ 【DefaultSqlSession】
13. │   └─ 委托 Executor.query() 执行查询（Executor 组件）
14. │
15. ├─ 【Executor（SimpleExecutor）】
16. │   ├─ 创建 StatementHandler（PreparedStatementHandler）
17. │   ├─ 调用 handler.prepare() 创建 PreparedStatement（含预编译 SQL）
18. │   ├─ 调用 handler.parameterize() 触发 ParameterHandler 设置参数
19. │   └─ 调用 handler.query() 执行 SQL，获取 ResultSet
20. │
21. ├─ 【StatementHandler（PreparedStatementHandler）】
22. │   ├─ instantiateStatement() 创建 PreparedStatement（SQL: "select * from user where name = ? and age > ?"）
23. │   ├─ setParameters() 委托 ParameterHandler 绑定参数（name=? 对应 "张三"，age=? 对应 20）
24. │   └─ execute() 执行查询，返回 ResultSet 给 ResultSetHandler
25. │
26. ├─ 【ParameterHandler（DefaultParameterHandler）】
27. │   └─ setParameters() 遍历参数映射，通过 TypeHandler 转换并设置到 PreparedStatement
28. │
29. └─ 【ResultSetHandler（DefaultResultSetHandler）】
30.     ├─ handleResultSets() 遍历 ResultSet 行
31.     ├─ createResultObject() 创建 User 实例
32.     └─ 通过反射将列值（name、age 等）设置到 User 对象属性

复制代码

2.2.2 关键源码串联（MyBatis 3.4.6 版本）

步调 1：Mapper 署理对象处理方法调用

1. // MapperProxy.java
2. public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
3.     try {
4.         // 处理 Object 类的通用方法（如 toString、equals 等）
5.         if (Object.class.equals(method.getDeclaringClass())) {
6.             return method.invoke(this, args);
7.         }
8.         // 处理 Java 8 引入的接口默认方法
9.         else if (isDefaultMethod(method)) {
10.             return invokeDefaultMethod(proxy, method, args);
11.         }
12.     } catch (Throwable t) {
13.         throw ExceptionUtil.unwrapThrowable(t);
14.     }
15.    
16.     // 对 Mapper 接口定义的方法进行缓存和执行
17.     final MapperMethod mapperMethod = cachedMapperMethod(method);
18.     // 执行实际的数据库操作
19.     return mapperMethod.execute(sqlSession, args);
20. }

复制代码

1. // MapperMethod.java
2. public Object execute(SqlSession sqlSession, Object[] args) {
3.     Object result;
4.    
5.     // 根据 SQL 命令类型选择执行方法
6.     switch (command.getType()) {
7.         case INSERT: {
8.             Object param = method.convertArgsToSqlCommandParam(args);
9.             result = rowCountResult(sqlSession.insert(command.getName(), param));
10.             break;
11.         }
12.         case UPDATE: {
13.             Object param = method.convertArgsToSqlCommandParam(args);
14.             result = rowCountResult(sqlSession.update(command.getName(), param));
15.             break;
16.         }
17.         case DELETE: {
18.             Object param = method.convertArgsToSqlCommandParam(args);
19.             result = rowCountResult(sqlSession.delete(command.getName(), param));
20.             break;
21.         }
22.         case SELECT:
23.             // 处理返回值为 void 且有 ResultHandler 的情况
24.             if (method.returnsVoid() && method.hasResultHandler()) {
25.                 executeWithResultHandler(sqlSession, args);
26.                 result = null;
27.             }
28.             // 处理返回值为集合的情况
29.             else if (method.returnsMany()) {
30.                 result = executeForMany(sqlSession, args);
31.             }
32.             // 处理返回值为 Map 的情况
33.             else if (method.returnsMap()) {
34.                 result = executeForMap(sqlSession, args);
35.             }
36.             // 处理返回值为 Cursor 的情况
37.             else if (method.returnsCursor()) {
38.                 result = executeForCursor(sqlSession, args);
39.             }
40.             // 处理返回单个对象的情况
41.             else {
42.                 Object param = method.convertArgsToSqlCommandParam(args);
43.                 result = sqlSession.selectOne(command.getName(), param);
44.                 // 处理返回值为 Optional 的情况
45.                 if (method.returnsOptional() && (result == null || !method.getReturnType().equals(result.getClass()))) {
46.                     result = Optional.ofNullable(result);
47.                 }
48.             }
49.             break;
50.         case FLUSH:
51.             result = sqlSession.flushStatements();
52.             break;
53.         default:
54.             throw new BindingException("Unknown execution method for: " + command.getName());
55.     }
56.    
57.     // 处理返回值为 null 但不允许 null 的情况
58.     if (result == null && method.getReturnType().isPrimitive() && !method.returnsVoid()) {
59.         throw new BindingException("Mapper method '" + command.getName()
60.                 + " attempted to return null from a method with a primitive return type ("
61.                 + method.getReturnType() + ").");
62.     }
63.    
64.     return result;
65. }
67. // 处理多参数情况，将参数转换为 SQL 参数
68. public Object convertArgsToSqlCommandParam(Object[] args) {
69.     // 无参数
70.     if (args == null || args.length == 0) {
71.         return null;
72.     }
73.     // 单个参数且无 @Param 注解
74.     else if (args.length == 1 && !hasNamedParameters) {
75.         return args[0];
76.     }
77.     // 多个参数或有 @Param 注解
78.     else {
79.         final Map<String, Object> param = new ParamMap<>();
80.         int i = 0;
81.         // 处理 @Param 注解的参数
82.         for (String name : paramNames) {
83.             param.put(name, args[i++]);
84.         }
85.         // 为参数添加 param1, param2 等键
86.         if (paramNames.size() < args.length) {
87.             for (int j = paramNames.size(); j < args.length; j++) {
88.                 param.put("param" + String.valueOf(j + 1), args[j]);
89.             }
90.         }
91.         return param;
92.     }
93. }

复制代码

步调 2：SqlSession 委托 Executor 执行查询

1. // DefaultSqlSession.java
2. @Override
3. public <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds) {
4.     try {
5.         // 根据 statement ID 获取 MappedStatement
6.         MappedStatement ms = configuration.getMappedStatement(statement);
7.         
8.         // 委托 Executor 执行查询
9.         return executor.query(ms, wrapCollection(parameter), rowBounds, Executor.NO_RESULT_HANDLER);
10.     } catch (Exception e) {
11.         throw ExceptionFactory.wrapException("Error querying database.  Cause: " + e, e);
12.     } finally {
13.         ErrorContext.instance().reset();
14.     }
15. }
17. // 处理集合参数
18. private Object wrapCollection(final Object object) {
19.     if (object instanceof Collection) {
20.         StrictMap<Object> map = new StrictMap<>();
21.         map.put("collection", object);
22.         if (object instanceof List) {
23.             map.put("list", object);
24.         }
25.         return map;
26.     } else if (object != null && object.getClass().isArray()) {
27.         StrictMap<Object> map = new StrictMap<>();
28.         map.put("array", object);
29.         return map;
30.     }
31.     return object;
32. }

复制代码

步调 3：Executor 执行查询（以 SimpleExecutor 为例）

1. // BaseExecutor.java
2. @Override
3. public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException {
4.     // 获取 BoundSql（包含解析后的 SQL 和参数映射信息）
5.     BoundSql boundSql = ms.getBoundSql(parameter);
6.    
7.     // 创建缓存键（基于 SQL、参数、RowBounds 等）
8.     CacheKey key = createCacheKey(ms, parameter, rowBounds, boundSql);
9.    
10.     // 执行查询（可能从缓存获取）
11.     return query(ms, parameter, rowBounds, resultHandler, key, boundSql);
12. }
14. @Override
15. public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
16.     ErrorContext.instance().resource(ms.getResource()).activity("executing a query").object(ms.getId());
17.    
18.     // 如果已关闭，抛出异常
19.     if (closed) {
20.         throw new ExecutorException("Executor was closed.");
21.     }
22.    
23.     // 先清空本地缓存（针对 select 语句，一级缓存会在查询前清空）
24.     if (queryStack == 0 && ms.isFlushCacheRequired()) {
25.         clearLocalCache();
26.     }
27.    
28.     List<E> list;
29.     try {
30.         queryStack++;
31.         
32.         // 从本地缓存获取结果
33.         list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
34.         
35.         if (list != null) {
36.             // 处理存储过程的输出参数
37.             handleLocallyCachedOutputParameters(ms, key, parameter);
38.         } else {
39.             // 本地缓存未命中，执行数据库查询
40.             list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
41.         }
42.     } finally {
43.         queryStack--;
44.     }
45.    
46.     if (queryStack == 0) {
47.         // 延迟加载队列处理
48.         for (DeferredLoad deferredLoad : deferredLoads) {
49.             deferredLoad.load();
50.         }
51.         // 清空延迟加载队列
52.         deferredLoads.clear();
53.         
54.         // 一级缓存的作用域是 session，默认情况下，select 语句执行后会清空本地缓存
55.         if (configuration.getLocalCacheScope() == LocalCacheScope.STATEMENT) {
56.             clearLocalCache();
57.         }
58.     }
59.    
60.     return list;
61. }
63. // 从数据库查询
64. private <E> List<E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
65.     List<E> list;
66.    
67.     // 先在缓存中放入占位符，避免递归查询
68.     localCache.putObject(key, EXECUTION_PLACEHOLDER);
69.    
70.     try {
71.         // 调用子类的 doQuery 方法执行实际查询
72.         list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
73.     } finally {
74.         // 移除占位符
75.         localCache.removeObject(key);
76.     }
77.    
78.     // 将查询结果放入缓存
79.     localCache.putObject(key, list);
80.    
81.     // 处理存储过程的输出参数
82.     if (ms.getStatementType() == StatementType.CALLABLE) {
83.         localOutputParameterCache.putObject(key, parameter);
84.     }
85.    
86.     return list;
87. }
89. // SimpleExecutor.java
90. @Override
91. public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
92.     Statement stmt = null;
93.     try {
94.         Configuration configuration = ms.getConfiguration();
95.         
96.         // 创建 StatementHandler（路由到实际的 StatementHandler 实现）
97.         StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
98.         
99.         // 准备 Statement
100.         stmt = prepareStatement(handler, ms.getStatementLog());
101.         
102.         // 执行查询
103.         return handler.query(stmt, resultHandler);
104.     } finally {
105.         // 关闭 Statement
106.         closeStatement(stmt);
107.     }
108. }
110. // 准备 Statement
111. private Statement prepareStatement(StatementHandler handler, Log statementLog) throws SQLException {
112.     Statement stmt;
113.     // 获取数据库连接
114.     Connection connection = getConnection(statementLog);
115.    
116.     // 准备 Statement
117.     stmt = handler.prepare(connection, transaction.getTimeout());
118.    
119.     // 设置参数
120.     handler.parameterize(stmt);
121.    
122.     return stmt;
123. }

复制代码

步调 4：创建 StatementHandler（RoutingStatementHandler）

1. // Configuration.java
2. public StatementHandler newStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
3.     // 创建 StatementHandler（实际创建的是 RoutingStatementHandler）
4.     StatementHandler statementHandler = new RoutingStatementHandler(executor, mappedStatement, parameterObject, rowBounds, resultHandler, boundSql);
5.    
6.     // 应用插件（如果有）
7.     statementHandler = (StatementHandler) interceptorChain.pluginAll(statementHandler);
8.    
9.     return statementHandler;
10. }
12. // RoutingStatementHandler.java
13. public RoutingStatementHandler(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
14.     // 根据 StatementType 选择实际的 StatementHandler 实现
15.     switch (ms.getStatementType()) {
16.         case STATEMENT:
17.             delegate = new SimpleStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
18.             break;
19.         case PREPARED:
20.             // 对于预编译语句，使用 PreparedStatementHandler
21.             delegate = new PreparedStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
22.             break;
23.         case CALLABLE:
24.             delegate = new CallableStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
25.             break;
26.         default:
27.             throw new ExecutorException("Unknown statement type: " + ms.getStatementType());
28.     }
29. }

复制代码

步调 5：StatementHandler 准备 Statement

1. // BaseStatementHandler.java
2. @Override
3. public Statement prepare(Connection connection, Integer transactionTimeout) throws SQLException {
4.     ErrorContext.instance().sql(boundSql.getSql());
5.     Statement statement = null;
6.    
7.     try {
8.         // 实例化 Statement
9.         statement = instantiateStatement(connection);
10.         
11.         // 设置超时时间
12.         setStatementTimeout(statement, transactionTimeout);
13.         
14.         // 设置 fetchSize
15.         setFetchSize(statement);
16.         
17.         return statement;
18.     } catch (SQLException e) {
19.         closeStatement(statement);
20.         throw e;
21.     } catch (Exception e) {
22.         closeStatement(statement);
23.         throw new ExecutorException("Error preparing statement.  Cause: " + e, e);
24.     }
25. }
27. // PreparedStatementHandler.java
28. @Override
29. protected Statement instantiateStatement(Connection connection) throws SQLException {
30.     String sql = boundSql.getSql();
31.    
32.     // 获取主键生成策略
33.     if (mappedStatement.getKeyGenerator() instanceof Jdbc3KeyGenerator) {
34.         String[] keyColumnNames = mappedStatement.getKeyColumns();
35.         if (keyColumnNames == null) {
36.             // 没有指定主键列，使用 JDBC 3.0 规范的方法获取自增主键
37.             return connection.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS);
38.         } else {
39.             // 指定了主键列，使用指定的列获取自增主键
40.             return connection.prepareStatement(sql, keyColumnNames);
41.         }
42.     } else if (mappedStatement.getResultSetType() != null) {
43.         // 设置结果集类型
44.         return connection.prepareStatement(sql, mappedStatement.getResultSetType().getValue(), ResultSet.CONCUR_READ_ONLY);
45.     } else {
46.         // 默认情况，创建预编译语句
47.         return connection.prepareStatement(sql);
48.     }
49. }

复制代码

步调 6：ParameterHandler 设置参数

1. // BaseStatementHandler.java
2. @Override
3. public void parameterize(Statement statement) throws SQLException {
4.     // 委托 ParameterHandler 设置参数
5.     parameterHandler.setParameters((PreparedStatement) statement);
6. }
8. // DefaultParameterHandler.java
9. @Override
10. public void setParameters(PreparedStatement ps) {
11.     ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());
12.    
13.     // 获取参数映射列表
14.     List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
15.    
16.     if (parameterMappings != null) {
17.         // 遍历参数映射
18.         for (int i = 0; i < parameterMappings.size(); i++) {
19.             ParameterMapping parameterMapping = parameterMappings.get(i);
20.             
21.             // 处理非输出参数（存储过程可能有输出参数）
22.             if (parameterMapping.getMode() != ParameterMode.OUT) {
23.                 Object value;
24.                 String propertyName = parameterMapping.getProperty();
25.                
26.                 // 处理动态参数（如 _parameter、_databaseId）
27.                 if (boundSql.hasAdditionalParameter(propertyName)) {
28.                     value = boundSql.getAdditionalParameter(propertyName);
29.                 }
30.                 // 处理参数为 null 的情况
31.                 else if (parameterObject == null) {
32.                     value = null;
33.                 }
34.                 // 处理参数为基本类型的情况
35.                 else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
36.                     value = parameterObject;
37.                 }
38.                 // 处理参数为对象或 Map 的情况
39.                 else {
40.                     MetaObject metaObject = configuration.newMetaObject(parameterObject);
41.                     value = metaObject.getValue(propertyName);
42.                 }
43.                
44.                 // 获取类型处理器
45.                 TypeHandler typeHandler = parameterMapping.getTypeHandler();
46.                 JdbcType jdbcType = parameterMapping.getJdbcType();
47.                
48.                 // 处理 jdbcType 为 null 的情况
49.                 if (value == null && jdbcType == null) {
50.                     jdbcType = configuration.getJdbcTypeForNull();
51.                 }
52.                
53.                 try {
54.                     // 设置参数（核心：类型处理器将 Java 对象转换为 JDBC 类型）
55.                     typeHandler.setParameter(ps, i + 1, value, jdbcType);
56.                 } catch (TypeException e) {
57.                     throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
58.                 } catch (SQLException e) {
59.                     throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
60.                 }
61.             }
62.         }
63.     }
64. }

复制代码

步调 7：StatementHandler 执行查询

1. // PreparedStatementHandler.java
2. @Override
3. public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
4.     // 转换为 PreparedStatement
5.     PreparedStatement ps = (PreparedStatement) statement;
6.    
7.     // 执行 SQL
8.     ps.execute();
9.    
10.     // 委托 ResultSetHandler 处理结果集
11.     return resultSetHandler.handleResultSets(ps);
12. }

复制代码

步调 8：ResultSetHandler 处理结果集

1. // DefaultResultSetHandler.java
2. @Override
3. public List<Object> handleResultSets(Statement stmt) throws SQLException {
4.     ErrorContext.instance().activity("handling results").object(mappedStatement.getId());
5.    
6.     final List<Object> multipleResults = new ArrayList<>();
7.    
8.     int resultSetCount = 0;
9.    
10.     // 获取第一个结果集
11.     ResultSet rs = getFirstResultSet(stmt);
12.    
13.     // 获取结果映射列表
14.     List<ResultMap> resultMaps = mappedStatement.getResultMaps();
15.    
16.     int resultMapCount = resultMaps.size();
17.    
18.     // 验证结果映射数量
19.     validateResultMapsCount(rs, resultMapCount);
20.    
21.     // 处理所有结果集
22.     while (rs != null && resultMapCount > resultSetCount) {
23.         ResultMap resultMap = resultMaps.get(resultSetCount);
24.         
25.         // 处理单个结果集
26.         handleResultSet(rs, resultMap, multipleResults, null);
27.         
28.         // 获取下一个结果集（适用于存储过程返回多个结果集的情况）
29.         rs = getNextResultSet(stmt);
30.         
31.         // 清理资源
32.         cleanUpAfterHandlingResultSet();
33.         
34.         resultSetCount++;
35.     }
36.    
37.     // 处理结果集映射
38.     String[] resultSets = mappedStatement.getResultSets();
39.     if (resultSets != null) {
40.         while (rs != null && resultSetCount < resultSets.length) {
41.             // 处理命名结果集
42.             ResultMapping parentMapping = nextResultMaps.get(resultSets[resultSetCount]);
43.             if (parentMapping != null) {
44.                 String nestedResultMapId = parentMapping.getNestedResultMapId();
45.                 ResultMap resultMap = configuration.getResultMap(nestedResultMapId);
46.                 handleResultSet(rs, resultMap, null, parentMapping);
47.             }
48.             rs = getNextResultSet(stmt);
49.             cleanUpAfterHandlingResultSet();
50.             resultSetCount++;
51.         }
52.     }
53.    
54.     // 处理单个结果集的情况，将其展开为列表
55.     return collapseSingleResultList(multipleResults);
56. }
58. // 处理单个结果集
59. private void handleResultSet(ResultSet rs, ResultMap resultMap, List<Object> multipleResults, ResultMapping parentMapping) throws SQLException {
60.     try {
61.         if (parentMapping != null) {
62.             // 处理嵌套结果集
63.             handleRowValues(rs, resultMap, null, RowBounds.DEFAULT, parentMapping);
64.         } else {
65.             // 处理普通结果集
66.             if (resultHandler == null) {
67.                 // 创建默认结果处理器
68.                 DefaultResultHandler defaultResultHandler = new DefaultResultHandler(objectFactory);
69.                
70.                 // 处理行值
71.                 handleRowValues(rs, resultMap, defaultResultHandler, rowBounds, null);
72.                
73.                 // 将结果添加到多个结果列表中
74.                 multipleResults.add(defaultResultHandler.getResultList());
75.             } else {
76.                 // 使用用户提供的结果处理器
77.                 handleRowValues(rs, resultMap, resultHandler, rowBounds, null);
78.             }
79.         }
80.     } finally {
81.         // 关闭结果集
82.         closeResultSet(rs);
83.     }
84. }
86. // 处理行值
87. private void handleRowValues(ResultSet rs, ResultMap resultMap, ResultHandler resultHandler, RowBounds rowBounds, ResultMapping parentMapping) throws SQLException {
88.     if (resultMap.hasNestedResultMaps()) {
89.         // 处理包含嵌套结果映射的情况
90.         ensureNoRowBounds();
91.         checkResultHandler();
92.         handleRowValuesForNestedResultMap(rs, resultMap, resultHandler, rowBounds, parentMapping);
93.     } else {
94.         // 处理简单结果映射的情况
95.         handleRowValuesForSimpleResultMap(rs, resultMap, resultHandler, rowBounds);
96.     }
97. }
99. // 处理简单结果映射的行值
100. private void handleRowValuesForSimpleResultMap(ResultSet rs, ResultMap resultMap, ResultHandler resultHandler, RowBounds rowBounds) throws SQLException {
101.     DefaultResultContext<Object> resultContext = new DefaultResultContext<>();
102.    
103.     // 跳过分页偏移量
104.     skipRows(rs, rowBounds.getOffset());
105.    
106.     // 处理行数据
107.     while (shouldProcessMoreRows(resultContext, rowBounds) && rs.next()) {
108.         // 获取判别式结果映射（用于动态结果映射）
109.         ResultMap discriminatedResultMap = resolveDiscriminatedResultMap(rs, resultMap, null);
110.         
111.         // 获取行值（创建结果对象并填充数据）
112.         Object rowValue = getRowValue(rs, discriminatedResultMap);
113.         
114.         // 将行值添加到结果上下文中
115.         resultContext.nextResultObject(rowValue);
116.         
117.         // 如果有结果处理器，调用它处理结果
118.         if (resultHandler != null) {
119.             resultHandler.handleResult(resultContext);
120.         }
121.     }
122. }
124. // 获取行值（创建结果对象并填充数据）
125. private Object getRowValue(ResultSet rs, ResultMap resultMap) throws SQLException {
126.     final ResultLoaderMap lazyLoader = new ResultLoaderMap();
127.    
128.     // 创建结果对象
129.     Object rowValue = createResultObject(rs, resultMap, lazyLoader, null);
130.    
131.     if (rowValue != null && !resultMap.isPrimitive()) {
132.         // 创建元对象
133.         MetaObject metaObject = configuration.newMetaObject(rowValue);
134.         
135.         // 标记是否找到值
136.         boolean foundValues = this.useConstructorMappings;
137.         
138.         // 处理自动映射
139.         if (shouldApplyAutomaticMappings(resultMap, false)) {
140.             foundValues = applyAutomaticMappings(rs, resultMap, metaObject, null) || foundValues;
141.         }
142.         
143.         // 处理手动映射
144.         foundValues = applyPropertyMappings(rs, resultMap, metaObject, lazyLoader, null) || foundValues;
145.         
146.         // 如果没有找到任何值且需要非空结果，则返回 null
147.         foundValues = lazyLoader.size() > 0 || foundValues;
148.         rowValue = foundValues || configuration.isReturnInstanceForEmptyRow() ? rowValue : null;
149.     }
150.    
151.     return rowValue;
152. }
154. // 创建结果对象
155. private Object createResultObject(ResultSet rs, ResultMap resultMap, ResultLoaderMap lazyLoader, String columnPrefix) throws SQLException {
156.     this.useConstructorMappings = false; // 重置构造函数映射标志
157.    
158.     // 获取结果类型
159.     final Class<?> resultType = resultMap.getType();
160.    
161.     // 创建元对象处理器
162.     final List<Class<?>> constructorArgTypes = new ArrayList<>();
163.     final List<Object> constructorArgs = new ArrayList<>();
164.    
165.     // 创建结果对象
166.     Object resultObject = createResultObject(rs, resultType, constructorArgTypes, constructorArgs, columnPrefix);
167.    
168.     // 如果结果类型不是基本类型
169.     if (resultObject != null && !resultType.isInterface()) {
170.         // 检查是否有构造函数映射
171.         if (shouldApplyAutomaticMappings(resultMap, true)) {
172.             // 应用自动映射
173.             applyAutomaticMappings(rs, resultMap, configuration.newMetaObject(resultObject), columnPrefix);
174.         }
175.         
176.         // 应用属性映射
177.         applyPropertyMappings(rs, resultMap, configuration.newMetaObject(resultObject), lazyLoader, columnPrefix);
178.     }
179.    
180.     // 标记使用了构造函数映射
181.     this.useConstructorMappings = resultObject != null && !constructorArgTypes.isEmpty();
182.    
183.     return resultObject;
184. }

复制代码