抽象语法树能匹配结构，匹配不了值：静态检查要按三层声明能力
一、可复用的做法与容易被误读的结论
有一篇技术文演示了这样一类做法：把代码交给静态检查工具解析出抽象语法树，再用 XPath 表达式去匹配”某个变量带着一个具体字面值被传进某个调用”这类模式。做法是成立的，抽象语法树上可以匹配节点类型、父子关系和属性里的字面值，XPath 只是这些结构上的一种查询语言。文中点出的限制同样关键：它无法追踪同一个变量在别处被赋了什么值。
值得沉淀下来的不是这条规则怎么写，而是这条限制背后的一般规律。工具给出的中间产物决定了规则的表达力上限；把结构性检查当成安全性检查交付，最直接的后果不是漏掉某个具体问题，而是报告里的数字很好看却拦不住东西。”门禁全部通过”和”这条业务不变量确实被守护”是两句不同的话，把前一句当成后一句，是静态检查在团队协作里最常见的失信方式。
我们的判据因此写成一句可执行的话：规则写在第几层，就只能承诺第几层的覆盖率。验收时要先看规则处于哪一层，再看这一层能给出什么结论。这个判据对所有以抽象语法树为中间产物的检查工具都适用，不专属某个工具，也不意味着某个工具”更先进”——工具之间的差别在能不能补上更高的那层，而不是名字。
二、三层能力划分与各层的结论边界
按结论的强度可以把静态检查分成三层。语法层只看单个节点是否合规，能给出”这行代码写成了这个样子”的结论。结构层看调用关系与形状匹配，能给出”存在这样一条调用形状”的结论。值流层看定义使用链与常量传播，能给出”这次调用携带的确实是那个值”的结论。三层是递进的，上层成立不等于下层成立，下层为空也不能用上层数量来凑。
| 层 | 能承诺什么 | 典型会漏什么 | 由哪一层补偿 |
|---|---|---|---|
| 语法层 | 命名、写法、禁用 API 的字面出现、单节点合规性 | 跨节点与跨方法的语义关系 | 结构层规则加代码评审 |
| 结构层 | 调用关系、参数形状、注解与声明的搭配、树模式匹配 | 值的来源与传播路径；改名；间接调用 | 值流层分析；缺失时改为人工检查项并显式记空白 |
| 值流层 | 定义使用链、常量子传播、赋值到调用点的路径 | 依赖运行时才能确定的值、反射与动态装载 | 动态测试与运行时断言，加灰度期观测 |
这张表的用途不是评价工具好坏，而是限定我们能说什么。填完之后，一个团队的检查能力就变成了可读的条款：某一层为空，就是那一类问题在流水线里没有自动防线，必须指名补偿方式。最怕的是表填不满却在外报里写”已完成静态代码检查”。
三、结构层的三种典型漏检与锚的选择
结构层最容易漏的有三类，且都是静默的。第一类是改名。规则的匹配条件如果挂在标识符名字上，变量重命名之后规则就不再命中，而流水线不会报”这条规则失效了”，只会报”没有违规”。第二类是跨方法传值。赋值发生在上游方法里，调用发生在下游，单棵语法树内看不到值的来源，规则命中与否取决于代码被切在哪个方法里，而不是逻辑本身。第三类是经由容器或反射的间接调用。调用形状被拆散成”放入”和”取出”两个动作，结构上根本不存在规则要找的那条父子关系。
三类漏检都指向同一个工程决定：锚的选择。把名字当锚是最省事也最脆的写法，改名即漏检。可用的替代锚有三类，各自带代价。用类型当锚，稳定性最好，代价是类型体系要收敛，接口与实现类型不一致时规则要写成对类型的判定；用注解当锚，表达力最直接，代价是它依赖团队纪律，写不全就等于没有，且注解本身可能只是给人看的标记；用来源标记当锚，即规定某类数据必须带特定包装类型或构造函数才允许进入某类调用，代价是有侵入性，需要框架和存量代码一起改造。
判断一条规则该用哪个锚，我们的问法很朴素：这段代码被别人正常重构时会不会破坏它。会被改名和拆方法破坏的规则，属于需要重写的规则，不属于需要加强的流程。
四、”先赋值再传参”为什么不该硬凑
回到那篇文里的模式：赋值在前，传参在后，中间可能隔着若干方法。在没有值流能力的层上表达它，会退化成两条独立规则加人工关联——一条查”是否存在这样的赋值”，一条查”是否存在这样的调用”。两条各自命中并不代表它们是同一个变量、同一条路径，把两者对上号的活儿落到了读报告的工程师身上。这种近似的危险在于它看起来是自动化的，实际把判定责任推给了人，而人不会逐条复核。
真正的值流检查需要的是数据流分析能力，也就是定义使用链与常量子传播：从变量的定义出发找到它的所有使用点，把沿途可确定的常量值带过去，才可能回答”到达调用点时携带的是什么”。这一层的成本明显高于结构层，需要分析框架支持，规则表达能力也更强，但它的产出是结论而不是形状。
我们的处置纪律是：值流层为空时，把这类模式显式记成空白项，同时指定补偿动作——通常是评审检查表里加一条人工核对，或者把它转成动态用例。允许用近似规则做提醒，但不允许在交付说明里把它写成”该模式已被自动覆盖”。近似就是近似，说清近似反而能建立信任；不说清，一旦出第一个逃逸问题，整套门禁的可信度会一起崩塌。
五、门禁按层设计，规则库按工程要求管
门禁的严格程度应当按层设置，而不是按规则条数设置。语法层的结论可靠且误报可控，可以阻断合并。结构层在锚选得好的前提下同样可以阻断，但要先确认规则的锚不是名字。值流层缺失时，门禁不能靠”多几条结构规则”充数，要把这一层标成空白，并把对应的补偿动作写进流水线出口条件，让空白可见。
规则库本身要有最小工程要求，这几条我们固定写进规范：
- 规则与工具版本解耦。把抽象语法树作为中间产物的一个好处正在这里：规则表达在树结构上，工具升级不必然导致规则重写，树也能被外部程序二次处理，用于统计和自定义分析。
- 规则当配置来评审。每条规则有负责人、有变更历史，改动走与其他配置相同的评审路径，避免”顺手改一条规则”绕过评审。
- 每条规则配正反用例，并随回归一起跑。正例证明它能命中，反例证明它不误伤；用例不进回归，规则失效就无人知晓。
- 规则标注所在层。没有层标注的规则库无法回答”这套门禁承诺什么”。
- 放行要有记录。人工豁免的规则、被关掉的检查，要留下理由与有效期。
指标也要按层重算。规则条数、告警数、通过率这三项是最容易失真的一组：条数多可能全是语法层的同质规则，告警数高可能全是噪声，通过率高可能只是覆盖面窄。更稳的一组是：需要守护的不变量在各层的覆盖情况，值流层为空的那几条要单列；正反用例的通过率；被门禁拦住后又被人工放行的比例；缺陷从测试阶段向前一阶段逃逸时的归因层级。这组指标不漂亮，但能指导下一步该补哪一层。
六、交付时的诚实写法
向甲方或上级交付这类能力时，我们随件附一张检查能力分层表，逐层写清能承诺什么、漏什么、空白由哪一层补偿，并明确这套门禁不构成任何安全或合规意义上的保证——它只对已覆盖的不变量负责，覆盖不到的部分要么补层，要么转成人工与动态手段，不能靠语言修饰。
洹拓把这张表当作流水线验收的一部分而非附录：验收会上念的是”值流层为空，因此值相关的判定依赖评审与用例，责任人是某岗”，而不是”检查项多少条”。这么做短期会让方案显得保守，但它换来的是一个可谈判的工程条款——下一期预算该补哪一层，有明确依据。检查能力的分层不是为了限制工具，而是为了让”我们把质量管住了”这句话在需要负责的时候站得住。