夜雨聆风SQL 一长，真正难的往往不是写出来，而是再次读懂、定位和修改。
SQL Heading Folding给 SQL 控制台和.sql文件加上了层级标题、原生折叠、阅读模式标签和大纲导航。它不改变 SQL 语法，也不要求你换编辑器，只是在熟悉的 IntelliJ IDEA 或 DataGrip 里，把一份很长的脚本变成一份可以快速扫描的文档。
先看一个常见场景
做数据分析、报表开发或线上排障时，一份 SQL 往往会同时包含：参数准备、临时表、用户口径、订单口径、明细查询、汇总查询和结果校验。
没有结构时，我们只能靠搜索关键字和不停滚动；有了结构之后，可以像读目录一样先看全貌，再跳到需要修改的区段。
这款插件的思路很简单：用 SQL 注释写标题，用 # 的数量表示层级。
-- # 用户分析-- ## 用户基础信息select id, name, created_atfrom users;-- ## 活跃用户select id, namefrom userswhere active = true;-- # 订单分析-- ## 订单金额汇总select user_id, sum(amount) as total_amountfrom ordersgroup by user_id;
五级标题，足够覆盖大多数脚本
插件识别完整的单行 SQL 注释标题：
-- # 一级标题-- ## 二级标题-- ### 三级标题-- #### 四级标题-- ##### 五级标题标题必须以 -- 开头，并在后面使用 1 到 5 个 #。标题可以带空格，也可以使用中英文内容。普通的 SQL 注释不会被误识别成标题，因此原有注释和 SQL 代码都可以继续保留。
层级会直接影响区段边界：一个二级区段会持续到下一个一级或二级标题；一级区段会持续到下一个一级标题。这样，折叠范围和你在目录中理解的范围是一致的。
编辑器里的阅读模式：标题一眼可见，编辑时仍是原文
当光标离开标题行，插件会把标题前缀收成紧凑的 H1 到 H5 标签，并将标题文字加粗。视觉上更像 Markdown 大纲，长脚本滚动时可以迅速定位当前区段。
这个变化只是显示层的增强，不会修改文档内容。光标回到标题行后，原始的 SQL 注释会立即恢复，仍然可以像平时一样编辑标题。
这点很适合“阅读和编辑交替进行”的场景：阅读时减少视觉噪音，修改时保留完整语法。
原生折叠：折叠的是区段，不是某几行
标题行左侧会出现 IntelliJ 原生折叠控制。点击后，插件会折叠从当前标题开始、直到下一个同级或更高级标题之前的整个区段，标题本身仍然保留在编辑器里。
因此你可以只留下几个一级标题作为“骨架”，也可以展开某个一级标题，再单独查看里面的二级区段。折叠状态和 IntelliJ 的编辑器体验一致，不需要学习新的快捷键或面板。
SQL Headings 工具窗口：把脚本变成可点击的目录
打开右侧的 SQL Headings 工具窗口后，当前 SQL 文件或 SQL 控制台中的标题会以树状结构显示。标题的层级关系会被保留下来，标题右侧还会标注 H1、H2 等级别。
点击目录中的任意标题，编辑器会跳转到对应位置，并自动展开包含该标题的折叠区段。面对几百行甚至上千行的脚本，定位一个查询区段只需要一次点击。
工具窗口顶部提供三个常用操作：
• Refresh：重新读取当前 SQL 标题； • Collapse All：折叠所有标题区段，只保留脚本骨架； • Expand All：展开所有标题区段，恢复完整内容。
面板支持树形展开和快速搜索，标题很多时也能快速筛选。
一个适合日常使用的组织方式
可以把一份报表 SQL 按下面的结构组织：
-- # 销售日报-- ## 参数与日期范围-- ### 业务日-- ### 对比周期-- ## 指标计算-- ### 销售额-- ### 订单数-- ## 结果校验建议一级标题表达业务主题，二级标题表达查询区段，三级及以下标题只在确实需要时使用。层级不宜为了“看起来完整”而堆得太深；能让下一次打开文件时快速回答“这段 SQL 在做什么”，就是合适的结构。
安装与兼容性
从 JetBrains Marketplace 安装
在 Settings / Preferences > Plugins > Marketplace 搜索 SQL Heading Folding，点击安装并重启 IDE。
从 ZIP 安装
从项目的 https://github.com/yc-2018/intellij-sql-heading-folding/releases/tag/continuous 下载最新 ZIP，然后进入 Settings / Preferences > Plugins > Install Plugin from Disk 选择文件。
插件最低支持 IntelliJ Platform build 232（对应 2023.2）。重点适配 IntelliJ IDEA 和 DataGrip；其他只要提供 com.intellij.database（Database Tools）的 JetBrains IDE 也可以使用。Community 版因为不包含 Database Tools，不在支持范围内。
适合谁？
• 经常维护报表、数据分析和运营 SQL 的同学； • 需要在 SQL 控制台里反复定位不同查询区段的开发者； • 希望保留原生编辑器体验，又想拥有目录导航的人； • 团队里需要共享一套轻量 SQL 结构约定的场景。
它不替你生成 SQL，也不改变数据库执行逻辑。它做的事情很克制：让已经写好的 SQL 更容易阅读、折叠、定位和维护。
写在最后
当 SQL 从几十行增长到几百行，问题通常不是“还能不能执行”，而是“下次还能不能快速读懂”。给脚本加上层级标题，是成本最低、收益很稳定的一种整理方式。
如果你日常使用 IntelliJ IDEA 或 DataGrip，可以从一份正在维护的 SQL 开始试试：先加几个 -- # 和 -- ##，再打开 SQL Headings 看看目录效果。结构一旦建立起来，后续的折叠和导航都会变得顺手。
项目地址：https://github.com/yc-2018/intellij-sql-heading-folding
