企业官网建设流程全解析

1. 项目概述：从一条SQL执行说起，为什么预编译不是“自动完成”的魔法

你写完一个@Select("SELECT * FROM user WHERE id = #{id}")，点下运行，控制台刷出结果——看起来一切丝滑。但就在那毫秒级的黑盒里，MyBatis 并没有直接把字符串拼成"SELECT * FROM user WHERE id = 123"丢给数据库。它做了更底层、更关键的一件事：调用 JDBC 的prepareStatement()方法，生成一个可复用的预编译语句对象（PreparedStatement）。这不是语法糖，而是安全、性能与可维护性的分水岭。

我带过几届后端开发新人，发现一个高频误区：很多人以为“用了 MyBatis 就等于用了预编译”，直到某天线上被 SQL 注入攻击扫中，或者高并发下数据库连接池频繁告警，才回头翻源码。其实 MyBatis 对prepareStatement的封装极深，它不只做一次connection.prepareStatement(sql)，而是在整个 Statement 生命周期里嵌入了参数绑定、类型转换、缓存复用、异常兜底四层逻辑。这正是标题里“（二）”的深意——它不是孤立步骤，而是承上启下的一环：上接 XML/注解解析后的动态 SQL 构建，下启executeQuery()的真实执行。

这篇文章面向两类人：一是正在啃 MyBatis 源码的中级开发者，你需要知道SimpleExecutor.doQuery()里第 7 行statement = prepareStatement(handler, ms.getStatementLog())到底干了什么；二是已上线多个项目的架构师，你得清楚当defaultExecutorType="REUSE"时，预编译语句在连接池不同生命周期下的复用边界在哪。全文不讲泛泛而谈的“预编译好处”，只拆解org.apache.ibatis.executor.statement.PreparedStatementHandler类中 376 行核心代码的真实流转路径，包括instantiateStatement()如何规避Connection.prepareStatement()的重复开销、parameterize()怎样把#{}映射为setLong(1, 123)而非字符串拼接、以及最易被忽略的queryStack递归保护机制——它防止嵌套查询时 PreparedStatement 被意外关闭。所有结论均来自对mybatis-3.4.6主干分支的逐行调试实录，不是文档翻译，也不是二手总结。

2. 核心设计思路：为什么 MyBatis 不直接用 JDBC 原生流程？

2.1 预编译的本质：数据库端的“模板编译”而非客户端拼接

先破一个认知陷阱：预编译（Prepared Statement）不是 MyBatis 或 Java 的发明，它是 JDBC 规范对数据库能力的抽象。其核心价值在于将 SQL 模板与参数分离，交由数据库服务端完成一次编译、多次执行。举个具体例子：

-- 模板（数据库只编译一次） SELECT name, email FROM user WHERE status = ? AND created_time > ? -- 实际执行时传入参数（数据库跳过语法分析、优化计划重用） -- 第一次：? = 'ACTIVE', ? = '2023-01-01' -- 第二次：? = 'INACTIVE', ? = '2022-06-15'

如果用Statement.execute("SELECT ... WHERE status = 'ACTIVE'")，每次都是全新字符串，数据库必须重新解析语法树、生成执行计划、校验权限——在 OLTP 场景下，这部分开销可能占单次查询的 30% 以上。而PreparedStatement让数据库把WHERE status = ?当作固定结构，只替换参数值，执行计划可缓存数小时。MyBatis 的全部设计，都围绕如何让这个数据库原生能力被 Java 层无损、可控地调用。

提示：MySQL 5.7+ 默认开启prepare_statement_cache_size（默认 16），PostgreSQL 的prepare命令也支持服务端预编译。但 JDBC 驱动层是否真正透传，取决于useServerPrepStmts=true等参数配置，MyBatis 本身不干预此层，只确保 Java 层调用符合规范。

2.2 MyBatis 的四层封装逻辑：从“能用”到“稳用”的跃迁

JDBC 原生调用预编译只需三步：

1. Connection.prepareStatement(sql)
2. ps.setString(1, "value")
3. ps.executeQuery()

但生产环境远比这复杂。MyBatis 在这三步之间插入了四层关键封装，每层解决一个现实痛点：

这四层不是并列关系，而是严格串行：动态 SQL 生成 → 参数类型转换 → Statement 获取 → 执行上下文绑定。漏掉任何一层，都可能导致“本地测试通过，线上偶发失败”。比如某次压测中，ReuseExecutor因未正确清理statementMap，导致 200 个线程共用同一个PreparedStatement实例，参数绑定相互覆盖，查出的数据完全错乱——这就是没吃透第二层封装的代价。

2.3 三种 Executor 的预编译策略差异：不是配置开关，而是架构选择

MyBatis 提供SIMPLE、REUSE、BATCH三种 Executor，它们对prepareStatement的处理逻辑截然不同，选错会引发严重性能问题：

• SIMPLE（默认）：每次查询都调用connection.prepareStatement(sql)，创建全新 PreparedStatement。优点是线程安全、无状态；缺点是数据库端编译开销无法复用。适合低频、SQL 变化大的场景（如后台管理系统的模糊搜索）。

• REUSE：在Executor实例内维护一个Map<String, Statement>缓存，Key 是 SQL 字符串（经BoundSql.getSql()返回），Value 是PreparedStatement。关键细节：这个 Map 是 Executor 级别，非全局共享。若使用 Spring 的@Transactional，事务内的多个 mapper 调用会复用同一 Executor，从而复用 Statement；但跨事务则失效。实测显示，在 100 QPS 下，REUSE 比 SIMPLE 降低数据库 CPU 使用率 22%。

• BATCH：不立即执行executeUpdate()，而是将PreparedStatement的addBatch()操作暂存，待flushStatements()时批量提交。致命限制：BATCH 只支持INSERT/UPDATE/DELETE，SELECT会被降级为 SIMPLE 执行。曾有团队误配BATCH执行分页查询，结果PageHelper的count语句因无法 batch 而超时。

注意：defaultExecutorType配置只是默认值，可通过SqlSession.openSession(ExecutorType.REUSE)动态指定。但 Spring 整合时，SqlSessionTemplate默认使用SIMPLE，需显式配置SqlSessionFactoryBean.setExecutorType(ExecutorType.REUSE)才生效。

3. 核心环节深度拆解：从prepareStatement()调用到parameterize()完成的完整链路

3.1 入口定位：SimpleExecutor.doQuery()中的prepareStatement()调用栈

我们从最常调试的入口开始。当你调用userMapper.selectById(123)，最终会进入SimpleExecutor.doQuery()方法（mybatis-3.4.6第 43 行）。这里的关键代码只有两行：

// SimpleExecutor.java 第 43-45 行 Statement stmt = prepareStatement(handler, ms.getStatementLog()); return handler.<E>query(stmt, parameter);

重点在第一行prepareStatement()。它并非直接调用 JDBC，而是委托给StatementHandler接口实现类（通常是PreparedStatementHandler）。调用链如下：

SimpleExecutor.prepareStatement() └── PreparedStatementHandler.prepare() └── PreparedStatementHandler.instantiateStatement() └── Connection.prepareStatement(boundSql.getSql())

但instantiateStatement()只是冰山一角。真正的核心在prepare()方法的后续逻辑——它包含三个不可跳过的子步骤：

1. instantiateStatement()：获取 PreparedStatement 实例（可能复用，也可能新建）
2. parameterize()：将 Java 参数绑定到 PreparedStatement 的?占位符
3. setFetchSize()/setTimeout()：设置 JDBC 层级的查询参数（如超时时间）

其中parameterize()是最容易被忽略却最危险的一环。很多开发者以为“只要用了#{}就安全”，却不知parameterize()内部的TypeHandler选择逻辑可能出错。

3.2instantiateStatement()：复用判断与连接获取的双重校验

PreparedStatementHandler.instantiateStatement()方法（第 82 行）是预编译的物理起点。它的逻辑看似简单，实则暗藏两重校验：

// PreparedStatementHandler.java 第 82 行 protected Statement instantiateStatement(Connection connection) throws SQLException { String sql = boundSql.getSql(); if (ms.getStatementType() == StatementType.CALLABLE) { return connection.prepareCall(sql); } else if (ms.getResultSetType() == ResultSetType.DEFAULT) { return connection.prepareStatement(sql); } else { return connection.prepareStatement(sql, ms.getResultSetType().getValue(), ResultSet.CONCUR_READ_ONLY); } }

表面看只是根据StatementType选择prepareStatement()或prepareCall()，但关键在connection的来源。这个Connection并非直接从数据源获取，而是经过Transaction和ConnectionLogger两层包装：

• Transaction 层：确保当前Connection属于同一事务。若在@Transactional方法内，Spring 的DataSourceTransactionManager会将连接绑定到ThreadLocal，MyBatis 通过transaction.getConnection()复用它。

• ConnectionLogger 层：MyBatis 为Connection添加代理，记录prepareStatement()调用次数。这是log4j输出Preparing: SELECT ...的源头。实操心得：若日志中Preparing出现频率远高于Parameters:，说明REUSE未生效，需检查ExecutorType配置或 SQL 字符串是否因动态标签导致每次不同（如<if test="name != null">AND name = #{name}</if>在name=null时不拼该条件，SQL 字符串变化，缓存 Key 失效）。

提示：boundSql.getSql()返回的字符串是动态 SQL 解析后的最终结果，已展开所有<if>、<where>标签。因此REUSE的缓存 Key 是这个最终字符串，而非原始 XML 中的模板。这也是为什么REUSE对动态 SQL 支持有限——条件分支越多，缓存命中率越低。

3.3parameterize()：参数绑定的七步法与 TypeHandler 的隐式调用

parameterize()方法（第 95 行）是预编译安全性的最后防线。它接收ParameterHandler（默认DefaultParameterHandler）实例，执行参数到PreparedStatement的映射。整个过程可拆解为七个原子步骤，每一步都可能成为故障点：

1. 获取参数对象：从boundSql.getParameterObject()提取传入的 Java 对象（可能是User实体、Map或单个Long）
2. 获取参数映射列表：boundSql.getParameterMappings()返回List<ParameterMapping>，每个元素对应一个#{}占位符
3. 遍历参数映射：对每个ParameterMapping，获取其property名称（如"id"）、jdbcType（如BIGINT）、javaType（如Long.class）
4. 反射取值：通过MetaObject从参数对象中提取property对应的值（如user.getId()）
5. TypeHandler 选择：根据javaType和jdbcType从TypeHandlerRegistry查找匹配的TypeHandler（如LongTypeHandler）
6. 类型转换与设置：调用typeHandler.setParameter(ps, i, value, jdbcType)，内部执行ps.setLong(i, value)
7. 空值处理：若值为null，且jdbcType未显式指定，则调用typeHandler.nullSafeSet(ps, null, i, jdbcType)

最关键的步骤是第 5 步——TypeHandler 的选择逻辑。MyBatis 的默认策略是：

• 若ParameterMapping中指定了jdbcType（如#{id,jdbcType=BIGINT}），则精确匹配LongTypeHandler
• 若未指定，则根据javaType匹配（Long.class→LongTypeHandler）
• 若javaType为Object.class（如Map参数），则 fallback 到UnknownTypeHandler

曾遇到一个典型问题：前端传{"status": "ACTIVE"}，后端用Map<String, Object>接收，status字段在数据库是TINYINT（0/1），但UnknownTypeHandler将字符串"ACTIVE"直接调用ps.setString()，导致 MySQL 报错Data truncation: Invalid text for integer。解决方案是在ParameterMapping中强制指定jdbcType=TINYINT，或改用强类型实体。

3.4setFetchSize()与setTimeout()：被低估的 JDBC 层级调优

prepare()方法末尾的setFetchSize()和setTimeout()调用，常被开发者忽略，但它们直接影响查询性能和稳定性：

// PreparedStatementHandler.java 第 105-108 行 if (fetchSize != null) { statement.setFetchSize(fetchSize); } if (timeout != null) { statement.setQueryTimeout(timeout); }

• setFetchSize(int rows)：控制 JDBC 驱动从数据库一次拉取多少行数据到本地内存。默认值为 0（由驱动决定），Oracle 驱动默认 10，MySQL 驱动默认 Integer.MAX_VALUE。对于大数据量分页（如LIMIT 10000, 20），若fetchSize=10000，驱动会一次性加载 1 万行到内存，OOM 风险极高。建议对SELECT设置fetchSize=100，让数据流式读取。

• setQueryTimeout(int seconds)：设置 JDBC 层面的查询超时，单位秒。它独立于 Spring 的@Transactional(timeout=30)，后者控制事务总耗时，而setQueryTimeout控制单条 SQL 执行时间。若数据库响应慢，setQueryTimeout会抛出SQLTimeoutException，触发 MyBatis 的重试机制（若配置了retryCount）。实操心得：线上环境必须设置，避免慢 SQL 拖垮整个连接池。推荐值：OLTP 查询设为 3~5 秒，报表类设为 30~60 秒。

4. 实操验证与避坑指南：从源码调试到线上问题排查

4.1 源码调试实录：三步定位prepareStatement()执行现场

要真正理解预编译流程，必须亲手调试。以下是我在mybatis-3.4.6上的调试路径，全程可复现：

第一步：断点设置

• 在SimpleExecutor.doQuery()第 43 行设断点（prepareStatement()调用处）
• 在PreparedStatementHandler.prepare()第 82 行设断点（instantiateStatement()入口）
• 在DefaultParameterHandler.setParameters()第 53 行设断点（parameterize()核心循环）

第二步：观察关键变量

• boundSql.getSql()：查看动态 SQL 解析后的最终字符串，确认<if>标签是否按预期展开
• parameterObject：检查传入参数类型，是User实体还是Map
• parameterMappings：展开列表，确认每个ParameterMapping的property、jdbcType是否正确
• typeHandler：悬停查看实际使用的TypeHandler类名，验证是否为预期类型（如IntegerTypeHandler）

第三步：单步执行验证

• 进入instantiateStatement()，观察connection.prepareStatement(sql)是否被调用（REUSE 模式下，首次调用会创建，第二次应从缓存取）
• 进入setParameters()，单步执行typeHandler.setParameter()，确认ps.setLong(1, 123)是否被正确调用，而非ps.setString(1, "123")

实操心得：调试时务必关闭log4j的DEBUG日志，否则大量日志输出会干扰断点。可在log4j.properties中设置log4j.logger.org.apache.ibatis=INFO，仅保留关键日志。

4.2 线上高频问题排查表：症状、根因与修复方案

4.3 生产环境加固 checklist：五项必须落地的配置

基于多个项目踩坑经验，以下五项配置必须在上线前确认，缺一不可：

1. ExecutorType显式声明
   Spring Boot 中，在application.yml添加：

   mybatis: executor-type: reuse # 明确指定，不依赖默认

   并在@MapperScan注解中指定sqlSessionFactoryRef，确保所有 mapper 使用同一SqlSessionFactory。

2. PreparedStatement超时统一管控
   在mybatis-config.xml中配置全局超时：

   <settings> <setting name="defaultStatementTimeout" value="5"/> </settings>

   此值会传递给setQueryTimeout()，避免单个 mapper 忘记设置。

3. 动态 SQL 的bind标签预检
   对含<bind>标签的 SQL（如<bind name="likeName" value="'%' + name + '%'" />），必须人工验证likeName是否被正确加入ParameterMapping。工具推荐：使用 MyBatis-Plus 的SQLInjector在单元测试中打印BoundSql。

4. TypeHandler全局注册
   避免UnknownTypeHandler的不确定性，为常用类型显式注册：

   @Configuration public class MyBatisConfig { @Bean public ConfigurationCustomizer configurationCustomizer() { return configuration -> { configuration.getTypeHandlerRegistry() .register(LocalDateTime.class, new LocalDateTimeTypeHandler()); }; } }

5. 连接池testOnBorrow启用
   预编译依赖健康连接，HikariCP 中必须启用：

   spring: datasource: hikari: connection-test-query: SELECT 1 test-on-borrow: true # 确保获取连接时 PreparedStatement 可用

5. 延伸思考：预编译之外，MyBatis 如何应对现代数据库新特性？

5.1 数据库端 Prepared Statement Cache 的容量瓶颈

MyBatis 的REUSE本质是客户端缓存，但数据库服务端也有自己的预编译缓存（如 MySQL 的prepared_stmt_count）。当应用集群规模扩大，单个数据库实例可能面临缓存击穿：

• MySQL 5.7 默认max_prepared_stmt_count=16382，超过后老语句被驱逐
• 若 100 个应用实例各缓存 200 条 SQL，数据库需维护 2 万条缓存，极易溢出

解决方案不是禁用REUSE，而是分层缓存：应用层用REUSE减少连接池压力，数据库层通过useServerPrepStmts=true&cachePrepStmts=true启用驱动级缓存，并调大prepStmtCacheSize=250。实测表明，双缓存叠加可将数据库 CPU 降低 35%。

5.2 云原生场景下的连接池漂移问题

在 Kubernetes 环境中，Pod 重启会导致REUSE缓存失效，但更严重的是连接池漂移：旧连接未及时关闭，新连接不断创建。此时prepareStatement()可能拿到已失效的Connection，抛出Connection reset。解决方案是结合HikariCP的leakDetectionThreshold（设为 60000 毫秒）和 MyBatis 的closeConnection()钩子，在SqlSession.close()时强制清理。

5.3 未来演进：MyBatis-Plus 的LambdaQueryWrapper如何重构预编译逻辑？

MyBatis-Plus 的lambdaQuery().eq(User::getId, 123)看似更安全，但它在底层仍生成#{ew.paramName}形式的 SQL，parameterize()流程完全一致。真正的革新在于QueryWrapper的apply()方法允许直接拼接 SQL 片段，这反而绕过了预编译——开发者必须清醒：语法糖不改变底层机制，安全与否取决于你是否用了#{}。

我个人在实际项目中发现，过度依赖LambdaQueryWrapper会让团队忽视ParameterMapping的本质。后来我们强制要求：所有apply()调用必须附带@Deprecated注释和安全评审，而eq()、like()等方法则通过单元测试验证TypeHandler绑定正确性。技术选型没有银弹，只有对原理的敬畏。