SQL 日志工具窗口

演示所示：带参 SELECT、WHERE id=NULL 零匹配 UPDATE（0 rows），以及固定只读 SELECT 的语法错误先后入列；还原后的 SQL、实参、影响行数与报错直接在列表中呈现。

自动捕获运行中的 SQL，统一还原成可执行 SQL 列表，并可精确跳转到触发这条 SQL 的源码位置。默认走增强捕获通道，开箱即得；控制台捕获作为不改工程的回落通道。

触发方式

方式	操作
手动捕捉	侧边栏「SQL Visualizer」工具窗口 → 切到「SQL 日志」页签 → 面板工具栏首位的「捕捉」按钮
自动监听	设置页「项目启动时自动开始监听」开启后，运行 / 调试项目时自动开始捕捉，无需手动点按钮

首次使用有引导：打开含 MyBatis-Plus 用法的代码文件会弹一次指路通知（本机一次性，设置页可关）；会话内首次捕获成功也会弹通知，可一键直达日志面板。

自动监听有几个细节：开启设置本身不会立即开始监听，等运行项目时才触发；手动点「停止捕捉」会抑制自动启动，本会话内不再自动弹回；只要开关还开着，下次运行项目时又会自动开始。

两种捕获通道

条目来源有两种，进入同一列表，展示与操作完全一致。默认用增强捕获——开箱即得、数据最全，也是本页推荐的方式；控制台捕获是不改工程、零注入的兼容与回落通道（增强捕获不可用、或你更希望完全不碰应用进程时用它）。

通道	来源	定位
增强捕获（默认，推荐）	字节码增强挂载到本机应用 JVM，在 JDBC 接口层直接采集	无需应用开启 SQL 日志；参数、耗时、影响行数、报错、源码位置与调用栈全是真实结构化数据
控制台捕获（回落）	监听运行控制台日志输出	不改工程、不注入；但要求应用把 SQL 打到控制台，参数还原依赖日志格式与级别（常见做法是开 TRACE），源码位置还需额外配置拦截器

增强捕获默认开启，打开即授权——不再有逐次注入确认框。打开项目、首次运行、进程出现、设置页勾选都直接进入采集，首轮运行即完整捕获（含启动期 SQL），不用等重启项目；不想用可在设置页关掉开关，关掉后回落控制台通道。核心能力：

• 真实参数值（默认不脱敏，设置页可开启打码）、毫秒级精确执行耗时、影响行数与执行报错信息——这些控制台通道要么拿不到，要么只能靠日志文本反查
• 条目带目标库角标（如 [MySQL]、[DM（达梦）]），按 JDBC URL 推断，覆盖全部 11 种方言数据库及 HSQL / GBASE
• 源码位置取自真实调用栈，跳转直达执行 SQL 的代码行，无需任何配置（见下文「跳转到源码」）；控制台通道要自己配拦截器才有同样精度
• 条目附带完整调用栈快照——预览面板悬停即可查看整条调用链，点击任意一帧跳到该帧源码（见下文「从调用栈跳转」）
• 采集到的数据仅展示在本机 IDE 内，不回传任何服务器；关闭开关即停止采集（已挂载的采集点保留但不工作）

目标库角标默认只显示数据库类型，设置页开启「数据源角标显示完整上下文」后即时切换为 方言 · 库名@主机:端口 全量形态（上图为切换过程）。

启动注入与开关行为（何时看：关注 JVM 注入机制或想彻底关掉采集时）

• 默认开启、打开即授权：总开关出厂为开，勾选或打开项目即视为授权，不再弹注入确认框；旧配置里遗留的「未确认」状态在加载时静默归一为已授权，用户显式关掉的开关保持关闭。
• 在跑进程补扫：监听启动时对已在运行的应用进程自动补扫并直接挂载，不再有确认环节。
• 启动即捕获：总开关开启时，Java 运行配置启动前自动写入 -javaagent，agent 在目标 JVM premain 阶段完成织入——启动期 SQL（框架初始化、数据源探活、Flyway / Liquibase 迁移）直接进增强通道，不再落在挂载完成之前。关闭总开关时零注入；注入任一步失败只回落既有 attach 挂载与控制台桥，不影响运行配置本身。
• 能力边界如实提示：注入失败回落 attach 热挂载成功时，会提示「挂载前已创建的连接不在捕获范围，重新运行项目后完整生效」（每轮至多一次）。
• 注入范围：-javaagent 只进真实应用运行任务；Gradle / Maven 的测试与 IDE 任务（test、runIde 等）fork 出的 JVM 一律不注入。
• 采集零替换：agent 绝不在宿主侧替换 JDBC 对象——连接默认原样保留（只登记连接 URL），SQL 与绑定参数经语句面字节码织入采集，应用侧对连接的强转（如达梦 DmdbConnection）不受影响；如需恢复旧的连接包装形态，显式加 -Dsqlvis.agent.wrapConnection=true（默认关，「不让应用起不来」优先于覆盖面）。已知边界：语句实现类不在织入名单的驱动（GBASE 8s、部分 SQLite / HSQLDB 形态）默认不再产出事件。
• 关掉开关：停止采集并回落控制台捕获，列表不断供；设置页可随时重新开启，不设冷却期。
• 告警说明：premain 启动注入是 JVM 认定的预期加载路径，不再产生动态挂载告警；仅注入失败回落动态挂载（attach）时，JDK 21+ 的应用控制台可能出现一条 agent 告警（JEP 451），属预期行为，仅告警不影响运行。
• 采集随监听启停：停止监听时同步停掉应用内采集——此前 agent 持续采集再被丢弃的白耗不再有，重新开启监听即恢复采集；应用启动挂载完成后也会按当前监听状态自动校正，监听关闭状态下启动项目不再白采集。

控制台捕获的日志格式与还原细节（何时看：你只用控制台通道，且日志形态特殊或捕获不全）

用增强捕获时本块与下面的「日志格式、耗时解析」描述都用不上，可以跳过。

• 识别格式：MyBatis Preparing: / Parameters:；Hibernate Hibernate: + binding parameter；JdbcTemplate（SQL 折成多行的语句跨行完整收集，字符串内的方括号不会误判截断；NamedParameterJdbcTemplate 的命名参数为集合值时按元素还原——IN (:p) 配 param=[a] 还原为 IN ('a')；并发多线程交错的日志按线程分桶还原，参数不再错挂丢失）
• 混合前缀：Preparing: SELECT ...（MyBatis 默认）、==> Preparing: SELECT ...（Spring Boot）、自定义前缀（设置页配置）
• 双路打印合并：同时开启 Hibernate show_sql 与 logger 时，同一条 SQL 自动合并为一个条目，参数归到一处，不再出现零参残留与「参数数量不匹配」误报
• 参数缺失提示：完全没有捕获到参数绑定日志时，面板提示未捕获到参数并引导开启 TRACE 级别（JdbcTemplate 语句会具体指到 org.springframework.jdbc.core）；只有参数确实不齐才提示数量不匹配
• 只打语句行的工程：语句后静默 1 秒即判定该条已完整并交出列表（如仅开 JdbcTemplate DEBUG、Tomcat 按请求新建线程），不再一直停在「已扫描 N 行 / 产出 0 条」

手动贴日志走面板的「日志 → SQL」页签——粘贴 MyBatis / Hibernate / JdbcTemplate 日志文本即还原为可执行 SQL，也可以直接从剪贴板一键读取：

功能特性

自动展开工具窗口

设置页「发现 SQL 时自动打开日志窗口」（默认开）生效时，捕获到第一条 SQL 会自动展开日志工具窗口——60 秒防抖、展开不抢编辑器焦点。

展开条件与恢复规则（何时看：窗口「关了又弹」或不再弹出时）

• 只随 SQL 捕获发生：开关开着但从未开始捕捉（「项目启动时自动开始监听」也关着）时不会弹；点「停止捕捉」后自动展开一并失效。
• 手动关掉窗口后，本次会话内不再自动展开；设置开关重新开启、重启 IDE，或（「项目启动时自动开始监听」开启时）再次运行项目后恢复。
• 升级前手动关过该开关的老用户保持关闭，不受默认值变化影响。

捕获诊断与状态

能力	说明
零产出诊断	捕捉中却一条都捕不到时，面板空态直接给出卡点——增强通道当前状态（未开启 / 等待应用进程 / 已挂载 / 心跳丢失已回落 / 已回落）、控制台已挂载数与已扫描行数，并按「等待项目运行 / 控制台暂无输出 / 有输出但没匹配到 SQL 日志」三档给出可执行的下一步
双通道状态栏	捕捉期间 SQL 日志页签底部常驻一行，如实显示控制台通道（已挂载 N 个、已扫描 N 行）与增强通道（未开启 / 等待挂载 / 已挂载 pid / 已回落；「暂停中」状态代码仍保留，但暂停按钮当前隐藏，正常使用看不到）以及已收事件数；非捕捉态整行隐藏
设置页状态行	设置页增强捕获状态行按五态如实显示（已挂载 / 连接中断已回落 / 心跳丢失已回落 / 连接已建立待首条心跳 / 已开启等待应用进程启动后挂载）；仅增强捕获关闭时显示空白

工具栏

SQL 日志页签的工具栏从左到右依次是：捕捉、管理屏蔽规则（眼睛加斜线）、清空、按耗时排序、按时间排序、SQL 类型过滤（漏斗）、跟随、去重、时间戳显示、交流群、帮助。所有图标都是插件自带的语义化 SVG（与其余三个页签同一套注册表），不依赖 IDE 主题的内置图标。

原先的「暂停捕获」入口已实装但当前隐藏，所以工具栏上看不到它。

SQL 高亮与耗时显示

• 列表中的 SQL 摘要按词法着色：关键字、表名、字符串、数字、注释分色显示，时间戳用灰色弱化，耗时按慢查询阈值着色
• 增强捕获条目的耗时是采集到的真实执行耗时（毫秒级精确）；控制台通道则从日志里解析，兼容 p6spy elapsed、MyBatis-Plus Time: 统计及自定义耗时前缀（设置页可配，默认 Time:）
• 以慢查询阈值 T（默认 1000ms，可配）为准：耗时 < T/2 为绿色，T/2 ≤ 耗时 < T 为橙色，≥ T 为红色，未知耗时为灰色；存在慢查询时显示慢查询计数
• 列表左侧图标组提供时间、耗时、行号排序，以及同结构聚类、按目标库分组；时间与耗时可切换升序 / 降序

下图展示日志列表的配色、长 SQL 省略，以及 5 条同结构 SQL 的聚类徽章。尾随暂停与恢复见下方「滚动到底部与尾部跟随」。

排序与增强通道细节（何时看：排序结果或耗时数据不符预期时）

• 左侧排序与分组图标悬停可查看说明；耗时与行号缺失的条目恒沉底（两个方向都不让空值顶到前面）；时间排序口径与列表时间列一致（选了「日志时间」源就按日志时间排，避免看到的时间与排序依据不一致）。
• 元信息行按固定顺序排列（来源在最后），来源显示完整文件名（带方括号与 .java 后缀，不剥不截），超宽时按顺序截断而不是丢片段；时间显示严格按设置的格式输出，不再因列宽偷偷剥掉日期。
• 带调用栈的条目，meta 行的栈摘要先取景到首个项目帧再按原契约截断——头部全是内部帧时不再显示一串框架类名。
• 增强捕获条目直接携带结构化耗时（毫秒级精确）、影响行数与执行报错信息，无需日志解析。

展示脱敏

截屏、录屏、贴日志给同事之前，参数里的密码和手机号不该跟着出去。设置页「SQL 日志」组里的**「展示与导出脱敏（敏感字面量打码）」（默认关闭）打开后，敏感值在展示层**打码为 ***：

覆盖范围是四条出去的路：

• SQL 日志列表的 SQL 摘要
• 单击预览浮层
• 历史 / 日志导出（CSV / TSV / TXT / SQL 四格式）
• MCP 的 sqlv_render_logs（这个另有独立开关「MCP 输出脱敏」，见 MCP 工具）

打码判据是双条件：列名提示命中（password / pwd / token / secret / idcard / mobile / phone 等中英文关键词）或值的形态命中（身份证、手机号）。规则与增强捕获侧的采集脱敏同源。

只动展示层：条目数据、参数预设与历史文件里的原值不受影响，关掉开关立刻恢复显示。所以它不是安全边界，只是「别把敏感值带进截图」的一道便利。

慢查询与性能建议

排查慢 SQL 分两步：先在列表里找出来，再到预览里看明白。

在列表里找（细节见上节）：耗时达到慢查询阈值（默认 1000ms，设置页可配）的条目，其耗时标红而非整行标红，并计入慢查询计数；在「全部」下拉中选择「只看慢查询」可筛出慢 SQL，在左侧图标组切到「耗时降序」可让最慢的几条排到最上面。反复出现的同一条语句还会被聚类——同结构条目达到 3 条时，元信息行出现「同结构 N 条」徽章，右键徽章可开一个只看该结构的聚焦页签；字面量不同也算同一结构（IN ('a') 与 IN ('b') 归一处），所以 N+1 式的循环调用一眼就能看出来。日志页与「SQL 历史」页共用这套标记。

在预览里看明白：打开任一预览（日志条目双击、或 Wrapper / XML / JPA 的 gutter 预览），面板元信息行后面会跟一段静态性能建议——每条以 ⚠（警告，红）或 ℹ（建议，蓝）开头、以 ； 分隔；一行放不下时截断加省略号，鼠标悬停看全文。规则盯的是常见的「索引用不上 / 全表扫 / 结果集过大」形态，例如：

• SELECT *（含 JOIN 时冗余字段传输更明显）
• 查询或写操作没有 WHERE 条件（全表扫 / 全表改风险）
• LIKE '%xxx' 前导通配符（B-Tree 索引无法利用）
• ORDER BY 没有 LIMIT、ORDER BY RAND()、ORDER BY 的列不在 SELECT 列表
• JOIN 缺少 ON 条件（笛卡尔积风险）
• 列被函数包裹、隐式类型转换（都会让索引失效）
• 子查询嵌套过深、关联子查询（每行外查询执行一次）
• IN 子句过长、深分页的大 OFFSET
• UNION 未用 UNION ALL、GROUP BY 没有聚合函数

静态建议只是「看着像有问题」；要确认真实代价，去预览面板点「执行计划」（英文界面 EXPLAIN）——静态规则与数据库返回的真实计划同屏对照，见 Wrapper → SQL 预览 · EXPLAIN 真实执行计划。接入了 MCP 的话，agent 也能用 sqlv_perf_advice 拿同一套建议（见 MCP Server 工具）。

执行报错同列展示

增强捕获条目自带执行报错（失败原因与报错全文随条目一起采集），执行失败一眼可见，无需任何解析。

用控制台捕获时，异常信息要从日志文本里认——控制台的 SQL 执行异常行（MyBatis ### 错误块、Spring DAO 异常、JDBC 异常家族、参数绑定报错）会被识别并反向绑定到时间窗内最近的对应条目。两种通道的展示一致：列表行直接显示错误片段，条目详情含报错全文（元信息红字标注、错误横幅与复制全文入口）。

条目序号

列表条目元信息行最前显示 #N 序号，表示本次会话内第 N 条捕获的 SQL，方便定位「第 N 条」：

• 每次以应用 / 测试等运行配置启动项目时从 1 重新计数（其他无关进程启动不会重置计数），手动清空列表同样归零
• 去重丢弃、暂停捕捉、关键字过滤命中的 SQL 不占号，列表不跳号
• 按耗时排序时序号保持可辨认，可看出原始捕获顺序；「SQL 历史」页二级列表也按文件内条目顺序显示 #N 行号，搜索过滤下行号稳定不变

时间戳与时间来源

每条条目可显示时间戳，时间取自设置页「SQL 日志」分组「时间来源」单选项：

时间来源	说明
日志时间（默认）	显示从日志行里解析出的原始时间，自动识别 Logback / Log4j2 / Spring Boot 默认、ISO 8601 等常见格式；该条日志行没带时间时回退为捕获时间（增强捕获条目没有日志行，直接用捕获时间）
捕获时间	显示插件捕获到这条日志的时刻

「时间戳显示」开关控制列表是否显示时间列；时间戳格式设置（默认 yyyy-MM-dd HH:mm:ss）对两种时间来源同样生效，右键复制的时间戳与历史页显示的时间均跟随这套配置。

CRUD 类型颜色标记

列表按语句类型给条目加颜色标记（SQL 日志列表与「SQL 历史」页二级列表生效）：SELECT 蓝、INSERT 绿、UPDATE 橙、DELETE 红（默认色，均可自定义），OTHER 类型不标记。

标记形态三选一，在设置页「SQL 日志」分组的「CRUD 颜色标记」配置，四色与形态可改、一键恢复默认：

• 左侧色条（默认）：条目左缘 3px 色条，选中态为平台高亮、色条保留
• 整行淡背景：底色与列表背景按主题混色，亮暗主题均自适应；选中态保留类型色调并带一圈描边，耗时快 / 慢着色不会被选中高亮抹掉
• 关闭：恢复无标记外观

日志页「类型过滤」弹窗的每个复选框旁带对应类型色块图例，颜色改动即时同步（标记关闭时不显示图例）。

DDL 语句同样纳入类型标记与筛选：CREATE / ALTER / RENAME 一档复用增色（绿），DROP / TRUNCATE 一档复用删色（红），两档在「类型过滤」弹窗里可分别勾选（此前 DDL 无类型，勾「只看插入」等筛选时表现含糊）；视觉上靠色条形态区分——DDL 画虚线、DML 实心，不新增设置项。

滚动到底部与尾部跟随

日志列表默认开启尾部跟随：新 SQL 到达时视图自动贴底，始终显示最新条目；使用滚轮、滚动条或键盘手动滚动即暂停跟随。手动滚回底部不会自动恢复，需点击工具栏「滚动到底部」才恢复跟随。

细节（何时看：列表不在底部、或想找这个动作时）

• 「滚动到底部」动作位于工具栏动作组中（其右侧还有按耗时/时间排序、交流群与帮助）：一键跳到列表底部并恢复跟随。
• 暂停由手动滚动触发，不按滚动方向自动恢复；新条目的程序性追加不会打断暂停后的阅读位置。
• 暂停跟随期间列表仍在收新 SQL：缓冲满载淘汰旧行时按被删行高补偿视口，正在看的内容不会被顶上去。

跳转到源码

右键日志条目 →「跳转到源码」。不同捕获通道的定位方式不同。

增强捕获条目：源码位置取自应用执行 SQL 时的真实调用栈，直达执行这条 SQL 的代码行。自研框架统一入口的调用自动沿调用栈上溯，跳过框架帧定位到你的业务代码。

框架帧过滤与业务帧登记（何时看：跳转落点总在框架代码或工具库里时）

框架帧的过滤按来源判定（开发态业务类来自目录、第三方依赖来自 JAR），不会被框架或数据层插件帧误导。框架帧的过滤与 JAR 态业务帧的归属都可在设置页登记：框架引擎链包名登记进「源码捕获帧过滤前缀」（一行一个），以依赖 JAR 运行的业务工具库包名登记进「JAR 业务帧包名前缀」——登记后跳转直接落进工具类内部的 SQL 行，不再上顶到上层调用方那一行；两栏随输入即时校验格式与跨栏冲突，可一键修复。实时列表与历史面板共用同一解析。

从调用栈跳转

增强捕获的条目不止一个「执行点」，还带着整条调用栈。预览这类条目时，面板元信息行的「调用栈:」处悬停片刻，弹出调试器 Frames 风格的弹层：

• 帧列表按调用顺序结构化展示——方法名 + 全限定类名 + :行号，类名超宽时中段省略、行号始终可见；栈顶帧默认选中，插件自身的采集帧整行淡灰降权
• 点击任意一帧即跳到该帧的源码行（全工程按类名解析，库类落到反编译视图，与调试器习惯一致）；解析不到时弹层保持不关，不制造「已跳转」的假象
• 列表尾部的基础设施帧（Tomcat / 线程池尾巴等）在解析时被跳过，弹层默认锚定最深的业务帧，一眼看到 Controller → Service 的调用路径；折叠名单覆盖 JDBC 驱动族与 MyBatis 内部包
• 定时任务等非 Web 线程产出的 SQL 同样能看到项目帧——@Scheduled 一类调度线程的栈底锚点会穿透 Spring scheduling 等框架前缀，业务帧不再被挤出帧数窗口；弹层标题带上线程名（scheduling-1、pool-2-thread-1），一眼分清 SQL 来自哪条线程
• 底部「复制调用栈全文」把原始快照整段复制走，便于贴进 issue 或对话

保留多少帧可在设置页调——「调用栈快照帧数」（默认 24，范围 12~64）：两端采样，栈顶保留 JDBC / 引擎侧帧，栈底固定保留 8 帧业务侧，中间以省略标记连接；改动保存后热下发生效，无需重启应用。

控制台通道的拦截器方案（何时看：你用的是控制台捕获，又需要精确落点）

用增强捕获不需要任何配置——它的源码位置来自真实调用栈。控制台日志本身不含调用位置，插件为此提供了一个可选的运行期拦截器：把插件自带的自包含示例 SqlSourceInterceptor（随插件仓库分发：docs/instrumentation/SqlSourceInterceptor.kt）复制到你的项目，注册为 MyBatis-Plus InnerInterceptor 即可。不想手工复制时，设置页「自动注入源码捕获拦截器」可以代劳——勾选后选择模块即自动生成拦截器并注册进 mybatis-config.xml：

@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    // 限定你自己的业务包，调用点定位更准
    interceptor.addInnerInterceptor(new SqlSourceInterceptor(Set.of("com.example.")));
    // 分页等其他拦截器按需追加
    return interceptor;
}

拦截器在 SQL 执行线程捕获真实调用点，向控制台打印一行 SQLVIS-SOURCE|相对路径|行号 标记（不影响 SQL 执行、无性能负担），插件解析后即可像 SQL 历史面板一样精确 file:line 跳转——直达触发这条 SQL 的 Service / Controller 行。

跳转到 Mapper XML：携带 mapper 语句信息的条目可右键「跳转到 Mapper XML」——statement id 拆出 namespace 与片段 id 后，在工程内索引定位 mapper XML，校验 namespace 匹配并落到语句节点起始行。

XML 不存在（注解 SQL、MP 内置语句）或定位失败时回退「跳转到 Java」，能力不劣化。日志页与「SQL 历史」页共用同一套入口。

跳转兜底行为（何时看：遇到「无法跳转」提示或想配置自动注入时）

• 跳转只认捕获到的真实位置，不做表名猜测回退——避免同名表把跳转指到无关文件。如 SELECT 1 这类语句本身无可跳转目标，提示无法跳转。
• 控制台通道条目没有携带位置（未配置拦截器，或使用的是旧版拦截器文件）时，会弹出引导对话框，可一键「打开设置」或「立即注入」补齐配置。
• 拦截器自动注入遇到无法识别的项目类型（非 Spring Boot + MyBatis-Plus 工程）时，弹窗改为引导一键开启增强捕获（增强通道不依赖项目类型），不再让用户自行翻手动配置示例（SqlSourceInterceptor 示例文件仍在插件仓库，手工配置路线保留）。
• 设置页「自动注入源码捕获拦截器」触发时，多模块项目会先弹窗勾选要注入的模块（默认全选）。

去重与过滤

功能	说明
去重窗口	相同 SQL 在窗口内重复不显示（默认 60000ms，可调；判重忽略首尾与连续空白差异，参数不同仍算不同语句）
即时去重	开启「SQL 去重」后，窗口内已有的重复条目立即裁剪，并显示 ⨉N 徽章标记丢弃数量
关键字过滤	移除包含指定关键字的日志行
列表搜索	搜索框支持 SQL 内容、源文件、#行号（输入 #5 或 5 精确匹配第 5 条）与时间文本（所见即所搜，按列表显示格式匹配）；日志页与历史页搜索框均可用
复制时间戳	选中条目（可多选）右键「复制时间戳」，逐行复制纯时间文本（不带显示用方括号，多选时菜单项带条数）；时间显示关闭时该菜单置灰

SQL 屏蔽

保活心跳类 SQL（如 SELECT 1）持续刷屏时，可将其屏蔽出列表：

• 右键条目「屏蔽此 SQL」一键屏蔽，支持多选（不同语句各成一条规则、已存在的自动跳过）；列表存量行立即消失、balloon 通知可直达管理对话框、管理对话框实时命中计数
• 工具栏「管理屏蔽规则」（眼睛加斜线图标；漏斗图标给的是 SQL 类型过滤）与右键「管理屏蔽规则…」打开同一管理对话框：规则列表（模式摘要 / 创建时间 / 已拦截 N 次计数）+ 右侧 SQL 语法高亮只读预览（带行号）；新增 / 删除 / 清空即时生效，对话框可拖拽缩放并记忆尺寸
• 规则应用级全局生效、独立存储（不进设置导入导出），上限 500 条；删除规则后仍在缓冲内的条目恢复显示（已入队丢弃的不可恢复）

匹配口径（何时看：规则加了却没命中时）

匹配口径＝还原 SQL 空白规范化后精确匹配（自动剥离尾部分号，规则粘贴态带 ; 也能命中），SELECT 1 与 select 1 命中同一条规则。可选结构匹配（默认关、按规则手动开启或一键全部开启）——开启后按语句形状匹配，参数值不同的同形状 SQL 一并屏蔽。

聚焦页签

日志条目右键菜单提供两种聚焦，以页签形式挂在面板顶部，可多开、可单独关闭，与类型过滤、搜索正确叠加。页签恒为单行不折行，开多了由平台自动压缩并用「显示全部页签」下拉收纳：

• 聚焦调用方方法：按源码位置的行号区间做静态近似过滤，列表只显示该方法区间内发出的 SQL
• 按请求聚焦：Web 请求内执行的 SQL 右键「按请求聚焦」，只看该请求发出的 SQL，呈现保持扁平时间序

聚焦边界（何时看：聚焦结果与预期不符时）

• 聚焦调用方方法：嵌套类、重载与 lambda 按最小包含方法界定范围，范围外条目隐藏并显示计数提示。已知边界：Kotlin 调用方首批暂不支持。
• 按请求聚焦：页签按请求去重且上限 8 个（超限挤掉最早的页签），长压测会话不会撑爆列表；无请求标签的条目（定时任务、启动期）在聚焦下隐藏并计数。

三种显示模式

设置页「SQL 日志」分组「列表显示」下拉控制条目中 SQL 的展示形态，切换即时生效：

• 单行：每条日志固定一行，长 SQL 截断显示
• 关键字换行（默认）：SQL 按关键字折行，行数随内容伸缩；折行取的是完整还原 SQL（超长按预算在空白边界截断），不再是摘要过短找不到换行点、只显示一行
• 格式化：完整格式化排版，长语句逐子句展开

SQL 日志页与「SQL 历史」页共享同一设置，重启 IDE 后保留；任意模式下选中条目 Ctrl+C 复制的都是纯 SQL，不是渲染文本。

条目选择、快速预览与双击弹窗

SQL 日志列表、历史 tab 二级列表、历史工具窗的条目操作一致：

• 单击条目：默认只选择，不弹出预览浮层；显式开启工具栏「快速预览」后，选中条目的 SQL 才显示在底部预览区
• 复制 SQL：选中条目后按 Ctrl+C 或右键「复制」获取完整 SQL，不受列表摘要截断影响
• 多选批量复制：Ctrl / Shift 多选后右键「复制」，一次复制全部选中 SQL（菜单项带条数如「复制选中 SQL（3 条）」，逐条分号收尾、换行拼接）
• 双击条目：打开完整预览弹窗（同 Wrapper 预览弹窗，支持参数回填和格式化），工具栏提供横排 / 竖向排列 / 关键字换行切换与「更多」菜单（导入参数、差异对比、分享等低频动作收纳其中）

预览行为细节（何时看：预览显示形态或弹窗行为不符预期时）

• 快速预览：工具栏开关控制底部 SQL 预览区，默认关闭；需要完整预览与参数回填时双击条目。完整预览的展示形态跟随设置页「预览时格式化还原 SQL」开关（默认开），关闭则保持原文；零占位符的字面量 SQL（值直接内联在 SQL 文本里）与 IN 列表同样会识别出可编辑参数行。
• 多选与右键：右键命中行已在多选集合内时保留多选，其余右键动作仍作用于被右键的行。
• 双击弹窗：竖排展示下 INSERT 每个值行尾带 -- 列名 配对标注（可在设置中关闭），IN 列表逐元素竖向排列——含逗号即 ≥2 元素一律 ( 自占一行逐元素展开，单元素形态（IN (1) / IN (?)）仍保持同行，子查询 IN 与 LIMIT 分页参数照旧不展开；切换后的显示形态在参数回填时保持，不会被重新渲染抹掉（点刷新复位）。弹窗为非模态，执行 SQL 时如数据源密码过期，IDEA 的密码输入框可正常置顶输入；未配置数据源时预览静默准备，不再拉起 Database 工具窗抢占侧边栏，仅显式执行时才引导配置。
• 自动折叠：设置页「字段较多时自动折叠」（默认关，阈值可配，默认 10）开启后，预览编辑器把 SELECT / INSERT 列清单、VALUES 组、UPDATE SET 等超长字段列表收起为「… N 列」占位符，点折叠标记即可还原——主预览弹窗、底部快速预览、历史预览、Log → SQL 结果区与原生 Database 控制台一并生效。
• Ctrl+C 复制语义处处一致：凡带 SQL 编辑器的界面（主预览面板、底部快速预览区、「最近执行记录」、屏蔽规则、回滚 SQL、SQL → Java 输入区、参数导入）Ctrl+C 都是同一套语义——编辑器内无选中复制整条 SQL、圈选后只复制片段（Ctrl+C 与 Ctrl+Insert 同义）；列表上的 Ctrl+C 复制的是纯 SQL 而不是渲染文本。

列表条目的展示形态跟随设置页「列表显示」（见上节）。

SQL 历史

「SQL 历史」标签页常驻面板——不必先开启自动保存就能看到入口（未开启且目录里没有历史文件时为空态），不像此前那样要满足条件才会挂出页签。

勾选「自动保存历史 SQL」（设置页，默认关）后，捕获到的条目全量落盘保存（不受列表最大条数限制）；保存目录内历史文件超过保留上限（默认 30 个，可配，0 = 全量保留）时自动清理最旧，防止磁盘无限增长。历史文件的读写走同一处目录解析：自定义「保存目录」后写入的文件同样能在历史页看到，改保存目录即触发重扫。

• 一级（默认视图）：文件列表，每行显示文件名、文件大小和 SQL 条数，搜索框按文件名过滤
• 二级（文件内容）：双击文件进入，逐条展示该文件的 SQL（同样带高亮、耗时、时间戳与源码位置，按文件内条目顺序显示 #N 行号）；大文件按滚动分批加载——首屏 30 条，滚动接近底部时续写；默认单击 SQL 只选择，显式开启工具栏「快速预览」后在底部显示 SQL，双击打开完整弹窗，右键可复制 SQL、复制时间戳或跳转到源码；搜索框支持按 SQL 内容 / 源文件 / #行号 / 时间文本过滤
• 返回：顶部「← 返回」回到文件列表；切换 tab 自动刷新，正在浏览的文件仍存在时不打断浏览
• 直达末条：二级列表工具栏的「↓≡」动作一次跳到当前过滤结果的最后一条——大文件（上千条）不用再滚到底。它会先把尚未加载的剩余条目一次补齐再定位，不是逐段滚
• 检索开关：搜索框右侧两枚开关与 IDE 原生查找同语义——.* 开正则匹配（等价于 regex: 前缀），Aa 开区分大小写（默认关＝忽略大小写）；一级的文件名检索同样跟随 Aa，正则不参与文件名过滤
• 参数识别与回填：历史条目与实时日志走同一识别通道，双击打开弹窗同样支持参数回填
• 导出与对比：二级列表右键「导出 SQL」（CSV/TSV/TXT/SQL 四格式，默认 SQL 带时间戳文件名）与「对比选中两条」（逐行差异；标题给出结构指纹结论——两条结构等价时标「结构等价，仅参数不同」，否则给差异行数）——

历史存储与版本兼容（何时看：自定义存储位置或新旧版本混用时）

• 历史文件默认保存在项目 .idea/sql-visualizer/sql-history/ 目录（v2026.9.2 起目录名由 mybatis-plus-sql-visualizer 改为 sql-visualizer，旧目录数据不再读取），保存目录与文件名模板均可在设置页自定义。
• 历史文件（v2 格式）随条目保存参数（以 -- pd: 注释行内嵌在语句旁）、原始时间与目标库信息——旧版插件会忽略新增字段照常打开，新版可正常读取全部旧文件。
• 二级列表的时间戳格式与来源跟随设置页当前配置。

加入交流群

工具栏中靠右的聊天气泡图标打开一个原生弹框（它右侧只剩帮助「?」），并排给出作者微信与交流群说明——遇到问题想直接问，不用去翻文档找联系方式。

二维码在弹框打开时异步从官网获取；加载失败时弹框给出「打开官网交流页」的兜底入口，不会留一块空白。

对日志功能有建议或遇到问题？直达需求反馈池