90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# SQLFluff AL06 生效修复 — 设计 Spec
|
||
|
||
日期：2026-08-08
|
||
状态：待审批
|
||
关联流程：① 用户提出 → ② 需求澄清 → ③ 方案设计
|
||
|
||
## 1. 背景与根因
|
||
|
||
用户反馈 SQLFluff 的 AL06（`aliasing.length`，强制表别名长度）未生效。
|
||
|
||
经代码调研 + 官方文档核实 + 本机 sqlfluff 4.2.2 实测，根因为：
|
||
|
||
1. 内置规则集 `rules = core,AM03,...`（`src/rules/builtin-rules.ts:94`）中的 `core` 组已包含 AL06。
|
||
- 佐证：static-rules.json 中 32 条 P0 规则与 SQLFluff 官方 core 组完全一致，AL06 在其中。
|
||
2. AL06 默认参数 `min_alias_length = None`、`max_alias_length = None`（官方默认配置），无限制时永不产生 violation，
|
||
表现为"未生效"。
|
||
3. 实测：`SELECT a FROM orders AS this_is_a_very_long_table_alias_x;` 在 `--rules core` 下仅报 AL05，无 AL06。
|
||
|
||
### 结论
|
||
|
||
AL06 不是"未启用"，而是"已启用但缺少长度参数"。修复方向是为内置 SQLFluff 配置补充
|
||
`[sqlfluff:rules:aliasing.length]` 参数段，而非向 `BUILTIN_SQLFLUFF_RULES` 添加 AL06。
|
||
|
||
## 2. 共识（Stage ② 确认）
|
||
|
||
- 场景：插件默认内置配置（无全局 configFile、无项目 .sqlfluff）下。
|
||
- 阈值：`max_alias_length = 30`（与 Oracle 标识符 30 字符上限对齐，本项目 sql/plsql 方言兜底为 oracle）；不设 `min_alias_length`。
|
||
- 范围：不做其它 AL 规则调整；不改 `BUILTIN_SQLFLUFF_RULES` 字符串（避免 i18n 计数文案连锁变更）。
|
||
|
||
## 3. 方案
|
||
|
||
### 3.1 架构概览
|
||
|
||
无需架构调整。改动局限于 `src/rules/builtin-rules.ts` 中两个配置生成函数，使生成的
|
||
配置文件同时携带 `[sqlfluff] rules` 与 `[sqlfluff:rules:aliasing.length] max_alias_length = 30`。
|
||
|
||
数据流不变：
|
||
|
||
```
|
||
SqlFluffAdapter.check()
|
||
└─ 无全局/项目配置时
|
||
└─ buildBuiltinSqlfluffConfig(dialect) ──写临时文件──> sqlfluff lint --config ...
|
||
```
|
||
|
||
### 3.2 文件变更清单
|
||
|
||
| 文件 | 变更 | 说明 |
|
||
|------|------|------|
|
||
| `src/rules/builtin-rules.ts` | 修改 | `buildBuiltinSqlfluffConfig()` 输出追加参数段 |
|
||
| `src/rules/builtin-rules.ts` | 修改 | `buildSqlfluffProjectConfigText()` 输出同步追加参数段（设置面板生成的项目 .sqlfluff 模板与内置保持一致） |
|
||
|
||
无新建、无删除。
|
||
|
||
### 3.3 关键接口
|
||
|
||
两函数签名不变：
|
||
|
||
```ts
|
||
export function buildBuiltinSqlfluffConfig(dialect: string): string
|
||
export function buildSqlfluffProjectConfigText(dialect: string, lang: Language): string
|
||
```
|
||
|
||
新增配置段内容（两处一致）：
|
||
|
||
```ini
|
||
[sqlfluff:rules:aliasing.length]
|
||
max_alias_length = 30
|
||
```
|
||
|
||
### 3.4 配置优先级影响
|
||
|
||
- 全局 `sqlfluff.configFile` / 项目 `.sqlfluff` 存在时仍优先（`sqlfluff.ts:141-149`），本次改动不影响这两条路径。
|
||
- 仅内置兜底配置获得 AL06 长度限制，行为符合"与插件内置规则一致"的产品语义。
|
||
|
||
### 3.5 验证方式
|
||
|
||
1. `npm test`（lint → compile → test）。
|
||
2. 手工端到端：`sqlfluff lint --rules core --config <生成配置>` 对超长别名 SQL 应报 AL06；现有 4.2.2 实测基线已确认改前不报。
|
||
3. 可选：新增单测断言 `buildBuiltinSqlfluffConfig` 输出包含 `max_alias_length = 30`。
|
||
|
||
## 4. 影响范围
|
||
|
||
- 仅影响未配置任何外部 SQLFluff 配置的默认路径。
|
||
- 不触发 i18n 文案、static-rules.json、package.json 变更。
|
||
- 诊断严重度：AL06 tier 为 P0 → 保持 error（`tierToSeverity`，sqlfluff.ts:38）。
|
||
|
||
## 5. 风险
|
||
|
||
- SQLFluff 低版本（< 4.x）对 `[sqlfluff:rules:aliasing.length]` 段名兼容性：暂无低版本支持承诺，目标版本 4.2.2+，风险低。
|
||
- 长别名在 Oracle 中本就受限（30 字符），阈值不会产生误报。 |