实现MyBatis动态SQL性能的可观测性 从Oracle到Prometheus再到Storybook诊断面板

Prometheus Oracle MyBatis Storybook
可观测性
文章字数:   3.5k
阅读时长:   15 分

一个陈旧但核心的报表模块，响应时间从几百毫秒悄无声息地攀升到了十几秒。应用性能监控（APM）系统只给出了一个模糊的告警：com.ourcompany.mapper.ReportMapper.queryComplexReport方法耗时过长。DBA团队介入，发现Oracle数据库的CPU在特定时间段内有毛刺，但面对连接池中涌入的大量SQL，他们也无法快速定位到具体是哪一个执行计划出了问题。

问题根源在于那个巨大的ReportMapper.xml。其中queryComplexReport这一个MyBatis方法，内部包含了超过二十个<if>标签和多个<foreach>循环，根据前端传入的不同筛选条件，它能组合出上百种形态各异的SQL。有些组合高效利用了索引，而另一些则可能导致全表扫描甚至笛卡尔积。传统的监控只能告诉我们这个Java方法变慢了，却无法揭示是哪一种参数组合，生成了哪一种劣质SQL，从而导致了性能灾难。我们需要的，是深入MyBatis动态SQL执行内部的“显微镜”。

初步构想：从日志到指标的转变

最初的想法是简单粗暴地在代码中加入日志，打印出每次执行的入参和最终生成的SQL。但在预生产环境的压力测试下，这个方案迅速暴露了其弊端：日志量瞬间爆炸，磁盘I/O成为新的瓶颈，海量的日志文本也让分析工作如同大海捞针。

我们需要的是一种量化的、聚合的、可持续观测的方式。日志是“事件”，而我们需要的是“指标”。如果能将动态SQL的“复杂度”转化为可度量的指标，问题就迎刃而解。例如：

  • 最终生成的SQL语句长度。
  • SQL中包含的AND或OR条件数量。
  • <foreach>循环生成的IN (...)子句中的元素个数。

这些指标与SQL的性能通常存在强相关性。将这些指标暴露给Prometheus，我们就能绘制出SQL复杂度的时序曲线，并与数据库的CPU使用率、查询耗时等指标进行关联分析，从而精准定位问题。

技术选型决策：MyBatis拦截器与Micrometer的组合拳

为了无侵入地收集这些指标，MyBatis的Interceptor机制是最佳选择。它可以拦截Executor（执行器）、StatementHandler（语句处理器）、ParameterHandler（参数处理器）和ResultSetHandler（结果集处理器）等核心组件的方法。我们决定拦截StatementHandler的prepare方法，因为在这个阶段，BoundSql对象已经被创建，包含了最终要执行的SQL字符串和参数信息。

指标的暴露则选用Micrometer。作为Spring Boot Actuator的底层库，它提供了一套统一的API来对接各种监控系统，包括Prometheus。这让我们的实现可以与现有技术栈无缝集成。

整个方案的技术链路因此确定：

  1. 数据采集：自定义一个MyBatis拦截器，在SQL执行前分析BoundSql，计算出复杂度指标。
  2. 指标暴露：使用Micrometer在应用内部注册和更新这些指标。
  3. 度量存储与查询：通过Spring Boot Actuator的/actuator/prometheus端点，让Prometheus Server定期抓取。
  4. 可视化与分析：在开发阶段，我们还需要一个更直接的反馈回路。与其让开发人员在编码、部署、压测、查看Grafana之间反复切换，不如构建一个专用的诊断面板。考虑到我们的前端团队重度使用React和Storybook，一个大胆的想法应运而生：利用Storybook创建一个“实时SQL性能诊断”组件，直接查询Prometheus API，让开发者在本地构建UI时就能看到后端SQL的性能变化。

步骤化实现：构建完整的可观测性闭环

第一阶段：心脏——DynamicSqlMetricsInterceptor

这是整个方案的核心。我们需要创建一个拦截器，它不仅要能正确捕获SQL，还要足够健壮和高效，避免对应用本身造成性能影响。

package com.ourcompany.platform.mybatis;

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Tag;
import org.apache.ibatis.executor.statement.StatementHandler;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.plugin.*;
import org.apache.ibatis.reflection.MetaObject;
import org.apache.ibatis.reflection.SystemMetaObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.sql.Connection;
import java.util.Arrays;
import java.util.List;
import java.util.Properties;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * MyBatis动态SQL性能指标拦截器
 * 拦截StatementHandler的prepare方法，在SQL执行前分析其复杂度。
 */
@Component
@Intercepts({@Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class})})
public class DynamicSqlMetricsInterceptor implements Interceptor {

    private static final Logger log = LoggerFactory.getLogger(DynamicSqlMetricsInterceptor.class);

    // 使用正则表达式来近似计算条件数量，这是一种权衡，避免了复杂的SQL解析
    private static final Pattern AND_OR_PATTERN = Pattern.compile("\\s+(and|or)\\s+", Pattern.CASE_INSENSITIVE);
    private static final Pattern IN_CLAUSE_PATTERN = Pattern.compile("\\s+in\\s*\\(", Pattern.CASE_INSENSITIVE);

    private final MeterRegistry meterRegistry;

    public DynamicSqlMetricsInterceptor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        long startTime = System.nanoTime();
        try {
            StatementHandler statementHandler = (StatementHandler) invocation.getTarget();
            MetaObject metaObject = SystemMetaObject.forObject(statementHandler);
            // MappedStatement包含了SQL的元数据信息，如ID
            MappedStatement mappedStatement = (MappedStatement) metaObject.getValue("delegate.mappedStatement");
            String mapperId = mappedStatement.getId();

            // BoundSql包含了最终生成的SQL和参数
            BoundSql boundSql = statementHandler.getBoundSql();
            String sql = cleanSql(boundSql.getSql());

            // --- 核心指标计算 ---
            int conditions = countMatches(AND_OR_PATTERN, sql);
            int inClauses = countMatches(IN_CLAUSE_PATTERN, sql);
            int sqlLength = sql.length();
            
            // --- 使用Micrometer上报指标 ---
            List<Tag> tags = Arrays.asList(Tag.of("mapper_id", mapperId));

            // 1. SQL长度
            meterRegistry.gauge("mybatis_sql_length", tags, sqlLength);

            // 2. 条件计数器
            Counter.builder("mybatis_sql_conditions_total")
                .description("Total number of AND/OR conditions in dynamic SQL")
                .tags(tags)
                .register(meterRegistry)
                .increment(conditions);
            
            // 3. IN子句计数器
            Counter.builder("mybatis_sql_in_clauses_total")
                .description("Total number of IN clauses in dynamic SQL")
                .tags(tags)
                .register(meterRegistry)
                .increment(inClauses);

        } catch (Exception e) {
            // 监控代码决不能影响主业务流程
            log.error("Error in DynamicSqlMetricsInterceptor", e);
        } finally {
            // 监控拦截器自身执行耗时，确保其性能
            long duration = System.nanoTime() - startTime;
            meterRegistry.timer("mybatis_interceptor_duration_nanos").record(duration, java.util.concurrent.TimeUnit.NANOSECONDS);
        }

        // 继续执行原始调用
        return invocation.proceed();
    }

    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

    @Override
    public void setProperties(Properties properties) {
        // no-op
    }

    /**
     * 清理SQL字符串，去除多余的空格和换行符，便于分析
     */
    private String cleanSql(String sql) {
        if (sql == null) {
            return "";
        }
        return sql.replaceAll("\\s+", " ").trim();
    }

    /**
     * 计算正则表达式匹配次数
     */
    private int countMatches(Pattern pattern, String input) {
        if (input == null || input.isEmpty()) {
            return 0;
        }
        Matcher matcher = pattern.matcher(input);
        int count = 0;
        while (matcher.find()) {
            count++;
        }
        return count;
    }
}

这个拦截器的关键在于：

  1. 注入MeterRegistry: 通过构造函数注入，方便与Spring生态集成。
  2. 健壮性: 使用try-catch块包裹所有逻辑，确保即使监控代码抛出异常，也不会影响正常的数据库操作。
  3. 自监控: 记录并监控拦截器本身的执行耗时，防止它成为新的性能瓶颈。
  4. 指标设计: 使用Tag来区分不同的MyBatis Mapper方法ID，这是实现精细化监控的核心。我们选择了gauge来记录SQL长度，Counter来累计条件数量。

第二阶段：集成与暴露

将拦截器集成到Spring Boot应用中非常直接。

首先，确保pom.xml中包含必要的依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
<!-- Oracle Driver -->
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <scope>runtime</scope>
</dependency>

然后，通过Java配置类注册我们的拦截器：

package com.ourcompany.platform.config;

import com.ourcompany.platform.mybatis.DynamicSqlMetricsInterceptor;
import org.apache.ibatis.session.SqlSessionFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;

import javax.annotation.PostConstruct;
import java.util.List;

@Configuration
public class MyBatisConfig {

    @Autowired
    private List<SqlSessionFactory> sqlSessionFactoryList;

    @Autowired
    private DynamicSqlMetricsInterceptor dynamicSqlMetricsInterceptor;

    @PostConstruct
    public void addCustomInterceptor() {
        for (SqlSessionFactory sqlSessionFactory : sqlSessionFactoryList) {
            // 将我们的拦截器添加到MyBatis的拦截器链中
            sqlSessionFactory.getConfiguration().addInterceptor(dynamicSqlMetricsInterceptor);
        }
    }
}

最后，配置application.yml以暴露Prometheus端点：

management:
  endpoints:
    web:
      exposure:
        include: "prometheus,health"
  metrics:
    tags:
      # 为所有指标添加应用级别的标签，便于区分
      application: my-reporting-service

启动应用，访问http://localhost:8080/actuator/prometheus，我们就能看到新添加的自定义指标了：

# HELP mybatis_sql_length 
# TYPE mybatis_sql_length gauge
mybatis_sql_length{application="my-reporting-service",mapper_id="com.ourcompany.mapper.ReportMapper.queryComplexReport",} 678.0
# HELP mybatis_sql_conditions_total_total Total number of AND/OR conditions in dynamic SQL
# TYPE mybatis_sql_conditions_total_total counter
mybatis_sql_conditions_total_total{application="my-reporting-service",mapper_id="com.ourcompany.mapper.ReportMapper.queryComplexReport",} 15.0

第三阶段：在Storybook中创建诊断面板

这是将后端可观测性直接赋能给前端开发者的关键一步。我们的目标是在Storybook中创建一个React组件，它能实时查询Prometheus并展示特定Mapper的性能指标。

// src/components/MybatisSqlMonitorPanel.jsx

import React, { useState, useEffect } from 'react';
import axios from 'axios';

// 这是一个简化的实现，真实项目中应处理更复杂的UI和错误状态
const cardStyle = {
  border: '1px solid #ddd',
  borderRadius: '8px',
  padding: '16px',
  fontFamily: 'monospace',
  width: '400px',
  boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
};

const metricStyle = {
  marginBottom: '12px',
};

const labelStyle = {
  fontWeight: 'bold',
  color: '#333',
};

const valueStyle = {
  marginLeft: '8px',
  color: '#007bff',
  fontSize: '1.2em',
};

export const MybatisSqlMonitorPanel = ({ prometheusUrl, mapperId }) => {
  const [metrics, setMetrics] = useState({
    sqlLength: 0,
    conditionsRate: 0,
    inClausesRate: 0,
  });
  const [error, setError] = useState(null);

  useEffect(() => {
    if (!prometheusUrl || !mapperId) {
      setError("Prometheus URL and Mapper ID are required.");
      return;
    }

    const fetchData = async () => {
      try {
        const promQlBase = `${prometheusUrl}/api/v1/query?query=`;
        
        // 构建PromQL查询语句
        const lengthQuery = `mybatis_sql_length{mapper_id="${mapperId}"}`;
        const conditionsQuery = `rate(mybatis_sql_conditions_total{mapper_id="${mapperId}"}[1m])`;
        const inClausesQuery = `rate(mybatis_sql_in_clauses_total{mapper_id="${mapperId}"}[1m])`;

        // 并发执行查询
        const [lengthRes, conditionsRes, inClausesRes] = await Promise.all([
          axios.get(promQlBase + encodeURIComponent(lengthQuery)),
          axios.get(promQlBase + encodeURIComponent(conditionsQuery)),
          axios.get(promQlBase + encodeURIComponent(inClausesQuery)),
        ]);

        // 解析Prometheus响应
        const parseResult = (res) => {
          if (res.data.status === 'success' && res.data.data.result.length > 0) {
            return parseFloat(res.data.data.result[0].value[1]).toFixed(2);
          }
          return 0;
        };

        setMetrics({
          sqlLength: parseResult(lengthRes),
          conditionsRate: parseResult(conditionsRes),
          inClausesRate: parseResult(inClausesRes),
        });
        setError(null);
      } catch (err) {
        console.error("Failed to fetch metrics from Prometheus:", err);
        setError("Failed to fetch metrics. Is Prometheus reachable?");
      }
    };

    const intervalId = setInterval(fetchData, 5000); // 每5秒刷新一次
    fetchData(); // 立即执行一次

    return () => clearInterval(intervalId);
  }, [prometheusUrl, mapperId]);

  return (
    <div style={cardStyle}>
      <h4>MyBatis SQL Monitor</h4>
      <p><strong>Mapper ID:</strong> {mapperId}</p>
      <hr />
      {error ? (
        <p style={{ color: 'red' }}>{error}</p>
      ) : (
        <div>
          <div style={metricStyle}>
            <span style={labelStyle}>SQL Length (Gauge):</span>
            <span style={valueStyle}>{metrics.sqlLength}</span>
          </div>
          <div style={metricStyle}>
            <span style={labelStyle}>Conditions Rate (per/sec):</span>
            <span style={valueStyle}>{metrics.conditionsRate}</span>
          </div>
          <div style={metricStyle}>
            <span style={labelStyle}>IN Clauses Rate (per/sec):</span>
            <span style={valueStyle}>{metrics.inClausesRate}</span>
          </div>
        </div>
      )}
    </div>
  );
};

接着，为这个组件创建Storybook的故事文件：

// src/components/MybatisSqlMonitorPanel.stories.js

import React from 'react';
import { MybatisSqlMonitorPanel } from './MybatisSqlMonitorPanel';

export default {
  title: 'Diagnostics/MybatisSqlMonitorPanel',
  component: MybatisSqlMonitorPanel,
  argTypes: {
    prometheusUrl: { control: 'text' },
    mapperId: { control: 'text' },
  },
};

const Template = (args) => <MybatisSqlMonitorPanel {...args} />;

export const LiveMonitor = Template.bind({});
LiveMonitor.args = {
  // 在真实开发环境中，这里应指向开发联调环境的Prometheus地址
  // 通常通过代理或直接配置
  prometheusUrl: 'http://localhost:9090', 
  mapperId: 'com.ourcompany.mapper.ReportMapper.queryComplexReport',
};

LiveMonitor.parameters = {
  docs: {
    description: {
      story: 'This component connects to a live Prometheus instance to display real-time metrics for a specific MyBatis mapper method. It requires a local proxy setup to avoid CORS issues during development.',
    },
  },
};

成果与反馈闭环

我们将这个MybatisSqlMonitorPanel组件集成到了报表筛选表单的Storybook页面中。现在，前端开发者在调整或增加一个新的筛选条件时，可以并排看到UI和这个诊断面板。

当一位开发者添加了一个新的“按区域”筛选，并选择多个区域时，他会立即看到：

  • SQL Length 指标显著增加。
  • IN Clauses Rate 指标从0跳升到一个正数。
  • Conditions Rate 指标也相应增加。

如果这个改动无意中与一个已有的<if>条件组合，导致了查询性能急剧下降，他甚至不需要等待后端部署或压测。他只需要观察本地开发环境中的后端应用日志，看到响应时间变长，同时在Storybook中看到复杂度指标的剧烈波动，就能立刻意识到问题所在。这个即时反馈的闭环，将原本需要跨越开发、测试、运维多个环节才能发现的性能问题，压缩到了开发者的编码阶段。

sequenceDiagram
    participant FE as Frontend Developer (in Storybook)
    participant UI as React Component
    participant Panel as MybatisSqlMonitorPanel
    participant BE as Backend App
    participant Interceptor as DynamicSqlMetricsInterceptor
    participant Oracle as Oracle DB
    participant Prom as Prometheus

    FE->>+UI: Interact with filters (e.g., add regions)
    UI->>+BE: API Call to fetch report data
    BE->>+Interceptor: MyBatis query execution starts
    Interceptor->>Oracle: Prepare Statement
    Interceptor-->>Prom: Records SQL metrics (length, conditions)
    Oracle-->>BE: Returns query result
    BE-->>-UI: Returns API response
    UI-->>-FE: Renders report data

    loop 5 seconds interval
        Panel->>+Prom: Query API for metrics (PromQL)
        Prom-->>-Panel: Returns latest metric values
        Panel->>FE: Updates displayed metrics in real-time
    end

遗留问题与未来迭代方向

这个方案的有效性在我们的项目中得到了验证，但它并非完美。首先，基于正则表达式的SQL复杂度分析是一种启发式方法，它无法理解SQL的语法结构，可能在面对极其复杂的嵌套子查询时出现误判。一个更精准的方案是引入一个轻量级的SQL解析器（如JSqlParser），但这会增加拦截器的执行开销，需要仔细进行性能评估。

其次，当前的指标仅限于SQL的静态结构。未来的迭代可以考虑引入更多动态指标，例如通过拦截ResultSetHandler来获取查询返回的行数，这对于发现因数据倾斜导致的性能问题非常有帮助。

最后，这个开发阶段的诊断面板非常有效，但它不能替代生产环境的监控。Grafana仍然是生产告警和长期趋势分析的最佳工具。我们方案的美妙之处在于，为Storybook和Grafana提供指标的是同一个Prometheus数据源，这确保了从开发到生产的可观测性数据的一致性。

Prometheus Oracle MyBatis Storybook
  目录