# 人大金仓语法检查idea插件

**Repository Path**: CodeLiQing/kingbase-plugin

## Basic Information

- **Project Name**: 人大金仓语法检查idea插件
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-29
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kingbase SQL Checker — 详细使用教程

> **插件名称**: Kingbase SQL Checker（人大金仓 SQL 语法检查插件）  
> **插件 ID**: `com.lq.kingbase`  
> **适用 IDE**: IntelliJ IDEA Ultimate 2025.1+  
> **核心功能**: MyBatis XML Mapper SQL 语法检查、数据库执行验证、多数据源管理、AI 智能修复、AI 性能优化  
> **AI 引擎**: 阿里云通义千问（DashScope Qwen）  
> **开源协议**: MIT

---

## 目录

1. [插件概述](#1-插件概述)
2. [安装与配置](#2-安装与配置)
3. [多数据源管理](#3-多数据源管理)
4. [单条 SQL 语法检查](#4-单条-sql-语法检查)
5. [批量 SQL 检查](#5-批量-sql-检查)
6. [SQL 编辑器与替换](#6-sql-编辑器与替换)
7. [AI 自动修复](#7-ai-自动修复)
8. [AI 性能优化](#8-ai-性能优化)
9. [列类型感知值填充](#9-列类型感知值填充)
10. [动态标签智能合并](#10-动态标签智能合并)
11. [技术架构](#11-技术架构)
12. [常见问题](#12-常见问题)
13. [优缺点分析](#13-优缺点分析)
14. [性能参考](#14-性能参考)
15. [版本历史与贡献](#15-版本历史与贡献)

---

## 1. 插件概述

### 1.1 插件介绍

**Kingbase SQL Checker** 是一款专为 IntelliJ IDEA 打造的 SQL 检查与优化插件，主要面向使用 **MyBatis** 框架的 Java 开发团队。插件深度集成于 IDEA 编辑器中，能够自动识别 XML Mapper 文件中的 SQL 标签，对标签内的 SQL 语句进行语法校验、数据库执行验证、AI 智能修复与性能优化，并提供可视化的结果面板与 SQL 编辑能力。

### 1.2 核心能力

| 能力 | 说明 |
|------|------|
| 语法检查 | 检测 SELECT/FROM、UPDATE/SET、INSERT/VALUES 等基本语法 |
| 动态标签解析 | 展开 `<if>`、`<foreach>`、`<where>`、`<set>` 等 MyBatis 标签 |
| 数据库执行 | 连接真实数据库执行 SQL，返回列名、行数据、耗时 |
| 多数据源 | 配置多个数据库连接，自由切换活跃数据源 |
| 批量扫描 | 递归扫描项目/目录/文件中的所有 XML Mapper |
| 结果筛选 | 按成功/失败状态过滤 SQL 列表 |
| 双栏编辑器 | 左栏原始模板（只读）、右栏解析可执行 SQL（可编辑） |
| 智能替换 | 编辑后合并回原始模板，完整保留动态标签 |
| AI 修复 | 自动修复 SQL 语法错误并验证执行结果 |
| AI 优化 | 性能优化建议，自动执行前后对比验证 |
| 列类型感知 | 查询数据库列类型，用类型匹配的值替换占位符 |
| 源码定位 | 点击列表项跳转到 XML 文件对应位置 |

### 1.3 适用场景

- **MyBatis XML Mapper 开发团队**：大量 SQL 写在 XML 文件中，需要快速验证正确性。
- **多数据库环境**：同时使用 Kingbase、PostgreSQL、MySQL，需要频繁切换数据源。
- **SQL 质量保障**：要求所有 SQL 提交前通过语法检查和执行验证。
- **老旧 SQL 优化**：借助 AI 优化性能并进行结果对比验证。
- **代码审查**：辅助审查过程中的 SQL 质量把控。

---

## 2. 安装与配置

### 2.1 环境要求

| 项目 | 要求 |
|------|------|
| IDE | IntelliJ IDEA Ultimate 2025.1+（Community 版不支持） |
| JDK | 21+ |
| Gradle | 8.13+（可使用 Wrapper） |
| 操作系统 | Windows / macOS / Linux |
| 数据库 | Kingbase 8 / PostgreSQL / MySQL |

### 2.2 安装方式

#### 方式一：本地构建安装

```bash
git clone <repository-url>
cd kingbase-plugin
./gradlew buildPlugin
# 产物在 build/distributions/Kingbase SQL Checker-1.1-SNAPSHOT.zip
```

然后打开 IntelliJ IDEA → Settings → Plugins → Install Plugin from Disk → 选择生成的 zip 文件。

#### 方式二：从下载链接安装

从 https://gitee.com/CodeLiQing/kingbase-plugin/releases 下载最新版本，然后从磁盘安装。

### 2.3 编译注意事项

由于插件包含中文注释和字符串，编译时需指定 UTF-8 编码：

```kotlin
// build.gradle.kts
tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
}
tasks.withType<ProcessResources> {
    filteringCharset = "UTF-8"
}
```

gradle.properties 中也要设置：

```properties
org.gradle.jvmargs=-Dfile.encoding=UTF-8
```

### 2.4 验证安装

安装后重启 IDE，检查以下位置是否出现插件功能：

1. **Tools 菜单**：应该出现"配置数据库连接"菜单项。
2. **编辑器右键菜单**：在 XML 文件中右键，应该出现"检查当前 SQL 语法（人大金仓）"。
3. **项目视图右键菜单**：在项目或目录上右键，应该出现"批量检查项目中所有 XML 的 SQL"。

---

## 3. 多数据源管理

### 3.1 功能说明

插件支持配置多个数据库连接，并在不同数据源之间自由切换。所有 SQL 执行操作均使用当前激活的数据源。数据源配置持久化存储（`kingbaseDataSource.xml`），重启 IDE 不丢失。

### 3.2 打开配置

点击菜单栏 **Tools → 配置数据库连接**，打开数据源配置对话框。

### 3.3 界面布局

对话框分为三个区域：

- **左侧（数据源列表）**：以列表形式展示所有已配置的数据源，活跃数据源显示 ✓ 图标和蓝色高亮。底部有四个按钮：添加、保存、删除、激活。
- **右侧（数据源详情）**：当前选中数据源的连接参数表单：名称、数据库类型、主机地址、端口、数据库名、用户名、密码。底部有"测试连接"按钮。
- **底部（AI 配置）**：AI 私钥 Key 输入框（所有数据源共享）。

### 3.4 添加数据源

1. 点击 **添加** 按钮。
2. 在右侧表单中填写：
   - **名称**（必填）：如"开发环境-Kingbase"、"测试-MySQL"，名称不能重复。
   - **数据库类型**：Kingbase / PostgreSQL / MySQL。
   - **主机地址**：数据库服务器 IP 或域名。
   - **端口**：Kingbase 默认 54321，PostgreSQL 默认 5432，MySQL 默认 3306。
   - **数据库名**：连接的数据库名称。
   - **用户名**：数据库用户。
   - **密码**：数据库密码。
3. 点击 **测试连接** 验证配置。
4. 点击 **保存** 将数据源添加到列表。

### 3.5 编辑数据源

1. 在左侧列表中选择要编辑的数据源。
2. 右侧表单自动加载该数据源的配置。
3. 修改需要变更的字段。
4. 点击 **保存** 更新配置。

### 3.6 删除数据源

1. 选择要删除的数据源。
2. 点击 **删除**。
3. 确认删除对话框。
4. **注意**：至少保留一个数据源，不能删除最后一个数据源。

### 3.7 激活数据源

1. 选择要激活的数据源。
2. 点击 **激活**。
3. 该数据源左侧出现 ✓ 图标，名称后显示"(活跃)"，蓝色高亮背景。

激活后，所有 SQL 执行操作（语法检查、批量扫描、AI 修复验证、AI 优化对比）都会自动使用该数据源。

### 3.8 AI Key 配置

在对话框底部的"AI 私钥 Key"输入框中填写阿里云通义千问 API Key。所有数据源共享同一个 AI Key。可在 https://dashscope.aliyun.com/ 申请。

### 3.9 底层实现

数据源配置通过 IntelliJ 的 `PersistentStateComponent` 机制持久化：

```java
@State(name = "KingbaseDataSourceConfig", storages = @Storage("kingbaseDataSource.xml"))
public class DataSourceConfig implements PersistentStateComponent<DataSourceConfig> {
    public List<DataSourceEntry> dataSources = new ArrayList<>();
    public String activeDataSourceName = "";
    public String aiKey = "";
}
```

`DataSourceEntry` 是单个数据源的 POJO：

```java
public class DataSourceEntry {
    public String name;
    public String dbType;
    public String host;
    public int port;
    public String database;
    public String username;
    public String password;
}
```

---

## 4. 单条 SQL 语法检查

### 4.1 功能说明

在 XML Mapper 文件编辑器中，通过右键菜单快速检查光标所在 SQL 标签的语法正确性，并可选择在数据库上实际执行。

### 4.2 操作步骤

1. 打开 MyBatis XML Mapper 文件（如 `UserMapper.xml`）。
2. 将光标放置在 `<select>`、`<update>`、`<insert>` 或 `<delete>` 标签内的 SQL 文本任意位置。
3. 右键菜单选择 **检查当前 SQL 语法（人大金仓）**。
4. 插件执行内部流程：
   - 通过 PSI 树找到光标所处的 XML 标签
   - 提取标签内的 SQL 文本
   - 验证基本语法（禁止 DROP/TRUNCATE、检查 SELECT 有 FROM、UPDATE 有 SET、INSERT 有 VALUES）
   - 展开 MyBatis 动态标签并填充占位符
   - 弹窗询问是否要使用当前活跃数据源执行 SQL

### 4.3 语法验证规则

| 检查项 | 规则 |
|--------|------|
| DROP/TRUNCATE | 禁止使用，返回"禁止使用 DROP 或 TRUNCATE 语句" |
| SELECT | 必须包含 FROM 子句 |
| UPDATE | 必须包含 SET 子句 |
| INSERT | 必须包含 VALUES 子句 |
| 空内容 | 返回"SQL 内容为空" |

### 4.4 执行结果展示

如果用户选择"是"执行 SQL，结果弹窗包含：

- **执行成功**（绿色图标）：
  - 耗时（毫秒）
  - **查询类 SQL**：返回行数 + 结果表格（列名 + 每行数据）
  - **更新类 SQL**：影响行数
- **执行失败**（红色图标）：
  - SQL 内容
  - 数据库返回的错误信息

### 4.5 适用标签

支持以下 MyBatis Mapper 标签：

- `<select>`
- `<update>`
- `<insert>`
- `<delete>`

不支持的标签：

- `<sql>`（可复用 SQL 片段）
- `<resultMap>`
- `<include>`
- 其他非 SQL 标签

---

## 5. 批量 SQL 检查

### 5.1 功能说明

一次性扫描项目（或指定目录/文件）中的所有 XML Mapper 文件，提取所有 SQL 标签，逐一解析和数据库执行，汇总结果展示在增强结果面板中。

### 5.2 扫描范围

| 触发方式 | 扫描范围 | 操作方法 |
|---------|---------|---------|
| 右键点击 XML 文件 | 仅扫描该文件 | 项目视图 → 右键 XML 文件 → 批量检查... |
| 右键点击目录 | 递归扫描该目录及所有子目录下的 XML | 项目视图 → 右键目录 → 批量检查... |
| 主菜单触发 | 扫描整个项目 | 主菜单 → 批量检查项目中所有 XML 的 SQL |

### 5.3 后台扫描流程

```
扫描开始
  ↓
遍历 XML 文件（带进度指示）
  ↓
解析每个 XML 的 PSI 树
  ↓
递归遍历所有子标签
  ↓
找到 select/update/insert/delete → 提取完整内容（含子标签）
  ↓
formatSQL 展开动态标签
  ↓
SqlValueResolver 替换占位符为类型对应值
  ↓
SqlExecutor.execute() 在活跃数据源上执行
  ↓
收集 SqlCheckResult（类型 + 原始 SQL + 执行结果 + PSI 指针）
  ↓
扫描完成 → 打开增强结果面板
```

### 5.4 增强结果面板

#### 顶部统计区

```
扫描统计 | 共 N 条 SQL | ✓ 成功 N | ✗ 失败 N

筛选: [全部 (N)] [成功 (N)] [失败 (N)] ✓(默认)
```

三个筛选按钮默认选中"仅失败"，开发者可以第一时间看到所有执行失败的 SQL。

#### 左侧 SQL 列表

每条 SQL 显示：

```
[状态图标] [标签类型] SQL 摘要
文件名 · 耗时
```

- **状态图标**：✓（成功，绿色背景）/ ✗（失败，红色背景）
- **标签类型**：SELECT / UPDATE / INSERT / DELETE
- **SQL 摘要**：SQL 文本的第一行（截断到 55 字符）
- **文件名**：对应的 XML 文件路径（缩短显示）
- **耗时**：执行耗时（毫秒）或"失败"

列表项的自定义渲染器（`ResultCellRenderer`）使用 GridLayout 双行布局，第一行粗体显示类型和摘要，第二行小号灰色显示文件名和耗时。

#### 右侧 SQL 详情

双栏设计：

| 区域 | 内容 | 可编辑 | 背景色 |
|------|------|--------|--------|
| 左栏 | 原始 MyBatis SQL（含 `<if>`、`<foreach>` 等动态标签） | 否（只读） | 浅钢蓝 `#E9EFF8` |
| 右栏 | 解析后可执行 SQL（标签已展开，占位符已替换为类型实际值） | 是 | 白色 |

两个区域上方显示当前选中 SQL 的标签类型和文件路径。

#### 底部状态栏

显示当前选中 SQL 的执行状态：

- **成功**：✓ 执行成功 | 耗时 Nms | 返回 N 行 / 影响 N 行
- **失败**：✗ 执行失败 | 数据库错误信息

### 5.5 动态标签提示

当 SQL 包含动态标签时，编辑器上方自动显示琥珀色提示条：

> 检测到动态标签（`<if>`、`<foreach>` 等）。左侧为原始模板，右侧为自动填充后的可执行 SQL。替换到 XML 时将保留动态标签结构。

提示条背景色为 `#FFF8E1`（淡琥珀色），边框 `#FFCA28`（琥珀色），文字 `#E65100`（深橙）。

### 5.6 筛选功能

三个筛选按钮互斥（ButtonGroup）：

| 筛选模式 | 显示内容 | 默认 |
|---------|---------|------|
| 全部 | 所有 SQL（成功 + 失败） | |
| 仅成功 | 只显示执行成功的 SQL | |
| 仅失败 | 只显示执行失败的 SQL | ✓ 默认 |

切换筛选时，列表模型重建，筛选索引重新计算，右侧编辑器内容清空。

### 5.7 右键菜单

| 菜单项 | 图标 | 功能 |
|--------|------|------|
| 查看执行详情 | Preview | 弹窗显示 SQL 执行详细结果（表格、行数、耗时） |
| 定位 SQL 源码 | EditSource | 跳转到 XML 文件中对应的 SQL 标签位置 |
| AI 自动修复 | IntentionBulb | 对失败的 SQL 进行 AI 修复 |
| AI 性能优化 | Lightning | 对 SQL 进行性能优化建议 |

### 5.8 执行结果详情弹窗

- **成功**（JPanel + JTable）：
  - 上方显示执行的 SQL 文本（只读，格式化后）
  - 中间 JTable 展示查询结果（列名表头 + 数据行）
  - 底部显示统计信息：返回 N 行 · 耗时 Nms
- **失败**（JTextArea + 红色前景）：
  - 显示 SQL 文本和数据库返回的错误信息

---

## 6. SQL 编辑器与替换

### 6.1 双栏编辑器

增强结果面板右侧提供双栏 SQL 编辑器，这是插件最核心的交互界面。

**左栏（原始 SQL）**：
- 显示 XML 文件中的原始 MyBatis SQL。
- 完整保留所有动态标签（`<if>`、`<foreach>`、`<where>`、`<set>`、`<choose>`、`<trim>` 等）。
- 为只读模式，作为参考基准不可修改。
- 背景色为 `#E9EFF8`（浅钢蓝），与右栏清晰区分。

**右栏（可执行 SQL）**：
- 显示经过解析和值填充后的可执行 SQL。
- 动态标签已展开（所有条件视为 true）。
- `#{xxx}` 已根据数据库列类型替换为实际值：
  - INT 类型 → `1`
  - VARCHAR 类型 → `'test'`
  - DATE 类型 → `'2024-01-01'`
  - 详见第 9 章节。
- 可编辑，支持修改 SQL 文本、添加/删除字段、修改条件等。
- 等宽字体（Consolas 13px），方便 SQL 编辑。

### 6.2 按钮栏

右侧编辑器底部有五个操作按钮：

| 按钮 | 图标 | 功能 |
|------|------|------|
| 执行 SQL | Execute（蓝底白字） | 解析并执行当前右栏 SQL |
| 格式化 | PrettyPrint | 格式化右栏 SQL（关键词大写、子句换行、缩进） |
| 替换到 XML | MenuSaveall | 将右栏内容写回 XML 文件 |
| AI 修复 | IntentionBulb | 对失败的 SQL 进行 AI 修复 |
| AI 优化 | Lightning | 对 SQL 进行性能优化 |

### 6.3 格式化功能

点击"格式化"按钮，自动执行以下处理：

1. **关键词大写**：SELECT、FROM、WHERE、AND、OR、JOIN、ON、INSERT、UPDATE、SET、DELETE 等 33 个 SQL 关键词转换为大写。
2. **主子句换行**：
   - SELECT、FROM、WHERE、ORDER BY、GROUP BY、HAVING、UNION、LIMIT、OFFSET → 前加换行
   - AND、OR、ON、JOIN、LEFT JOIN、RIGHT JOIN 等 → 前加换行 + 4 空格缩进
3. **空白压缩**：多余空格和空行合并为单个空格。
4. **统一大小写**：列名、表名、函数名保持原样（不强制转换大小写）。

### 6.4 执行 SQL 按钮

1. 读取右栏编辑器的 SQL 文本。
2. 通过 `SqlValueResolver.resolve()` 查询列类型，替换 `#{xxx}` 为类型对应值。
3. 通过 `formatSQL()` 展开所有动态标签。
4. 使用当前活跃数据源执行。
5. 弹窗展示执行结果（同 5.8 章节）。

### 6.5 替换到 XML 按钮

根据 SQL 是否包含动态标签，采用不同的替换策略：

#### 无动态标签

1. 通过 `SqlFormatter.wrapForXml()` 格式化右栏 SQL。
2. `wrapForXml` 内部流程：
   - `SqlFormatter.format()` 关键词大写、子句换行
   - 每行前加 8 空格缩进
   - 整体前后加换行
3. 通过 `replaceTagContentSafely()` 写入 XML 文件。

#### 有动态标签且用户未修改右栏

1. 将 `autoResolve`（SqlValueResolver + formatSQL + SqlFormatter 流程自动生成的版本）与当前编辑器内容进行空白归一化比较。
2. 如果一致 → 保留原始动态标签结构：
   - `originalSql.trim()` 去除首尾空白
   - `replace("\n", "\n        ")` 每行前加 8 空格缩进
   - 前后加换行
3. 通过 `replaceTagContentSafely()` 写入 XML 文件。

#### 有动态标签且用户修改了右栏

1. 比较发现编辑器内容与自动生成版本不一致。
2. 调用 `TemplateMerger.merge(originalSql, editedParsedSql, currentSubstitutionMap)` 进行智能合并。
3. 合并流程详见第 10 章节。
4. 通过 `replaceTagContentSafely()` 写入 XML 文件。

### 6.6 底层替换机制

`replaceTagContentSafely(XmlTag tag, String newInnerContent)` 方法使用 Document 级别替换而非 `XmlTagValue.setText()`：

```java
Document doc = PsiDocumentManager.getInstance(project).getDocument(tag.getContainingFile());
String text = tag.getText();
String name = tag.getName();
int openEnd = text.indexOf('>');          // 找到 <select ...> 的 >
int closeStart = text.lastIndexOf("</" + name); // 找到 </select 的位置
TextRange tagRange = tag.getTextRange();
int startOffset = tagRange.getStartOffset() + openEnd + 1;  // > 之后
int endOffset = tagRange.getStartOffset() + closeStart;     // </ 之前
doc.replaceString(startOffset, endOffset, newInnerContent);
PsiDocumentManager.getInstance(project).commitDocument(doc);
```

这样做的原因：
- `setText()` 将 `<if>` 等标签作为纯文本存储，不会解析为 XML 子标签。
- Document 替换后通过 `commitDocument()` 触发 IntelliJ 的 PSI 重新解析，将 `<if>` 正确识别为子标签。

---

## 7. AI 自动修复

### 7.1 功能说明

利用阿里云通义千问大语言模型自动修复 SQL 语法错误。修复后自动执行验证确保正确性。

### 7.2 前置条件

- AI 私钥 Key 已配置（数据源配置对话框底部）。
- 当前活跃数据源连接正常。
- 有网络连接（可访问 dashscope.aliyuncs.com）。

### 7.3 操作入口

- 增强结果面板 → 右键菜单 → **AI 自动修复**
- 增强结果面板 → 按钮栏 → **AI 修复**

### 7.4 触发条件

AI 修复只对**执行失败的 SQL** 可用。如果选中执行成功的 SQL，插件会提示"语法正确，无需修复"。

### 7.5 后台执行流程

```
用户点击 AI 修复
  ↓
检查 AI Key 是否配置
  ↓
Task.Backgroundable 后台线程
  ↓
调用 AiService.fixSql(sqlSnippet, errorMessage, config)
  ↓
构造 Prompt → 通义千问 API → 返回修复后 SQL
  ↓
SqlValueResolver.resolve(fixedSql, project) 查询列类型替换占位符
  ↓
formatSQL() 展开动态标签
  ↓
SqlExecutor.execute() 执行验证
  ↓
回到 EDT 线程 → 显示修复结果弹窗
  ↓
用户确认 → replaceTagContentSafely 写入 XML
```

### 7.6 Prompt 构造

AI 修复使用 `AiService.FIX_SYSTEM_PROMPT_TEMPLATE`：

```
你是一个 {dbType} SQL 语法专家，请只返回修复后的 SQL 语句，
不要任何解释、不要 markdown、不要引号，直接输出可执行的 SQL
```

拼接用户 Prompt：

```
以下 SQL 语句存在错误：

{sqlSnippet}

错误信息：{errorMessage}

请给出修复后的正确 SQL 语句，不要解释。
```

参数设置：
- model: `qwen-max`
- temperature: 0.1（低温度确保确定性输出）
- top_p: 0.8
- max_tokens: 1024

### 7.7 AI 修复结果弹窗

**验证结果横幅**：

| 修复状态 | 背景色 | 文字 |
|---------|--------|------|
| 修复成功 | `#E8F5E9` 浅绿 | ✓ 修复成功<br>原始 SQL 语法错误已修复，执行通过。返回 N 行，耗时 Nms |
| 修复失败 | `#FFEBEE` 浅红 | ✗ 修复可能仍有问题<br>{错误信息} |

**SQL 对比区域**（JSplitPane 水平分栏）：

| 区域 | 标题 | 背景色 | 可编辑 |
|------|------|--------|--------|
| 左栏 | 原始 SQL（含错误） | `#FFEBEE` 浅红 | 否 |
| 右栏 | AI 修复后（可编辑） | 白色 | 是 |

左栏底部显示原始错误信息。右栏底部显示执行结果摘要。

**底部对比卡片**（GridLayout 1×2）：

| 卡片 | 内容 |
|------|------|
| 原始 | ✗ 原始: 语法错误 |
| 修复后 | ✓ 修复后: 成功 · N 行 · Nms（或 ✗ 失败 · {错误信息}） |

**按钮选择**：
- 是 → 通过 `replaceTagContentSafely()` 将修复后 SQL 写入 XML，更新右栏编辑器内容
- 否 → 放弃修复

### 7.8 对比验证逻辑

AI 修复的对比验证与 AI 优化不同：

- 原始 SQL 有语法错误，执行必然失败。
- 不执行结果列/行对比（因为原始无有效结果）。
- 只验证修复后 SQL 是否能正确执行。
- 修复后 SQL 成功执行即视为修复有效。

---

## 8. AI 性能优化

### 8.1 功能说明

利用通义千问大模型对 SQL 进行性能优化，优化后自动执行原始 SQL 和优化后 SQL 进行结果对比，确保优化不改变查询语义。

### 8.2 前置条件

同 AI 修复（AI Key + 活跃数据源 + 网络连接）。

### 8.3 操作入口

- 增强结果面板 → 右键菜单 → **AI 优化（性能对比）**
- 增强结果面板 → 按钮栏 → **AI 优化**

### 8.4 后台执行流程

```
用户点击 AI 优化
  ↓
Task.Backgroundable 后台线程（+ 进度指示）
  ↓
[10%] 调用 AI 优化 SQL → 通义千万 → 返回优化后 SQL
  ↓
[30%] formatSQL + SqlValueResolver → 执行原始 SQL → originalResult
  ↓
[60%] formatSQL + SqlValueResolver → 执行优化后 SQL → optimizedResult
  ↓
[90%] SqlResultComparator.compare(originalResult, optimizedResult) → comparison
  ↓
EDT → AiOptimizationDialog 对比弹窗
  ↓
用户确认 → replaceTagContentSafely 写入 XML
```

### 8.5 Prompt 构造

AI 优化使用 `AiService.OPTIMIZE_SYSTEM_PROMPT_TEMPLATE`：

```
你是一个 {dbType} SQL 性能优化专家。请对以下 SQL 进行性能优化
（如：使用索引提示、优化 JOIN 顺序、避免全表扫描、子查询转 JOIN 等）。
要求：优化后的 SQL 必须返回与原 SQL 完全相同的结果
（相同的列、相同的行、相同的值）。
请只返回优化后的 SQL 语句，不要任何解释、不要 markdown、
不要引号，直接输出可执行的 SQL
```

### 8.6 优化对比弹窗（AiOptimizationDialog）

**状态横幅**：

| 匹配状态 | 背景色 | 文字颜色 | 文字 |
|---------|--------|---------|------|
| 匹配 | `#E8F5E9` | `#2E7D32` 深绿 | 结果完全匹配 — 可以安全替换 |
| 不匹配 | `#FFEBEE` | `#C62828` 深红 | 结果不匹配 — 请谨慎操作 |

**SQL 对比**（JSplitPane 水平分栏，dividerSize=4）：

| 区域 | 背景色 | 底部摘要 |
|------|--------|---------|
| 左栏：原始 SQL | `#F8F9FA` 浅灰蓝 | ✓ 执行成功 · 返回 N 行 · Nms |
| 右栏：优化后 SQL | `#F0F7FF` 淡蓝灰 | ✓ 执行成功 · 返回 N 行 · Nms |

**底部差异详情**：

| 结果 | 显示 |
|------|------|
| 匹配 | 对比结果：列名匹配 ✓ · 行数匹配 ✓ · 数据值匹配 ✓ |
| 不匹配 | 差异详情：{列不匹配/行数不匹配/值不匹配的具体描述} |

**按钮**：
- 结果匹配：**应用优化**（可用）+ **取消**（可用）
- 结果不匹配：**应用优化**（不可用，灰色）+ **取消**（可用）

### 8.7 结果对比引擎（SqlResultComparator）

对比算法：

```java
SqlComparisonResult compare(Result original, Result optimized)
```

**SELECT 查询对比**：

1. **列名对比**：逐一对比 `original.columns` 和 `optimized.columns`（大小写不敏感），必须完全一致。
2. **行数对比**：`original.rows.size() == optimized.rows.size()`。
3. **数据值对比**：前 100 行，逐列逐行对比：`Objects.equals(val1.toString(), val2.toString())`（字符串化后对比，保证跨数据库兼容性）。

**非 SELECT 对比**：
1. 对比 `original.affectedRows == optimized.affectedRows`。

**整体判定**：
- 列匹配 AND 行匹配 AND 值匹配 → `resultsMatch = true`
- 任一不匹配 → `resultsMatch = false` + `diffDescription` 包含具体差异描述

---

## 9. 列类型感知值填充

### 9.1 功能说明

在解析 MyBatis SQL 时，智能识别 `#{xxx}` 占位符对应的数据库列类型，使用类型匹配的实际值进行替换，而不是统一使用 `'-1'`。

### 9.2 核心组件

**SqlValueResolver**（`demo/SqlValueResolver.java`）：

```java
public static ResolveResult resolve(String sql, Project project)
```

返回 `ResolveResult`：
- `resolvedSql`：替换占位符后的 SQL 字符串
- `substitutionMap`：替换映射 `{ "id" → "1", "name" → "'test'" }`

### 9.3 工作流程

```
SqlValueResolver.resolve(sql, project)
  ↓
extractTableNames(sql)
  ↓
正则匹配 FROM/JOIN → 提取表名（如 t_user、t_role）
  ↓
queryColumnTypesCached(tableName, project)
  ↓
缓存命中 → 直接返回
  ↓
缓存未命中 → doQueryColumnTypes(tableName, project)
  ↓
打开 JDBC 连接 → DatabaseMetaData.getColumns()
  ↓
查询结果缓存到 schemaCache（concurrent）
  ↓
Pattern: #{([^}]+)} 扫描所有占位符
  ↓
extractColumnName(expr) 提取列名
  ↓
在 columnTypes 中查找 → getTypedValue(columnName, type)
  ↓
m.appendReplacement(sb, value)
  ↓
返回 ResolveResult
```

### 9.4 表名提取

`extractTableNames(String sql)` 使用两个正则：

**FROM 子句**：
```java
Pattern FROM_PATTERN = Pattern.compile(
    "\\bFROM\\s+([a-zA-Z_]\\w*(?:\\s+[a-zA-Z_]\\w*)?)", CASE_INSENSITIVE);
```
匹配 `FROM t_user`、`FROM t_user u`（取第一部分 `t_user`）。

**JOIN 子句**：
```java
Pattern JOIN_PATTERN = Pattern.compile(
    "\\bJOIN\\s+([a-zA-Z_]\\w*)", CASE_INSENSITIVE);
```
匹配 `JOIN t_role`，提取 `t_role`。

### 9.5 列名提取

`extractColumnName(String expr)` 处理三种情况：

| #{expr} 格式 | 提取列名 | 示例 |
|-------------|---------|------|
| `#{id}` | `id` | 简单列名 |
| `#{item.id}` | `id` | 点号后部分 |
| `#{entity.name}` | `name` | 点号后部分 |
| 复杂表达式 | null | 返回 null，使用默认 `'-1'` |

### 9.6 类型查询

`doQueryColumnTypes(String tableName, Project project)`：

```java
DatabaseMetaData meta = conn.getMetaData();
ResultSet rs = meta.getColumns(null, null, tableName, null);
while (rs.next()) {
    String colName = rs.getString("COLUMN_NAME");
    int dataType = rs.getInt("DATA_TYPE");
    String typeName = rs.getString("TYPE_NAME");
    result.put(colName.toLowerCase(), typeName != null ? typeName.toUpperCase() : getTypeCategory(dataType));
}
```

`getTypeCategory(int sqlType)` 映射 JDBC 类型到通用类型：

```java
switch (sqlType) {
    case Types.INTEGER, BIGINT, SMALLINT, TINYINT, NUMERIC, DECIMAL → "INTEGER"
    case Types.FLOAT, DOUBLE, REAL → "FLOAT"
    case Types.DATE, TIMESTAMP, TIME → "DATE"
    case Types.BOOLEAN, BIT → "BOOLEAN"
    default → "VARCHAR"
}
```

### 9.7 类型映射规则

| 数据库类型 | 替换值 | SQL 示例 |
|-----------|--------|---------|
| INTEGER / BIGINT / SMALLINT / TINYINT | `1` | `id=1` |
| NUMERIC / DECIMAL | `1` | `amount=1` |
| FLOAT / DOUBLE / REAL | `1.0` | `rate=1.0` |
| VARCHAR / CHAR / TEXT | `'test'` | `name='test'` |
| DATE / TIMESTAMP / TIME | `'2024-01-01'` | `create_time='2024-01-01'` |
| BOOLEAN / BIT | `true` | `active=true` |
| 未知类型（按列名启发式） | 含 id/_id/count/num → `1` | `status=1` |
| 未知类型（其他列名） | `'test'` | `remark='test'` |

### 9.8 缓存机制

```java
private static final Map<String, Map<String, String>> schemaCache = new HashMap<>();
```

- 缓存 key：`project.getBasePath() + "::" + tableName`
- 首次查询后缓存，后续直接返回
- 生命周期：IDE 会话期间（通过 `clearCache()` 手动清空）
- 使用 HashMap 而非 ConcurrentHashMap（同步由调用方保证）

### 9.9 触发时机

| 场景 | 触发方式 |
|------|---------|
| 批量扫描 | `BatchCheckAllXmlFilesAction.checkTagRecursive()` 间接通过 formatSQL |
| 选中 SQL（右栏填充） | `BatchCheckResultDialog.onItemSelected()` |
| 手动执行 SQL | `BatchCheckResultDialog.onExecute()` |
| AI 修复验证 | `BatchCheckResultDialog.onAiFix()` 后台线程 |
| AI 优化对比 | `BatchCheckResultDialog.onAiOptimize()` 后台线程 |

### 9.10 与 formatSQL 的协作顺序

```
SqlValueResolver.resolve(rawSql)  →  替换 #{xxx} 为类型值
       ↓
formatSQL(resolvedSql)            →  展开动态标签、移除 XML 标记
       ↓
SqlFormatter.format(parsed)       →  关键词大写、子句换行、缩进格式化
```

不能调换顺序：如果先 formatSQL 再 SqlValueResolver，formatSQL 会先将 `#{id}` 替换为 `'-1'`，导致 SqlValueResolver 找不到任何 `#{xxx}` 模式。

---

## 10. 动态标签智能合并

### 10.1 功能说明

`TemplateMerger` 组件负责在用户编辑了 SQL 后，将修改内容智能合并回原始 MyBatis 模板，完整保留 `<if>`、`<foreach>` 等动态标签结构。

### 10.2 核心方法

```java
public static String merge(String originalTemplate, String userEdited,
                            Map<String, String> substitutionMap)
```

**参数**：
- `originalTemplate`：原始 MyBatis 模板（含 `<if>`、`#{xxx}` 等）
- `userEdited`：用户编辑后的可执行 SQL（含具体值如 `1`、`'test'`）
- `substitutionMap`：SqlValueResolver 生成的替换映射（`{id → 1}`）

**返回值**：
- 合并后的模板字符串，保持原始动态标签结构，已添加 XML 缩进和换行

### 10.3 合并流程

#### 步骤一：空映射处理

如果 substitutionMap 为空（无法反向替换），直接返回缩进后的原始模板：

```java
return "\n        " + originalTemplate.trim().replace("\n", "\n        ") + "\n    ";
```

#### 步骤二：反向替换

`reverseSubstitute(String sql, Map<String, String> substitutionMap)`

对 substitutionMap 中的每个条目：

```java
String regex = "(?i)(\\b" + Pattern.quote(colName) + "\\s*=[\\s]*)" + Pattern.quote(value) + "(?=[\\s,;)\\)]|$)";
result = result.replaceAll(regex, "$1#{" + colName + "}");
```

示例：
```
映射：{id → 1}
用户编辑：AND id = 1
反向替换：AND id = #{id}
```

正则说明：
- `\\b` 确保列名作为完整单词匹配
- `\\s*=[\\s]*` 匹配 `=` 及两侧空格
- `Pattern.quote()` 转义值中的特殊字符
- `(?=[\\s,;)\\)]|$)` 前瞻确保值后有边界

#### 步骤三：骨架提取与快速比较

`mergeChanges(String originalTemplate, String userTemplate)`

先用正则提取原始模板中的 XML 标签：

```java
Pattern tagPattern = Pattern.compile("<[^>]+>");
Matcher tagMatcher = tagPattern.matcher(originalTemplate);
```

将标签替换为 `@@TAG0@@`、`@@TAG1@@` 等占位符，得到"SQL 骨架"：

```
原始模板：
SELECT ur_username
FROM t_user
WHERE 1 = 1
<if test="id!=null">
    and id=#{id}
</if>

骨架：
SELECT ur_username
FROM t_user
WHERE 1 = 1
@@TAG0@@
@@TAG1@@
@@TAG2@@
```

骨架移除占位符后，与用户模板（反向替换后）进行空白归一化比较：

```java
String skeletonResolved = skeletonStr.replaceAll("@TAG\\d+@@", "")
    .replaceAll("\\s+", " ").trim();
String userNorm = userTemplate.replaceAll("\\s+", " ").trim();

if (skeletonResolved.equalsIgnoreCase(userNorm)) {
    return originalTemplate.trim();  // 用户未修改结构，直接返回原始模板
}
```

如果骨架和用户内容一致，说明用户只修改了值（如 `id=1` → `id=#{id}`），未修改 SQL 结构，直接返回原始模板。

#### 步骤四：行级合并

当用户修改了 SQL 结构时，进行逐行合并：

```java
String[] templateLines = originalTemplate.split("\n", -1);
String[] userLines = userTemplate.split("\n", -1);
```

对每行模板，进行六路分支判断：

| 条件 | 处理方式 |
|------|---------|
| 开标签行（`<if ...>`、`<foreach ...>` 等） | 保留原行，设 `insideTag=true` |
| 关标签行（`</if>`、`</foreach>` 等） | 保留原行，设 `insideTag=false` |
| 标签内内容行（`insideTag=true`） | 从 `userLines` 取对应行，保留缩进 |
| 标签外 SQL 内容行（非空、非标签） | 从 `userLines` 取对应行，保留缩进 |
| 其他非空行（混合内容） | 保留模板原行 |
| 空行 | 保留模板原行 |

缩进保留方式：

```java
String indent = tLine.substring(0, tLine.indexOf(tLine.trim()));
merged.append(indent).append(userLines[userLineIdx].trim()).append("\n");
```

从模板行中提取前导空白作为缩进，用用户内容（trimmed）替换 SQL 文本。

#### 步骤五：最终格式化

```java
return "\n        " + merged.trim().replace("\n", "\n        ") + "\n    ";
```

- 整体前后加换行
- 每行前加 8 空格缩进（适配 XML Mapper 的典型缩进风格）

### 10.4 完整合并示例

**原始模板**：
```sql
SELECT ur_username
FROM t_user
WHERE 1 = 1
<if test="id!=null">
    and id=#{id}
</if>
```

**用户编辑**（右栏修改后）：
```sql
SELECT ur_username, ur_password
FROM t_user
WHERE 1 = 1
    AND id = 1
```

**substitutionMap**：`{"id" → "1"}`

**步骤一**：反向替换
```sql
SELECT ur_username, ur_password
FROM t_user
WHERE 1 = 1
    AND id = #{id}
```

**步骤二**：骨架提取 → 检测到结构变化（添加了 ur_password）

**步骤三**：行级合并
```
Line 0: "    SELECT ur_username" → userLines[0] "SELECT ur_username, ur_password"  ✓
Line 1: "    FROM t_user"        → userLines[1] "FROM t_user"                       ✓
Line 2: "    WHERE 1 = 1"        → userLines[2] "WHERE 1 = 1"                       ✓
Line 3: "    <if...>"            → 保留标签行                                    ✓
Line 4: "        and id=#{id}"   → userLines[3] "AND id = #{id}" + 8空格缩进     ✓
Line 5: "    </if>"              → 保留标签行                                    ✓
```

**合并结果**：
```sql
SELECT ur_username, ur_password
FROM t_user
WHERE 1 = 1
<if test="id!=null">
    AND id = #{id}
</if>
```

**最终输出**（添加 XML 缩进后写入文件）。

---

## 11. 技术架构

### 11.1 组件分层

```
┌──────────────────────────────────────────────────────────┐
│                     Action 层                             │
│  CheckSqlSyntaxAction (单条检查)                           │
│  OpenDataSourceDialogAction (配置数据源)                   │
│  BatchCheckAllXmlFilesAction (批量扫描)                    │
├──────────────────────────────────────────────────────────┤
│                      UI 层                                │
│  DataSourceDialog (多数据源管理)                            │
│  BatchCheckResultDialog (增强结果面板)                     │
│  AiOptimizationDialog (AI 优化对比)                       │
├──────────────────────────────────────────────────────────┤
│                    服务层                                  │
│  DataSourceConfig (持久化配置)                             │
│  DataSourceEntry (数据源条目)                              │
│  SqlExecutor (JDBC 执行引擎)                              │
│  SqlValidator (语法校验 + 标签展开)                         │
│  SqlFormatter (格式化)                                     │
│  SqlValueResolver (列类型感知值填充)                        │
│  TemplateMerger (动态标签合并)                             │
├──────────────────────────────────────────────────────────┤
│                    AI 服务层                                │
│  AiService (通义千问 API)                                 │
│  SqlComparisonResult (对比数据)                           │
│  SqlResultComparator (结果对比引擎)                        │
├──────────────────────────────────────────────────────────┤
│                   基础设施                                  │
│  SqlCheckResult (检查结果持有)                             │
│  SqlGutterIconProvider (编辑器图标)                       │
│  SqlExecutionCache (执行缓存)                             │
│  SqlExecutionResultInspection (代码检查)                   │
│  SqlResultGutterIconFix (快速修复)                        │
└──────────────────────────────────────────────────────────┘
```

### 11.2 关键数据流

#### 批量扫描数据流

```
XML File → PSI (XmlTag)
    ↓ getFullTagInnerText()
rawSql (含 <if> 标签全文)
    ↓ formatSQL()
标签展开后的 SQL
    ↓ replace #{xxx}
可执行 SQL
    ↓ SqlExecutor.execute()
Result { success, columns, rows, duration, message }
    ↓ new SqlCheckResult(type, rawSql, result, tagPointer)
    ↓ 收集到 Map<filePath, List<SqlCheckResult>>
    ↓ new BatchCheckResultDialog(project, allResults)
```

#### 编辑器双栏数据流

```
item.sqlCheckResult.sql (原始 SQL)
    ↓                         ↘
左栏显示                       SqlValueResolver.resolve(rawSql, project)
(原始模板，只读)                   ↓
                                formatSQL(resolvedSql)
                                    ↓
                                SqlFormatter.format(parsed)
                                    ↓
                                右栏显示（可编辑）
```

#### 替换数据流

```
右栏编辑 → 用户点击"替换到 XML"
    ↓
hasDynamicTags(originalSql) ?
    ├─ No → SqlFormatter.wrapForXml(editedParsedSql)
    ├─ Yes, 未修改 → 原始模板缩进保留
    └─ Yes, 已修改 → TemplateMerger.merge(original, edited, substitutionMap)
    ↓
replaceTagContentSafely(tag, wrappedSql)
    ↓
Document.replaceString(startOffset, endOffset, newInnerContent)
    ↓
PsiDocumentManager.commitDocument(doc)
    ↓
PSI 重新解析 → <if> 被正确识别为子标签
```

### 11.3 线程模型

| 操作 | 线程 | 说明 |
|------|------|------|
| 批量扫描 | Backgroundable 后台线程 | ReadAction.compute() 中读取 PSI |
| AI API 调用 | executeOnPooledThread | 网络请求，不阻塞 UI |
| SQL 执行 | Backgroundable 后台线程 | JDBC 操作，不阻塞 UI |
| 结果面板显示 | invokeLater(EDT) | 所有 UI 更新在 EDT |
| PSI 写入 | WriteCommandAction | 写锁保护 |
| Document 操作 | WriteCommandAction | 写锁保护 |

### 11.4 持久化

| 数据 | 存储方式 | 存储位置 |
|------|---------|---------|
| 数据源配置 | PersistentStateComponent | kingbaseDataSource.xml |
| 列类型缓存 | HashMap（内存） | 会话级，IDE 重启后清空 |
| SQL 执行缓存 | ConcurrentHashMap（内存） | 会话级，项目关闭后清空 |

---

## 12. 常见问题

### Q1: 插件安装后没有在右键菜单显示？

插件的 Action 注册在插件 XML 中：

```xml
<action id="CheckKingbaseSqlSyntax"
        class="org.example.demo.CheckSqlSyntaxAction"
        text="检查当前 SQL 语法（人大金仓）">
    <add-to-group group-id="EditorPopupMenu" anchor="last"/>
</action>
```

确保：
1. 使用 IntelliJ IDEA Ultimate 2025.1+（Community 版不支持 Database 插件和 PSI）。
2. 插件已启用：Settings → Plugins → Installed → Kingbase SQL Checker ✓。
3. 打开的是 XML 文件（非 Java 文件或其他类型文件）。
4. 光标放置在正确的 SQL 标签内。

### Q2: AI 修复/优化报"缺少 AI 私钥 Key"？

在 Tools → 配置数据库连接 → 对话框底部填写 AI 私钥 Key：
- 需要阿里云通义千问 API Key
- 申请地址：https://dashscope.aliyun.com/
- 创建 API Key 后复制到输入框

### Q3: AI 调用失败提示 HTTP 401/403？

检查：
1. API Key 是否有效（有没有过期）。
2. 是否在阿里云 DashScope 开通了通义千问服务。
3. Key 格式是否正确（通常是 `sk-` 开头）。

### Q4: 数据源测试连接失败？

可能原因：
1. 数据库服务未启动。
2. 防火墙阻止了连接。
3. 用户名/密码错误。
4. JDBC 驱动版本与数据库版本不兼容。
5. 数据库 URL 格式错误。

### Q5: 替换 SQL 后动态标签丢失？

可能原因：
1. 没有使用增强结果面板的"替换到 XML"按钮（而是手动编辑了 XML）。
2. `replaceTagContentSafely()` 回退到 `setText()`（Document 为 null）。
3. 用户编辑了右栏导致动态标签影响范围之外的内容变更。

解决方法：
1. 使用"替换到 XML"按钮而不是手动编辑。
2. 如果标签已丢失，可以使用 IDE 的 Local History 恢复。
3. 重新运行批量扫描获取最新的标签结构。

### Q6: 列类型查询返回空（所有占位符仍为默认值）？

可能原因：
1. `FROM` 子句中的表名无法正确提取（使用了子查询、视图等）。
2. 数据库用户没有 `information_schema` 或 `DatabaseMetaData.getColumns()` 的查询权限。
3. 表名大小写不匹配（某些数据库区分大小写）。
4. 数据库连接失败导致查询未执行。

插件行为：查询失败时自动降级为列名启发式推断：
- 列名以 id、_id、count、num 结尾 → `1`
- 其他列名 → `'test'`

### Q7: 批量扫描非常慢？

影响因素：
1. 每条 SQL 都需要在数据库上实际执行（网络延迟 + 执行时间）。
2. 单线程串行执行。
3. 大项目 XML 文件数量多。

优化建议：
1. 使用目录级扫描而非全项目扫描。
2. 确保数据库网络延迟低。
3. 只关注失败 SQL（默认筛选）。

### Q8: 如何处理 PL/SQL 或存储过程？

插件仅支持 `<select>`、`<update>`、`<insert>`、`<delete>` 标签中的 SQL 语句，不支持：
- PL/SQL（Oracle 存储过程语言）
- 数据库函数定义
- 触发器
- 存储过程

### Q9: 替换操作可以撤销吗？

替换操作通过 `Document.replaceString()` 写入文件，IDE 的 Local History 可以查看和恢复历史版本：
- 右键点击文件 → Local History → Show History
- 可以对比和恢复之前的内容

### Q10: 支持 MyBatis 注解（@Select）方式吗？

不支持。插件仅扫描 XML Mapper 文件（通过 `FileTypeIndex.getFiles(XmlFileType.INSTANCE, ...)`），不扫描 Java 文件中的注解 SQL。

### Q11: 如何添加新的数据库类型？

修改 `DataSourceEntry.java` 中的 `getDriverClass()` 和 `getJdbcUrl()` 方法：

```java
public String getDriverClass() {
    return switch (dbType.toLowerCase()) {
        case "kingbase" -> "com.kingbase8.Driver";
        case "postgresql" -> "org.postgresql.Driver";
        case "mysql" -> "com.mysql.cj.jdbc.Driver";
        case "oracle" -> "oracle.jdbc.OracleDriver";       // 新增
        case "sqlserver" -> "com.microsoft.sqlserver.jdbc.SQLServerDriver"; // 新增
        default -> "com.kingbase8.Driver";
    };
}
```

同时更新 `DataSourceDialog` 中的数据库类型下拉框。

### Q12: 如何调试插件？

```bash
# 运行沙箱 IDE
./gradlew runIde

# 查看插件日志
Help → Show Log in Explorer（沙箱 IDE 中）
```

---

## 13. 优缺点分析

### 13.1 优点

#### 1.1 深度集成 MyBatis 生态

插件专门针对 MyBatis XML Mapper 设计，能够正确解析 `<if>`、`<foreach>`、`<where>`、`<set>`、`<choose>`、`<trim>` 等全部 MyBatis 动态标签。双栏编辑器让开发者可以同时看到原始模板和解析后的可执行 SQL，避免了手动替换占位符的繁琐工作。模板合并算法（TemplateMerger）能够智能地将用户编辑后的 SQL 合并回原始模板，完整保留动态标签结构。

#### 1.2 列类型感知的值填充

不同于简单的 `'-1'` 替代，插件通过 JDBC `DatabaseMetaData.getColumns()` 实时查询数据库 schema，获取每个字段的数据类型，然后根据类型使用合适的测试值（INT → 1，VARCHAR → 'test'，DATE → '2024-01-01' 等）。这大大提高了 SQL 执行测试的准确性和实用性。当数据库查询失败时，自动降级为列名启发式推断，保证至少有一个合理的默认值。

#### 1.3 AI 驱动的智能修复与优化

利用阿里云通义千问大语言模型（qwen-max），插件不仅能自动修复 SQL 语法错误，还能进行性能优化。AI 修复自动执行验证确保修复正确性；AI 优化自动执行原始和优化 SQL 并进行列名、行数、数据值的逐项对比，只有在完全匹配时才允许应用，确保优化安全性。

#### 1.4 动态标签智能合并（TemplateMerger）

这是插件最具特色的技术亮点之一。通过反向替换（`id=1` → `id=#{id}`）和行级对比算法，自动将修改的 SQL 内容合并回原始模板，完整保留 `<if>`、`<foreach>` 等标签结构。开发者可以自由编辑解析后的 SQL（添加字段、修改条件等），无需手工回填动态标签。

#### 1.5 文档级替换保证子标签完整性

通过 Document 级别的内容替换（`Document.replaceString()` + `commitDocument()`）而非 `XmlTagValue.setText()`，确保 IntelliJ 的 PSI 解析器能正确将 `<if>` 等标签重新解析为 XML 子标签而非纯文本。这从根本上避免了「替换后标签消失」的问题。

#### 1.6 多数据源灵活切换

支持配置多个数据库连接并在不同数据源间自由切换，适合开发、测试、生产多环境并行的团队。数据源配置通过 `PersistentStateComponent` 持久化存储（`kingbaseDataSource.xml`），重启 IDE 不丢失。

#### 1.7 丰富的筛选和查看能力

增强结果面板支持按成功/失败状态筛选 SQL，默认显示失败项目（让开发者第一时间关注问题 SQL）。提供详细的执行结果表格展示（JTable 渲染列名 + 数据行 + 耗时 + 影响行数），支持点击定位到源码位置（`OpenFileDescriptor.navigate()`）。

#### 1.8 AI 优化结果验证机制

AI 优化不是「黑箱操作」—— 插件会同时执行优化前后的 SQL，使用 `SqlResultComparator` 进行列名、行数、数据值的逐项对比，只有在完全匹配时才允许应用优化。对比结果在 `AiOptimizationDialog` 中直观展示（绿色/红色状态横幅 + 差异详情），让开发者清楚知道优化是否安全。

#### 1.9 缓存机制减少重复查询

数据库列类型查询结果缓存在内存中（按项目路径 + 表名索引），避免重复查询相同表的元数据，提高响应速度。缓存使用字符串 key（`project.getBasePath() + "::" + tableName`），确保不同项目/表之间的隔离性。

#### 1.10 Material Design 3 风格 UI

使用专业的 MD3 配色方案：
- 成功状态：深绿 `#2E7D32` + 浅绿背景 `#E8F5E9`
- 失败状态：深红 `#C62828` + 浅红背景 `#FFEBEE`
- 主色：沉稳宝蓝 `#1565C0`
- 警告色：琥珀 `#E67E22`
- 分隔线：中性灰 `#C8C8D2`
- 主文字：深灰 `#212121`
- 次要文字：中灰 `#757575`

### 13.2 缺点

#### 2.1 仅限 IntelliJ IDEA Ultimate

插件依赖 IntelliJ 的 `com.intellij.database` 插件和 XML PSI 功能（`XmlFile`、`XmlTag`、`XmlTagValue`、`SmartPsiElementPointer` 等），Community 版无法使用。这限制了使用范围，团队成员必须统一使用 Ultimate 版 IDE。

#### 2.2 AI 功能依赖外部 API

AI 修复和优化功能需要阿里云通义千问 API Key，且需要网络连接（dashscope.aliyuncs.com）。在无网络环境（如内网开发环境）中无法使用 AI 功能。API 调用可能产生额外费用（按 token 计费），虽然单次调用成本较低（约 0.01-0.05 元/次），但大量使用时仍需注意。

#### 2.3 SQL 解析能力有限

`SqlValidator.formatSQL()` 方法对 MyBatis 动态标签的解析较为基础：
- `<if>` 标签只能模拟条件为 true 的情况，不支持条件为 false 的分支。
- `<foreach>` 标签只能模拟单次循环，无法模拟多元素集合。
- `<choose>`/`<when>`/`<otherwise>` 会被简单移除而非智能选择 when 分支。
- 复杂嵌套标签的处理可能不够精确（如 `<if>` 内嵌 `<foreach>`）。
- 不支持 MyBatis 3.5+ 的新功能（如 `<bind>` 标签）。

#### 2.4 列类型查询的局限性

`SqlValueResolver` 依赖 FROM/JOIN 子句提取表名，对于以下场景可能失败或不够精确：
- 使用复杂子查询（FROM 子查询、CTE 表达式）。
- 动态表名（运行时确定的表名，如 `${tableName}`）。
- 视图或物化视图（需要额外权限）。
- 同名字段分布在多张表中（缓存 key 可能冲突）。
- 表名大小写敏感时（某些数据库区分大小写，如 PostgreSQL 未引号括起的表名会被自动转为小写）。

失败时降级为基于列名模式的启发式推断（含 id → 1，其他 → 'test'），可能不够准确。

#### 2.5 模板合并的非通用性

`TemplateMerger` 的行级对比算法依赖 SQL 的行结构。如果用户大幅改变了 SQL 的格式（如将所有内容写在一行、删除了所有换行），行级对比可能不准确。算法对以下场景效果良好：
- ✓ 添加/删除字段（SELECT 子句添加列）
- ✓ 修改条件（WHERE 子句修改条件值）
- ✓ 添加 ORDER BY / GROUP BY 子句
- △ 大幅重排 SQL 结构（部分效果）

但以下场景效果有限：
- ✗ 完全删除所有换行（写在一行）
- ✗ 在标签内部添加 SQL 内容（行数不匹配导致 fallback）
- ✗ 同时修改多个标签的内容（内部行数的映射可能错位）

#### 2.6 不支持 Java 注解 SQL

插件仅扫描 XML Mapper 文件中的 SQL，不支持 MyBatis 注解方式（如 `@Select`、`@Update`、`@Insert`、`@Delete`）写在 Java 接口类中的 SQL。现代 MyBatis 项目越来越多地使用注解方式，这部分用户无法使用本插件。

#### 2.7 不支持存储过程和函数

插件仅检查 Mapper 文件中的 DML/DDL SQL 语句（SELECT、UPDATE、INSERT、DELETE），不支持：
- 数据库存储过程（如 PostgreSQL 的 CREATE FUNCTION）。
- 触发器（Trigger）。
- 事件（Event）。
- 序列（Sequence）的 DDL。
- 索引创建的 DDL。

#### 2.8 无 SQL 语法高亮

右侧编辑器的 SQL 没有语法高亮——仅使用 Consolas 等宽字体渲染，没有关键词着色、字符串高亮、注释着色等常见的 SQL 编辑器功能。这降低了 SQL 编辑的可读性和效率。

#### 2.9 无 SQL 历史记录

编辑器中修改的 SQL 没有版本历史记录，用户无法回退到之前的修改版本。替换操作不可直接撤销（IDE 的 Local History 可以部分弥补，但需要手动操作）。建议用户编辑前手动备份或使用 Git 跟踪 XML 文件变更。

#### 2.10 不支持事务管理

插件对 SQL 的执行是独立进行、即时提交的（auto-commit 模式），不支持事务测试。对于需要事务上下文的更新操作（INSERT、UPDATE、DELETE）可能产生副作用——例如插入测试数据、修改真实数据等。建议：
- 在执行更新类 SQL 前手动备份或确认数据。
- 使用专用的测试数据库而非生产数据库。
- 插件默认启用 `DROP` 和 `TRUNCATE` 的禁止检测。

#### 2.11 单线程执行

批量扫描使用单线程串行执行，对于包含大量 XML 文件的项目（1000+ SQL），扫描时间可能较长（尤其是在数据库网络延迟高的情况下）。未使用多线程并行加速，也未支持可配置的并发度。

#### 2.12 嵌入式 JDBC 驱动版本固定

JDBC 驱动打包在 `src/main/resources/lib/` 目录下，版本是固定的：
- kingbase8-8.6.0.jar
- mysql-connector-java-8.0.21.jar

如果数据库版本较新（如 MySQL 8.4+），可能需要更新驱动版本。驱动不能通过 Maven/Gradle 自动管理，需要手动替换 jar 包。

#### 2.13 数据库兼容性限制

虽然插件支持 MySQL 和 PostgreSQL，但主要针对 Kingbase（人大金仓）设计和测试。以下方面可能存在兼容性问题：
- Kingbase 特有的 SQL 语法（如 `LIMIT ALL` 语义）。
- 类型映射差异（Kingbase 的某些类型与标准 PostgreSQL 不同）。
- 元数据查询的 schema/catalog 参数差异。
- 自增列/序列的处理方式不同。

#### 2.14 对 AI 输出的零控制

AI 修复和优化结果完全依赖大模型的输出质量。当模型升级或 API 更新时，输出可能发生变化：
- 可能返回格式不正确的 SQL（包含 markdown 标记、多余的解释文字等）。
- 可能修改了 SQL 的业务语义（即使 ResultComparator 检测到差异）。
- 对复杂 SQL（多层嵌套、窗口函数、CTE 等）的修复能力有限。
- 不支持自定义 Prompt 模板（Prompt 硬编码在 AiService 中）。

#### 2.15 缺少国际化支持

插件的 UI 和错误提示均为中文（简体），没有英文版本。对于国际化团队的成员，可能造成理解障碍。所有用户可见的字符串（对话框标题、按钮文字、错误信息、提示文字）均硬编码为中文。

---

## 14. 性能参考

### 14.1 扫描性能

| 项目规模 | XML 文件数 | SQL 总数 | PSI 解析耗时 | 单 SQL 执行耗时（平均） | 总耗时（含执行） |
|---------|-----------|---------|-------------|----------------------|----------------|
| 小型 | 10-50 | 50-200 | < 1s | 10-50ms | 2-15s |
| 中型 | 50-200 | 200-1000 | 2-5s | 10-100ms | 10-100s |
| 大型 | 200-500 | 1000-5000 | 5-15s | 10-200ms | 30-500s |

**注意**：总耗时主要取决于 SQL 执行耗时，因为每条 SQL 都需要在数据库上实际执行。网络延迟（ping 每增加 1ms，总耗时增加 N×1ms）和数据库负载（慢查询、锁等待）会影响执行时间。

### 14.2 缓存命中率

| 缓存 | 首次访问 | 后续访问 | 场景 |
|------|---------|---------|------|
| 列类型缓存 | 10-50ms（含 JDBC 连接 + 元数据查询） | 0ms（内存读取） | 同一项目的相同表 |
| PSI 指针 | 0.1-1ms（SmartPointerManager.create） | 0.1-1ms（getElement） | 文件未变更时 |
| 执行结果缓存 | 10-1000ms（含 SQL 执行） | 0ms（ConcurrentMap 读取） | 完全相同的 SQL + 文件 + 项目 |

### 14.3 内存占用

| 组件 | 内存占用 | 说明 |
|------|---------|------|
| 列类型缓存 | ~1KB/表（平均 20 列 × 50bytes） | 100 张表约 100KB |
| 结果面板 | ~1KB/SQL（显示数据） | 1000 条 SQL 约 1MB |
| PSI 树 | 由 IntelliJ 管理 | 打开的文件才占用 |
| 总体 | 通常在 10-50MB 以内 | 远低于 IDEA 的默认堆内存 |

---

## 15. 版本历史与贡献

### 15.1 版本历史

| 版本 | 日期 | 主要变更 |
|------|------|---------|
| 1.1.2 | 2025-09 | 多数据源管理、AI 优化对比验证、增强结果面板、动态标签智能合并、列类型感知值填充、Document 级别替换、Material Design 3 配色 |
| 1.1.0 | 2025-08 | AI 自动修复功能、批量扫描进度指示、编辑器侧边栏图标 |
| 1.0.0 | 2025-06 | 初始版本：单数据源连接、基本 SQL 语法检查、批量扫描 |

### 15.2 贡献指南

欢迎提交 Issue 和 Pull Request。提交代码前请确保：

1. **代码风格**：与项目一致（使用 IntelliJ 默认 Java 代码风格，缩进 4 空格，Kotlin 风格一致）。
2. **测试覆盖**：新增功能有对应的单元测试或手动测试步骤。
3. **编码**：中文注释和字符串使用 UTF-8 编码，编译配置已指定 `options.encoding = "UTF-8"`。
4. **PR 描述**：清楚说明变更内容、原因、测试方式。
5. **API 兼容性**：尽量使用稳定的 IntelliJ Platform API（不依赖 internal API）。

### 15.3 反馈与支持

- 作者邮箱：1578442238@qq.com
- 开源发布：https://gitee.com/CodeLiQing/kingbase-plugin
- 问题反馈：提交 Issue 到 Gitee 仓库

### 15.4 许可证

本项目基于 MIT 许可证开源。允许自由使用、修改和分发，需保留版权声明和许可证文本。

---

*本文档基于 Kingbase SQL Checker v1.1.2 版本编写，内容涵盖全部功能和实现细节。文档字数超过 10,000 字，全面覆盖插件使用、配置、技术实现、常见问题和性能参考。*