SQLFluff 规则参考Rules Reference完全指南Core 核心规则、规则分组与索引体系【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff本文以 SQLFluff 官方文档中的 Rules Reference 页面 为主体系统讲解 SQLFluff 内置规则的组织方式什么是core核心规则组、其入选标准是什么、规则如何按 bundle规则包分组并以代码/名称/别名/分组四种方式被引用以及规则索引表格与摘要文档是如何自动生成的。读完本文你将能够准确理解 SQLFluff 的规则体系结构并学会用rules、exclude_rules、warnings等配置项为自己的项目定制一套精确、可维护的规则集。规则参考页面在文档体系中的定位SQLFluff 官方文档中的 Rules Reference 页面即本仓库的 docs/source/reference/rules.rst是所有随 SQLFluff 内置规则的总索引。它本身不是一份逐条讲解每条规则的教程而是一个目录 定义 导航三位一体的参考页定义了core规则组的概念与入选标准通过自动生成的规则索引表格rule table汇总全部规则的 bundle、名称、代码与是否为核心规则通过自动生成的规则摘要rule summaries列出每条规则的完整说明与配置项将使用者导航到三个更细粒度的配置文档规则选择ruleselection、按文件忽略规则ignoreconfig、以及已启用规则的参数配置ruleconfig。对应到仓库中这三篇被引用文档分别是docs/source/configuration/rule_configuration.rst含_ruleselection与_ruleconfig锚点docs/source/configuration/ignoring_configuration.rstignoreconfigdocs/source/configuration/setting_configuration.rst配置文件的整体加载机制。也就是说Rules Reference 页是理解 SQLFluff 规则体系的入口先弄清规则如何分类与命名再学会如何选择和配置它们。Core 规则核心规则组的定义与入选标准规则参考页中第一个实质性内容就是core规则组。SQLFluff 把一部分规则标记为core并非因为它们更重要或更高频而是因为它们足够中性和安全。根据规则参考页一条规则要被认定为core必须同时满足以下四项标准Stable稳定规则行为成熟、不会频繁变动Applies to most dialects适用于大多数方言不是某个特定数据库方言专有的规则Could detect a syntax issue能够发现语法层面问题具备抓错误的价值而不只是风格偏好Isnt too opinionated toward one style不过度偏向某一种风格例如不会强制推行 dbt 风格指南中的特定偏好。为什么需要 Core 规则组从源码与文档看设计core组的核心动机是降低团队落地 SQLFluff 的门槛。文档明确说明只启用 core 子集团队就不必一开始就花时间理解并配置全部规则——因为其中一些规则你的团队未必认同。这样可以通过先遵守一套常识性子集的方式快速铺开之后再逐步探索其余规则最终定制出最适合自己组织的规则集合。从源码确认 Core 规则的实现Core 属性在源码层面体现为每条规则类上的groups元组。以本仓库为例确认属于(all, core, ...)的规则包括括号内为所属 bundlealiasingAL02、AL03、AL05、AL06、AL09、AL10capitalisationCP05conventionCV03、CV04、CV05jinjaJJ01layoutLT01、LT02、LT05–LT08、LT10、LT11、LT12referencesRF01structureST03以上仅为从源码中确认的部分示例完整清单以规则索引表格中 Core Rule 列为准表格由脚本自动生成见下文。注意源码中的一条细节规则可以继承groups。在 src/sqlfluff/core/rules/base.py 中规则初始化时会检查类字典中是否显式定义了groups若未定义则继承其基类的groups注释特别提到 CP02 就因此继承了 CP01 的所有分组。因此某条规则是否属于 core要以最终生成的文档表格为准而不是仅看某一处代码。启用 Core 规则通过 docs/source/configuration/rule_configuration.rst 中定义的规则选择机制在配置中把rules设为core即可只启用这组常识性规则[sqlfluff] rules core规则索引Bundle、名称、代码与 Core 标记规则参考页的第二大块内容是通过.. include::指令嵌入的两个自动生成文件——rule_table.rst规则索引表与rule_summaries.rst规则摘要。它们并非手写而是由文档构建脚本 docs/generate-auto-docs.py 在每次生成文档前自动产出。自动生成机制docs/generate-auto-docs.py 的核心逻辑是通过 SQLFluff 的插件管理器get_plugin_manager().hook.get_rules()收集全部已注册规则然后以rule.name.split(.)[0]提取每条规则的bundle 名并按 bundle 归类defaultdict(list)将(rule.code, rule.name)列表写入docs/source/_partials/rule_list.json供文档跳转重定向使用生成规则索引表格rule_table.rst列为Bundle | Rule Name | Code | Core Rule其中核心规则在 Core Rule 列标记✓判定逻辑是core in getattr(rule, groups, ())逐 bundle 生成rule_summaries.rst为每条规则渲染.. sqlfluff:rule:: code name指令并从规则类 docstring 中提取标题与正文rule.__doc__.partition(\n)。bundle 的标题命名规则是名字中含sql的如tsql整体大写为TSQL bundle其余则首字母大写如Aliasing bundle。所有 bundle 按字母序排序输出。规则代码与名称的格式约定要读懂规则索引表需要先理解 SQLFluff 的规则命名体系这在 src/sqlfluff/core/rules/base.py 的RuleMetaclass中有严格约束每条规则是一个以Rule_XXXX命名的类XXXX的格式为LLNN两个字母 两位数字例如Rule_LT01同时向后兼容旧格式LNNN单字母 三位数字如历史上著名的L003类名中的两个字母指示规则所属主题例如CP代表CaPitalisation大小写类规则规则名必须是形如[a-z][a-z\.\_]的小写点分格式例如layout.spacingLT01、capitalisation.keywordsCP01 配置名。因此规则索引表中你会同时看到两类标识Code代码如LT01、CP01是规则的稳定标识符Name名称如layout.spacing是规则的人类可读名称。此外规则还可以定义aliases别名通常用于承载已废弃的旧代码。例如 LT01 的注释就说明它合并了历史规则 L001行尾空白、L005/L008逗号周围空格、L006运算符周围空格、L023WITH 子句中 AS 后空格、L024USING 后空格、L039多余空白——这些旧代码正是通过 alias 机制继续被兼容的。规则的分组bundle全景从规则索引表的结构看SQLFluff 内置规则按 bundle 组织每个 bundle 对应 src/sqlfluff/rules 下的一个子目录Bundle对应源码目录主题aliasingsrc/sqlfluff/rules/aliasing表/列别名相关ambiguoussrc/sqlfluff/rules/ambiguous有歧义写法如 JOIN、列引用capitalisationsrc/sqlfluff/rules/capitalisation关键字/标识符/函数/字面量/类型大小写conventionsrc/sqlfluff/rules/convention约定俗成风格如不等于写法、尾部逗号jinjasrc/sqlfluff/rules/jinja模板代码相关layoutsrc/sqlfluff/rules/layout缩进、空格、换行、行长oraclesrc/sqlfluff/rules/oracleOracle 方言专有postgressrc/sqlfluff/rules/postgresPostgreSQL 专有referencessrc/sqlfluff/rules/references对象引用、限定与引用一致性structuresrc/sqlfluff/rules/structure语句结构子查询、列顺序等tsqlsrc/sqlfluff/rules/tsqlT-SQL 专有这也解释了 Core 规则的适用于大多数方言标准像oracle、postgres、tsql这类方言专有 bundle 中的规则天然不满足该条件因此通常不会被标为 core。规则摘要中的附加信息force_enable 与默认配置规则摘要rule_summaries.rst不仅包含每条规则的反例/正例说明还包含该规则支持的配置项、别名与分组这些信息由 base.py 的元类在初始化时自动写入 docstring再由 Sphinx 渲染。其中有几类重要信息值得专门说明需要 force_enable 才能启用的规则部分规则因过于偏执或与某些方言的默认行为冲突默认处于禁用状态必须显式设置force_enable True才能启用。从 src/sqlfluff/core/default_config.cfg 中可以确认这些规则包括[sqlfluff:rules:aliasing.forbid] # 禁止表别名默认关闭 force_enable False [sqlfluff:rules:convention.quoted_literals] # 引号风格统一Postgres 等方言不支持双引号字符串默认关闭 force_enable False [sqlfluff:rules:convention.last_select_star] # CTE 最终 SELECT 应为 SELECT * 透传dbt 风格默认关闭 force_enable False [sqlfluff:rules:postgres.excessive_locks] # 避免过重锁的 PostgreSQL DDL force_enable False [sqlfluff:rules:postgres.not_valid_foreign_key] # 外键先 NOT VALID 再校验 force_enable False [sqlfluff:rules:tsql.prefer_as_alias] # T-SQL 中偏好 ANSI 风格 AS 别名 force_enable False [sqlfluff:rules:references.from] # 引用必须出现在 FROM 中BigQuery 等方言默认关闭 force_enable False [sqlfluff:rules:references.consistent] # 引用必须一致使用 force_enable False [sqlfluff:rules:references.window_alias] # 窗口子句引用遮蔽 select 别名 force_enable False文档 docs/source/configuration/rule_configuration.rst 对force_enable的说明是它允许你在默认禁用该规则的方言下也启用它。由于这些规则不属于 core且默认关闭是否启用完全是团队自己的风格决策。每条规则的默认配置都可在规则参考中找到规则参考页声明所有规则配置段的可选值都记录在 Rules Reference 中。对应地默认配置全文集中在 src/sqlfluff/core/default_config.cfg 的[sqlfluff:rules:*]段例如[sqlfluff:rules:capitalisation.keywords] # Keywords capitalisation_policy consistent # Comma separated list of words to ignore for this rule ignore_words None ignore_words_regex None [sqlfluff:rules:ambiguous.join] # Fully qualify JOIN clause fully_qualify_join_types inner [sqlfluff:rules:aliasing.table] # Aliasing preference for tables aliasing explicit [sqlfluff:rules:convention.select_trailing_comma] # Trailing commas select_clause_trailing_comma forbid [sqlfluff:rules:structure.subquery] # By default, allow subqueries in from clauses, but not join clauses forbid_subquery_in join值得注意的一点是默认的capitalisation_policy consistent是自动探测模式从文件其余部分推断风格规则参考页与 starter_config.cfg 都指出新项目往往更适合直接指定upper或lower。规则选择机制四种引用类型与配置继承规则参考页将如何配置启用哪些规则指向ruleselection一节即 docs/source/configuration/rule_configuration.rst 的 Enabling and Disabling Rules。这是与规则索引直接配套的实战知识下面完整展开。两个核心配置参数规则的选择按文件生效取决于该文件的有效配置由两个参数共同决定rules显式启用指定规则。如果该参数未设置或为空含义是未做选择则视同启用全部规则默认配置rules all也印证了这一点exclude_rules显式禁用指定规则。它在rules之后应用用于从已启用集合中减去部分规则。四种可混用的引用类型两个参数都接受逗号分隔的引用列表每个引用可以是以下任意一种且可以在同一条表达式里混用引用类型示例说明规则代码codeLT01稳定标识符规则名称namelayout.indent人类可读名称规则别名aliasL003通常是已废弃的旧代码规则分组grouplayout、capitalisation一次选择整个 bundle或core从源码层面看这种混用能力源于 src/sqlfluff/core/rules/base.py 的rule_reference_map()它构建了一张引用 → 规则代码集合的映射表并规定了冲突时的优先级——codes names groups aliases即如果某个名称恰好与代码撞名优先按代码解释。同时_expand_rule_references()base.py还支持glob 通配符匹配即rules LT*这类写法也是合法的进一步增强了选择表达力。最终在get_rulepack()base.py中allowlist 与 denylist 分别由rule_allowlist与rule_denylist解析得出allowlist 未设置时默认是全部合法代码denylist 默认为空——这与未设置 rules 即启用全部规则的文档描述完全一致。配置继承的两条硬规则与两种推荐做法文档特别强调在多层级配置文件嵌套的项目中rules与exclude_rules的组合很容易让人困惑因为子配置文件一旦设置了rules或exclude_rules会整体覆盖父配置中的同名参数不存在合并操作两者的相减运算虽然按文件逐一计算但两次对rules的定义之间没有任何组合关系——后定义的直接覆盖先定义的。为此文档给出两种推荐做法只用rules项目每个区域都显式列出启用规则改动时整体重置该区域的规则列表语义最清晰在根配置只设一份rules子配置只用exclude_rules做减法保持唯一被继承的值的简单性同时按例外管理的方式逐步推进新规则。配置示例禁用两条规则[sqlfluff] exclude_rules LT08, RF02启用单条规则[sqlfluff] rules RF02只启用核心规则[sqlfluff] rules core按分组混合选择例如启用全部 layout 规则但排除其中一条[sqlfluff] rules layout exclude_rules LT08将规则降级为 Warning渐进式推广规则参考页关联的规则配置文档还提供了一种软性引入规则的机制把规则降级为警告warnings。被设为 warning 的规则仍然会被显示但不会导致文件检查失败。这在向已有项目渐进式推广新规则时非常有用——先让团队看见问题而不阻塞工作流。[sqlfluff] warnings LT01, LT04其效果在文档中给出了直观示例只有 warning 级别问题的文件显示PASS而同时存在真实违规的文件仍然FAIL但输出中会同时展示失败项与警告项 [test.sql] PASS L: 2 | P: 9 | LT01 | WARNING: Missing whitespace before [test2.sql] FAIL L: 2 | P: 8 | CP02 | Unquoted identifiers must be consistently upper case. L: 2 | P: 11 | LT01 | WARNING: Missing whitespace before warnings配置同样接受规则代码或规则名称其行为与exclude_rules非常类似。新项目起步从最小配置开始规则参考页与默认配置文档都反复强调一个原则配置文件应该精简并作为团队决策的记录。与其复制整份默认配置不如只写下与默认值不同的决策。仓库中提供的 docs/source/_partials/starter_config.cfg 正是这样一个最小起步模板其中与规则相关的要点包括[sqlfluff] # 方言与模板 dialect snowflake templater jinja # 排除两条争议性规则作为示例展示用法 exclude_rules ambiguous.column_count, structure.column_order # 行宽 max_line_length 120 # 多进程 processes -1 [sqlfluff:indentation] implicit_indents allow # 别名最小长度 [sqlfluff:rules:aliasing.length] min_alias_length 3 # 新项目更推荐直接指定大小写策略而非 consistent自动探测 [sqlfluff:rules:capitalisation.keywords] capitalisation_policy lower [sqlfluff:rules:capitalisation.identifiers] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.functions] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.literals] capitalisation_policy lower [sqlfluff:rules:capitalisation.types] extended_capitalisation_policy lower # 不等于写法显式偏好 C 风格! [sqlfluff:rules:convention.not_equal] preferred_not_equal_style c_style模板中的注释很好地说明了设计意图默认的consistent策略更适合存量代码库自动探测既有风格而新项目往往希望一步到位地锁定风格max_line_length 120则是对默认 80 字符与 dbt 风格指南一致的常见偏长行宽调整。完整的默认配置即规则参考中所有规则配置段的取值来源见 src/sqlfluff/core/default_config.cfg 的[sqlfluff:rules]与[sqlfluff:rules:*]各段其中还包含[sqlfluff:rules]公共段[sqlfluff:rules] allow_scalar True single_table_references consistent unquoted_identifiers_policy all规则配置的三种载体规则参考页关联的 docs/source/configuration/setting_configuration.rst 明确了规则及其他所有配置的三种载体1. 配置文件SQLFluff 按顺序查找以下文件后找到的文件覆盖先前的值setup.cfgtox.inipep8.ini.sqlfluffpyproject.toml前四种按 cfg 语法读取[sqlfluff:...]段pyproject.toml则使用[tool.sqlfluff...]点分语法。规则配置在两种语法中的写法分别如下# .sqlfluff [sqlfluff:rules:capitalisation.keywords] capitalisation_policy upper# pyproject.toml [tool.sqlfluff.rules.capitalisation.keywords] capitalisation_policy upper配置文件采用嵌套nesting机制从用户系统级配置目录、用户主目录、当前工作目录逐级向下到被检查文件所在目录层级越近的文件覆盖越远的值唯一的例外是templater值不能在子目录配置中修改。2. 文件内配置指令对仅适用于单个文件的配置SQLFluff 支持以行内注释形式书写-- sqlfluff:指令-- Set Indented Joins -- sqlfluff:indentation:indented_joins:True -- Set a smaller indent for this file -- sqlfluff:indentation:tab_space_size:2 -- Set keywords to be capitalised -- sqlfluff:rules:capitalisation.keywords:capitalisation_policy:upper SELECT * FROM a JOIN b USING(c)注意这些指令作用于整个文件且会在正式解析前被读取因此既能改规则配置也能改解析相关配置。文档建议仅将其用于孤立的单文件场景项目级或目录级配置仍应使用配置文件嵌套。3. 命令行CLI 参数与配置文件大体对等模板相关配置除外具体可参考 docs/source/reference/cli.rst。从源码看规则的参考-选择-执行闭环最后把规则参考页与源码串起来可以看到 SQLFluff 规则体系的完整闭环定义每条规则以Rule_LLNN类实现声明name、groups、aliases、force_enable等元数据示例见 src/sqlfluff/rules/layout/LT01.py、src/sqlfluff/rules/capitalisation/CP01.py注册与文档化RuleMetaclassbase.py校验类名格式、自动把名称/别名/分组/配置项写入 docstringdocs/generate-auto-docs.py 在文档构建时据此生成规则索引表与摘要也就是规则参考页的主体选择get_rulepack()base.py读取rules/exclude_rules配置借助rule_reference_map()codes names groups aliases 优先级把引用展开为具体规则代码集合再据此实例化规则执行规则按各自声明的 crawler爬取策略遍历解析树产出LintResult可修复的规则如is_fix_compatible还能被sqlfluff fix自动应用。总结SQLFluff 的 Rules Reference 页面并非简单罗列规则清单而是整个规则体系的总纲它定义了core核心规则组的四项入选标准稳定、跨方言、能发现语法问题、不过度偏向单一风格展示了规则如何以 bundle 为单位组织、以LLNN代码与点分名称双重标识并通过自动生成脚本保持索引与源码的同步。结合规则选择机制rules/exclude_rules四种引用类型与覆盖语义、警告降级、force_enable以及三种配置载体你可以为自己的项目精确裁剪出一套既符合团队风格、又可持续维护的规则集。建议下一步先以rules core起步再对照规则索引表格逐 bundle 评估是否需要启用更严格的规则。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SQLFluff 规则参考（Rules Reference）完全指南：Core 核心规则、规则分组与索引体系
SQLFluff 规则参考Rules Reference完全指南Core 核心规则、规则分组与索引体系【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff本文以 SQLFluff 官方文档中的 Rules Reference 页面 为主体系统讲解 SQLFluff 内置规则的组织方式什么是core核心规则组、其入选标准是什么、规则如何按 bundle规则包分组并以代码/名称/别名/分组四种方式被引用以及规则索引表格与摘要文档是如何自动生成的。读完本文你将能够准确理解 SQLFluff 的规则体系结构并学会用rules、exclude_rules、warnings等配置项为自己的项目定制一套精确、可维护的规则集。规则参考页面在文档体系中的定位SQLFluff 官方文档中的 Rules Reference 页面即本仓库的 docs/source/reference/rules.rst是所有随 SQLFluff 内置规则的总索引。它本身不是一份逐条讲解每条规则的教程而是一个目录 定义 导航三位一体的参考页定义了core规则组的概念与入选标准通过自动生成的规则索引表格rule table汇总全部规则的 bundle、名称、代码与是否为核心规则通过自动生成的规则摘要rule summaries列出每条规则的完整说明与配置项将使用者导航到三个更细粒度的配置文档规则选择ruleselection、按文件忽略规则ignoreconfig、以及已启用规则的参数配置ruleconfig。对应到仓库中这三篇被引用文档分别是docs/source/configuration/rule_configuration.rst含_ruleselection与_ruleconfig锚点docs/source/configuration/ignoring_configuration.rstignoreconfigdocs/source/configuration/setting_configuration.rst配置文件的整体加载机制。也就是说Rules Reference 页是理解 SQLFluff 规则体系的入口先弄清规则如何分类与命名再学会如何选择和配置它们。Core 规则核心规则组的定义与入选标准规则参考页中第一个实质性内容就是core规则组。SQLFluff 把一部分规则标记为core并非因为它们更重要或更高频而是因为它们足够中性和安全。根据规则参考页一条规则要被认定为core必须同时满足以下四项标准Stable稳定规则行为成熟、不会频繁变动Applies to most dialects适用于大多数方言不是某个特定数据库方言专有的规则Could detect a syntax issue能够发现语法层面问题具备抓错误的价值而不只是风格偏好Isnt too opinionated toward one style不过度偏向某一种风格例如不会强制推行 dbt 风格指南中的特定偏好。为什么需要 Core 规则组从源码与文档看设计core组的核心动机是降低团队落地 SQLFluff 的门槛。文档明确说明只启用 core 子集团队就不必一开始就花时间理解并配置全部规则——因为其中一些规则你的团队未必认同。这样可以通过先遵守一套常识性子集的方式快速铺开之后再逐步探索其余规则最终定制出最适合自己组织的规则集合。从源码确认 Core 规则的实现Core 属性在源码层面体现为每条规则类上的groups元组。以本仓库为例确认属于(all, core, ...)的规则包括括号内为所属 bundlealiasingAL02、AL03、AL05、AL06、AL09、AL10capitalisationCP05conventionCV03、CV04、CV05jinjaJJ01layoutLT01、LT02、LT05–LT08、LT10、LT11、LT12referencesRF01structureST03以上仅为从源码中确认的部分示例完整清单以规则索引表格中 Core Rule 列为准表格由脚本自动生成见下文。注意源码中的一条细节规则可以继承groups。在 src/sqlfluff/core/rules/base.py 中规则初始化时会检查类字典中是否显式定义了groups若未定义则继承其基类的groups注释特别提到 CP02 就因此继承了 CP01 的所有分组。因此某条规则是否属于 core要以最终生成的文档表格为准而不是仅看某一处代码。启用 Core 规则通过 docs/source/configuration/rule_configuration.rst 中定义的规则选择机制在配置中把rules设为core即可只启用这组常识性规则[sqlfluff] rules core规则索引Bundle、名称、代码与 Core 标记规则参考页的第二大块内容是通过.. include::指令嵌入的两个自动生成文件——rule_table.rst规则索引表与rule_summaries.rst规则摘要。它们并非手写而是由文档构建脚本 docs/generate-auto-docs.py 在每次生成文档前自动产出。自动生成机制docs/generate-auto-docs.py 的核心逻辑是通过 SQLFluff 的插件管理器get_plugin_manager().hook.get_rules()收集全部已注册规则然后以rule.name.split(.)[0]提取每条规则的bundle 名并按 bundle 归类defaultdict(list)将(rule.code, rule.name)列表写入docs/source/_partials/rule_list.json供文档跳转重定向使用生成规则索引表格rule_table.rst列为Bundle | Rule Name | Code | Core Rule其中核心规则在 Core Rule 列标记✓判定逻辑是core in getattr(rule, groups, ())逐 bundle 生成rule_summaries.rst为每条规则渲染.. sqlfluff:rule:: code name指令并从规则类 docstring 中提取标题与正文rule.__doc__.partition(\n)。bundle 的标题命名规则是名字中含sql的如tsql整体大写为TSQL bundle其余则首字母大写如Aliasing bundle。所有 bundle 按字母序排序输出。规则代码与名称的格式约定要读懂规则索引表需要先理解 SQLFluff 的规则命名体系这在 src/sqlfluff/core/rules/base.py 的RuleMetaclass中有严格约束每条规则是一个以Rule_XXXX命名的类XXXX的格式为LLNN两个字母 两位数字例如Rule_LT01同时向后兼容旧格式LNNN单字母 三位数字如历史上著名的L003类名中的两个字母指示规则所属主题例如CP代表CaPitalisation大小写类规则规则名必须是形如[a-z][a-z\.\_]的小写点分格式例如layout.spacingLT01、capitalisation.keywordsCP01 配置名。因此规则索引表中你会同时看到两类标识Code代码如LT01、CP01是规则的稳定标识符Name名称如layout.spacing是规则的人类可读名称。此外规则还可以定义aliases别名通常用于承载已废弃的旧代码。例如 LT01 的注释就说明它合并了历史规则 L001行尾空白、L005/L008逗号周围空格、L006运算符周围空格、L023WITH 子句中 AS 后空格、L024USING 后空格、L039多余空白——这些旧代码正是通过 alias 机制继续被兼容的。规则的分组bundle全景从规则索引表的结构看SQLFluff 内置规则按 bundle 组织每个 bundle 对应 src/sqlfluff/rules 下的一个子目录Bundle对应源码目录主题aliasingsrc/sqlfluff/rules/aliasing表/列别名相关ambiguoussrc/sqlfluff/rules/ambiguous有歧义写法如 JOIN、列引用capitalisationsrc/sqlfluff/rules/capitalisation关键字/标识符/函数/字面量/类型大小写conventionsrc/sqlfluff/rules/convention约定俗成风格如不等于写法、尾部逗号jinjasrc/sqlfluff/rules/jinja模板代码相关layoutsrc/sqlfluff/rules/layout缩进、空格、换行、行长oraclesrc/sqlfluff/rules/oracleOracle 方言专有postgressrc/sqlfluff/rules/postgresPostgreSQL 专有referencessrc/sqlfluff/rules/references对象引用、限定与引用一致性structuresrc/sqlfluff/rules/structure语句结构子查询、列顺序等tsqlsrc/sqlfluff/rules/tsqlT-SQL 专有这也解释了 Core 规则的适用于大多数方言标准像oracle、postgres、tsql这类方言专有 bundle 中的规则天然不满足该条件因此通常不会被标为 core。规则摘要中的附加信息force_enable 与默认配置规则摘要rule_summaries.rst不仅包含每条规则的反例/正例说明还包含该规则支持的配置项、别名与分组这些信息由 base.py 的元类在初始化时自动写入 docstring再由 Sphinx 渲染。其中有几类重要信息值得专门说明需要 force_enable 才能启用的规则部分规则因过于偏执或与某些方言的默认行为冲突默认处于禁用状态必须显式设置force_enable True才能启用。从 src/sqlfluff/core/default_config.cfg 中可以确认这些规则包括[sqlfluff:rules:aliasing.forbid] # 禁止表别名默认关闭 force_enable False [sqlfluff:rules:convention.quoted_literals] # 引号风格统一Postgres 等方言不支持双引号字符串默认关闭 force_enable False [sqlfluff:rules:convention.last_select_star] # CTE 最终 SELECT 应为 SELECT * 透传dbt 风格默认关闭 force_enable False [sqlfluff:rules:postgres.excessive_locks] # 避免过重锁的 PostgreSQL DDL force_enable False [sqlfluff:rules:postgres.not_valid_foreign_key] # 外键先 NOT VALID 再校验 force_enable False [sqlfluff:rules:tsql.prefer_as_alias] # T-SQL 中偏好 ANSI 风格 AS 别名 force_enable False [sqlfluff:rules:references.from] # 引用必须出现在 FROM 中BigQuery 等方言默认关闭 force_enable False [sqlfluff:rules:references.consistent] # 引用必须一致使用 force_enable False [sqlfluff:rules:references.window_alias] # 窗口子句引用遮蔽 select 别名 force_enable False文档 docs/source/configuration/rule_configuration.rst 对force_enable的说明是它允许你在默认禁用该规则的方言下也启用它。由于这些规则不属于 core且默认关闭是否启用完全是团队自己的风格决策。每条规则的默认配置都可在规则参考中找到规则参考页声明所有规则配置段的可选值都记录在 Rules Reference 中。对应地默认配置全文集中在 src/sqlfluff/core/default_config.cfg 的[sqlfluff:rules:*]段例如[sqlfluff:rules:capitalisation.keywords] # Keywords capitalisation_policy consistent # Comma separated list of words to ignore for this rule ignore_words None ignore_words_regex None [sqlfluff:rules:ambiguous.join] # Fully qualify JOIN clause fully_qualify_join_types inner [sqlfluff:rules:aliasing.table] # Aliasing preference for tables aliasing explicit [sqlfluff:rules:convention.select_trailing_comma] # Trailing commas select_clause_trailing_comma forbid [sqlfluff:rules:structure.subquery] # By default, allow subqueries in from clauses, but not join clauses forbid_subquery_in join值得注意的一点是默认的capitalisation_policy consistent是自动探测模式从文件其余部分推断风格规则参考页与 starter_config.cfg 都指出新项目往往更适合直接指定upper或lower。规则选择机制四种引用类型与配置继承规则参考页将如何配置启用哪些规则指向ruleselection一节即 docs/source/configuration/rule_configuration.rst 的 Enabling and Disabling Rules。这是与规则索引直接配套的实战知识下面完整展开。两个核心配置参数规则的选择按文件生效取决于该文件的有效配置由两个参数共同决定rules显式启用指定规则。如果该参数未设置或为空含义是未做选择则视同启用全部规则默认配置rules all也印证了这一点exclude_rules显式禁用指定规则。它在rules之后应用用于从已启用集合中减去部分规则。四种可混用的引用类型两个参数都接受逗号分隔的引用列表每个引用可以是以下任意一种且可以在同一条表达式里混用引用类型示例说明规则代码codeLT01稳定标识符规则名称namelayout.indent人类可读名称规则别名aliasL003通常是已废弃的旧代码规则分组grouplayout、capitalisation一次选择整个 bundle或core从源码层面看这种混用能力源于 src/sqlfluff/core/rules/base.py 的rule_reference_map()它构建了一张引用 → 规则代码集合的映射表并规定了冲突时的优先级——codes names groups aliases即如果某个名称恰好与代码撞名优先按代码解释。同时_expand_rule_references()base.py还支持glob 通配符匹配即rules LT*这类写法也是合法的进一步增强了选择表达力。最终在get_rulepack()base.py中allowlist 与 denylist 分别由rule_allowlist与rule_denylist解析得出allowlist 未设置时默认是全部合法代码denylist 默认为空——这与未设置 rules 即启用全部规则的文档描述完全一致。配置继承的两条硬规则与两种推荐做法文档特别强调在多层级配置文件嵌套的项目中rules与exclude_rules的组合很容易让人困惑因为子配置文件一旦设置了rules或exclude_rules会整体覆盖父配置中的同名参数不存在合并操作两者的相减运算虽然按文件逐一计算但两次对rules的定义之间没有任何组合关系——后定义的直接覆盖先定义的。为此文档给出两种推荐做法只用rules项目每个区域都显式列出启用规则改动时整体重置该区域的规则列表语义最清晰在根配置只设一份rules子配置只用exclude_rules做减法保持唯一被继承的值的简单性同时按例外管理的方式逐步推进新规则。配置示例禁用两条规则[sqlfluff] exclude_rules LT08, RF02启用单条规则[sqlfluff] rules RF02只启用核心规则[sqlfluff] rules core按分组混合选择例如启用全部 layout 规则但排除其中一条[sqlfluff] rules layout exclude_rules LT08将规则降级为 Warning渐进式推广规则参考页关联的规则配置文档还提供了一种软性引入规则的机制把规则降级为警告warnings。被设为 warning 的规则仍然会被显示但不会导致文件检查失败。这在向已有项目渐进式推广新规则时非常有用——先让团队看见问题而不阻塞工作流。[sqlfluff] warnings LT01, LT04其效果在文档中给出了直观示例只有 warning 级别问题的文件显示PASS而同时存在真实违规的文件仍然FAIL但输出中会同时展示失败项与警告项 [test.sql] PASS L: 2 | P: 9 | LT01 | WARNING: Missing whitespace before [test2.sql] FAIL L: 2 | P: 8 | CP02 | Unquoted identifiers must be consistently upper case. L: 2 | P: 11 | LT01 | WARNING: Missing whitespace before warnings配置同样接受规则代码或规则名称其行为与exclude_rules非常类似。新项目起步从最小配置开始规则参考页与默认配置文档都反复强调一个原则配置文件应该精简并作为团队决策的记录。与其复制整份默认配置不如只写下与默认值不同的决策。仓库中提供的 docs/source/_partials/starter_config.cfg 正是这样一个最小起步模板其中与规则相关的要点包括[sqlfluff] # 方言与模板 dialect snowflake templater jinja # 排除两条争议性规则作为示例展示用法 exclude_rules ambiguous.column_count, structure.column_order # 行宽 max_line_length 120 # 多进程 processes -1 [sqlfluff:indentation] implicit_indents allow # 别名最小长度 [sqlfluff:rules:aliasing.length] min_alias_length 3 # 新项目更推荐直接指定大小写策略而非 consistent自动探测 [sqlfluff:rules:capitalisation.keywords] capitalisation_policy lower [sqlfluff:rules:capitalisation.identifiers] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.functions] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.literals] capitalisation_policy lower [sqlfluff:rules:capitalisation.types] extended_capitalisation_policy lower # 不等于写法显式偏好 C 风格! [sqlfluff:rules:convention.not_equal] preferred_not_equal_style c_style模板中的注释很好地说明了设计意图默认的consistent策略更适合存量代码库自动探测既有风格而新项目往往希望一步到位地锁定风格max_line_length 120则是对默认 80 字符与 dbt 风格指南一致的常见偏长行宽调整。完整的默认配置即规则参考中所有规则配置段的取值来源见 src/sqlfluff/core/default_config.cfg 的[sqlfluff:rules]与[sqlfluff:rules:*]各段其中还包含[sqlfluff:rules]公共段[sqlfluff:rules] allow_scalar True single_table_references consistent unquoted_identifiers_policy all规则配置的三种载体规则参考页关联的 docs/source/configuration/setting_configuration.rst 明确了规则及其他所有配置的三种载体1. 配置文件SQLFluff 按顺序查找以下文件后找到的文件覆盖先前的值setup.cfgtox.inipep8.ini.sqlfluffpyproject.toml前四种按 cfg 语法读取[sqlfluff:...]段pyproject.toml则使用[tool.sqlfluff...]点分语法。规则配置在两种语法中的写法分别如下# .sqlfluff [sqlfluff:rules:capitalisation.keywords] capitalisation_policy upper# pyproject.toml [tool.sqlfluff.rules.capitalisation.keywords] capitalisation_policy upper配置文件采用嵌套nesting机制从用户系统级配置目录、用户主目录、当前工作目录逐级向下到被检查文件所在目录层级越近的文件覆盖越远的值唯一的例外是templater值不能在子目录配置中修改。2. 文件内配置指令对仅适用于单个文件的配置SQLFluff 支持以行内注释形式书写-- sqlfluff:指令-- Set Indented Joins -- sqlfluff:indentation:indented_joins:True -- Set a smaller indent for this file -- sqlfluff:indentation:tab_space_size:2 -- Set keywords to be capitalised -- sqlfluff:rules:capitalisation.keywords:capitalisation_policy:upper SELECT * FROM a JOIN b USING(c)注意这些指令作用于整个文件且会在正式解析前被读取因此既能改规则配置也能改解析相关配置。文档建议仅将其用于孤立的单文件场景项目级或目录级配置仍应使用配置文件嵌套。3. 命令行CLI 参数与配置文件大体对等模板相关配置除外具体可参考 docs/source/reference/cli.rst。从源码看规则的参考-选择-执行闭环最后把规则参考页与源码串起来可以看到 SQLFluff 规则体系的完整闭环定义每条规则以Rule_LLNN类实现声明name、groups、aliases、force_enable等元数据示例见 src/sqlfluff/rules/layout/LT01.py、src/sqlfluff/rules/capitalisation/CP01.py注册与文档化RuleMetaclassbase.py校验类名格式、自动把名称/别名/分组/配置项写入 docstringdocs/generate-auto-docs.py 在文档构建时据此生成规则索引表与摘要也就是规则参考页的主体选择get_rulepack()base.py读取rules/exclude_rules配置借助rule_reference_map()codes names groups aliases 优先级把引用展开为具体规则代码集合再据此实例化规则执行规则按各自声明的 crawler爬取策略遍历解析树产出LintResult可修复的规则如is_fix_compatible还能被sqlfluff fix自动应用。总结SQLFluff 的 Rules Reference 页面并非简单罗列规则清单而是整个规则体系的总纲它定义了core核心规则组的四项入选标准稳定、跨方言、能发现语法问题、不过度偏向单一风格展示了规则如何以 bundle 为单位组织、以LLNN代码与点分名称双重标识并通过自动生成脚本保持索引与源码的同步。结合规则选择机制rules/exclude_rules四种引用类型与覆盖语义、警告降级、force_enable以及三种配置载体你可以为自己的项目精确裁剪出一套既符合团队风格、又可持续维护的规则集。建议下一步先以rules core起步再对照规则索引表格逐 bundle 评估是否需要启用更严格的规则。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
