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

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

接下来文章内容主要围绕上述代码的底层源码逻辑展开讲解

一、Mapper 代理对象的创建：sqlSession.getMapper(UserMapper.class)

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

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

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

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

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

梳理源码逻辑后，执行到 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（执行器）：流程控制核心

类层级：

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

关键方法：query（处理查询）、update（处理更新）

核心源码片段（BaseExecutor）：

public
abstract
class BaseExecutor
implements Executor {
// 一级缓存（本地缓存）
private
final PerpetualCache localCache =
new PerpetualCache("LocalCache"
)
;
// 占位符对象，用于标记正在执行的查询
private
static
final Object EXECUTION_PLACEHOLDER =
new Object(
)
;
@Override
public <
E> List<
E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) {
BoundSql boundSql = ms.getBoundSql(parameter)
;
// 生成缓存键（基于 SQL、参数、RowBounds 等）
CacheKey key = createCacheKey(ms, parameter, rowBounds, boundSql)
;
return query(ms, parameter, rowBounds, resultHandler, key, boundSql)
;
}
public <
E> List<
E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql)
throws SQLException {
// ...
List<
E> list;
try {
queryStack++
;
// 从本地缓存获取结果
list = resultHandler ==
null ? (List<
E>
) localCache.getObject(key) :
null
;
// 如果缓存命中，处理本地缓存的输出参数（如存储过程的OUT参数）
if (list !=
null
) {
handleLocallyCachedOutputParameters(ms, key, parameter, boundSql)
;
}
else {
// 缓存未命中，从数据库查询并缓存结果
list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql)
;
}
}
finally {
queryStack--
;
}
// ...
// 返回查询结果列表
return list;
}
private <
E> List<
E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) {
List<
E> list;
// 先在缓存中放入占位符，标记该查询正在执行
localCache.putObject(key, EXECUTION_PLACEHOLDER
)
;
try {
// 执行实际的数据库查询
list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql)
;
}
finally {
// 移除占位符
localCache.removeObject(key)
;
}
// 将实际查询结果存入缓存
localCache.putObject(key, list)
;
// 处理存储过程的输出参数（本文示例不涉及）
if (ms.getStatementType(
) == StatementType.CALLABLE
) {
localOutputParameterCache.putObject(key, parameter)
;
}
return list;
}
// 子类实现具体执行逻辑（如 SimpleExecutor 的 doQuery）
protected
abstract <
E> List<
E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql)
throws SQLException
;
}

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

类层级：

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

关键方法：prepare（创建 Statement）、parameterize（设置参数）、query（执行查询）

核心源码片段（BaseExecutor）：

public
class PreparedStatementHandler
extends BaseStatementHandler {
public PreparedStatementHandler(Executor executor, MappedStatement ms,
Object parameter, RowBounds rowBounds,
ResultHandler resultHandler, BoundSql boundSql) {
super(executor, ms, parameter, rowBounds, resultHandler, boundSql)
;
}
// 创建预编译 Statement
@Override
protected Statement instantiateStatement(Connection connection)
throws SQLException {
String sql = boundSql.getSql(
)
;
// 处理需要返回自动生成键的情况（如INSERT语句）
if (mappedStatement.getKeyGenerator(
)
instanceof Jdbc3KeyGenerator
) {
String[] keyColumnNames = mappedStatement.getKeyColumns(
)
;
if (keyColumnNames ==
null
) {
// 如果没有指定主键列名，使用默认方式返回所有生成的键
return connection.prepareStatement(sql, PreparedStatement.RETURN_GENERATED_KEYS
)
;
}
else {
// 如果指定了主键列名，只返回这些列的生成键
return connection.prepareStatement(sql, keyColumnNames)
;
}
}
// 处理需要指定结果集类型的情况
else
if (mappedStatement.getResultSetType(
) !=
null
) {
return connection.prepareStatement(
sql,
mappedStatement.getResultSetType(
).getValue(
)
,
ResultSet.CONCUR_READ_ONLY // 设置结果集为只读
)
;
}
// 默认情况，使用标准的PreparedStatement
else {
return connection.prepareStatement(sql)
;
}
}
// 执行查询并处理结果集
@Override
public <
E> List<
E> query(Statement statement, ResultHandler resultHandler)
throws SQLException {
PreparedStatement ps = (PreparedStatement
) statement;
// 执行 SQL
ps.execute(
)
;
// 委托 ResultSetHandler 处理结果集
return resultSetHandler.handleResultSets(ps)
;
}
}

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

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

public
void setParameters(PreparedStatement ps) {
// 设置错误上下文，记录当前活动为"设置参数"，并关联到对应的参数映射ID
ErrorContext.instance(
).activity("setting parameters"
).object(mappedStatement.getParameterMap(
).getId(
)
)
;
// 获取SQL语句中的参数映射列表
List<
ParameterMapping> parameterMappings = boundSql.getParameterMappings(
)
;
// 遍历参数映射列表，为每个参数设置值
if (parameterMappings !=
null
) {
for (
int i = 0
; i < parameterMappings.size(
)
; i++
) {
ParameterMapping parameterMapping = parameterMappings.get(i)
;
// 仅处理输入参数(IN或INOUT)，忽略输出参数(OUT)
if (parameterMapping.getMode(
) != ParameterMode.OUT
) {
Object value;
String propertyName = parameterMapping.getProperty(
)
;
// 1. 首先检查是否为额外参数(如动态SQL中定义的参数)
if (boundSql.hasAdditionalParameter(propertyName)
) {
value = boundSql.getAdditionalParameter(propertyName)
;
}
// 2. 检查参数对象是否为null
else
if (parameterObject ==
null
) {
value =
null
;
}
// 3. 检查参数对象是否可以直接使用类型处理器处理(如基本类型)
else
if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass(
)
)
) {
value = parameterObject;
}
// 4. 对于复杂对象，使用MetaObject反射获取属性值
else {
MetaObject metaObject = configuration.newMetaObject(parameterObject)
;
value = metaObject.getValue(propertyName)
;
}
// 获取参数的类型处理器和JDBC类型
TypeHandler typeHandler = parameterMapping.getTypeHandler(
)
;
JdbcType jdbcType = parameterMapping.getJdbcType(
)
;
// 处理null值的JDBC类型
if (value ==
null && jdbcType ==
null
) {
jdbcType = configuration.getJdbcTypeForNull(
)
;
}
try {
// 使用类型处理器将Java对象转换为JDBC参数并设置到PreparedStatement中
// 注意：JDBC参数索引从1开始，而不是从0开始
typeHandler.setParameter(ps, i + 1
, value, jdbcType)
;
}
catch (TypeException e) {
throw
new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e)
;
}
catch (SQLException e) {
throw
new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e)
;
}
}
}
}
}

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

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

public List<
Object> handleResultSets(Statement stmt)
throws SQLException {
// 存储所有结果
List<
Object> results =
new ArrayList<
>(
)
;
// 获取第一个结果集
ResultSetWrapper rsw = getFirstResultSet(stmt)
;
List<
ResultMap> resultMaps = mappedStatement.getResultMaps(
)
;
// 处理主结果集
for (ResultMap resultMap : resultMaps) {
if (rsw ==
null
)
break
;
handleResultSet(rsw, resultMap, results,
null
)
;
rsw = getNextResultSet(stmt)
;
// ...清理资源
}
// 处理命名结果集（如存储过程返回的多个结果集）
String[] resultSets = mappedStatement.getResultSets(
)
;
if (resultSets !=
null
) {
for (String resultSet : resultSets) {
if (rsw ==
null
)
break
;
ResultMapping mapping = nextResultMaps.get(resultSet)
;
if (mapping !=
null
) {
ResultMap nestedMap = configuration.getResultMap(mapping.getNestedResultMapId(
)
)
;
handleResultSet(rsw, nestedMap,
null
, mapping)
;
}
rsw = getNextResultSet(stmt)
;
// ...清理资源
}
}
// 整理结果
return collapseSingleResultList(results)
;
}
private
void handleResultSet(ResultSetWrapper rsw, ResultMap resultMap, List<
Object> multipleResults, ResultMapping parentMapping)
throws SQLException {
try {
// 处理嵌套结果映射（如一对多关系）
if (parentMapping !=
null
) {
handleRowValues(rsw, resultMap,
null
, RowBounds.DEFAULT
, parentMapping)
;
}
// 处理普通结果集
else {
// 使用默认结果处理器收集结果
if (resultHandler ==
null
) {
DefaultResultHandler defaultHandler =
new DefaultResultHandler(objectFactory)
;
handleRowValues(rsw, resultMap, defaultHandler, rowBounds,
null
)
;
multipleResults.add(defaultHandler.getResultList(
)
)
;
}
// 使用自定义结果处理器
else {
handleRowValues(rsw, resultMap, resultHandler, rowBounds,
null
)
;
}
}
}
finally {
// 关闭结果集
closeResultSet(rsw.getResultSet(
)
)
;
}
}

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

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

2.2.1 调用链路步骤分解

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

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

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

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

// MapperMethod.java
public Object execute(SqlSession sqlSession, Object[] args) {
Object result;
// 根据 SQL 命令类型选择执行方法
switch (command.getType(
)
) {
case INSERT: {
Object param = method.convertArgsToSqlCommandParam(args)
;
result = rowCountResult(sqlSession.insert(command.getName(
)
, param)
)
;
break
;
}
case UPDATE: {
Object param = method.convertArgsToSqlCommandParam(args)
;
result = rowCountResult(sqlSession.update(command.getName(
)
, param)
)
;
break
;
}
case DELETE: {
Object param = method.convertArgsToSqlCommandParam(args)
;
result = rowCountResult(sqlSession.delete(command.getName(
)
, param)
)
;
break
;
}
case SELECT:
// 处理返回值为 void 且有 ResultHandler 的情况
if (method.returnsVoid(
) && method.hasResultHandler(
)
) {
executeWithResultHandler(sqlSession, args)
;
result =
null
;
}
// 处理返回值为集合的情况
else
if (method.returnsMany(
)
) {
result = executeForMany(sqlSession, args)
;
}
// 处理返回值为 Map 的情况
else
if (method.returnsMap(
)
) {
result = executeForMap(sqlSession, args)
;
}
// 处理返回值为 Cursor 的情况
else
if (method.returnsCursor(
)
) {
result = executeForCursor(sqlSession, args)
;
}
// 处理返回单个对象的情况
else {
Object param = method.convertArgsToSqlCommandParam(args)
;
result = sqlSession.selectOne(command.getName(
)
, param)
;
// 处理返回值为 Optional 的情况
if (method.returnsOptional(
) &&
(result ==
null || !method.getReturnType(
).equals(result.getClass(
)
)
)
) {
result = Optional.ofNullable(result)
;
}
}
break
;
case FLUSH:
result = sqlSession.flushStatements(
)
;
break
;
default:
throw
new BindingException("Unknown execution method for: " + command.getName(
)
)
;
}
// 处理返回值为 null 但不允许 null 的情况
if (result ==
null && method.getReturnType(
).isPrimitive(
) &&
!method.returnsVoid(
)
) {
throw
new BindingException("Mapper method '" + command.getName(
)
+ " attempted to return null from a method with a primitive return type ("
+ method.getReturnType(
) + ")."
)
;
}
return result;
}
// 处理多参数情况，将参数转换为 SQL 参数
public Object convertArgsToSqlCommandParam(Object[] args) {
// 无参数
if (args ==
null || args.length == 0
) {
return
null
;
}
// 单个参数且无 @Param 注解
else
if (args.length == 1 &&
!hasNamedParameters) {
return args[0]
;
}
// 多个参数或有 @Param 注解
else {
final Map<
String
, Object> param =
new ParamMap<
>(
)
;
int i = 0
;
// 处理 @Param 注解的参数
for (String name : paramNames) {
param.put(name, args[i++]
)
;
}
// 为参数添加 param1, param2 等键
if (paramNames.size(
) < args.length) {
for (
int j = paramNames.size(
)
; j < args.length; j++
) {
param.put("param" + String.valueOf(j + 1
)
, args[j]
)
;
}
}
return param;
}
}

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

// DefaultSqlSession.java
@Override
public <
E> List<
E> selectList(String statement, Object parameter, RowBounds rowBounds) {
try {
// 根据 statement ID 获取 MappedStatement
MappedStatement ms = configuration.getMappedStatement(statement)
;
// 委托 Executor 执行查询
return executor.query(ms, wrapCollection(parameter)
, rowBounds, Executor.NO_RESULT_HANDLER
)
;
}
catch (Exception e) {
throw ExceptionFactory.wrapException("Error querying database. Cause: " + e, e)
;
}
finally {
ErrorContext.instance(
).reset(
)
;
}
}
// 处理集合参数
private Object wrapCollection(
final Object object) {
if (object instanceof Collection
) {
StrictMap<
Object> map =
new StrictMap<
>(
)
;
map.put("collection"
, object)
;
if (object instanceof List
) {
map.put("list"
, object)
;
}
return map;
}
else
if (object !=
null && object.getClass(
).isArray(
)
) {
StrictMap<
Object> map =
new StrictMap<
>(
)
;
map.put("array"
, object)
;
return map;
}
return object;
}

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

// BaseExecutor.java
@Override
public <
E> List<
E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler)
throws SQLException {
// 获取 BoundSql（包含解析后的 SQL 和参数映射信息）
BoundSql boundSql = ms.getBoundSql(parameter)
;
// 创建缓存键（基于 SQL、参数、RowBounds 等）
CacheKey key = createCacheKey(ms, parameter, rowBounds, boundSql)
;
// 执行查询（可能从缓存获取）
return query(ms, parameter, rowBounds, resultHandler, key, boundSql)
;
}
@Override
public <
E> List<
E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql)
throws SQLException {
ErrorContext.instance(
).resource(ms.getResource(
)
).activity("executing a query"
).object(ms.getId(
)
)
;
// 如果已关闭，抛出异常
if (closed) {
throw
new ExecutorException("Executor was closed."
)
;
}
// 先清空本地缓存（针对 select 语句，一级缓存会在查询前清空）
if (queryStack == 0 && ms.isFlushCacheRequired(
)
) {
clearLocalCache(
)
;
}
List<
E> list;
try {
queryStack++
;
// 从本地缓存获取结果
list = resultHandler ==
null ? (List<
E>
) localCache.getObject(key) :
null
;
if (list !=
null
) {
// 处理存储过程的输出参数
handleLocallyCachedOutputParameters(ms, key, parameter)
;
}
else {
// 本地缓存未命中，执行数据库查询
list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql)
;
}
}
finally {
queryStack--
;
}
if (queryStack == 0
) {
// 延迟加载队列处理
for (DeferredLoad deferredLoad : deferredLoads) {
deferredLoad.load(
)
;
}
// 清空延迟加载队列
deferredLoads.clear(
)
;
// 一级缓存的作用域是 session，默认情况下，select 语句执行后会清空本地缓存
if (configuration.getLocalCacheScope(
) == LocalCacheScope.STATEMENT
) {
clearLocalCache(
)
;
}
}
return list;
}
// 从数据库查询
private <
E> List<
E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql)
throws SQLException {
List<
E> list;
// 先在缓存中放入占位符，避免递归查询
localCache.putObject(key, EXECUTION_PLACEHOLDER
)
;
try {
// 调用子类的 doQuery 方法执行实际查询
list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql)
;
}
finally {
// 移除占位符
localCache.removeObject(key)
;
}
// 将查询结果放入缓存
localCache.putObject(key, list)
;
// 处理存储过程的输出参数
if (ms.getStatementType(
) == StatementType.CALLABLE
) {
localOutputParameterCache.putObject(key, parameter)
;
}
return list;
}
// SimpleExecutor.java
@Override
public <
E> List<
E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql)
throws SQLException {
Statement stmt =
null
;
try {
Configuration configuration = ms.getConfiguration(
)
;
// 创建 StatementHandler（路由到实际的 StatementHandler 实现）
StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql)
;
// 准备 Statement
stmt = prepareStatement(handler, ms.getStatementLog(
)
)
;
// 执行查询
return handler.query(stmt, resultHandler)
;
}
finally {
// 关闭 Statement
closeStatement(stmt)
;
}
}
// 准备 Statement
private Statement prepareStatement(StatementHandler handler, Log statementLog)
throws SQLException {
Statement stmt;
// 获取数据库连接
Connection connection = getConnection(statementLog)
;
// 准备 Statement
stmt = handler.prepare(connection, transaction.getTimeout(
)
)
;
// 设置参数
handler.parameterize(stmt)
;
return stmt;
}

步骤 4：创建 StatementHandler（RoutingStatementHandler）

// Configuration.java
public StatementHandler newStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
// 创建 StatementHandler（实际创建的是 RoutingStatementHandler）
StatementHandler statementHandler =
new RoutingStatementHandler(executor, mappedStatement, parameterObject, rowBounds, resultHandler, boundSql)
;
// 应用插件（如果有）
statementHandler = (StatementHandler
) interceptorChain.pluginAll(statementHandler)
;
return statementHandler;
}
// RoutingStatementHandler.java
public RoutingStatementHandler(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
// 根据 StatementType 选择实际的 StatementHandler 实现
switch (ms.getStatementType(
)
) {
case STATEMENT:
delegate =
new SimpleStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql)
;
break
;
case PREPARED:
// 对于预编译语句，使用 PreparedStatementHandler
delegate =
new PreparedStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql)
;
break
;
case CALLABLE:
delegate =
new CallableStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql)
;
break
;
default:
throw
new ExecutorException("Unknown statement type: " + ms.getStatementType(
)
)
;
}
}

步骤 5：StatementHandler 准备 Statement

// BaseStatementHandler.java
@Override
public Statement prepare(Connection connection, Integer transactionTimeout)
throws SQLException {
ErrorContext.instance(
).sql(boundSql.getSql(
)
)
;
Statement statement =
null
;
try {
// 实例化 Statement
statement = instantiateStatement(connection)
;
// 设置超时时间
setStatementTimeout(statement, transactionTimeout)
;
// 设置 fetchSize
setFetchSize(statement)
;
return statement;
}
catch (SQLException e) {
closeStatement(statement)
;
throw e;
}
catch (Exception e) {
closeStatement(statement)
;
throw
new ExecutorException("Error preparing statement. Cause: " + e, e)
;
}
}
// PreparedStatementHandler.java
@Override
protected Statement instantiateStatement(Connection connection)
throws SQLException {
String sql = boundSql.getSql(
)
;
// 获取主键生成策略
if (mappedStatement.getKeyGenerator(
)
instanceof Jdbc3KeyGenerator
) {
String[] keyColumnNames = mappedStatement.getKeyColumns(
)
;
if (keyColumnNames ==
null
) {
// 没有指定主键列，使用 JDBC 3.0 规范的方法获取自增主键
return connection.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS
)
;
}
else {
// 指定了主键列，使用指定的列获取自增主键
return connection.prepareStatement(sql, keyColumnNames)
;
}
}
else
if (mappedStatement.getResultSetType(
) !=
null
) {
// 设置结果集类型
return connection.prepareStatement(sql, mappedStatement.getResultSetType(
).getValue(
)
, ResultSet.CONCUR_READ_ONLY
)
;
}
else {
// 默认情况，创建预编译语句
return connection.prepareStatement(sql)
;
}
}

步骤 6：ParameterHandler 设置参数

// BaseStatementHandler.java
@Override
public
void parameterize(Statement statement)
throws SQLException {
// 委托 ParameterHandler 设置参数
parameterHandler.setParameters((PreparedStatement
) statement)
;
}
// DefaultParameterHandler.java
@Override
public
void setParameters(PreparedStatement ps) {
ErrorContext.instance(
).activity("setting parameters"
).object(mappedStatement.getParameterMap(
).getId(
)
)
;
// 获取参数映射列表
List<
ParameterMapping> parameterMappings = boundSql.getParameterMappings(
)
;
if (parameterMappings !=
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(
)
;
// 处理动态参数（如 _parameter、_databaseId）
if (boundSql.hasAdditionalParameter(propertyName)
) {
value = boundSql.getAdditionalParameter(propertyName)
;
}
// 处理参数为 null 的情况
else
if (parameterObject ==
null
) {
value =
null
;
}
// 处理参数为基本类型的情况
else
if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass(
)
)
) {
value = parameterObject;
}
// 处理参数为对象或 Map 的情况
else {
MetaObject metaObject = configuration.newMetaObject(parameterObject)
;
value = metaObject.getValue(propertyName)
;
}
// 获取类型处理器
TypeHandler typeHandler = parameterMapping.getTypeHandler(
)
;
JdbcType jdbcType = parameterMapping.getJdbcType(
)
;
// 处理 jdbcType 为 null 的情况
if (value ==
null && jdbcType ==
null
) {
jdbcType = configuration.getJdbcTypeForNull(
)
;
}
try {
// 设置参数（核心：类型处理器将 Java 对象转换为 JDBC 类型）
typeHandler.setParameter(ps, i + 1
, value, jdbcType)
;
}
catch (TypeException e) {
throw
new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e)
;
}
catch (SQLException e) {
throw
new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e)
;
}
}
}
}
}

步骤 7：StatementHandler 执行查询

// PreparedStatementHandler.java
@Override
public <
E> List<
E> query(Statement statement, ResultHandler resultHandler)
throws SQLException {
// 转换为 PreparedStatement
PreparedStatement ps = (PreparedStatement
) statement;
// 执行 SQL
ps.execute(
)
;
// 委托 ResultSetHandler 处理结果集
return resultSetHandler.handleResultSets(ps)
;
}

步骤 8：ResultSetHandler 处理结果集

// DefaultResultSetHandler.java
@Override
public List<
Object> handleResultSets(Statement stmt)
throws SQLException {
ErrorContext.instance(
).activity("handling results"
).object(mappedStatement.getId(
)
)
;
final List<
Object> multipleResults =
new ArrayList<
>(
)
;
int resultSetCount = 0
;
// 获取第一个结果集
ResultSet rs = getFirstResultSet(stmt)
;
// 获取结果映射列表
List<
ResultMap> resultMaps = mappedStatement.getResultMaps(
)
;
int resultMapCount = resultMaps.size(
)
;
// 验证结果映射数量
validateResultMapsCount(rs, resultMapCount)
;
// 处理所有结果集
while (rs !=
null && resultMapCount > resultSetCount) {
ResultMap resultMap = resultMaps.get(resultSetCount)
;
// 处理单个结果集
handleResultSet(rs, resultMap, multipleResults,
null
)
;
// 获取下一个结果集（适用于存储过程返回多个结果集的情况）
rs = getNextResultSet(stmt)
;
// 清理资源
cleanUpAfterHandlingResultSet(
)
;
resultSetCount++
;
}
// 处理结果集映射
String[] resultSets = mappedStatement.getResultSets(
)
;
if (resultSets !=
null
) {
while (rs !=
null && resultSetCount < resultSets.length) {
// 处理命名结果集
ResultMapping parentMapping = nextResultMaps.get(resultSets[resultSetCount]
)
;
if (parentMapping !=
null
) {
String nestedResultMapId = parentMapping.getNestedResultMapId(
)
;
ResultMap resultMap = configuration.getResultMap(nestedResultMapId)
;
handleResultSet(rs, resultMap,
null
, parentMapping)
;
}
rs = getNextResultSet(stmt)
;
cleanUpAfterHandlingResultSet(
)
;
resultSetCount++
;
}
}
// 处理单个结果集的情况，将其展开为列表
return collapseSingleResultList(multipleResults)
;
}
// 处理单个结果集
private
void handleResultSet(ResultSet rs, ResultMap resultMap, List<
Object> multipleResults, ResultMapping parentMapping)
throws SQLException {
try {
if (parentMapping !=
null
) {
// 处理嵌套结果集
handleRowValues(rs, resultMap,
null
, RowBounds.DEFAULT
, parentMapping)
;
}
else {
// 处理普通结果集
if (resultHandler ==
null
) {
// 创建默认结果处理器
DefaultResultHandler defaultResultHandler =
new DefaultResultHandler(objectFactory)
;
// 处理行值
handleRowValues(rs, resultMap, defaultResultHandler, rowBounds,
null
)
;
// 将结果添加到多个结果列表中
multipleResults.add(defaultResultHandler.getResultList(
)
)
;
}
else {
// 使用用户提供的结果处理器
handleRowValues(rs, resultMap, resultHandler, rowBounds,
null
)
;
}
}
}
finally {
// 关闭结果集
closeResultSet(rs)
;
}
}
// 处理行值
private
void handleRowValues(ResultSet rs, ResultMap resultMap, ResultHandler resultHandler, RowBounds rowBounds, ResultMapping parentMapping)
throws SQLException {
if (resultMap.hasNestedResultMaps(
)
) {
// 处理包含嵌套结果映射的情况
ensureNoRowBounds(
)
;
checkResultHandler(
)
;
handleRowValuesForNestedResultMap(rs, resultMap, resultHandler, rowBounds, parentMapping)
;
}
else {
// 处理简单结果映射的情况
handleRowValuesForSimpleResultMap(rs, resultMap, resultHandler, rowBounds)
;
}
}
// 处理简单结果映射的行值
private
void handleRowValuesForSimpleResultMap(ResultSet rs, ResultMap resultMap, ResultHandler resultHandler, RowBounds rowBounds)
throws SQLException {
DefaultResultContext<
Object> resultContext =
new DefaultResultContext<
>(
)
;
// 跳过分页偏移量
skipRows(rs, rowBounds.getOffset(
)
)
;
// 处理行数据
while (shouldProcessMoreRows(resultContext, rowBounds) && rs.next(
)
) {
// 获取判别式结果映射（用于动态结果映射）
ResultMap discriminatedResultMap = resolveDiscriminatedResultMap(rs, resultMap,
null
)
;
// 获取行值（创建结果对象并填充数据）
Object rowValue = getRowValue(rs, discriminatedResultMap)
;
// 将行值添加到结果上下文中
resultContext.nextResultObject(rowValue)
;
// 如果有结果处理器，调用它处理结果
if (resultHandler !=
null
) {
resultHandler.handleResult(resultContext)
;
}
}
}
// 获取行值（创建结果对象并填充数据）
private Object getRowValue(ResultSet rs, ResultMap resultMap)
throws SQLException {
final ResultLoaderMap lazyLoader =
new ResultLoaderMap(
)
;
// 创建结果对象
Object rowValue = createResultObject(rs, resultMap, lazyLoader,
null
)
;
if (rowValue !=
null &&
!resultMap.isPrimitive(
)
) {
// 创建元对象
MetaObject metaObject = configuration.newMetaObject(rowValue)
;
// 标记是否找到值
boolean foundValues =
this.useConstructorMappings;
// 处理自动映射
if (shouldApplyAutomaticMappings(resultMap, false
)
) {
foundValues = applyAutomaticMappings(rs, resultMap, metaObject,
null
) || foundValues;
}
// 处理手动映射
foundValues = applyPropertyMappings(rs, resultMap, metaObject, lazyLoader,
null
) || foundValues;
// 如果没有找到任何值且需要非空结果，则返回 null
foundValues = lazyLoader.size(
) >
0 || foundValues;
rowValue = foundValues || configuration.isReturnInstanceForEmptyRow(
) ? rowValue :
null
;
}
return rowValue;
}
// 创建结果对象
private Object createResultObject(ResultSet rs, ResultMap resultMap, ResultLoaderMap lazyLoader, String columnPrefix)
throws SQLException {
this.useConstructorMappings = false
;
// 重置构造函数映射标志
// 获取结果类型
final Class<
?> resultType = resultMap.getType(
)
;
// 创建元对象处理器
final List<
Class<
?>
> constructorArgTypes =
new ArrayList<
>(
)
;
final List<
Object> constructorArgs =
new ArrayList<
>(
)
;
// 创建结果对象
Object resultObject = createResultObject(rs, resultType, constructorArgTypes, constructorArgs, columnPrefix)
;
// 如果结果类型不是基本类型
if (resultObject !=
null &&
!resultType.isInterface(
)
) {
// 检查是否有构造函数映射
if (shouldApplyAutomaticMappings(resultMap, true
)
) {
// 应用自动映射
applyAutomaticMappings(rs, resultMap, configuration.newMetaObject(resultObject)
, columnPrefix)
;
}
// 应用属性映射
applyPropertyMappings(rs, resultMap, configuration.newMetaObject(resultObject)
, lazyLoader, columnPrefix)
;
}
// 标记使用了构造函数映射
this.useConstructorMappings = resultObject !=
null &&
!constructorArgTypes.isEmpty(
)
;
return resultObject;
}