Druid 内核重构实录SQL AST 继承层次一致性收敛与 Visitor 分发契约的兼容性改造【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid导读本文基于 Apache Druid阿里 Druid 数据库连接池/ SQL 解析内核开源仓库中的一份已归档变更提案完整拆解一次纯结构性、零行为变化的继承层次治理实践当SQLWithSubqueryClause.Entry等 AST 节点家族在父类与子类之间出现访问/分发契约不一致时如何以兼容优先的方式收敛父类契约、保持 visitor 遍历不变量并用聚焦回归 全量闸门验证改造无回归。读完本文你将掌握 Druid SQL AST 继承层次的 visitor 委托机制、此类重构的标准流程基线 → 收敛 → 回归 → 闸门以及等价输入产出等价遍历结果的验收方法。背景为什么需要治理继承层次Why近期 Druid SQL 解析器parser与访问器visitor的重构暴露出部分 SQL AST 继承层次在长期演进后的脆弱性相近的节点族node family在父类与子类之间没有共享一致的遍历契约traversal contract同类行为分散在多个子类分支中重复实现导致同类节点不同行为结构保持型重构behavior-preserving refactor因为缺少统一契约而难以验证回归成本升高。因此本次变更选择在 parser/visitor 相关代码路径仍处于活跃改进期时提前收敛继承层次以降低未来回归风险。相关提案、设计、任务与验证记录均归档于 openspec/changes/archive/2026-02-20-address-inheritance-hierarchy-issues/ 目录下其中proposal.md 定义变更范围与能力影响design.md 给出三大决策与风险权衡specs/sql-parser-core/spec.md 沉淀为可验收的需求条目verification-notes.md 记录基线、改造与闸门验证的完整证据链。变更范围与能力影响What Changes / Capabilities提案明确了本次变更的边界标准化选定 SQL AST 基类/派生类节点族的继承契约减少重复或分叉行为对齐这些继承分支上的 visitor 分发预期使等价节点遵循一致的遍历语义保持解析成功/失败行为与外部 SQL 输出兼容——这是一次兼容优先的结构清理新增围绕继承敏感遍历/分发路径的聚焦回归覆盖防止行为漂移不引入破坏性BREAKINGAPI 变更。从能力视角看本次变更不新增任何能力none而是收紧sql-parser-core的既有行为契约要求继承层次一致性、visitor/分发行为在结构重构过程中保持不丢失。受影响模块集中于core下的com.alibaba.druid.sql.ast与com.alibaba.druid.sql.visitor及其相关测试变更类型为 Refactoring maintainability enhancement无新增运行时依赖。三大核心决策Design Decisions决策 1兼容优先的父类契约收敛选择在父类或共享抽象层定义统一的默认行为入口并让目标子类显式复用该入口。理由可在最小改动范围内消除重复逻辑同时保留现有调用面。被否方案直接重写为全新层次结构——风险高、回归面过大本次不采用。这体现了小步收敛的工程取舍宁可保留部分历史不一致也不冒大规模重写的风险。决策 2访问分发行为保持不变量选择将可接受/可拒绝边界、token 推进、遍历顺序视为不变量invariant仅优化层次内部组织。理由下游测试与外部使用对这些行为存在隐式依赖。若在收敛时顺带修复局部行为差异会混入语义变更导致问题难以归因。决策 3聚焦回归 全量闸门验证选择先运行继承层次敏感测试再执行mvn -pl core test并记录性能/内存对比。理由兼顾迭代速度与发布级信心。仅跑全量测试反馈慢、定位成本高仅跑聚焦测试又不足以支撑发布决策。具体实现CTE Entry 的 visitor 委托收敛问题定位CTE 条目节点绕过 table-source 钩子通过继承层次盘点Task 1.1定位到的核心不一致点位于core中SQLWithSubqueryClause.java 的内部类Entry extends SQLTableSourceImpl implements SQLReplaceable——即 WITH 子句中的 CTE 条目如with cte as (select 1) ...中的cte as (...)在类型上是一个表源table source然而SQLASTVisitor中针对visit(SQLWithSubqueryClause.Entry)/endVisit(...)的默认方法没有委托给visitTableSource/endVisitTableSource。修复前的后果等价的SQLTableSourceImpl节点族在 visitor 钩子行为上不一致针对表源级别的通用钩子如visitTableSource会漏掉 CTE 条目节点。修复默认方法改为委托 table-source 钩子在 SQLASTVisitor.java 中两个默认方法被更新为委托模式// endVisit 委托Entry 结束访问时触发 endVisitTableSource default void endVisit(SQLWithSubqueryClause.Entry x) { // 委托至 endVisitTableSource(x) } // visit 委托Entry 开始访问时触发 visitTableSource default boolean visit(SQLWithSubqueryClause.Entry x) { return visitTableSource(x); }这样任何只覆写visitTableSource/endVisitTableSource的访问器例如输出 visitor、wall 安全检查、统计采集等都能统一拦截到 CTE 条目节点与其它SQLTableSourceImpl家族保持一致的遍历语义。整个修复不触碰解析器语法、不改变 token 推进顺序、不改变接受/拒绝边界。回归覆盖新增继承层次敏感测试为验证委托行为新增测试 SQLASTVisitorInheritanceHierarchyTest.javaSQLStatement stmt SQLUtils.parseSingleStatement( with cte as (select 1 as id) select * from cte, DbType.mysql );测试访问器同时覆写visit(SQLWithSubqueryClause.Entry)与visitTableSource/endVisitTableSource并断言三个计数全部为 1withEntryVisitBySpecificMethodCTE 条目确实通过专用方法visit(SQLWithSubqueryClause.Entry)被访问withEntryVisitByTableSourceHookCTE 条目同时触发了visitTableSource委托withEntryEndVisitByTableSourceHookCTE 条目结束访问时同样触发了endVisitTableSource委托。该测试恰好覆盖了修复前缺失的CTE-entry 委托缺口并锚定了专用方法 表源钩子双重触发的契约。验证过程与质量闸门Verification基线证据Task 1.2 / 1.3改造前先执行聚焦回归mvn -pl core -DtestSQLASTVisitorInterfaceOptimizationTest,SQLASTOutputVisitorSplitRefactorTest,SQLParserUtilsDialectDispatchTest,LateralViewTest,HiveSelectTest_2_lateralview,HiveSelectTest_distribute test结果13 个测试、0 失败确认既有套件可通过但未覆盖 CTE-entry 委托缺口。基线性能/内存mvn -pl core -DtestMySqlPerfTest,MemoryTest testMySqlPerfTest采样序列756, 548, 528, 513, 500, 501, 505, 498, 499, 502MemoryTestmemory used : 25,165,824。改造后验证Task 3.3 / 4.1加入新增测试后的聚焦回归mvn -pl core -DtestSQLASTVisitorInheritanceHierarchyTest,SQLASTVisitorInterfaceOptimizationTest,SQLASTOutputVisitorSplitRefactorTest,SQLParserUtilsDialectDispatchTest,LateralViewTest,HiveSelectTest_2_lateralview,HiveSelectTest_distribute test结果14 个测试、0 失败13 个既有 1 个新增。改造后性能/内存对比MySqlPerfTest采样序列766, 518, 504, 504, 504, 504, 504, 508, 575, 509MemoryTestmemory used : 25,165,824。结论未观察到有意义回归内存占用在观测运行中完全不变。需要说明的是这些是仓库验证记录中采样的原始数据性能测试本身受机器环境波动影响其价值在于前后对比而非绝对值。全量闸门Task 4.2 / 4.3全模块测试mvn -pl core test——PASS风格闸门模块测试生命周期内等价执行了checkstyle阶段成功运行输出为You have 0 Checkstyle violations.。验收结论Task 4.4CTE 条目的继承层次 visitor 契约已对齐遍历/分发一致性提升且遵循兼容优先的行为保持原则聚焦回归、性能、内存与全模块验证全部通过。规格沉淀三条可验收需求Spec Requirementsspecs/sql-parser-core/spec.md 将本次目标固化为 ADDED Requirements需求 1AST 遍历中的继承层次一致性涉及 SQL AST 继承层次的 parser/visitor 重构SHALL让等价节点族保持一致的基类契约使遍历与分发行为可预测且行为保持。场景 A将共享行为从重复的子类分支收敛到公共父级契约后等价 SQL 输入SHALL与基线产生行为等价的遍历/分发结果且不得仅因层次收敛引入新的接受/拒绝行为场景 B重构实例化相关 AST 子类的解析分支时token 推进顺序与分支选择SHALL与基线等价且不得在成功或失败路径上额外消耗 token场景 C受影响的解析路径上出现畸形 SQL 失败时异常SHALL保留与基线可比的 token/位置上下文诊断信息SHALL足以定位失败的解析分支。风险、权衡与迁移计划风险与缓解风险缓解措施历史测试对具体调用路径耦合过深重构后出现脆弱失败优先断言行为结果与关键上下文而非过度绑定内部实现细节继承收敛意外影响多方言 visitor 分支增加跨方言最小回归样例并执行核心模块全量测试小步收敛会保留部分历史不一致本次完成后整理后续候选分支分批推进迁移计划五步走识别并记录目标继承分支中的重复/分叉行为点在core内做局部、可回滚的契约收敛改造补充继承敏感回归测试并执行聚焦验证执行mvn -pl core test并记录性能/内存基线对比若出现行为回归按分支级别回退并缩小范围重试。遗留开放问题是否需要在后续变更中沉淀一份 AST 继承层次的统一约束指南是否将继承层次敏感回归拆分为独立测试分组以便持续执行。结语可复用的兼容优先重构范式这次变更的示范意义在于其方法论先锁不变量接受/拒绝边界、token 推进、遍历顺序再收契约父类默认方法统一委托最后双轨验证聚焦回归 全量闸门 性能/内存对比。整个过程中解析结果与输出 SQL 完全不变没有新增任何运行时依赖却消除了SQLWithSubqueryClause.Entry与其它表源家族在 visitor 钩子上的行为分叉。对于任何希望安全演进大型 AST/Visitor 体系的项目这份归档提案、设计与验证记录都是一份值得对照的工程蓝本。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Druid 内核重构实录：SQL AST 继承层次一致性收敛与 Visitor 分发契约的兼容性改造
Druid 内核重构实录SQL AST 继承层次一致性收敛与 Visitor 分发契约的兼容性改造【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid导读本文基于 Apache Druid阿里 Druid 数据库连接池/ SQL 解析内核开源仓库中的一份已归档变更提案完整拆解一次纯结构性、零行为变化的继承层次治理实践当SQLWithSubqueryClause.Entry等 AST 节点家族在父类与子类之间出现访问/分发契约不一致时如何以兼容优先的方式收敛父类契约、保持 visitor 遍历不变量并用聚焦回归 全量闸门验证改造无回归。读完本文你将掌握 Druid SQL AST 继承层次的 visitor 委托机制、此类重构的标准流程基线 → 收敛 → 回归 → 闸门以及等价输入产出等价遍历结果的验收方法。背景为什么需要治理继承层次Why近期 Druid SQL 解析器parser与访问器visitor的重构暴露出部分 SQL AST 继承层次在长期演进后的脆弱性相近的节点族node family在父类与子类之间没有共享一致的遍历契约traversal contract同类行为分散在多个子类分支中重复实现导致同类节点不同行为结构保持型重构behavior-preserving refactor因为缺少统一契约而难以验证回归成本升高。因此本次变更选择在 parser/visitor 相关代码路径仍处于活跃改进期时提前收敛继承层次以降低未来回归风险。相关提案、设计、任务与验证记录均归档于 openspec/changes/archive/2026-02-20-address-inheritance-hierarchy-issues/ 目录下其中proposal.md 定义变更范围与能力影响design.md 给出三大决策与风险权衡specs/sql-parser-core/spec.md 沉淀为可验收的需求条目verification-notes.md 记录基线、改造与闸门验证的完整证据链。变更范围与能力影响What Changes / Capabilities提案明确了本次变更的边界标准化选定 SQL AST 基类/派生类节点族的继承契约减少重复或分叉行为对齐这些继承分支上的 visitor 分发预期使等价节点遵循一致的遍历语义保持解析成功/失败行为与外部 SQL 输出兼容——这是一次兼容优先的结构清理新增围绕继承敏感遍历/分发路径的聚焦回归覆盖防止行为漂移不引入破坏性BREAKINGAPI 变更。从能力视角看本次变更不新增任何能力none而是收紧sql-parser-core的既有行为契约要求继承层次一致性、visitor/分发行为在结构重构过程中保持不丢失。受影响模块集中于core下的com.alibaba.druid.sql.ast与com.alibaba.druid.sql.visitor及其相关测试变更类型为 Refactoring maintainability enhancement无新增运行时依赖。三大核心决策Design Decisions决策 1兼容优先的父类契约收敛选择在父类或共享抽象层定义统一的默认行为入口并让目标子类显式复用该入口。理由可在最小改动范围内消除重复逻辑同时保留现有调用面。被否方案直接重写为全新层次结构——风险高、回归面过大本次不采用。这体现了小步收敛的工程取舍宁可保留部分历史不一致也不冒大规模重写的风险。决策 2访问分发行为保持不变量选择将可接受/可拒绝边界、token 推进、遍历顺序视为不变量invariant仅优化层次内部组织。理由下游测试与外部使用对这些行为存在隐式依赖。若在收敛时顺带修复局部行为差异会混入语义变更导致问题难以归因。决策 3聚焦回归 全量闸门验证选择先运行继承层次敏感测试再执行mvn -pl core test并记录性能/内存对比。理由兼顾迭代速度与发布级信心。仅跑全量测试反馈慢、定位成本高仅跑聚焦测试又不足以支撑发布决策。具体实现CTE Entry 的 visitor 委托收敛问题定位CTE 条目节点绕过 table-source 钩子通过继承层次盘点Task 1.1定位到的核心不一致点位于core中SQLWithSubqueryClause.java 的内部类Entry extends SQLTableSourceImpl implements SQLReplaceable——即 WITH 子句中的 CTE 条目如with cte as (select 1) ...中的cte as (...)在类型上是一个表源table source然而SQLASTVisitor中针对visit(SQLWithSubqueryClause.Entry)/endVisit(...)的默认方法没有委托给visitTableSource/endVisitTableSource。修复前的后果等价的SQLTableSourceImpl节点族在 visitor 钩子行为上不一致针对表源级别的通用钩子如visitTableSource会漏掉 CTE 条目节点。修复默认方法改为委托 table-source 钩子在 SQLASTVisitor.java 中两个默认方法被更新为委托模式// endVisit 委托Entry 结束访问时触发 endVisitTableSource default void endVisit(SQLWithSubqueryClause.Entry x) { // 委托至 endVisitTableSource(x) } // visit 委托Entry 开始访问时触发 visitTableSource default boolean visit(SQLWithSubqueryClause.Entry x) { return visitTableSource(x); }这样任何只覆写visitTableSource/endVisitTableSource的访问器例如输出 visitor、wall 安全检查、统计采集等都能统一拦截到 CTE 条目节点与其它SQLTableSourceImpl家族保持一致的遍历语义。整个修复不触碰解析器语法、不改变 token 推进顺序、不改变接受/拒绝边界。回归覆盖新增继承层次敏感测试为验证委托行为新增测试 SQLASTVisitorInheritanceHierarchyTest.javaSQLStatement stmt SQLUtils.parseSingleStatement( with cte as (select 1 as id) select * from cte, DbType.mysql );测试访问器同时覆写visit(SQLWithSubqueryClause.Entry)与visitTableSource/endVisitTableSource并断言三个计数全部为 1withEntryVisitBySpecificMethodCTE 条目确实通过专用方法visit(SQLWithSubqueryClause.Entry)被访问withEntryVisitByTableSourceHookCTE 条目同时触发了visitTableSource委托withEntryEndVisitByTableSourceHookCTE 条目结束访问时同样触发了endVisitTableSource委托。该测试恰好覆盖了修复前缺失的CTE-entry 委托缺口并锚定了专用方法 表源钩子双重触发的契约。验证过程与质量闸门Verification基线证据Task 1.2 / 1.3改造前先执行聚焦回归mvn -pl core -DtestSQLASTVisitorInterfaceOptimizationTest,SQLASTOutputVisitorSplitRefactorTest,SQLParserUtilsDialectDispatchTest,LateralViewTest,HiveSelectTest_2_lateralview,HiveSelectTest_distribute test结果13 个测试、0 失败确认既有套件可通过但未覆盖 CTE-entry 委托缺口。基线性能/内存mvn -pl core -DtestMySqlPerfTest,MemoryTest testMySqlPerfTest采样序列756, 548, 528, 513, 500, 501, 505, 498, 499, 502MemoryTestmemory used : 25,165,824。改造后验证Task 3.3 / 4.1加入新增测试后的聚焦回归mvn -pl core -DtestSQLASTVisitorInheritanceHierarchyTest,SQLASTVisitorInterfaceOptimizationTest,SQLASTOutputVisitorSplitRefactorTest,SQLParserUtilsDialectDispatchTest,LateralViewTest,HiveSelectTest_2_lateralview,HiveSelectTest_distribute test结果14 个测试、0 失败13 个既有 1 个新增。改造后性能/内存对比MySqlPerfTest采样序列766, 518, 504, 504, 504, 504, 504, 508, 575, 509MemoryTestmemory used : 25,165,824。结论未观察到有意义回归内存占用在观测运行中完全不变。需要说明的是这些是仓库验证记录中采样的原始数据性能测试本身受机器环境波动影响其价值在于前后对比而非绝对值。全量闸门Task 4.2 / 4.3全模块测试mvn -pl core test——PASS风格闸门模块测试生命周期内等价执行了checkstyle阶段成功运行输出为You have 0 Checkstyle violations.。验收结论Task 4.4CTE 条目的继承层次 visitor 契约已对齐遍历/分发一致性提升且遵循兼容优先的行为保持原则聚焦回归、性能、内存与全模块验证全部通过。规格沉淀三条可验收需求Spec Requirementsspecs/sql-parser-core/spec.md 将本次目标固化为 ADDED Requirements需求 1AST 遍历中的继承层次一致性涉及 SQL AST 继承层次的 parser/visitor 重构SHALL让等价节点族保持一致的基类契约使遍历与分发行为可预测且行为保持。场景 A将共享行为从重复的子类分支收敛到公共父级契约后等价 SQL 输入SHALL与基线产生行为等价的遍历/分发结果且不得仅因层次收敛引入新的接受/拒绝行为场景 B重构实例化相关 AST 子类的解析分支时token 推进顺序与分支选择SHALL与基线等价且不得在成功或失败路径上额外消耗 token场景 C受影响的解析路径上出现畸形 SQL 失败时异常SHALL保留与基线可比的 token/位置上下文诊断信息SHALL足以定位失败的解析分支。风险、权衡与迁移计划风险与缓解风险缓解措施历史测试对具体调用路径耦合过深重构后出现脆弱失败优先断言行为结果与关键上下文而非过度绑定内部实现细节继承收敛意外影响多方言 visitor 分支增加跨方言最小回归样例并执行核心模块全量测试小步收敛会保留部分历史不一致本次完成后整理后续候选分支分批推进迁移计划五步走识别并记录目标继承分支中的重复/分叉行为点在core内做局部、可回滚的契约收敛改造补充继承敏感回归测试并执行聚焦验证执行mvn -pl core test并记录性能/内存基线对比若出现行为回归按分支级别回退并缩小范围重试。遗留开放问题是否需要在后续变更中沉淀一份 AST 继承层次的统一约束指南是否将继承层次敏感回归拆分为独立测试分组以便持续执行。结语可复用的兼容优先重构范式这次变更的示范意义在于其方法论先锁不变量接受/拒绝边界、token 推进、遍历顺序再收契约父类默认方法统一委托最后双轨验证聚焦回归 全量闸门 性能/内存对比。整个过程中解析结果与输出 SQL 完全不变没有新增任何运行时依赖却消除了SQLWithSubqueryClause.Entry与其它表源家族在 visitor 钩子上的行为分叉。对于任何希望安全演进大型 AST/Visitor 体系的项目这份归档提案、设计与验证记录都是一份值得对照的工程蓝本。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考