前端SQL格式化工具如何精准识别并保留注释与关键字大小写？

Question

在前端SQL格式化工具开发中，一个典型技术问题是：**如何在语法解析与重排版过程中，精准识别并区分SQL注释（单行`--`、多行`/* */`、内联注释）与可执行语句，同时严格保留用户原始注释内容及关键字（如`SELECT`/`select`）的大小写形式？** 由于SQL本身不区分关键字大小写，但团队规范或可读性常要求保留原始大小写；而注释可能包含代码片段、TODO标记甚至嵌套SQL，若被误解析为语法节点或遭自动转大写/小写，将破坏语义与协作信息。常见错误包括：正则预处理破坏注释边界、AST解析器忽略注释token位置、格式化后注释被移至行首丢失上下文、大小写归一化逻辑未按作用域隔离（如字符串字面量内的`SELECT`不应被修改）。需结合词法分析阶段的token级注释捕获、AST中注释附着机制（如ESTree的`leadingComments`/`trailingComments`），以及大小写感知的上下文敏感重写策略，方能兼顾标准化与忠实性。

Answer 1

```html

一、词法分析阶段：注释的精准捕获与上下文隔离

在SQL格式化工具中，首要防线是词法分析器（Lexer）——它必须将输入流切分为语义明确的Token，且严格区分Comment、Keyword、StringLiteral、Identifier等类型。常见错误如用/--.*$/gm正则全局替换，会误吞--出现在字符串或正则表达式中的情况（如SELECT '--' AS dash）。正确做法是实现状态机驱动的Lexer：进入/*后切换至IN_BLOCK_COMMENT状态，跳过所有字符直至*/；对--则需校验其前为空白或行首，且后接换行或EOF。关键点在于：每个Comment Token 必须携带原始字节偏移（startOffset、endOffset）、行号列号（loc），并标记类型（LineComment / BlockComment / InlineComment）。

二、语法解析阶段：AST中注释的结构化附着机制

仅识别注释不够，必须将其“锚定”到AST节点上。参考ESTree规范，现代SQL解析器（如sql-parser-js或自研ANTLR4语法）应支持leadingComments、trailingComments、innerComments三类附着属性。例如：

SELECT /*+ INDEX(t idx_name) */ 
  id, -- 主键ID
  name -- 用户姓名
FROM users;

其中/*+ ... */作为SelectStatement节点的leadingComments，而-- 主键ID是ColumnReference节点的trailingComments。这要求解析器在构建AST时，不丢弃注释Token，而是根据其物理位置（如紧邻某token之前/之后/之间）动态挂载。若解析器忽略Comment token（如Babel默认行为），则后续格式化必然丢失上下文。

三、格式化重排阶段：注释位置保真与上下文感知布局

格式化不是简单缩进换行，而是基于AST的“带注释重写”。需定义三类布局策略：

• 行内注释（--）：强制保留在原token右侧同一行，禁止跨行迁移；
• 块级注释（/* */）：若位于语句开头且无前置空白，则保持左对齐；若嵌入表达式中间（如WHERE a = /* legacy */ 1），则维持相对位置偏移；
• 悬挂注释：当注释位于逗号后、括号内等“弱连接点”，需按团队规范决定是否提升至上一行（如列定义前）或下沉至下一行（如JOIN条件后）。

四、大小写保留策略：作用域敏感的上下文判定矩阵

关键字大小写不可全局统一，必须依据其语法角色动态决策。下表定义核心判定逻辑：

Token位置	所属AST节点	是否保留原始大小写	原因说明
SELECT in SelectStatement.keyword	SelectStatement	✅ 是	顶层关键字，反映作者意图与团队风格
select inside StringLiteral	StringLiteral	✅ 是	纯文本内容，非SQL语法
SELECT inside Comment	BlockComment	✅ 是	注释即文档，含TODO/SQL片段需零修改

五、工程实践：可验证的端到端保障链路

为防止回归，需构建多层防护：

1. Token流快照测试：对含混合注释/大小写的SQL样本，断言输出Token数组包含完整Comment且value未被截断；
2. AST注释映射测试：验证SELECT ... FROM t -- comment中-- comment确为FromClause节点的trailingComments；
3. 格式化黄金测试（Golden Test）：保存原始输入与期望输出diff，覆盖嵌套注释、引号内关键字、Unicode标识符等边界场景。

六、架构演进：从正则修补到编译器级设计思维

成熟方案需摒弃“文本即最终形态”的思维，转向编译器三级流水线：

graph LR
A[Source Text] --> B[Lexer: Token Stream with Comments]
B --> C[Parser: AST with Comment Attachments]
C --> D[Formatter: Context-Aware Rewrite + Positional Comments]
D --> E[Formatted Text preserving offsets & casing]

七、典型反模式与修复对照表

以下为5年+开发者高频踩坑及对应解法：

反模式	后果	修复方案
预处理阶段用replace(/--.*$/gm, '')清除注释	删除字符串内--、破坏嵌套SQL注释	仅在Lexer状态机中识别，绝不文本替换
格式化器对所有Keyword统一.toUpperCase()	将select变SELECT，破坏历史脚本兼容性	引入casingPolicy: 'preserve'配置，按AST节点类型路由大小写处理器

八、扩展性考量：注释驱动的元编程能力

高级格式化工具可将注释升格为指令源。例如识别/* format: no-wrap */禁用某子句换行，或-- @formatter: off / -- @formatter: on划定格式化豁免区。这要求Lexer能提取注释中的结构化指令（如正则/@formatter:\s*(on|off)/），并在Formatter中维护一个“格式化开关栈”。该能力使SQL格式化从静态美化升级为协作契约载体。

九、性能权衡：增量解析与注释缓存策略

对于大型SQL文件（>10MB），全量重解析成本高昂。可行优化包括：
① 基于AST节点range字段做差异定位，仅重解析编辑区域附近Token；
② 对Comment Token建立LRU缓存，因其内容永不变更；
③ 将注释位置信息序列化为稀疏索引（如每1000字符记录最近3个注释偏移），加速光标悬停时的注释查找。

十、行业前沿：SQL方言兼容与注释语义增强

PostgreSQL支持-- single-line、/* block */、$tag$...$tag$美元引用字符串（内可含任意内容，含注释）；T-SQL有--和/* */但不支持内联注释。格式化工具必须通过dialect: 'postgresql'参数切换Lexer状态机分支。更进一步，可对接VS Code语言服务器协议（LSP），将TODO、FIXME注释自动转为诊断（Diagnostic），实现“注释即任务”的开发闭环。

```