SQL Formatter 处理 sqlc 宏的解决方案

在 Go 语言开发中使用 sqlc 工具时，开发者经常会遇到 SQL 格式化工具与 sqlc 宏语法冲突的问题。本文将深入分析这一问题的成因，并提供专业级的解决方案。

问题背景

sqlc 是一个流行的 SQL 查询代码生成工具，它允许开发者在 SQL 文件中使用特殊宏语法。这些宏看起来像 SQL 函数，但实际上是 sqlc 特有的语法结构，会在代码生成阶段被转换为标准 SQL。

典型的 sqlc 宏示例如下：

SELECT sqlc.embed(students), sqlc.embed(test_scores)
FROM students
JOIN test_scores ON test_scores.student_id = students.id

这个宏会被 sqlc 转换为：

SELECT students.*, test_scores.*
FROM students
JOIN test_scores ON test_scores.student_id = students.id

格式化冲突问题

当使用 SQL 格式化工具（如 SQL Formatter）处理包含 sqlc 宏的 SQL 文件时，格式化工具会按照标准 SQL 函数调用的规则进行处理，自动在函数名和括号之间添加空格：

-- 格式化前
sqlc.embed(students)

-- 格式化后
sqlc.embed (students)

这种格式化虽然符合标准 SQL 的规范，但却破坏了 sqlc 宏的语法结构，导致 sqlc 无法正确解析这些宏。

解决方案

SQL Formatter 提供了灵活的配置选项来解决这类特殊语法问题。我们可以通过配置 paramTypes 选项，将 sqlc 宏识别为特殊参数类型，从而避免格式化工具对其进行不必要的修改。

配置方法

在 VSCode 的 SQL Formatter 扩展设置中，添加以下配置：

{
  "custom": [
    { "regex": "sqlc\\.\\w+\\(.*?\\)" }
  ]
}

这个正则表达式会匹配所有以 sqlc. 开头，后跟单词字符和括号的语法结构，将其识别为特殊格式，从而保持原样不进行格式化。

技术原理

这种解决方案的核心在于利用了 SQL Formatter 的参数类型识别机制：

1. paramTypes 配置允许开发者定义自定义参数模式
2. 使用正则表达式可以精确匹配特定的语法结构
3. 匹配到的内容会被视为整体，不会被内部格式化

这种方法不仅适用于 sqlc 宏，也可以推广到其他类似的 SQL 预处理语法或特殊语法结构。

最佳实践

对于使用 sqlc 的项目，建议：

1. 将上述配置加入项目级的 VSCode 设置
2. 在团队开发环境中统一配置，确保代码风格一致
3. 定期检查 sqlc 宏的语法变化，必要时调整正则表达式

通过这种配置，开发者可以同时享受 SQL 格式化带来的代码整洁性，又不会影响 sqlc 宏的正常工作，实现两全其美的开发体验。