SQL 格式化完全指南：美化、方言与安全粘贴

1. 美化、压缩、校验各自解决什么

日常说的「整理 SQL」至少有三件事，工具可能都做，目标却不同。

关键边界： 正常格式化不应改写表名、列名、字面量与运算符语义；它服务的是人眼与 diff。若你依赖注释说明业务规则，压缩前先备份——本页「压缩」会剥注释再折叠空白。

前后对照（同一逻辑，仅空白与关键字风格不同）：

-- 压缩前（故意挤在一行）
select u.id,u.name from users u left join orders o on u.id=o.user_id where o.amount>100 order by o.created_at desc;

-- 美化后（示意，缩进与换行依选项而定）
SELECT
  u.id,
  u.name
FROM
  users u
  LEFT JOIN orders o ON u.id = o.user_id
WHERE
  o.amount > 100
ORDER BY
  o.created_at DESC;

2. 方言不是装饰：为何要先选对

SQL 有共同骨架，但标识符引用、函数名、分页、布尔与部分关键字因引擎而异。WebUtils 工具基于 sql-formatter，页面提供：

选错方言会发生什么？

• 格式化器对某段语法「不认识」→ 抛错，页面提示格式化失败。
• 仍能出结果，但换行位置怪异，或把方言特有关键字当普通标识符处理。
• 团队规范要求关键字大写、标识符小写时，要靠「关键字大小写」选项配合，而不是换方言硬凑。

建议：生产引擎是什么就选什么；跨库迁移脚本可先用「标准 SQL」看公共部分，再用目标方言各跑一遍，对比差异。

3. 工具上的参数分别管什么

打开 /tools/dev/sql-formatter，工具栏从左到右大致是：

1. 方言下拉 — 见上表。
2. 缩进 — 数字 0～8，默认 2；控制空格缩进宽度（实现为 tabWidth，不使用 Tab 字符）。
3. 关键字大小写 — 保持原样 / 关键字大写 / 关键字小写。选「保持原样」时不强制改关键字大小写。
4. 格式化 — 调用库美化当前编辑器全文。
5. 压缩 — 去注释 + 空白折叠（见下文注意）。
6. 复制 / 清空 — 剪贴板与重置。

处理在浏览器内完成；依赖 CDN 加载的 sql-formatter 库。离线或拦截 CDN 时格式化会不可用——这是环境问题，不是「SQL 写错了」。

4. 逐步操作

1. 打开工具页。 进入 SQL 格式化，确认编辑区与工具栏可见。
2. 选方言。 按真实数据库选择；不确定时用「标准 SQL」试跑，再切到具体方言。
3. 设缩进与关键字风格。 与团队规范对齐（例如关键字大写、缩进 2）。
4. 粘贴 SQL。 一次贴一条或一段；超大脚本可先截取出问题的子查询再美化。
5. 点「格式化」。 成功时编辑区变为多行结构，并出现「格式化成功」提示；失败时弹窗带错误信息。
6. 需要紧凑串时点「压缩」。 确认不再需要注释后再做；结果可复制进日志或单行配置。
7. 复制带走。 用「复制」；若还要对照 JSON 配置或接口体，可另开 JSON 格式化。

能力边界（对照真实页面）

• 支持： 多方言美化、缩进宽度、关键字大小写、简易压缩、复制清空。
• 不宣称： 执行 SQL、连接数据库、解释执行计划、自动修复语义错误、完整存储过程 IDE。
• 压缩副作用： 会去掉 -- 行注释与 / / 块注释；不要把「压缩」当成无损往返。

5. 常见失败与处理

排错顺序

1. 是否完整 SQL（有无日志时间戳、有无 ORM 前缀）。
2. 引号与括号是否成对。
3. 方言是否与目标引擎一致。
4. 是否误点了压缩导致注释丢失。
5. 再谈业务条件对不对——格式化只解决「看得见」。

6. 真实工作场景

场景 A：慢查询日志里的一行怪物

从 MySQL slow log 或 APM 复制出单行 SQL，贴进工具，方言选 MySQL，关键字大写。先看 JOIN 顺序与 WHERE 是否能下推索引条件，再决定是否加覆盖索引。把美化后的版本贴进工单，比截图糊成一团更利于复现。

场景 B：Code Review 风格不统一

有人关键字全小写、有人混用 Tab。约定「提交前用本工具：PostgreSQL + 缩进 2 + 关键字大写」，Review 只盯语义与索引，不再争论空格。注意：格式化不能替代 SQL Review 规范（禁止 SELECT *、必须有限流等）。

场景 C：迁移 MySQL → PostgreSQL

同一业务语句在两边各格式化一次，肉眼对比函数与分页写法。格式化器不会自动改写 LIMIT 为 FETCH，但能让差异段落对齐，方便写迁移清单。

场景 D：BI 同学导出的「能跑」脚本

报表工具导出常带多余别名与嵌套。先美化，标出可下推过滤的子查询，再交给数仓改写。压缩仅用于「确认去掉空白后是否同一句」，不要当交付格式。

场景 E：教学演示危险写法

用虚构表名与假数据演示笛卡尔积、漏连接条件。切勿把真实客户表结构、身份证号、手机号写进公开示例。

场景 F：和 JSON / 配置联调

接口用 JSON 传动态 SQL 片段（不推荐但现实存在）时：先把 JSON 在 JSON 格式化 里拆开，再把 SQL 字段值贴到本工具。两段工具分工，避免在一个框里混语法。

7. 安全与隐私：生产 SQL 不是普通文本

格式化工具让语句更易读，也让敏感信息更显眼。粘贴前默认假设：屏幕可能被录、历史可能被同步、公共电脑剪贴板不可信。

原则：

• 优先在测试库构造等价 SQL，再格式化分享。
• 必须用生产形态复现时，本地可信机器 + 用完清空编辑区与剪贴板。
• WebUtils 在浏览器处理，不因此等于「可以随便贴主库 dump」。
• 不要把格式化后的生产语句提交到公开 Issue 或群文件。

8. 相关工具怎么选

选型口诀：要读 SQL 用 SQL 格式化；要读 JSON 用 JSON 工具；编码层先解码；执行与权限永远在数据库侧完成。

9. 团队落地建议

• 文档与 Wiki 中的示例 SQL 统一走同一套选项（方言 + 缩进 + 关键字）。
• PR 模板加一句：「新增/修改 SQL 请附格式化后版本」。
• 慢查询值班手册：粘贴前脱敏检查表（库名可留，字面量 PII 必换）。
• 区分「格式化风格」与「查询性能」：美化漂亮的全表扫描仍然是慢查询。
• 存储过程、动态 SQL 拼接若格式化失败，优先缩小到静态片段，再处理字符串拼接层。

把「先排版再争论」变成习惯后，SQL 协作从审美争论回到谓词、索引与数据量。

常见问题

继续浏览

用一条无敏感数据的查询走通「选方言 → 格式化 → 复制」，再处理真实慢查询时先做脱敏。也可返回指南列表继续浏览。