SqlToy Navigator：一个支持 SqlToy ORM SQL 双向跳转的 IDEA 插件
一、背景
在 Java 后端开发中，ORM 框架通常用于简化数据库访问逻辑。
SqlToy ORM 是一种以 SQL 为核心的持久层框架，常见使用方式是将 SQL 定义在 XML 文件中，然后在 Java 代码中通过 sqlId 进行调用。
例如，在 Java 代码中：
lightDao.find("view_user_list", queryParam, User.class);
对应的 XML SQL 定义可能是：
<sqls>
<sql id="view_user_list">
SELECT *
FROM TEST_TABLE
</sql>
</sqls>
这种方式可以将复杂 SQL 与 Java 业务代码分离，便于集中管理 SQL，也方便进行 SQL 调优和维护。
但是在实际开发过程中，这种模式也会带来一个常见问题：
Java 代码中的 sqlId 和 XML 文件中的 SQL 定义之间缺少直接跳转能力。
当项目中的 SQL 文件较多、业务模块较复杂时，开发人员通常需要手动复制 sqlId，再通过全局搜索查找对应的 XML SQL 定义。
这种操作虽然可以完成定位，但步骤繁琐，尤其在老项目维护、问题排查和 SQL 修改场景中，会明显影响开发效率。
为了解决这个问题，开发了一个 IntelliJ IDEA 插件：SqlToy Navigator。
二、插件简介
SqlToy Navigator 是一个面向 SqlToy ORM 使用场景的 IntelliJ IDEA 插件。
插件的核心功能是：
支持 Java 代码中的 SqlToy sqlId 与 XML SQL 定义之间进行双向跳转。
也就是说，开发人员可以直接从 Java 代码中的 SQL ID 跳转到 XML 中对应的 SQL 定义，也可以从 XML 中的 SQL ID 反向查找 Java 代码中的调用位置。
该插件主要用于提升 SqlToy ORM 项目中的 SQL 定位效率，减少手动搜索操作，使 SQL 查看、维护和问题排查更加直观。
三、核心功能
1. 从 Java 代码跳转到 XML SQL
在 Java 代码中，当调用 SqlToy 相关方法时，通常会传入一个字符串形式的 sqlId。
示例：
lightDao.find("view_user_list", queryParam, User.class);
当光标位于 "view_user_list" 上时，可以通过 IDEA 的跳转操作直接定位到 XML 文件中对应的 SQL 定义。
对应 XML：
<sqls>
<sql id="view_user_list">
SELECT *
FROM TEST_TABLE
</sql>
</sqls>
使用插件后，不需要再手动复制 sqlId 进行全局搜索，直接通过 IDE 原生跳转即可完成定位。
2. 从 XML SQL 跳转到 Java 调用位置
除了支持从 Java 代码跳转到 XML，插件也支持从 XML 中的 SQL ID 反向查找 Java 代码中的使用位置。
例如 XML 中存在如下 SQL 定义：
<sql id="view_user_list">
SELECT *
FROM TEST_TABLE
</sql>
在 view_user_list 上执行跳转或查找引用操作，可以定位到项目中调用该 SQL ID 的 Java 代码。
例如：
lightDao.find("view_user_list", queryParam, User.class);
这个功能在维护 SQL 时非常实用。
当开发人员需要修改某个 SQL 时，可以先查看该 SQL 被哪些 Java 代码调用，从而判断修改影响范围，降低误改风险。
3. 支持常见 SqlToy 调用方式
插件主要面向 SqlToy ORM 中通过字符串 sqlId 调用 SQL 的场景。
常见调用示例：
lightDao.find("view_user_list", queryParam, User.class);
lightDao.findOne("get_user_detail", queryParam, User.class);
只要 Java 代码中的字符串参数能够对应 XML 中的 SQL ID，插件就可以提供跳转支持。
四、使用示例
Java 调用示例
public List<User> queryUsers(Map<String, Object> queryParam) {
return lightDao.find("view_user_list", queryParam, User.class);
}
XML SQL 示例
<sqls>
<sql id="view_user_list">
SELECT *
FROM sys_user
WHERE status = 1
</sql>
</sqls>
在未安装插件之前，如果想查看 view_user_list 对应的 SQL，通常需要：
安装插件之后，只需要：
整个过程更加直接，也更符合日常开发中的代码阅读习惯。
五、适用场景
1. 阅读业务代码时快速查看 SQL
在阅读业务代码时，开发人员经常需要确认某个方法最终执行了什么 SQL。
如果没有跳转能力，需要手动搜索 sql id。
使用插件后，可以直接跳转到 XML 中查看 SQL 内容。
1. 修改 SQL 时分析影响范围
在修改 XML SQL 时，开发人员需要知道该 SQL 被哪些 Java 代码调用。
例如：
<sql id="update_user_status">
UPDATE sys_user
SET status = :status
WHERE id = :id
</sql>
通过插件可以反向查看 update_user_status 在 Java 代码中的使用位置，方便判断当前 SQL 是否被多个业务场景复用。
2. 项目维护
在一些长期维护的项目中，SQL 文件数量较多，模块划分可能也比较复杂。
开发人员经常需要在 Java 代码和 XML SQL 文件之间来回切换。
使用该插件后，可以减少大量重复搜索操作，提升代码定位效率。
4. 问题排查
当接口出现数据异常、查询结果不符合预期或 SQL 执行性能较差时，开发人员通常需要快速找到对应 SQL。
插件可以帮助开发人员从 Java 调用入口快速定位到 SQL 定义，从而更快进入问题分析阶段。
六、插件实现思路
该插件基于 IntelliJ Platform SDK 开发，主要利用 IDEA 提供的 PSI 机制完成代码结构解析和跳转目标解析。
整体实现流程如下：
七、关键技术点
1. PSI 元素解析
IntelliJ IDEA 内部通过 PSI 表示代码结构。
插件可以通过 PSI 访问 Java 文件、XML 文件、字符串字面量、XML 标签、XML 属性等结构化信息。
在本插件中，主要处理以下 PSI 元素：
- Java 字符串字面量
- Java 方法调用表达式
- XML 标签
- XML 属性
- XML 属性值
- 项目文件索引
2. Java 字符串识别
插件需要识别 Java 代码中的字符串内容，例如：
"view_user_list"
然后判断该字符串是否可能是 SqlToy SQL ID。
在实际实现中，可以根据以下条件进行判断：
3. XML SQL ID 查找
SqlToy 的 SQL 通常定义在 XML 文件中。
示例：
<sql id="view_user_list">
SELECT *
FROM sys_user
</sql>
插件需要扫描项目中的 XML 文件，并查找具有相同 id 属性值的 <sql> 标签。
查找到目标节点后，将其作为 Java 字符串的跳转目标。
4. 双向引用支持
插件不仅需要支持 Java 到 XML 的跳转，也需要支持 XML 到 Java 的反向查找。
例如，从 XML 中：
<sql id="view_user_list">
可以反向定位到 Java 代码：
lightDao.find("view_user_list", queryParam, User.class);
这样可以让开发人员快速确认某个 SQL 的使用位置。
八、插件优势
1. 提升 SQL 定位效率
使用插件后，开发人员不再需要频繁复制 SQL ID 并进行全局搜索，可以直接通过 IDEA 跳转功能定位 SQL。
2. 更符合 IDEA 使用习惯
IDEA 本身支持 Java 类、方法、变量等符号跳转。
该插件将 SqlToy 的 sqlId 也纳入类似的跳转体验中，使 SQL 定义和 Java 代码之间的关系更加清晰。
3. 降低维护成本
在修改 SQL 前，可以快速查看 SQL 的调用位置，方便判断影响范围，降低误改风险。
4. 不侵入业务代码
插件只增强 IDE 开发体验，不需要修改项目代码，也不改变 SqlToy 原有使用方式。
5. 适合 SqlToy 项目
对于 SQL 数量较多、XML 文件分布较广的项目，该插件可以显著减少搜索和定位成本。
九、后续优化方向
目前插件主要实现 SqlToy SQL ID 的基础双向跳转和语法高亮能力。
后续可以继续扩展以下功能：
1. SQL ID 自动补全
在 Java 代码中输入 SqlToy 方法参数时，根据项目 XML 文件中已有的 SQL ID 提供自动补全。
示例：
lightDao.find("view_user_list", queryParam, User.class);
当输入引号内容时，自动提示已有 SQL ID。
2. 重复 SQL ID 检查
当多个 XML 文件中存在相同 SQL ID 时，可能会造成 SQL 定位混乱。
插件可以增加重复 SQL ID 检查能力，并在 IDEA 中进行提示。
3. 未使用 SQL 检查
对于 XML 中定义但 Java 代码中没有使用的 SQL，可以进行静态检查。
该功能可以帮助开发人员清理无效 SQL，降低项目维护成本。
4. SQL ID 重命名支持
当需要修改 SQL ID 时，可以支持 Java 代码和 XML 定义同步重命名。
例如将：
view_user_list
重命名为：
query_user_list
插件可以同时更新 XML 中的 SQL ID 和 Java 代码中的调用位置。
5. 支持更多 SqlToy 方法识别
后续可以扩展更多 SqlToy 常用 API 的识别能力，使插件覆盖更多实际业务场景。
6. XML SQL 文件导航
可以基于 XML SQL ID 生成结构化导航列表，方便开发人员在大型 SQL 文件中快速定位目标 SQL。
十、总结
SqlToy Navigator 是一个面向 SqlToy ORM 使用场景的 IntelliJ IDEA 插件，主要解决 Java 代码中的 sqlId 与 XML SQL 定义之间缺少快速跳转的问题。
通过该插件，开发人员可以在 Java 代码和 XML SQL 文件之间进行双向跳转，减少手动搜索，提高代码阅读、SQL 维护和问题排查效率。
对于长期使用 SqlToy ORM 的项目来说，该插件可以有效改善开发体验，使 SQL 定位更加直观、高效。
