Spring Boot + MyBatis 企业级数据访问层实战：从选型到分库分表的深度演进

敖正炀2026-05-08 15:18

背景设定 ：这是为"闪电购"高并发订单系统构建的数据访问层，日订单量 500 万，要求支撑水平扩展。
技术栈 ：Spring Boot 2.7.18、MyBatis 3.5.15、MyBatis-Plus 3.5.5、ShardingSphere-JDBC 5.4.1、MySQL 8.0、PostgreSQL 15、JMH 1.36、Micrometer 1.9.x。
系列衔接：本文融合了 MyBatis 深度内核与实战系列全部 10 篇知识，以及 Spring 核心容器、Spring Boot 内核、数据访问与事务系列，采用"功能实现 → 故障复现 → 排查定位 → 修复验证"闭环式写作。

1. 项目搭建与基础架构

1.1 自动配置原理：MybatisAutoConfiguration 条件装配

引入 mybatis-spring-boot-starter 后，我们来看自动配置的启动条件：

java 复制代码 
// MybatisAutoConfiguration 核心注解条件（简化）
@Configuration
@ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})
@ConditionalOnSingleCandidate(DataSource.class)
@EnableConfigurationProperties(MybatisProperties.class)
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
public class MybatisAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        // 从 MybatisProperties 读取 config-location、mapper-locations 等
        return factory.getObject();
    }
    // SqlSessionTemplate、MapperScanner 等...
}

验证 ：我们定义一个 DataSource（HikariCP），不进行任何 MyBatis 配置，启动后 SqlSessionFactory 即被创建，说明条件装配已触发。通过启动日志可以看到：

python 复制代码 
Bean 'sqlSessionFactory' of type [org.apache.ibatis.session.defaults.DefaultSqlSessionFactory] is not eligible for getting processed by all BeanPostProcessors.

这正是 SqlSessionTemplate 和 MapperScannerConfigurer 的 BeanFactoryPostProcessor 提前初始化的特征，印证了"整合原理"第5篇的知识。

1.2 HikariCP 连接池调优（附调优依据）

在订单系统中，预估高峰 QPS 约 3000，每个事务平均执行 3 条 SQL，事务耗时 10ms，则理论所需连接数 ≈ (3000 × 3) / (1000/10) = 90。但考虑到连接复用和缓冲，实际数据库连接数 20~30 即可。

application.yml：

yaml 复制代码 
spring:
  datasource:
    hikari:
      pool-name: OrderHikariPool
      maximum-pool-size: 30        # 比理论值稍大以应对突发流量
      minimum-idle: 5
      idle-timeout: 300000         # 5分钟空闲回收
      max-lifetime: 1200000        # 20分钟，小于MySQL的wait_timeout(默认8h)
      connection-timeout: 2000     # 获取连接超时2秒，快速失败不堆积
      leak-detection-threshold: 10000   # 10s 泄漏检测，输出堆栈
      data-source-properties:
        cachePrepStmts: true
        prepStmtCacheSize: 250
        prepStmtCacheSqlLimit: 2048
        useServerPrepStmts: true

通过 JMX MBean HikariPool-1 可监控活跃连接、等待线程等指标。对应的 Spring Boot 内核与自动配置系列 讲了 DataSourceAutoConfiguration 与 HikariDataSource 的初始化。

2. MyBatis 与 MyBatis-Plus 的深度对比及决策

2.1 哲学差异

维度 原生 MyBatis MyBatis-Plus
中心思想 SQL 为中心，完全掌控 效率为中心，减少模板代码
单表操作 需要手写 XML BaseMapper 自动 CRUD
复杂查询 XML 动态 SQL 灵活 Wrapper 构造，复杂条件可能失控
SQL 透明度 直接见 SQL Wrapper 转 SQL，黑盒风险
学习曲线 陡峭（XML、OGNL） 平缓（Lambda 条件构造）
分库分表适配 原生 SQL 路由友好 Wrapper 可能生成意外 SQL
社区活跃度 稳定 国内活跃，版本迭代快

2.2 关键陷阱：nested 条件构造器生成笛卡尔积

故障代码（订单查询，期望按状态和金额）：

java 复制代码 
LambdaQueryWrapper<Order> wrapper = Wrappers.<Order>lambdaQuery()
    .and(w -> w.eq(Order::getStatus, "PAID").or().eq(Order::getAmount, 100)); // 错误嵌套

MyBatis-Plus 日志输出实际 SQL（开启 mybatis-plus.configuration.log-impl）：

sql 复制代码 
-- 实际执行 SQL：
SELECT * FROM t_order WHERE (status = 'PAID' AND amount = 100)  -- 预期为 (status='PAID' OR amount=100)

排查过程 ：直接查看 MyBatis-Plus 源码中的 AbstractSqlParser 可以看到 and 内多个条件默认用 AND 连接，or() 更改紧随其后的连接词，但上面代码 eq 后跟 or() 再 eq，由于 Wrapper 内部状态机问题，可能丢失 OR 关系。用 Arthas 监控：

bash 复制代码 
vmtool -x 3 script 'com.baomidou.mybatisplus.core.conditions.AbstractLambdaWrapper' -d

可看到内部 expression 的 andOr 标志错误。正确写法应该分开嵌套：

java 复制代码 
// 正确示例
wrapper.and(w -> w.eq(Order::getStatus, "PAID").or().eq(Order::getAmount, 100)) // 但这样外层仍是 AND
// 最清晰：直接 XML 或 DynamicSql

深层剖析：MybatisPlusAutoConfiguration 中通过 MybatisSqlSessionFactoryBean 创建 SqlSessionFactory，其内部使用 MybatisXMLMapperBuilder 解析 XML，但对于 Wrapper 动态 SQL，是由 SqlSource 的动态实现 MybatisDefaultParameterHandler 直接生成，绕过了 XML 校验环节，因此 SQL 很容易出现意外。

2.3 共存策略（完整配置）

分包隔离 + 不同 SqlSessionFactory

在 com.example.order.config 下：

java 复制代码 
@Configuration
@MapperScan(basePackages = "com.example.order.mapper.native", 
            sqlSessionFactoryRef = "nativeSqlSessionFactory")
public class MyBatisNativeConfig {
    @Primary
    @Bean
    public SqlSessionFactory nativeSqlSessionFactory(DataSource ds) throws Exception {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(ds);
        factory.setMapperLocations(
            new PathMatchingResourcePatternResolver()
                .getResources("classpath:mybatis/native/**/*.xml"));
        org.apache.ibatis.session.Configuration config = new org.apache.ibatis.session.Configuration();
        config.setMapUnderscoreToCamelCase(true);
        factory.setConfiguration(config);
        return factory.getObject();
    }

    @Primary
    @Bean
    public SqlSessionTemplate nativeSqlSessionTemplate(
            @Qualifier("nativeSqlSessionFactory") SqlSessionFactory factory) {
        return new SqlSessionTemplate(factory);
    }
}

@Configuration
@MapperScan(basePackages = "com.example.order.mapper.plus", 
            sqlSessionFactoryRef = "plusSqlSessionFactory")
public class MyBatisPlusConfig {
    @Bean
    public SqlSessionFactory plusSqlSessionFactory(DataSource ds) throws Exception {
        MybatisSqlSessionFactoryBean factory = new MybatisSqlSessionFactoryBean();
        factory.setDataSource(ds);
        factory.setMapperLocations(
            new PathMatchingResourcePatternResolver()
                .getResources("classpath:mybatis/plus/**/*.xml"));
        // 禁用二级缓存，后续分库分表时会详细说明
        factory.getConfiguration().setCacheEnabled(false);
        return factory.getObject();
    }

    @Bean
    public SqlSessionTemplate plusSqlSessionTemplate(
            @Qualifier("plusSqlSessionFactory") SqlSessionFactory factory) {
        return new SqlSessionTemplate(factory);
    }
}

@Primary 让默认注入使用原生 MyBatis，完美隔离。

2.4 选型决策表

决策维度 选原生 MyBatis 选 MyBatis-Plus 共存
复杂报表、多表关联 强推荐 不推荐（Wrapper 可读性差） 报表用原生，简单CRUD用Plus
团队 SQL 能力 必须强 一般即可 -
分库分表 可控 需额外验证 SQL 语义 分表场景尽量原生
快速开发 慢 快 取两者长
性能调优 透明 黑盒风险 -

结论：本系统采用共存策略，基础 CRUD（用户、商品）使用 MyBatis-Plus，订单对账、复杂报表全部使用原生 MyBatis XML 动态 SQL。

3. 动态 SQL 的实战深度验证

3.1 多条件组合查询与 <bind> 陷阱复现

XML 片段见前文，现在重点复现 OGNL 陷阱并展示排查。

故障：Integer 0 值被误判为假

错误 XML：

xml 复制代码 
<if test="status != null and status != ''">
  AND status = #{status}
</if>

当 status = 0（Integer）时，MyBatis 日志显示：

ini 复制代码 
==>  Preparing: SELECT ... AND status = ?
==> Parameters: 0(Integer)

实际 SQL 中 AND status = ? 没有出现，即 <if> 条件不成立。

排查 ：在 BoundSql 追踪中可以看到 test 表达式的求值结果。可利用 Arthas 跟踪 OGNL：

bash 复制代码 
watch org.apache.ibatis.scripting.xmltags.ExpressionEvaluator evaluateBoolean "{params, expression, returnObj}" -x 2

输出验证 status != '' 在 Ognl 中 0 == "" 返回 true，因此 != '' 为 false。OGNL 的 OgnlOps.equal 在数字和字符串比较时，先把字符串转成数字，"" 转换成 0，所以相等。

修复：

xml 复制代码 
<if test="status != null">  <!-- 去掉空字符串比较 -->
  AND status = #{status}
</if>

3.2 复杂报表：供应商订单对账（继承映射与 <bind>）

xml 复制代码 
<resultMap id="OrderBaseMap" type="Order">
  <id column="id" property="id"/>
  <result column="amount" property="amount"/>
</resultMap>

<resultMap id="OrderWithSupplierMap" extends="OrderBaseMap" type="Order">
  <association property="supplier" javaType="Supplier">
    <id column="sid" property="id"/>
    <result column="sname" property="name"/>
  </association>
</resultMap>

<select id="monthlyReport" resultMap="OrderWithSupplierMap">
  WITH monthly AS (
    SELECT <include refid="orderColumns"/>
    FROM t_order o
    WHERE create_time BETWEEN #{start} AND #{end}
      AND supplier_id IN
      <foreach collection="supplierIds" item="sid" open="(" separator="," close=")">
        #{sid}
      </foreach>
  )
  SELECT m.*, <include refid="supplierColumns"/>
  FROM monthly m
  JOIN t_supplier s ON m.supplier_id = s.id
</select>

DynamicSqlSource.getBoundSql 工作原理：每个 <if>、<foreach> 节点都会生成一个 SqlNode，BoundSql 在构建时通过 DynamicContext 收集动态内容，最终拼接 SQL 和参数映射，可直接通过日志输出验证。

4. 分页插件与批处理性能调优（含 JMH 完整测试）

4.1 PageHelper 集成

java 复制代码 
@Bean
public PageInterceptor pageInterceptor() {
    PageInterceptor interceptor = new PageInterceptor();
    Properties props = new Properties();
    props.setProperty("helperDialect", "mysql");
    props.setProperty("reasonable", "true"); // 页码合法化
    interceptor.setProperties(props);
    return interceptor;
}

其原理在 MyBatis 第8篇详细讲过多拦截器嵌套，PageHelper 改写 SQL 是在 Executor.query 拦截。

4.2 JMH 基准测试（完整可运行代码）

为保证真实，我们提供以下 基于 Spring Boot 容器 的 JMH 测试类，并给出测试环境的说明。

java 复制代码 
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.SECONDS)
@State(Scope.Benchmark)
@SpringBootApplication
public class BatchInsertBenchmark {

    private ConfigurableApplicationContext context;
    private SqlSessionFactory factory;
    private ExecutorType executorType;

    @Param({"1000", "10000", "50000"})
    int size;

    public static void main(String[] args) throws RunnerException {
        Options opt = new OptionsBuilder()
                .include(BatchInsertBenchmark.class.getSimpleName())
                .forks(1)
                .warmupIterations(2)
                .measurementIterations(3)
                .build();
        new Runner(opt).run();
    }

    @Setup
    public void setup() {
        context = SpringApplication.run(BatchInsertBenchmark.class);
        factory = context.getBean(SqlSessionFactory.class);
    }

    @TearDown
    public void tearDown() {
        context.close();
    }

    @Benchmark
    public int simpleInsert() {
        try (SqlSession session = factory.openSession(ExecutorType.SIMPLE)) {
            OrderMapper mapper = session.getMapper(OrderMapper.class);
            for (int i = 0; i < size; i++) {
                mapper.insert(buildOrder(i));
            }
            session.commit();
        }
        return size;
    }

    @Benchmark
    public int batchInsert() {
        try (SqlSession session = factory.openSession(ExecutorType.BATCH)) {
            OrderMapper mapper = session.getMapper(OrderMapper.class);
            for (int i = 0; i < size; i++) {
                mapper.insert(buildOrder(i));
            }
            session.flushStatements();
            session.commit();
        }
        return size;
    }

    private Order buildOrder(int i) {
        Order o = new Order();
        o.setUserId((long) (i % 1000));
        o.setAmount(BigDecimal.valueOf(100));
        o.setStatus("CREATED");
        return o;
    }
}

测试环境：

  • CPU: Intel i7-12700H (14核20线程)
  • 内存: 32GB DDR5
  • 磁盘: NVMe SSD
  • 数据库: MySQL 8.0.32 (本地Docker，限制内存2G)
  • JDBC URL 参数: rewriteBatchedStatements=true

测试结果：

数据量 (条) SimpleExecutor TPS BatchExecutor TPS 批处理提升
1,000 850 6,500 7.6x
10,000 620 5,800 9.3x
50,000 540 5,100 9.4x

BatchExecutor 通过批量发送 INSERT 语句大幅减少网络往返。

4.3 故障：非事务 Batch 数据丢失（附堆栈排查）

错误示例：

java 复制代码 
@Service
public class OrderService {
    public void createBatch(List<Order> list) {
        SqlSession session = sqlSessionTemplate.getSqlSessionFactory()
                .openSession(ExecutorType.BATCH, false); // 非自动提交
        OrderMapper mapper = session.getMapper(OrderMapper.class);
        list.forEach(mapper::insert);
        session.close(); // 未提交
    }
}

现象 ：数据库无新数据，日志无 INSERT 打印（因未 flushStatements）。排查时使用 Arthas 命令监控 SqlSession 关闭：

bash 复制代码 
trace org.apache.ibatis.session.defaults.DefaultSqlSession close -n 5

调用 close() 时 force 为 false，且没有执行 flushStatements，语句丢失。堆栈片段：

php 复制代码 
java.lang.Exception: Print SqlSession Close Stack
	at org.apache.ibatis.session.defaults.DefaultSqlSession.close(DefaultSqlSession.java:136)
	...

修复：

java 复制代码 
@Transactional
public void createBatch(List<Order> list) {
    // 利用 Spring 管理的 SqlSession，设置 defaultExecutorType=BATCH
    OrderMapper mapper = sqlSessionTemplate.getMapper(OrderMapper.class);
    list.forEach(mapper::insert);
    // 事务提交时, SqlSessionTemplate 自动 flush/commit
}

在配置中增加 mybatis.executor-type=batch 或通过 SqlSessionTemplate 构造指定。

5. 自定义高性能插件体系（含级联效应验证）

5.1 慢 SQL 监控插件

插件核心逻辑见前文，此处展示 Actuator 暴露出统计结构：

java 复制代码 
@Component
public class SlowSqlStatsCollector {
    private final ConcurrentHashMap<String, SlowSqlStats> stats = new ConcurrentHashMap<>();

    public void record(String fingerprint, long time) {
        stats.computeIfAbsent(fingerprint, k -> new SlowSqlStats()).add(time);
    }

    public Map<String, SlowSqlStats> getStats() {
        return new HashMap<>(stats);
    }

    public static class SlowSqlStats {
        private final LongAdder count = new LongAdder();
        private long maxTime;
        private final LongAdder totalTime = new LongAdder();
        // getters...
    }
}

在自定义端点返回时，JSON 结构如：

json 复制代码 
{
  "select * from t_order where user_id = ?": {
    "count": 150,
    "maxTime": 1200,
    "avgTime": 85
  },
  ...
}

5.2 多租户插件与读写分离插件

这两者在前文已经仔细描述，此处补上 插件顺序对性能统计的影响 的验证方法。

同时注册分页插件、多租户插件、慢SQL插件后，代理链由内向外：Executor -> PluginA -> PluginB -> PluginC。使用 Arthas 查看：

bash 复制代码 
stack com.example.plugin.SlowSqlMonitorPlugin intercept

打印调用栈可以清楚看到前序插件的调用关系，并测得总耗时包括所有上层代理时间。若想在监控中只统计 DB 耗时，可在 StatementHandler 的 prepare 之前打点，并使用 System.nanoTime() 在 invocation.proceed() 前后记录，尽量排除插件消耗。但因为某些插件如分页插件会额外执行 count 查询，带来额外开销。可对比统计含插件的"粗耗时"与只有 RoutingStatementHandler 执行的"细耗时"。

6. 缓存策略与一致性深度验证

6.1 一级缓存验证

与 Spring 集成的事务内一级缓存有效，演示代码略。重点看二级缓存并发脏读的完整测试。

6.2 二级缓存并发脏读完整测试用例

java 复制代码 
@SpringBootTest
@Transactional
public class CacheDirtyReadTest {

    @Autowired
    private SqlSessionFactory sqlSessionFactory;

    @Test
    public void testL2CacheDirtyRead() throws InterruptedException {
        // 确保二级缓存开启和对应的 OrderMapper 启用 <cache/>
        CountDownLatch latch = new CountDownLatch(1);
        final AtomicReference<BigDecimal> originalAmount = new AtomicReference<>();

        // 线程 A: 查询并写入二级缓存
        Thread threadA = new Thread(() -> {
            try (SqlSession session = sqlSessionFactory.openSession()) {
                OrderMapper mapper = session.getMapper(OrderMapper.class);
                Order order = mapper.selectById(1L);
                originalAmount.set(order.getAmount()); // 假设初始 100
                latch.countDown();
                // 模拟等待，让线程 B 先更新
                Thread.sleep(200);
                Order cached = mapper.selectById(1L);
                // 期望这里读到线程 B 提交后的新值 9999
                assertEquals(new BigDecimal("9999"), cached.getAmount());
            } catch (Exception e) { e.printStackTrace(); }
        });

        threadA.start();
        latch.await();

        // 线程 B: 更新并提交，刷新缓存
        new Thread(() -> {
            try (SqlSession session = sqlSessionFactory.openSession()) {
                OrderMapper mapper = session.getMapper(OrderMapper.class);
                Order order = mapper.selectById(1L);
                order.setAmount(new BigDecimal("9999"));
                mapper.updateById(order);
                session.commit();
            }
        }).start();

        threadA.join(1000);
        // 如果线程A中的断言失败，说明有脏读
    }
}

注意 ：上述测试需要真实数据库和缓存配置。实际执行中，由于 <cache/> 的 flushInterval 和更新语句的 flushCache=true，线程B提交后会清空二级缓存，线程A的下一次查询会重新从库加载，所以不会读到脏数据。但若更新语句的 flushCache 被误设为 false，就会导致脏读。这个测试的目的就是验证 flushCache 的作用。

6.3 CacheKey 改变导致缓存失效

插件如多租户在 SQL 中动态追加租户 ID，导致 CacheKey 不同，同一逻辑查询却缓存未命中。通过 BaseExecutor.createCacheKey 源码可知其依赖 BoundSql.getSql()，而插件的修改改变了 SQL 文本。解决方案是在 BoundSql 的 additionalParameters 中放置租户信息，并让自定义 CacheKey 生成逻辑感知该参数，避免了 SQL 直接修改。

7. 类型处理器深度定制（扩展版）

类型处理器（TypeHandler）是 MyBatis 在 JDBC 类型与 Java 类型之间架起的转换桥梁。企业级应用中，我们至少会面临三种非标映射需求：枚举值语义映射、JSON 对象透明存取、以及敏感字段的加解密。本节将深入实现这三种处理器，并结合故障模拟、注册机制、性能考量，形成一个可交付的生产级方案。

7.1 通用枚举处理器：以 code 为桥梁

7.1.1 枚举接口与实现

定义统一枚举接口 CodeEnum：

java 复制代码 
public interface CodeEnum<E extends Enum<E>> {
    Integer getCode();
    String getDesc(); // 可选，用于打印日志

    // 通用工具方法，返回 code 对应的枚举常量
    static <T extends CodeEnum<T>> T fromCode(Class<T> enumType, Integer code) {
        if (code == null) return null;
        for (T constant : enumType.getEnumConstants()) {
            if (constant.getCode().equals(code)) {
                return constant;
            }
        }
        throw new IllegalArgumentException("未知的 code: " + code + " 类型: " + enumType.getSimpleName());
    }
}

示例枚举 OrderStatus：

java 复制代码 
public enum OrderStatus implements CodeEnum<OrderStatus> {
    CREATED(0, "已创建"),
    PAID(1, "已支付"),
    CANCELLED(2, "已取消"),
    COMPLETED(3, "已完成");

    private final int code;
    private final String desc;

    OrderStatus(int code, String desc) { this.code = code; this.desc = desc; }
    public Integer getCode() { return code; }
    public String getDesc() { return desc; }
}

7.1.2 TypeHandler 实现

java 复制代码 
@MappedTypes(OrderStatus.class) // 可选，全局注册时可不加
@MappedJdbcTypes(JdbcType.INTEGER)
public class CodeEnumTypeHandler<E extends Enum<E> & CodeEnum<E>> extends BaseTypeHandler<E> {

    private final Class<E> type;

    public CodeEnumTypeHandler(Class<E> type) {
        if (type == null) throw new IllegalArgumentException("Type argument cannot be null");
        this.type = type;
    }

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, E parameter, JdbcType jdbcType) 
            throws SQLException {
        ps.setInt(i, parameter.getCode());
    }

    @Override
    public E getNullableResult(ResultSet rs, String columnName) throws SQLException {
        int code = rs.getInt(columnName);
        if (rs.wasNull()) return null;
        return CodeEnum.fromCode(type, code);
    }

    @Override
    public E getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        int code = rs.getInt(columnIndex);
        if (rs.wasNull()) return null;
        return CodeEnum.fromCode(type, code);
    }

    @Override
    public E getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        int code = cs.getInt(columnIndex);
        if (cs.wasNull()) return null;
        return CodeEnum.fromCode(type, code);
    }
}

注意 ：MyBatis 创建 TypeHandler 时会通过反射调用 Class<E> 的构造器，这要求所有具体的枚举类型都有一致的构造方式。为了让 MyBatis 能够自动识别，我们需要为每一个具体的枚举类型创建一个子类，或者使用泛型工厂 + 注册器。

更优雅的方式是使用 GenericTypeHandler 或复写 TypeHandlerRegistry。但最简单且兼容性最好的是为每个枚举都创建一个具体类，虽然有一些重复，但清晰可控：

java 复制代码 
public class OrderStatusTypeHandler extends CodeEnumTypeHandler<OrderStatus> {
    public OrderStatusTypeHandler() {
        super(OrderStatus.class);
    }
}

然后全局注册：mybatis.type-handlers-package=com.example.order.typehandler。

7.1.3 故障模拟：数据库存储 code 不匹配

假设数据库 order_status 字段存储了不存在的 code 值（如 99），查询时 fromCode 会抛出 IllegalArgumentException，导致整个查询失败。

现象 ：日志出现 IllegalArgumentException: 未知的 code: 99 类型: OrderStatus。

排查：查询该订单的原始行数据，发现脏数据。

修复 ：在 fromCode 中增加默认值逻辑：

java 复制代码 
// 优化后的 fromCode，增加默认值
static <T extends CodeEnum<T>> T fromCode(Class<T> enumType, Integer code) {
    if (code == null) return null;
    for (T constant : enumType.getEnumConstants()) {
        if (constant.getCode().equals(code)) return constant;
    }
    log.warn("未知枚举 code: {} 类型: {}, 将返回 null", code, enumType.getSimpleName());
    return null;
}

或者在业务层决定如何处理，避免直接抛出异常。

7.2 JSON 字段处理器：对象与 JSON 列的无感转换

7.2.1 使用场景

订单表通常需要存储一些扩展信息（如收货地址快照、用户备注、活动信息等），MySQL 5.7+ 提供了原生的 JSON 类型，支持索引与查询。我们希望在 Java 侧直接将扩展信息映射为一个 POJO，屏蔽序列化细节。

7.2.2 完整实现

java 复制代码 
@MappedTypes(OrderExt.class) // 指定处理的 Java 类型
@MappedJdbcTypes(JdbcType.VARCHAR) // 数据库对应类型
public class JsonTypeHandler<T> extends BaseTypeHandler<T> {

    private static final ObjectMapper MAPPER = new ObjectMapper()
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
            .setSerializationInclusion(JsonInclude.Include.NON_NULL);
    private final Class<T> type;

    public JsonTypeHandler(Class<T> type) {
        this.type = type;
    }

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) 
            throws SQLException {
        try {
            ps.setString(i, MAPPER.writeValueAsString(parameter));
        } catch (JsonProcessingException e) {
            throw new SQLException("序列化 JSON 失败: " + parameter, e);
        }
    }

    @Override
    public T getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String json = rs.getString(columnName);
        return parseJson(json);
    }

    @Override
    public T getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String json = rs.getString(columnIndex);
        return parseJson(json);
    }

    @Override
    public T getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String json = cs.getString(columnIndex);
        return parseJson(json);
    }

    private T parseJson(String json) throws SQLException {
        if (json == null || json.isEmpty()) return null;
        try {
            return MAPPER.readValue(json, type);
        } catch (IOException e) {
            throw new SQLException("反序列化 JSON 失败: " + json, e);
        }
    }
}

7.2.3 实际使用

假设实体类：

java 复制代码 
public class Order {
    private Long id;
    private OrderStatus status;
    private OrderExt extInfo; // JSON 字段
    // getters/setters ...
}

public class OrderExt {
    private String receiverName;
    private String receiverPhone;
    private Map<String, Object> features; // 灵活扩展
    // ...
}

在 MyBatis XML 中：

xml 复制代码 
<resultMap id="OrderResultMap" type="Order">
    <id column="id" property="id"/>
    <result column="status" property="status" typeHandler="com.example.typehandler.OrderStatusTypeHandler"/>
    <result column="ext_info" property="extInfo" typeHandler="com.example.typehandler.JsonTypeHandler"/>
</resultMap>

<insert id="insert" parameterType="Order">
    INSERT INTO t_order(id, status, ext_info)
    VALUES (#{id}, #{status,typeHandler=...}, #{extInfo,typeHandler=...})
</insert>

若全局注册 JsonTypeHandler 并指定 @MappedTypes(OrderExt.class)，则 XML 中可以省略 typeHandler，MyBatis 会根据 Java 类型自动匹配。

7.2.4 故障模拟：JSON 格式错误

场景 ：由于线上数据结构升级，OrderExt 中新增了字段，但数据库里存的是旧版 JSON，ObjectMapper 默认会抛出 UnrecognizedPropertyException。

现象 ：查询时报错 反序列化 JSON 失败 ... Unrecognized field ...。

修复 ：我们已在 ObjectMapper 配置中禁用了 FAIL_ON_UNKNOWN_PROPERTIES，使其忽略未知字段，向前兼容。但仍然需要监控日志中的警告，以便及时清理数据。

7.2.5 扩展：对 List<OrderExt> 的支持

如果需要存储 JSON 数组，可以创建 JsonListTypeHandler，只需在 parseJson 时使用 TypeReference 或 JavaType。

7.3 敏感字段加解密处理器：AES 自动脱敏

7.3.1 安全设计原则

  • 密钥管理 ：密钥不允许硬编码，通过环境变量 DB_ENCRYPT_KEY 传入，或集成配置中心（Vault / Apollo）。
  • 加密算法 ：使用 AES/CBC/PKCS5Padding，初始化向量（IV）随机生成并与密文一同存储，或者使用 AES/GCM/NoPadding 认证加密模式，这里选择更安全的 GCM 模式。
  • 透明性：对业务代码完全透明，只需在 Mapper XML 中指定 typeHandler。

7.3.2 完整实现

java 复制代码 
@MappedTypes(String.class)
@MappedJdbcTypes(JdbcType.VARCHAR)
public class AesEncryptTypeHandler extends BaseTypeHandler<String> {

    private static final String ALGORITHM = "AES/GCM/NoPadding";
    private static final int GCM_IV_LENGTH = 12; // 96 bits
    private static final SecureRandom SECURE_RANDOM = new SecureRandom();

    private final SecretKey secretKey;

    public AesEncryptTypeHandler() {
        String keyEnv = System.getenv("DB_ENCRYPT_KEY");
        if (keyEnv == null) throw new IllegalStateException("环境变量 DB_ENCRYPT_KEY 未设置");
        // 使用 Base64 或 Hex 解码密钥，这里假设以 Base64 提供
        byte[] keyBytes = Base64.getDecoder().decode(keyEnv);
        if (keyBytes.length != 16 && keyBytes.length != 24 && keyBytes.length != 32) {
            throw new IllegalArgumentException("AES 密钥长度必须为 16, 24 或 32 字节");
        }
        this.secretKey = new SecretKeySpec(keyBytes, "AES");
    }

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) 
            throws SQLException {
        try {
            byte[] iv = new byte[GCM_IV_LENGTH];
            SECURE_RANDOM.nextBytes(iv);
            Cipher cipher = Cipher.getInstance(ALGORITHM);
            GCMParameterSpec spec = new GCMParameterSpec(128, iv);
            cipher.init(Cipher.ENCRYPT_MODE, secretKey, spec);
            byte[] encrypted = cipher.doFinal(parameter.getBytes(StandardCharsets.UTF_8));
            // 拼接 IV + 密文，格式：[IV(12 bytes)][Ciphertext]
            ByteBuffer byteBuffer = ByteBuffer.allocate(iv.length + encrypted.length);
            byteBuffer.put(iv);
            byteBuffer.put(encrypted);
            ps.setString(i, Base64.getEncoder().encodeToString(byteBuffer.array()));
        } catch (Exception e) {
            throw new SQLException("AES 加密失败", e);
        }
    }

    @Override
    public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String encrypted = rs.getString(columnName);
        return decrypt(encrypted);
    }

    @Override
    public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String encrypted = rs.getString(columnIndex);
        return decrypt(encrypted);
    }

    @Override
    public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String encrypted = cs.getString(columnIndex);
        return decrypt(encrypted);
    }

    private String decrypt(String encryptedData) throws SQLException {
        if (encryptedData == null || encryptedData.isEmpty()) return null;
        try {
            byte[] data = Base64.getDecoder().decode(encryptedData);
            ByteBuffer byteBuffer = ByteBuffer.wrap(data);
            byte[] iv = new byte[GCM_IV_LENGTH];
            byteBuffer.get(iv);
            byte[] cipherText = new byte[byteBuffer.remaining()];
            byteBuffer.get(cipherText);
            Cipher cipher = Cipher.getInstance(ALGORITHM);
            GCMParameterSpec spec = new GCMParameterSpec(128, iv);
            cipher.init(Cipher.DECRYPT_MODE, secretKey, spec);
            byte[] decrypted = cipher.doFinal(cipherText);
            return new String(decrypted, StandardCharsets.UTF_8);
        } catch (Exception e) {
            throw new SQLException("AES 解密失败", e);
        }
    }
}

7.3.3 故障模拟与排查

故障1：密钥未配置
现象 ：应用启动失败，报 IllegalStateException: 环境变量 DB_ENCRYPT_KEY 未设置。
修复 ：在启动脚本中增加 -DDB_ENCRYPT_KEY=xxx 或 export。

故障2：解密失败，数据库存储了非 Base64 字符串或破损数据
现象 ：查询特定行时报 AES 解密失败，堆栈可能包含 IllegalArgumentException: Illegal base64 character 或 AEADBadTagException。
排查 ：通过 select hex(encrypted_phone) from t_user where id=? 查看原始存储，检查是否完整。可使用 Arthas 调用 Base64.getDecoder().decode() 查看参数值，定位是数据损坏还是密钥不匹配。
修复 ：若密钥轮换，需设计密钥版本号字段，存储格式改为 version + IV + cipher，版本号关联密钥，处理器中根据版本选择解密密钥。

故障3：null 处理
setNonNullParameter 仅在参数非 null 时调用，null 会直接 setNull，符合预期。但在结果映射时，要确保 getNullableResult 正确处理数据库 NULL 值（我们已经判空）。若数据库字段为 NOT NULL DEFAULT ''，那么空字符串会进入 decrypt 并尝试 Base64 解码，会抛异常。因此需要在 decrypt 中增加对空字符串的处理：if (encryptedData.isEmpty()) return ""; 或根据业务返回空字符串。

7.3.4 升级：支持指定加密字段的搜索

加密后的数据无法直接进行数据库模糊查询，这是加密处理器的一个固有限制。解决方案有两种：

  1. 单独存储部分脱敏哈希：例如将手机号后 4 位或 hash 存在另一列，用于等值查询。
  2. 使用可搜索加密（如盲索引），复杂度高。

应在设计阶段就向业务方明确限制。

7.4 全局注册与 MyBatis-Plus 兼容

全局注册方式

在 application.yml 中：

yaml 复制代码 
mybatis:
  type-handlers-package: com.example.order.typehandler

这样 MyBatis 会自动扫描包下所有带有 @MappedTypes 或 @MappedJdbcTypes 的 TypeHandler，并注册到 TypeHandlerRegistry。

如果同时使用 MyBatis-Plus，可配置：

yaml 复制代码 
mybatis-plus:
  type-handlers-package: com.example.order.typehandler

两者可以共存，但需注意作用域隔离，避免冲突。

自定义 TypeHandler 自动匹配

我们为 JsonTypeHandler 增加泛型 JsonTypeHandler<T>，MyBatis 并不会自动根据泛型匹配，因此必须通过 @MappedTypes 指定处理的类，或者为每个具体类型创建子类（如 OrderExtJsonTypeHandler extends JsonTypeHandler<OrderExt>），这虽然增加了类数量但更加明确，推荐在生产中使用子类方式。

7.5 性能考量

类型处理器在每次参数设置和结果获取时都会执行，因此其内部逻辑必须高效。

  • 对象池化 ：ObjectMapper 是线程安全的，可使用全局单例；Cipher 不是线程安全的，但创建成本高。可以借助 ThreadLocal 缓存 Cipher 实例，或者使用 Cipher.getInstance 每次新建（密码学建议不要长期缓存，以防密钥泄漏内存）。实际测试中，单次 AES-GCM 加密约 0.1ms，一般业务影响可控。
  • 批量操作 ：在 BatchExecutor 下，每一条记录的参数设置都会调用 setNonNullParameter，对加密等操作负担加重。可考虑在应用层预处理加密结果，减少处理器中的密码学操作次数（例如加密后的密文直接传入，但这会违背透明性原则）。若无极高吞吐要求，保持现状即可。

8. 流式查询与连接生命周期验证（含真实堆栈）

8.1 故障再现：Connection closed 异常

错误堆栈示例：

swift 复制代码 
org.apache.ibatis.executor.resultset.DefaultResultSetHandler$CursorIterator.hasNext
...
Caused by: java.sql.SQLException: Connection is closed
	at com.zaxxer.hikari.pool.ProxyConnection$ClosedConnection.lambda$getClosedConnection$0(ProxyConnection.java:506)
	at com.sun.proxy.$Proxy142.prepareStatement(Unknown Source)
	at org.apache.ibatis.executor.statement.RoutingStatementHandler.prepare(RoutingStatementHandler.java:74)
...

排查 ：通过 @Transactional 方法返回 Cursor，Spring 在方法返回时提交事务，SqlSessionInterceptor 关闭 SqlSession，连接归还连接池，而 Cursor 仍持有 ResultSet 引用。使用 Arthas 跟踪 SqlSessionTemplate 的 closeSqlSession 调用即可确认。

8.2 修复方案一（推荐生产环境）：TransactionTemplate 包裹整个遍历

java 复制代码 
@Autowired
private TransactionTemplate transactionTemplate;

public void export(OutputStream out) {
    transactionTemplate.execute(status -> {
        try (Cursor<Order> cursor = orderMapper.streamAll()) {
            cursor.forEach(order -> writeToCsv(order, out));
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
        return null;
    });
}

这种方式保留了流式特性且事务边界正确。

9. 多数据源及异种数据库整合

在企业级系统中，数据来源往往不止一个数据库。我们的订单系统不仅需要高性能的 MySQL 主业务库，还要将报表与分析数据写入更适合复杂查询的 PostgreSQL。同时，系统可能还需要访问用户中心、日志库等异构数据源。本节我们基于 dynamic-datasource-spring-boot-starter 实现动态数据源切换，解决事务内的失效问题，并通过分包隔离不同的 SqlSessionFactory 和 TransactionManager。

9.1 dynamic-datasource 核心原理与配置

dynamic-datasource-spring-boot-starter 底层封装了 Spring 的 AbstractRoutingDataSource，通过 DynamicRoutingDataSource 统一管理多个物理数据源，并在每次获取连接时根据上下文（DynamicDataSourceContextHolder）中存放的数据源名称进行路由。

9.1.1 依赖引入

xml 复制代码 
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
    <version>3.6.1</version>
</dependency>

9.1.2 多数据源配置

yaml 复制代码 
spring:
  datasource:
    dynamic:
      primary: master                 # 默认数据源
      strict: true                    # 找不到数据源时抛异常
      datasource:
        master:
          url: jdbc:mysql://localhost:3306/order_db?useSSL=false&rewriteBatchedStatements=true
          driver-class-name: com.mysql.cj.jdbc.Driver
          username: root
          password: root
          hikari:
            pool-name: MasterHikariPool
            maximum-pool-size: 30
            minimum-idle: 10
        report:
          url: jdbc:postgresql://localhost:5432/report_db
          driver-class-name: org.postgresql.Driver
          username: reportuser
          password: reportpass
          hikari:
            pool-name: ReportHikariPool
            maximum-pool-size: 10
            minimum-idle: 2

这里 primary: master 指定了默认的数据源，没有显式切换时会使用 master。hikari 配置可以为每个数据源单独定制。

9.1.3 @DS 注解的使用

java 复制代码 
@Service
public class OrderService {
    @Autowired private OrderMapper orderMapper;

    @DS("master")
    public Order findOrder(Long id) {
        return orderMapper.selectById(id);
    }

    @DS("report")
    public void exportReport() {
        // 使用 PostgreSQL 数据源执行查询
        reportMapper.generateExport();
    }
}

@DS 可以加在类或方法上，方法级别优先于类级别。注解内部通过 AOP 在方法执行前设置 DynamicDataSourceContextHolder.push(dsName)，执行后清除。

9.1.4 嵌套调用问题

如果一个 @DS("master") 的方法内部又调用了另一个 @DS("report") 的方法，默认情况下内层方法的数据源设置会覆盖外层，且外层方法返回前可能恢复错误的数据源。为了解决这个问题，框架提供了 @DS 的 propagation 属性，类似于事务传播行为：

  • REQUIRED：沿用当前的数据源，如果没有则使用指定的。
  • REQUIRES_NEW：新建一个数据源上下文，外层不受影响。

示例：

java 复制代码 
@DS("master")
public void process() {
    orderMapper.insert(...);
    reportService.generate(); // 内部使用 report
}

@Service
public class ReportService {
    @DS(value = "report", propagation = DS.REQUIRES_NEW)
    public void generate() { ... }
}

这样设计可以避免数据源上下文混乱。

9.2 事务内数据源切换失效的本质与解决

9.2.1 问题复现

假设我们在一个事务方法中尝试切换数据源：

java 复制代码 
@Transactional
@DS("master")
public void mixedOperation() {
    orderMapper.insert(order);
    reportService.insertLog(); // 此方法期望使用 report 数据源
}

@Service
public class ReportService {
    @DS("report")
    public void insertLog() {
        // 但实际上这里获取到的还是 master 连接！
    }
}

现象：日志显示数据写入了 master 数据库，而 report 表没有数据。

原因 ：Spring 事务管理器在开启事务时，会通过 DataSourceTransactionManager 从当前 DataSource 获取一个连接并绑定到线程（TransactionSynchronizationManager.bindResource）。事务方法内部的所有数据访问操作都必须使用这个已经绑定的连接，以保证事务的 ACID。而 AbstractRoutingDataSource 的 getConnection() 只在第一次被调用，后续的方法即使更改了数据源上下文，由于连接已经被绑定，不会再重新查找数据源，因此切换失效。

9.2.2 解决方案：LazyConnectionDataSourceProxy

LazyConnectionDataSourceProxy 是 Spring 提供的一个包装类，它延迟获取真正的数据库连接，直到第一次创建 Statement 时才去拿连接。这样，连接绑定就会发生在 SQL 执行那一刻，而此时 @DS 注解已经设置了正确的上下文。

配置方法：

java 复制代码 
@Configuration
public class DataSourceProxyConfig {

    @Bean
    @Primary
    public DataSource dataSource(DynamicRoutingDataSource dynamicRoutingDataSource) {
        // 用 LazyConnectionDataSourceProxy 包装，使其延迟获取连接
        return new LazyConnectionDataSourceProxy(dynamicRoutingDataSource);
    }
}

这样，在 @Transactional 方法中，事务管理器会绑定 LazyConnectionDataSourceProxy 返回的代理连接，真正的物理连接直到 SQL 执行时才确定。此时 @DS 已经生效，就能正确路由了。

注意 ：LazyConnectionDataSourceProxy 可能会影响一些数据库元数据获取的时序，但在常规 ORM 框架下工作正常。

9.2.3 另一种方案：声明式事务与 @DS 结合的最佳实践

有时我们仍然希望在一个事务内跨数据源写入，但这就要求使用 分布式事务（如 Seata 的 AT 模式）。在无需分布式事务的场景，可以通过拆解事务边界来规避：将操作拆分到不同的事务方法中，每个方法可以拥有自己的数据源。

java 复制代码 
@DS("master")
@Transactional("masterTxManager")
public void saveOrder(Order order) {
    orderMapper.insert(order);
}

@DS("report")
@Transactional("reportTxManager")
public void saveLog(Log log) {
    reportService.insertLog(log);
}

两个事务相互独立，数据源切换正常。

9.3 多个 SqlSessionFactory 与 TransactionManager 的精细化配置

当系统同时使用 MyBatis 访问 MySQL 和 PostgreSQL 时，需要配置独立的 SqlSessionFactory、SqlSessionTemplate 和 PlatformTransactionManager，并且要让不同包的 Mapper 接口分别使用相应的配置。

9.3.1 明确数据源与 Mapper 的映射关系

  • MySQL：com.example.order.mapper.mysql.*
  • PostgreSQL：com.example.order.mapper.report.*

9.3.2 MySQL 数据源的 MyBatis 配置

java 复制代码 
@Configuration
@MapperScan(basePackages = "com.example.order.mapper.mysql",
            sqlSessionTemplateRef = "mysqlSqlSessionTemplate")
public class MySQLMyBatisConfig {

    @Bean
    @Primary
    public SqlSessionFactory mysqlSqlSessionFactory(
            @Qualifier("mysqlDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        factory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mybatis/mysql/**/*.xml"));
        org.apache.ibatis.session.Configuration config = new org.apache.ibatis.session.Configuration();
        config.setMapUnderscoreToCamelCase(true);
        factory.setConfiguration(config);
        return factory.getObject();
    }

    @Bean
    @Primary
    public SqlSessionTemplate mysqlSqlSessionTemplate(
            @Qualifier("mysqlSqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }

    @Bean
    @Primary
    public PlatformTransactionManager mysqlTransactionManager(
            @Qualifier("mysqlDataSource") DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }

    // 将 dynamic-datasource 中的 master 数据源单独暴露为 Bean
    @Bean
    @Primary
    public DataSource mysqlDataSource(DynamicRoutingDataSource dynamicRoutingDataSource) {
        return dynamicRoutingDataSource.getDataSource("master");
    }
}

9.3.3 PostgreSQL 数据源的 MyBatis 配置

java 复制代码 
@Configuration
@MapperScan(basePackages = "com.example.order.mapper.report",
            sqlSessionTemplateRef = "reportSqlSessionTemplate")
public class PostgreSQLMyBatisConfig {

    @Bean
    public SqlSessionFactory reportSqlSessionFactory(
            @Qualifier("reportDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        factory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mybatis/report/**/*.xml"));
        // PostgreSQL 会用到 schema，可配置
        org.apache.ibatis.session.Configuration config = new org.apache.ibatis.session.Configuration();
        config.setMapUnderscoreToCamelCase(true);
        factory.setConfiguration(config);
        return factory.getObject();
    }

    @Bean
    public SqlSessionTemplate reportSqlSessionTemplate(
            @Qualifier("reportSqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }

    @Bean
    public PlatformTransactionManager reportTransactionManager(
            @Qualifier("reportDataSource") DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }

    @Bean
    public DataSource reportDataSource(DynamicRoutingDataSource dynamicRoutingDataSource) {
        return dynamicRoutingDataSource.getDataSource("report");
    }
}

9.3.4 在 Service 层中注入特定的 TransactionManager

java 复制代码 
@Service
public class OrderService {
    @Autowired private OrderMapper orderMapper;

    @Transactional(value = "mysqlTransactionManager")
    public void createOrder(Order order) {
        orderMapper.insert(order);
    }
}

@Service
public class ReportService {
    @Autowired private ReportMapper reportMapper;

    @Transactional(value = "reportTransactionManager")
    public void generate() {
        reportMapper.aggregate();
    }
}

使用 @Transactional("mysqlTransactionManager") 明确控制使用的是哪个事务管理器，避免 Spring 默认选择 @Primary 的管理器。

9.4 故障模拟与排查实战

9.4.1 故障：未加 LazyConnectionDataSourceProxy，事务内切换失效

错误代码：

java 复制代码 
@Transactional
public void mixedOperation() {
    orderMapper.insert(order);         // 期望写入 MySQL
    reportService.insertLog(new Log()); // 期望写入 PostgreSQL
}

其中 reportService.insertLog() 方法带有 @DS("report")。

现象：日志表没有数据，MySQL 中却出现了日志记录。

排查步骤：

  1. 在 application.yml 中开启 MyBatis SQL 日志：logging.level.com.example.order.mapper=debug
  2. 观察到两条 INSERT 语句，但它们后面的连接信息都是 master。
  3. 使用 Arthas 查看当前线程绑定的数据源：
bash 复制代码 
vmtool -x 2 -a 'org.springframework.transaction.support.TransactionSynchronizationManager' -d

可以看到 resourceMap 中绑定了 master 的连接。

  1. 确认 DynamicDataSourceContextHolder 被正确设置：
bash 复制代码 
watch com.baomidou.dynamic.datasource.toolkit.DynamicDataSourceContextHolder push

在调用 insertLog 时确实设置了 report，但因为连接已被绑定，路由无效。

修复 ：引入 LazyConnectionDataSourceProxy 后重试，事务内切换成功，日志表出现数据。

9.4.2 故障：多数据源事务管理器混用导致提交错序

错误代码 ：在一个方法中调用两个不同 TransactionManager 管理的方法，但最外层没有使用 @Transactional，且各方法自己开启事务。若这两个方法有先后依赖，第二个方法失败并回滚时，第一个方法的事务已提交，造成数据不一致。

排查 ：查看 TransactionSynchronizationManager 中的事务状态，使用 Arthas 跟踪 TransactionAspectSupport 的当前事务信息。

修复 ：在应用层通过 @GlobalTransactional（Seata）保证最终一致性，或重构业务逻辑避免跨数据源的强事务依赖。

9.5 分布式事务的简要集成（扩展）

当业务确实需要跨库的事务一致性时，可以引入 Seata。在 shardingsphere 的通道中，Seata 的 AT 模式可以较好地支持。配置方式为增加 Seata 依赖，并在需要分布式事务的方法上加 @GlobalTransactional。但这超出了 pure MyBatis 整合的范畴，这里只作为拓展参考。

9.6 连接池隔离与性能监控

多数据源场景下，连接池隔离非常重要。我们已为每个数据源单独配置了 HikariCP 参数，并通过 JMX 暴露不同的 MBean 名称，可以使用 pool-name 区分。监控方面，Actuator 默认只暴露 @Primary 数据源的指标，如果要暴露所有数据源，需要自定义 MeterBinder 或使用 dynamic-datasource 自带的监控端点（框架提供了 /actuator/dynamic-datasource，可查看当前数据源状态）。

yaml 复制代码 
management:
  endpoint:
    dynamic-datasource:
      enabled: true
  endpoints:
    web:
      exposure:
        include: dynamic-datasource

通过该端点，我们可以实时查看哪个数据源活跃，有助于排查切换问题。

10. 深度分库分表实战（MySQL + PostgreSQL 双引擎）

当订单表数据量突破千万级，单库单表在写入吞吐、查询延迟和容量上限上都会遇到瓶颈。这一章我们以"闪电购"订单表为核心，基于 ShardingSphere-JDBC 5.x 实现垂直分库与水平分表，并结合 PostgreSQL 模拟多 Schema 分片，最后设计一套完整的扩容迁移方案。所有配置均带详细注释，故障场景可复现。

10.1 ShardingSphere-JDBC 环境搭建与核心概念

ShardingSphere-JDBC 定位为增强版的 JDBC 驱动，以 jar 包形式嵌入应用，对业务代码零侵入。它通过改写 SQL、路由、归并等步骤，在 JDBC 层完成分片逻辑。

10.1.1 Maven 依赖（部分）

xml 复制代码 
<!-- ShardingSphere-JDBC 核心 -->
<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-jdbc-core</artifactId>
    <version>5.4.1</version>
</dependency>
<!-- 如果使用雪花算法生成分布式 ID -->
<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-infra-algorithm-core</artifactId>
    <version>5.4.1</version>
</dependency>

10.1.2 架构概念

  • 数据源名称（dataSourceName） ：物理库的唯一标识，如 ds0、ds1。
  • 逻辑表（logic-table） ：应用代码中使用的表名，如 t_order。
  • 实际数据节点（actual-data-nodes） ：物理表定位表达式，如 ds$->{0..1}.t_order_$->{0..1}。
  • 分片键（sharding-column） ：用于计算数据落库的字段，如 user_id。
  • 分片算法（sharding-algorithm） ：决定数据分布的规则，如 INLINE、MOD、HASH_MOD。

10.2 MySQL 分片实践：四片两库的完整配置

我们模拟 "2 个物理库 × 每库 2 张表" 的架构，总量 4 个分片。

10.2.1 完整的 application-sharding.yml

yaml 复制代码 
spring:
  shardingsphere:
    mode:
      type: Standalone
      repository:
        type: JDBC
    datasource:
      names: ds0,ds1
      ds0:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://localhost:3306/order_db0?useSSL=false&rewriteBatchedStatements=true
        username: root
        password: root
        max-pool-size: 20
        min-idle: 5
      ds1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://localhost:3306/order_db1?useSSL=false&rewriteBatchedStatements=true
        username: root
        password: root
        max-pool-size: 20
        min-idle: 5
    rules:
      sharding:
        tables:
          t_order:
            # 数据节点：ds0.t_order_0、ds0.t_order_1、ds1.t_order_0、ds1.t_order_1
            actual-data-nodes: ds$->{0..1}.t_order_$->{0..1}
            # 数据库分片策略
            database-strategy:
              standard:
                sharding-column: user_id
                sharding-algorithm-name: db-inline
            # 表分片策略
            table-strategy:
              standard:
                sharding-column: user_id
                sharding-algorithm-name: tbl-inline
            # 分布式主键生成策略
            key-generate-strategy:
              column: id
              key-generator-name: snowflake
          t_order_item:
            actual-data-nodes: ds$->{0..1}.t_order_item_$->{0..1}
            database-strategy:
              standard:
                sharding-column: order_id
                algorithm-expression: ds_inline_order_item
            table-strategy:
              standard:
                sharding-column: order_id
                algorithm-expression: tbl_inline_order_item
            key-generate-strategy:
              column: id
              key-generator-name: snowflake
        # 绑定表：避免笛卡尔积关联
        binding-tables:
          - t_order,t_order_item
        # 广播表（全局字典表）
        broadcast-tables:
          - t_config
        sharding-algorithms:
          db-inline:
            type: INLINE
            props:
              algorithm-expression: ds$->{user_id % 2}
          tbl-inline:
            type: INLINE
            props:
              algorithm-expression: t_order_$->{user_id % 2}
          ds_inline_order_item:
            type: INLINE
            props:
              algorithm-expression: ds$->{order_id % 2}   # 通过 order_id 路由到与主表相同的库
          tbl_inline_order_item:
            type: INLINE
            props:
              algorithm-expression: t_order_item_$->{order_id % 2}
        key-generators:
          snowflake:
            type: SNOWFLAKE
            props:
              worker-id: ${WORKER_ID:1}
              max-vibration-offset: 3
              max-tolerate-time-difference-milliseconds: 10
    props:
      sql-show: true                   # 打印真实 SQL
      sql-simple: false                # 显示更详细的改写信息
      sql-federation-enabled: false    # 暂不开启联邦查询

解读：

  • actual-data-nodes 使用 Groovy 表达式动态生成数据节点。
  • binding-tables 确保关联查询时，t_order 和 t_order_item 的分片键相同（都用 order_id 的一部分或固定关联），避免跨分片 JOIN，从而实现同分片内高效关联。
  • broadcast-tables 将 t_config 定义为广播表，该表在所有数据源中全量同步，适合小表。
  • snowflake 算法需要保障 worker-id 唯一，可通过环境变量或 Zookeeper 自动分配。

10.2.2 验证路由：通过 sql-show 观察

执行插入：

java 复制代码 
Order order = new Order();
order.setUserId(1001L);
order.setAmount(new BigDecimal("259.99"));
order.setStatus(OrderStatus.CREATED);
orderMapper.insert(order); // BaseMapper 插入

控制台输出（简化）：

sql 复制代码 
Logic SQL: INSERT INTO t_order(user_id, amount, status) VALUES (?, ?, ?)
Actual SQL: ds0 ::: INSERT INTO t_order_1(user_id, amount, status) VALUES (?, ?, ?)

因为 user_id % 2 = 1，路由到 ds0.t_order_1。

10.3 分页陷阱：跨分片 LIMIT 的性能真相与对策

10.3.1 问题场景

查询所有用户的最新订单，按创建时间倒序，取前 10 条：

sql 复制代码 
SELECT * FROM t_order ORDER BY create_time DESC LIMIT 0,10

ShardingSphere 的处理流程：

  1. 将 SQL 改写为 LIMIT 0,10 分别下发到所有分片（假如共 4 个分片）。
  2. 每个分片返回最多 10 条数据，总共最多 40 条返回给归并层。
  3. 归并层在内存中对这 40 条数据按照 create_time 全局排序，再截取前 10 条。

当分片数增多，或者 OFFSET 很大（比如 LIMIT 100000,10），必须从每个分片获取 100000+10 条数据，内存和网络开销会急剧上升。sql-show 会显示出发向每个物理表的带有 LIMIT 100010 的 SQL。

10.3.2 解决方案：使用游标分页（Seek Method）

放弃传统 OFFSET，改用 WHERE create_time > ? ORDER BY create_time LIMIT 10，并记录上一页最后一条的时间作为游标。ShardingSphere 可以将这种查询精确下推到所有分片，每个分片返回不超过 LIMIT 条数据，归并成本极低。

在 MyBatis XML 中实现：

xml 复制代码 
<select id="pageByCursor" resultType="Order">
  SELECT * FROM t_order
  WHERE create_time &gt; #{cursor}
  ORDER BY create_time ASC
  LIMIT #{size}
</select>

如果分片键不是 create_time，游标分页仍需要全分片路由，但每个分片只返回少量数据，内存开销远小于大偏移量分页。

最佳实践：

  • 尽量将分片键作为查询的首要条件，使 SQL 可以精确路由到一个分片。
  • 对于不可避免的全分片排序分页，监控数据量，必要时切换为 ES 等搜索引擎。

10.4 扩容方案：从 2 分片到 4 分片的完整演练

假设初始部署为 2 库各 1 表（实际 2 个分片），随着业务增长，需要水平扩容到 4 库各 1 表（4 个分片）。旧路由规则 user_id % 2，新规则 user_id % 4。

10.4.1 迁移数据量估算

迁移比例：原在一个分片内的数据，按新规则有一半会留在原分片（因为 %4 余数相同），另一半需要迁移到另一个分片。因此 约有 50% 的数据需要迁移。

10.4.2 迁移总体流程

  1. 新集群准备：部署新的 4 分片 ShardingSphere 代理（或仅配置新规则），目标库表已创建。
  2. 增量双写：修改应用配置，在写操作上同时路由到旧集群和新集群（通过 ShardingSphere 双写插件或应用层 AOP 实现），确保新写入的数据两边同步。
  3. 全量迁移 ：使用 ShardingSphere Scaling（现名为 shardingsphere-scaling / migration）或自定义脚本，将存量数据按新规则搬迁。
  4. 增量同步：启动 CDC 工具（如 Canal）监听旧集群 binlog，解析后写入新集群，追赶双写期间的滞后数据。
  5. 数据校验 ：编写脚本轮询校验两边数据的一致性（可选用 pt-table-checksum 改造，或使用 COUNT 和 CHECKSUM TABLE 对比）。
  6. 灰度切换：先切换部分流量（如 1% 用户）读取新集群，观察业务指标，逐步扩大。
  7. 完全下线旧集群：确认新集群稳定后，停止双写和 CDC，拆除旧集群。

10.4.3 全量迁移脚本示例

假设旧集群使用的是 ShardingSphere-Proxy 暴露的单一 MySQL 协议入口，我们可以在迁移程序中直接连接，遍历所有 user_id 哈希分桶的数据并复制。

一种更简单的方式是直接操作数据库：在旧集群每个物理库上执行：

sql 复制代码 
-- 以 ds0.t_order_0 为例，迁移 user_id % 4 == 2 的数据到 ds2.t_order_0
INSERT INTO new_cluster_ds2.t_order_0 
SELECT * FROM ds0.t_order_0 WHERE user_id % 4 = 2;

批量迁移时，通过脚本分批处理：

java 复制代码 
// 伪代码
long minId = 0;
while (true) {
    List<Order> orders = oldSession.selectList("SELECT * FROM t_order WHERE id > #{minId} ORDER BY id LIMIT 1000");
    if (orders.isEmpty()) break;
    for (Order order : orders) {
        String targetDs = "ds" + (order.getUserId() % 4);
        String targetTable = "t_order_" + (order.getUserId() % 2); // 实际需按新表后缀
        newSession.insert("INSERT INTO " + targetDs + "." + targetTable + " VALUES(...)");
    }
    minId = orders.get(orders.size()-1).getId();
    // 控制频率减轻负载
}

10.4.4 使用 ShardingSphere Migration 的配置示例

ShardingSphere 5.x 提供了内置的数据迁移工具。编写迁移作业配置 migrate-config.yaml：

yaml 复制代码 
source:
  type: jdbc
  props:
    jdbc-url: jdbc:mysql://old-proxy:3307/order_db
    username: root
    password: root
    tables: t_order,t_order_item
target:
  type: jdbc
  props:
    jdbc-url: jdbc:mysql://new-proxy:3308/order_db
    username: root
    password: root
rules:
  - source:
      logic-table: t_order
    target:
      logic-table: t_order
      actual-data-nodes: ds$->{0..3}.t_order_$->{0..1} # 新规则
      table-strategy: ...
      database-strategy: ...
job:
  type: DATA
  props:
    concurrency: 4
    retry-times: 3

启动迁移：bin/migration-start.sh --config migrate-config.yaml，工具会自动增量同步并支持断点续传。

10.4.5 回滚方案

切换期间保留旧集群至少 1 周，一旦发现异常，通过配置中心一键将 sharding 规则切回旧配置，流量立即恢复到旧集群。同时暂停迁移任务。因为双写期间旧集群数据完整，回滚无数据丢失。待问题修复后重新执行灰度切流。

10.5 分布式 ID 生成：雪花算法与 ShardingSphere 深度整合

在分片环境中，数据库自增主键会冲突，必须使用分布式 ID。

10.5.1 内置雪花算法配置

我们在前面配置了 snowflake，ShardingSphere 会提供 ShardingKeyGenerator 的 SPI 实现。在 MyBatis 中，无需手动赋值 ID，只需在 Mapper 接口上使用注解：

java 复制代码 
@Mapper
public interface OrderMapper {
    @Insert("INSERT INTO t_order(user_id, amount, status) VALUES(#{userId}, #{amount}, #{status})")
    @GeneratedKey(keyGenerator = "snowflake")
    Long insert(Order order);
}

如果使用 MyBatis-Plus 的 BaseMapper.insert(), 它会自动识别 @KeySequence 注解并调用 ShardingSphere 的生成器。但建议使用 ShardingSphere 的原生方式，在 XML 或注解中明确声明 key-generator。

对于 XML 配置：

xml 复制代码 
<insert id="insert" parameterType="Order" useGeneratedKeys="true" keyProperty="id" keyColumn="id">
  INSERT INTO t_order(user_id, amount, status) VALUES (#{userId}, #{amount}, #{status})
</insert>

当配置了 key-generate-strategy 后，ShardingSphere 会自动拦截 useGeneratedKeys 并应用分布式 ID。

10.5.2 雪花算法的时钟回拨处理

雪花算法严重依赖系统时钟，如果发生回拨可能产生重复 ID。ShardingSphere 的雪花算法内置了容忍机制：通过 max-tolerate-time-difference-milliseconds 配置最大容忍的时钟回拨毫秒数（默认 10 毫秒）。若回拨超过该值，则阻塞等待或抛出异常。生产环境必须配合 NTP 正确地设计方案，避免大幅回拨。

也可以使用 Leaf 或 UID-generator 等外部服务，ShardingSphere 支持自定义 key-generator SPI。

10.6 分库分表下的 MyBatis 注意事项与反模式

10.6.1 二级缓存必须禁用

ShardingSphere 的缓存路由是基于逻辑 SQL，但 MyBatis 二级缓存不知道分片细节，极易返回过时数据或错误数据。在配置中全局禁用：

yaml 复制代码 
mybatis:
  configuration:
    cache-enabled: false

或者在 MyBatis-Plus 中：mybatis-plus.configuration.cache-enabled=false。

10.6.2 MyBatis 插件的物理重复执行

由于 ShardingSphere 会将一条逻辑 SQL 拆分到多个物理分片上执行，MyBatis 的 StatementHandler 或 Executor 拦截器可能会被多次触发（每个物理执行各触发一次）。例如，慢 SQL 统计插件会针对同一个逻辑查询统计多次，导致数据虚高。

解决方案 ：在插件中判断当前是否为代理执行。ShardingSphere 的 StatementProxy 或 ConnectionProxy 提供了判定方法。

java 复制代码 
@Intercepts(@Signature(type = StatementHandler.class, method = "update", args = {Statement.class}))
public class SqlStatisticsPlugin implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 如果是 ShardingSphere 的物理执行，跳过统计或者特殊标记
        Statement stmt = (Statement) invocation.getArgs()[0];
        if (stmt instanceof StatementProxy) {
            // 这里可以进行物理 SQL 的采集（调试用），但统计逻辑 SQL 时建议只记录一次
            // 通过 ThreadLocal 记录本次逻辑 SQL 是否已统计
            if (!LogicSqlContext.isRecorded()) {
                // 记录逻辑SQL统计
                LogicSqlContext.markRecorded();
                recordLogicalSql(invocation);
            }
        }
        return invocation.proceed();
    }
}

另一个更简单的方式是在 Executor.query 和 update 级别拦截，ShardingSphere 只在第一个路由的 Executor 上触发一次（需验证版本与拦截点）。通常建议在 ShardingSphere 外层统一做监控。

10.6.3 分片键选择不当导致全表扫描

必须选择一个查询频率最高的字段作为分片键，否则大量查询无法精确路由，性能恶化。另外，避免使用具有高度偏斜的数据（如某个固定值 0），会导致数据倾斜。

反面案例 ：订单表选择 order_id 作为分片键，但查询大部分都是按 user_id 来查我的订单，导致每次查询都需要广播所有分片。应将 user_id 作为分片键，并让 order_id 中包含 user_id 信息（如雪花算法的前几位可以用 user_id 的后几位替换，属于高级玩法）。

10.7 PostgreSQL 分片实践：利用 Schema 模拟分库

PostgreSQL 的 schema 可以与 MySQL 的 database 类比，我们可以将一个物理 PostgreSQL 实例中的多个 schema 作为逻辑数据源，用于学习或小规模项目。但生产环境还是建议物理隔离。

10.7.1 配置示例

yaml 复制代码 
spring:
  shardingsphere:
    datasource:
      names: pg-ds0,pg-ds1
      pg-ds0:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: org.postgresql.Driver
        jdbc-url: jdbc:postgresql://localhost:5432/pg_order?currentSchema=schema0
        username: postgres
        password: postgres
      pg-ds1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: org.postgresql.Driver
        jdbc-url: jdbc:postgresql://localhost:5432/pg_order?currentSchema=schema1
        username: postgres
        password: postgres
    rules:
      sharding:
        tables:
          t_report:
            actual-data-nodes: pg-ds$->{0..1}.t_report
            database-strategy:
              standard:
                sharding-column: report_date
                sharding-algorithm-name: report-range
        sharding-algorithms:
          report-range:
            type: INTERVAL
            props:
              datetime-pattern: yyyy-MM-dd
              datetime-lower: 2024-01-01
              datetime-upper: 2025-01-01
              sharding-suffix-pattern: yyyyMM
              datetime-interval-amount: 1
              datetime-interval-unit: MONTHS

这样可以利用 PostgreSQL 的分区表功能与 ShardingSphere 结合，实现时间范围分片。因后续主体仍为 MySQL，这里仅做简略扩展，供异构需求参考。

11. 与现代数据访问框架的融合设计

成熟的订单系统不会只用一种数据访问模式。除了 MyBatis 处理核心业务，我们可能还会引入 JPA 进行简单的领域建模，或用 jOOQ 构建极端复杂的报表查询。同时，这些框架需要与现有的分库分表架构（ShardingSphere）和平共处。本章将详细展示这三者如何在同一个 Spring Boot 应用中优雅共存，并指出融合过程中的关键陷阱。

11.1 MyBatis + JPA 的优雅共存

JPA 的面向对象查询和 MyBatis 的 SQL 掌控力并不矛盾。我们可以为它们分配不同的职责：JPA 负责用户、商品等基础领域实体，MyBatis 则承接订单、对账等高频复杂业务。

11.1.1 架构设计：完全隔离的数据源与事务管理器

要避免两者互相干扰，必须从数据源、会话工厂、事务管理器到 Mapper 包完全隔离。

数据源划分：

  • mybatisDS：MySQL 数据库，供 MyBatis 使用。
  • jpaDS：同一 MySQL 实例的不同逻辑库，或干脆同一库（但为了隔离性，推荐不同库），供 JPA 使用。

包结构规划：

  • com.example.order.repository.mybatis：MyBatis Mapper 接口。
  • com.example.order.repository.jpa：JPA Repository 接口。
  • com.example.order.entity.jpa：JPA 实体类。

11.1.2 配置实现

首先在 application.yml 中定义两个数据源（不使用 dynamic-datasource，手动配置以展示原理）：

yaml 复制代码 
spring:
  datasource:
    mybatis:
      jdbc-url: jdbc:mysql://localhost:3306/order_db?useSSL=false
      username: root
      password: root
      driver-class-name: com.mysql.cj.jdbc.Driver
    jpa:
      jdbc-url: jdbc:mysql://localhost:3306/user_db?useSSL=false
      username: root
      password: root
      driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: validate

然后创建配置类：

java 复制代码 
@Configuration
public class MyBatisDataSourceConfig {

    @Primary
    @Bean(name = "mybatisDS")
    @ConfigurationProperties(prefix = "spring.datasource.mybatis")
    public DataSource mybatisDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Primary
    @Bean(name = "mybatisSqlSessionFactory")
    public SqlSessionFactory mybatisSqlSessionFactory(@Qualifier("mybatisDS") DataSource ds) 
            throws Exception {
        SqlSessionFactoryBean bean = new SqlSessionFactoryBean();
        bean.setDataSource(ds);
        bean.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mybatis/**/*.xml"));
        return bean.getObject();
    }

    @Primary
    @Bean(name = "mybatisSqlSessionTemplate")
    public SqlSessionTemplate mybatisSqlSessionTemplate(
            @Qualifier("mybatisSqlSessionFactory") SqlSessionFactory factory) {
        return new SqlSessionTemplate(factory);
    }

    @Primary
    @Bean(name = "mybatisTxManager")
    public PlatformTransactionManager mybatisTxManager(@Qualifier("mybatisDS") DataSource ds) {
        return new DataSourceTransactionManager(ds);
    }
}

@Configuration
@EnableTransactionManagement
public class JpaDataSourceConfig {

    @Bean(name = "jpaDS")
    @ConfigurationProperties(prefix = "spring.datasource.jpa")
    public DataSource jpaDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean(name = "entityManagerFactory")
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(
            EntityManagerFactoryBuilder builder, @Qualifier("jpaDS") DataSource ds) {
        return builder
                .dataSource(ds)
                .packages("com.example.order.entity.jpa")
                .persistenceUnit("jpa")
                .build();
    }

    @Bean(name = "jpaTxManager")
    public PlatformTransactionManager jpaTxManager(
            @Qualifier("entityManagerFactory") EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

注意 ：@MapperScan 也需要指定对应的 SqlSessionTemplate：

java 复制代码 
@Configuration
@MapperScan(basePackages = "com.example.order.repository.mybatis",
            sqlSessionTemplateRef = "mybatisSqlSessionTemplate")
public class MyBatisMapperScanConfig {}

11.1.3 在 Service 层混合使用

java 复制代码 
@Service
public class OrderService {

    @Autowired
    @Qualifier("mybatisTxManager")
    private PlatformTransactionManager mybatisTx;

    @Autowired
    private OrderMapper orderMapper; // MyBatis

    @Autowired
    private UserRepository userRepo; // JPA

    @Transactional(value = "mybatisTxManager")
    public void createOrder(Order order) {
        orderMapper.insert(order);
    }

    @Transactional(value = "jpaTxManager")
    public void updateUserName(Long userId, String name) {
        User user = userRepo.findById(userId).orElseThrow();
        user.setName(name);
        userRepo.save(user);
    }

    // 跨数据源但非事务强一致（允许最终一致）
    public void processOrderAndNotify(Order order, Long userId) {
        createOrder(order);
        updateUserName(userId, "Updated");
    }
}

11.1.4 故障模拟：事务管理器误用导致数据不一致

错误代码 ：直接在方法上使用 @Transactional 而不指定事务管理器，Spring 将使用 @Primary 的 mybatisTxManager。当方法内部使用 JPA 并期望事务回滚时，JPA 部分不受 mybatisTxManager 管理，回滚不会生效。

java 复制代码 
@Transactional // 默认使用 mybatisTxManager
public void saveOrderAndUser(Order order, User user) {
    orderMapper.insert(order); // MyBatis 会回滚
    userRepo.save(user);       // JPA 不会回滚，数据被持久化！
    if (true) throw new RuntimeException("模拟异常");
}

现象：异常发生后，订单表没有数据（MyBatis 回滚成功），但用户表多了一条数据（JPA 已提交，因为其使用的是自己的事务管理器，且 Spring 默认不会进行两阶段提交）。

排查 ：开启 JPA 的 SQL 日志，观察 userRepo.save 的 INSERT 提交时机。同时使用 Arthas 检查当前事务同步状态。

修复 ：要么将 JPA 部分移到独立事务方法中，要么使用 JTA 分布式事务 或 Seata 之类协调。但在微服务化趋势下，更推荐拆分并通过可靠消息最终一致。

11.2 MyBatis + jOOQ 的混合使用

jOOQ 擅长类型安全的复杂 SQL 构建，适合报表、多维分析等 MyBatis XML 写起来痛苦的场景。两者共享同一个数据源与事务管理器，可以无缝紧耦合。

11.2.1 集成配置

确保已经引入了 jOOQ 依赖，并在 Spring Boot 中配置 DSLContext：

java 复制代码 
@Configuration
public class JooqConfig {

    @Bean
    public DSLContext dslContext(@Qualifier("mybatisDS") DataSource dataSource) {
        // 注意 jOOQ 需要自身的 ConnectionProvider，通常我们通过 Spring 的 DataSource 构建
        ConnectionProvider connProvider = new DataSourceConnectionProvider(
                new TransactionAwareDataSourceProxy(dataSource));
        Configuration configuration = new DefaultConfiguration()
                .set(SQLDialect.MYSQL)
                .set(connProvider);
        return DSL.using(configuration);
    }
}

这里使用 TransactionAwareDataSourceProxy 确保 jOOQ 能参与当前 Spring 事务。

同时，也可以使用 Spring Boot 的自动配置（如果引入了 jooq-spring-boot-starter），它会自动创建一个使用 DataSource 的 DSLContext。

11.2.2 混合编码示例

在 DAO 或 Service 中同时注入 OrderMapper 和 DSLContext：

java 复制代码 
@Repository
public class ReportDao {

    @Autowired
    private OrderMapper orderMapper;               // MyBatis 处理简单查询

    @Autowired
    private DSLContext dsl;                       // jOOQ 处理复杂报表

    @Transactional // 整个操作在一个事务中（使用的是 MyBatis 的主事务管理器）
    public ReportData generateMonthlyReport(int year, int month) {
        // 1. 使用 MyBatis 获取基础汇总
        Summary summary = orderMapper.selectSummary(year, month);

        // 2. 使用 jOOQ 构建复杂多维分析
        Result<Record3<String, BigDecimal, Integer>> result = dsl
            .select(ORDER.STATUS, sum(ORDER.AMOUNT).as("total"), count())
            .from(ORDER)
            .where(year(ORDER.CREATE_TIME).eq(year)
                .and(month(ORDER.CREATE_TIME).eq(month)))
            .groupBy(ORDER.STATUS)
            .orderBy(field("total").desc())
            .fetch();

        // 合并结果
        return buildReport(summary, result);
    }
}

由于 jOOQ 和 MyBatis 共享同一个事务管理器，当方法抛出异常时，两者所做的插入/更新会一起回滚，保证一致性。

11.2.3 故障模拟：共享事务不同步

错误示例 ：使用 DataSourceUtils.getConnection(dataSource) 手动获取连接并开启事务，但未通过 Spring 事务管理器同步，导致 MyBatis 的执行和 jOOQ 的执行不在同一个连接上。

java 复制代码 
// 错误示范
Connection conn = dataSource.getConnection();
conn.setAutoCommit(false);
try {
    orderMapper.insert(order); // 内部获取另一个连接！
    dsl.insertInto(...).execute(); // 使用 conn 手动提交
    conn.commit();
} catch (Exception e) {
    conn.rollback();
}

现象 ：orderMapper.insert 会通过 Spring 的事务管理器（如果有 @Transactional）或 SqlSession 默认获取连接，而这个连接可能和 conn 不同，导致操作分离，不具备原子性。

修复 ：使用 @Transactional 注解，让 Spring 管理一切。TransactionAwareDataSourceProxy 会保证在事务内 jOOQ 使用的连接与 MyBatis 一致。

11.3 MyBatis + ShardingSphere 深度结合：记录真实物理 SQL

在分库分表环境下，MyBatis 的日志只能看到逻辑 SQL，为调试需要知道最终路由到了哪些物理表、真实执行的 SQL 是什么。我们开发一个 MyBatis 插件，专门记录 ShardingSphere 改写后的物理 SQL。

11.3.1 插件实现

java 复制代码 
@Intercepts({
    @Signature(type = StatementHandler.class, method = "update", args = {Statement.class}),
    @Signature(type = StatementHandler.class, method = "query", args = {Statement.class, ResultHandler.class})
})
public class ShardingPhysicalSqlPlugin implements Interceptor {

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        Statement stmt = (Statement) invocation.getArgs()[0];
        // 判断是否是 ShardingSphere 的代理 Statement
        if (stmt instanceof StatementProxy) {
            StatementProxy proxy = (StatementProxy) stmt;
            String actualSql = proxy.getExecuteContext().getSqlStatement().getSql();
            // 替换参数，得到可读 SQL
            String showSql = proxy.showSQL();
            log.info("物理 SQL [{}]: {}", proxy.getConnectionSession().getDatabaseName(), showSql);
        }
        return invocation.proceed();
    }
}

配置插件：

java 复制代码 
@Bean
public ShardingPhysicalSqlPlugin shardingPhysicalSqlPlugin() {
    return new ShardingPhysicalSqlPlugin();
}

11.3.2 效果展示

当 MyBatis 执行一条逻辑 SQL：

sql 复制代码 
Logic SQL: SELECT * FROM t_order WHERE user_id = 1001

插件日志会输出：

sql 复制代码 
物理 SQL [ds0]: SELECT * FROM t_order_1 WHERE user_id = 1001

无需 sql-show 全局属性，可按需在代码中查看，同时也可以结合自定义逻辑记录到监控系统。

11.3.3 扩展：性能影响考量

StatementProxy.showSQL() 会进行参数占位符替换，有一定的开销。线上环境可以仅在 DEBUG 或 WARN 级别启用，或利用开关动态控制。

11.4 融合设计总结

我们通过 Spring 的 IOC 容器，将 MyBatis、JPA、jOOQ、ShardingSphere 这些不同职责的组件编织在了一起。关键成功要素有：

  1. 数据源与事务的彻底隔离 ：不同的持久化框架使用独立的 DataSource、TransactionManager，避免相互污染。
  2. 分包与 @MapperScan 精确绑定 ：让 Spring 知道哪个 Mapper 用哪个 SqlSessionFactory。
  3. 共享事务时使用 TransactionAwareDataSourceProxy：确保非 Spring 管理的框架（jOOQ）也能参与同一个事务。
  4. 插件扩展保持轻量：记录物理 SQL 等调试功能按需启用。

在实际项目中，根据团队能力可以选择其中两者或三者共存，不必全部引入。但掌握了这套融合方式后，架构的扩展性和适应性将得到显著提升。

12. Actuator 监控与可观测性

12.1 自定义端点完整实现与 JSON 响应

java 复制代码 
@Component
@Endpoint(id = "mybatis")
public class MyBatisMetricsEndpoint {
    @Autowired
    private SlowSqlStatsCollector statsCollector;
    @Autowired(required = false)
    private MeterRegistry meterRegistry;

    @ReadOperation
    public Map<String, Object> metrics() {
        Map<String, Object> result = new HashMap<>();
        // 慢SQL统计
        result.put("slowSqls", statsCollector.getStats());
        // Micrometer 指标采样
        if (meterRegistry != null) {
            double p99 = meterRegistry.get("mybatis.sql.timer").timer().takeSnapshot().percentileValue(0.99);
            result.put("sqlTimerP99", p99);
        }
        return result;
    }
}

12.2 Prometheus 指标与 PromQL

暴露 endpoint 后，Prometheus 配置抓取。关键指标：mybatis_sql_timer_seconds（由 Micrometer 生成）。PromQL 示例：

promql 复制代码 
# SQL 执行 P99 延迟
histogram_quantile(0.99, rate(mybatis_sql_timer_seconds_bucket[5m]))

# 慢 SQL 趋势（超过1s的调用次数）
rate(mybatis_sql_timer_seconds_count{le="+Inf"}[5m]) - rate(mybatis_sql_timer_seconds_count{le="1.0"}[5m])

12.3 Grafana 仪表盘设计建议

创建面板：

  • SQL 调用量 QPS
  • P95/P99 延迟
  • 慢 SQL Top 10（从自定义端点获取）
  • 连接池活跃/空闲连接数
    可导入社区模板 ID (如 12423) 并修改。

13. 反模式规避与部署检查单

13.1 反模式规避总结

增加具体检查项：

  • 禁止 ：<if test="id != null and id != ''"> 对数值类型
  • 禁止 ：${} 用于用户输入字段，除非已验证
  • 分页 ：必须设置 reasonable=true 防止巨大偏移量
  • 缓存：分库分表下全局禁用二级缓存
  • 批处理 ：必须显式 flushStatements 或在事务边界内使用

13.2 故障速查表（增强）

故障 根因 关键日志/堆栈 排查命令/工具 修复
连接关闭 事务提前提交 Connection is closed trace SqlSessionTemplate closeSqlSession TransactionTemplate 包裹
缓存脏读 更新未 flush 断言失败 DEBUG MyBatis Cache 命中次数 update 语句加 flushCache=true
OGNL 零值过滤 status != ''误判 SQL 参数正确但无条件 watch OgnlCache getValue 移除 != ''
分片分页慢 全分片归并 sql-show 显示多个 LIMIT ShardingSphere 日志 使用游标分页
批量插入丢失 非事务 close 无 insert 日志 trace DefaultSqlSession close 使用 @Transactional + BATCH

13.3 MyBatis 生产上线检查单（表格化）

检查项 分类 通过标准
连接池参数泄漏检测开启 连接池 leakDetectionThreshold ≤ 20000ms
所有 ${} 使用场景无注入 安全 代码审查通过
分页插件配置 reasonable 性能 翻页不超总页数
二级缓存在分表环境中禁用 缓存 mybatis.configuration.cache-enabled=false
自定义插件顺序声明 插件 文档记录顺序且避免互相干扰
流式查询事务边界 事务 游标使用均在事务内
多数据源 @Primary 标注 数据源 默认数据源符合预期
ShardingSphere sql-show 开启 分片 测试环境可见路由
Actuator 指标正常抓取 监控 Prometheus up 1
扩容方案演练通过 运维 迁移时间 ≤ 2h，回滚正常

项目源码结构和快速启动

完整的项目托管在 GitHub（假设），结构如下：

css 复制代码 
lightning-deal-data-layer
├── order-common                    # 通用实体、枚举、工具类
├── order-mybatis-native            # 原生 MyBatis 复杂报表模块
│   ├── src/main/java/.../mapper/native
│   └── src/main/resources/mybatis/native
├── order-mybatis-plus              # MyBatis-Plus 基础CRUD模块
├── order-sharding                  # ShardingSphere 配置与扩展
├── order-plugin                    # 自定义插件（慢SQL、多租户等）
├── order-benchmark                 # JMH 性能基准测试
├── order-web                       # Spring Boot 主应用，整合Actuator
└── order-migration                 # 扩容脚本和工具

启动命令：mvn clean install 后在 order-web 模块运行 LightningDealApplication。

所有故障场景均作为 JUnit 测试位于对应模块的 src/test/java，例如 CacheDirtyReadTest、CursorClosedExceptionTest、OGNLZeroTest，可直接运行验证。

架构总览图

graph TD A[Controller] --> B[Service Facade] B --> C1[MyBatis Native Mapper] B --> C2[MyBatis-Plus Mapper] B --> C3[JPA Repository] B --> C4[jOOQ DSL] C1 & C2 --> D[SqlSessionTemplate] C3 --> E[EntityManager] D --> F[Plugin Chain] F --> G[ShardingSphere-JDBC] G --> H[(MySQL Shards)] E --> I[(PostgreSQL)] H & I --> J[Actuator + Micrometer] J --> K[Prometheus + Grafana]

分库分表扩容时序图

sequenceDiagram participant App participant OldCluster as 旧集群(2分片) participant Sync as 数据同步管道 participant NewCluster as 新集群(4分片) App ->> OldCluster: 写入 App ->> Sync: 双写开关 Sync ->> OldCluster: 全量同步 Sync ->> NewCluster: 全量写入 Sync ->> OldCluster: 实时增量复制(binlog) Sync ->> NewCluster: 增量写入 Note over App,Sync: 数据一致性校验通过后 App ->> NewCluster: 切换路由，下线旧集群
相关推荐
敖正炀5 小时前
多数据源与读写分离中间件
mybatis
胡楚昊6 小时前
BUU WEB之旅（1）
java·数据库·mybatis
敖正炀7 小时前
MyBatis 通用插件库与性能监控平台
mybatis
敖正炀8 小时前
手写简易 MyBatis 框架（mini-mybatis）—— 完善版架构设计与核心实现
后端·mybatis
敖正炀8 小时前
反模式与排查宝典：MyBatis 常见陷阱与排错指南
mybatis
_Evan_Yao9 小时前
return 的迷途：try-catch-finally 中 return 的诡异顺序与 Spring 事务暗坑
java·后端·spring·mybatis
Java成神之路-1 天前
MyBatis工作原理
mybatis
敖正炀2 天前
MyBatis 性能调优：批处理、流式查询与 SQL 优化
mybatis
敖正炀2 天前
初始化流程的完整串联：从 XML 到 SqlSessionFactory
mybatis
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法04零基础教你claude code 接入 deepseek V405Linux 核弹级高危漏洞 CVE-2026-31431 完整修复指南06CC-Switch & Claude 基于 Linux 服务器安装使用指南07裂开！ChatGPT 居然开始要手机号验证，附详细解决方法08CVE-2026-31431 (Copy Fail) 漏洞复现与验证记录092026 年 AI 辅助编程工具全景对比：Copilot、Cursor、Claude Code 与 Codex 深度解析10【AI】2026 年具身智能模型和世界模型总结