从AST到自动修复：自研代码质量检查工具impeccable的实践

1. 先说说我为什么非要造一个impeccableimpeccable这个代号是我在去年搭起来的一套代码质量检查工具英文原意是无可挑剔、没有瑕疵。起因其实很俗我所在的团队每天花在代码评审上的时间越来越多但吵的内容却越来越奇怪——空行多了一个、某变量名用了缩写、一段重构没有拆成小函数……这些问题的本质不是大家不认真而是团队从来没有一个能把规范自动执行起来的东西。于是我花了三周时间写了impeccable专门解决一件事让无可挑剔不再是一句口号而是一个可以被代码库自动校验和自动修复的机制。工具刚做出来的时候团队里有人觉得是多此一举有人觉得是在挑战市面上的开源方案。但真正跑了一个月之后评审时间缩短了接近一半新人上手时也不会再因为不懂规矩被反复打回。这篇博客不打算写成宣传稿我就把从设计、实现到接入工作流的完整过程拆开讲一遍包括踩过的坑和让我后半夜爬起来修Bug的那个修复逻辑事故。如果你也在跟代码风格和评审效率较劲这套思路应该能给你一些启发。1.1 一次鸡毛蒜皮的Code Review事故事情发生在一次普普通通的周五。A同学提交了一个功能分支B同学负责评审。两个人在评论里来回纠缠了七八轮核心争议是一个缓存对象里的字段到底应该按字母序排列还是按访问顺序排列。A说按访问顺序更贴近业务B说按字母序方便查找。最后组长拍板按字母序因为这是团队规范但翻遍团队文档发现这条规范只存在于某次周会的会议纪要里。这么一件小事最终消耗了两个人加组长大约两个小时。这其实不是人的问题而是规范这个抽象的东西没有落地工具。文档会过时口头约定会被遗忘唯一能长期稳定执行的就是代码。我当时的第一个想法是如果有一套工具能把字段排序这种规则变成机器检查项并且能自动把不合适的排序改成合适的样子那这场架根本不会发生。那次事故之后我在团队里做了一次小调查发现大家的痛点其实高度集中规则散落、评审标准因人而异、简单格式问题占用了大量讨论时间、新人需要反复试错才知道什么叫符合团队风格。这些痛点是通用的也是impeccable最原始的出发点。1.2 为什么现成的工具满足不了我们当时我们已经在用一些常见的开源代码检查工具它们确实能帮助团队少踩很多坑。但用了一段时间之后我开始意识到它们的边界在哪里。首先是规则的可定制性不够。很多工具的核心规则集是社区定义的面向的是全行业的通用规范团队内部那条缓存字段按字母序的特定约定很难通过简单配置表达出来。如果硬要扩展就得跳到插件机制里写比较底层的代码维护成本一开始就很高。其次是自动修复的深度问题。大多数工具能自动修的只是行尾分号、空格、引号这一类的表层格式问题。像把import语句按字母序排列这种涉及抽象语法树深层结构的操作要么不支持要么修出来的结果经常和团队习惯不一致。更别说语义级别的检查比如某个重构分支根本没有被调用、这段代码和上面的逻辑互相矛盾这些都不是简单规则能覆盖的。还有一点是性能和集成成本。整套检查在本地跑一遍要等很久团队里几台配置稍低一点的机器跑一下就要两到三分钟大家为了省时间就选择跳过检查最后变成CI里的一次红灯而已。这不是工具不好而是它为了通用性牺牲了针对性和可落地性。我当时的判断是与其在通用工具上打补丁不如按自己的实际流程做一个足够聚焦的方案把检查什么、怎么修、什么时候跑这三件事完全握在自己手里。1.3 impeccable要解决的三大问题经过梳理我给这个项目定了三个必须解决的终极问题后面的所有设计都围这三个问题展开。第一把散落各处的规范变成可执行代码。不管是周会纪要、评审留言还是某人的口头习惯都必须变成一条一条结构化的规则。每条规则要有固定的ID、描述、默认等级和对应的修复策略。这样团队在讨论该不该这么做的时候讨论的是具体的一条规则ID而不是模糊的感受。第二不只会报错还要能安全地修。一个检查工具如果只是把问题标红其实只是把评审员换成了机器人并不会减少修复的工作量。impeccable要能做到对于低风险问题直接自动修复对于高风险问题给出精准提示和修复建议让开发者一键确认。这背后需要一套比较完善的安全回退机制后面我会详细讲。第三规则必须可插拔。不同团队、不同项目甚至前端和后端代码都应该能够共享一部分通用规则同时保留各自的定制能力。也就是说impeccable本身只是个引擎规则全部以插件形式存在用户可以组合出适合自己的规则集。这样才能避免用了工具之后反而被工具绑架的尴尬。2. 把无可挑剔翻译成机器能懂的规则确定方向之后最核心的问题是怎么把人类语言里的规范翻译成程序能理解的逻辑。我一开始踩过一个误区以为写几个正则表达式就能搞定所有检查结果做出来的工具既慢又容易误判面对多行嵌套代码几乎无能为力。后来我才意识到要做真正可靠的检查必须让程序理解代码的结构而不仅仅是文本。2.1 规则的三个抽象层次设计规则体系的时候我把所有检查项分成三个层次。第一个层次是词法和语法层主要看代码长什么样比如函数名是否用了驼峰式、字符串里是否出现了禁止的URL、文件末尾是否有换行。第二个层次是语义层主要看代码能不能在运行时有预期行为比如变量是否被声明、循环里是否有无限递归风险、分支条件是不是恒为真。第三个层次是风格与架构层主要看代码组织结构是否符合团队约定比如领域文件的划分、组件文件是否包含过多可复用模块。这三个层次对应了不同的检查手段和修复难度。词法语法层靠解析后生成的抽象语法树就能搞定语义层需要结合符号表和类型信息风格与架构层最难因为有时候同一个问题可以有很多种正确修法。我把这条认知直接放进了规则引擎的接口设计里每条规则在声明时必须指定自己属于哪个层次并且提供修复建议的可执行函数。抽象层次检查内容典型规则示例自动修复难度词法与语法层代码文本结构和AST形态禁止使用废弃的调用语法、函数参数数量不得超过3个低语义层变量引用、作用域、常量与类型禁止声明后未使用的变量、禁止读取未初始化的状态中风格与架构层命名方式、模块边界、依赖方向缓存对象的字段必须按字母序排序高这个分层不只是为了好听它直接影响了我后面修Bug的方式。例如语法层的修复可以大胆反复执行修坏了语法检查立刻能发现语义层的修复一旦出错可能不会报错但运行时逻辑会变所以修复前必须做更严格的判定风格层的修复则最容易改坏别人的代码我把这类修复默认标记为需要人工确认。2.2 为什么核心要选AST而不是正则在很多人的印象里代码检查工具就是一堆正则表达式。但正则只能看到文本的表面它不理解嵌套关系。举一个最简单的例子检查循环体内不允许调用某个带副作用的方法。如果只用正则去搜索方法名很容易把注释里的内容、字符串里的内容、其他同名函数里的内容都误伤。再比如检查JSX组件里是否缺少key属性正则几乎无法分辨哪个标签是真正的组件实例。AST的优势是把源代码变成一棵结构化的树。每个节点都携带位置信息、父节点和兄弟节点的关系规则只需在树上做一次遍历就可以精确判断某个方法调用到底是被循环包裹还是只是恰好出现在同一行的注释里。更重要的是AST能支持重写。修复的过程本质上就是修改这棵树的节点再把新的树还原成源代码。如果不用AST自动修复就无从谈起因为你无法在文本层面安全地做把第二个参数挪到第三个参数后面这种操作。当然AST也有代价最明显的是解析耗时。一个大型文件解析成完整AST可能要几百毫秒这比正则慢得多。所以我在impeccable里做了非常激进的增量缓存只要文件内容和依赖环境没变就直接复用上次的解析结果。这样全量扫描速度也可以控制在几秒到几十秒之间完全够用。2.3 一个最小规则的完整示例为了让思路更具体我写一条非常简单的规则示例。假设团队约定函数参数不能超过4个超过的话需要合并成配置对象。impeccable里的规则就是一个带有meta和create两个字段的对象。meta里放规则描述、等级和修复策略create里返回一个处理器集合在不同AST节点触发对应逻辑。// 示例规则函数参数最多4个 module.exports { meta: { id: local/function-params-limit, description: 函数参数个数不应超过4个超出的参数建议合并为配置对象, severity: warn, fixStrategy: suggestion }, create(context) { return { FunctionDeclaration(node) { if (node.params.length 4) { const diff node.params.length - 4; context.report({ node, message: 参数数量超出限制当前${node.params.length}个最多允许4个超出${diff}个, suggestions: [ { desc: 将超出部分合并为对象参数, // 这里省略具体的AST改写逻辑 } ] }); } } }; } };你可能注意到它没有直接修而是给了一个suggestion。我的设计原则是凡是不能100%保证语义不变的修复都只给建议不给自动修改。上面这条规则在自动修复时很容易犯错因为把参数合并为对象可能要同时修改函数体内所有引用这在AST层面是一个较大的重构风险太高。所以它只负责把问题找出来再配合编辑器的自动化操作提示给开发者参考。2.4 自动修复的安全回退设计这是impeccable里我最满意的一块设计。自动修复最怕的不是修不到位而是修坏了还没人发现。为了这个我把所有修复策略分成了三个安全级别绿的、黄的、红的。绿色代表纯格式修复比如删除行尾空格、调整缩进这类修复可以批量自动执行即使执行一万次也不会改变运行结果。黄色代表需要依赖上下文分析比如变量声明式改成const这需要先确认这个变量没有被重新赋值一般可以在同一次AST遍历里完成验证。红色代表高风险重构比如调整import顺序或合并重复分支这类修复会自动生成一个diff预览并且默认不会在CI里自动应用必须由开发者在本地确认。颜色分级背后还有一个安全回退机制每次自动修复之前工具会先对源文件做一次语义快照。快照不只是一份哈希而是记录文件里每个函数和模块的引用关系。修复完成之后如果引用关系发生变化工具会主动撤销这次修复并输出警告。这个设计非常有用因为即使我的引擎有Bug也不会把错误扩散到整个代码库。3. 跑通核心链路从扫描到修复有了规则和AST解析接下来的事情就是把它串成一条完整流水线。这个过程远比想象中复杂。很多人觉得检查工具就是读取文件、解析、跑规则、输出结果真正动手之后你会发现光是文件的编码、二进制文件的过滤、解析失败的降级处理每个环节都能卡住你半天。3.1 文件收集与解析器的容错impeccable最开始只打算扫描源代码目录但很快我遇到了一个尴尬的问题直接把所有文件灌进解析器有的文件编码是GBK有的文件里还混着测试模板的代码解析器一遇到语法错误就抛异常整个流程直接中断。后来我加了一个文件级容错层先根据后缀名和路径白名单过滤出需要检查的候选文件再读取文件头部字节判断编码最后在解析时捕获语法错误把错误文件单独记录到待人工处理列表绝不阻断其他文件的检查。这个容错设计看起来很简单但对真实代码库的稳定性贡献很大。以前遇到一个文件有语法错误整个CI任务就会红但那个文件可能是生成器自动生成的临时文件根本不在我们应该审查的范围内。现在impeccable可以把这类文件跳过同时生成一份报告提醒大家注意。我特别建议你要做类似工具时永远不要假设输入文件都是干净的容错率决定了工具的人缘。3.2 规则调度顺序的讲究规则不是拿到AST上跑一遍就完事儿的。规则之间经常有依赖关系比如禁止未使用的变量这条规则应该先于删掉未使用的import这条规则执行因为后者可能会改动import节点而前者依赖的引用信息还没计算。为了避免这种互相干扰我加了一个简单的规则调度器按语义层规则 - 词法层规则 - 风格层规则的顺序执行。这个顺序背后有一个直觉语义层规则先建立全代码库的引用地图词法层规则依赖引用地图来判断一段代码是否真的没用风格层规则在结构稳定的前提下做格式化调整更安全。实际执行下来这个顺序能显著减少同一份代码被不同规则反复打回的情况。当然规则依赖也可能比这个复杂所以我在规则定义里额外暴露了requiresRules和conflictsWithRules两个字段让调度器能自动处理显式依赖。3.3 修复落盘与幂等性自动修复并不是把改完的文件直接覆盖回去就结束了。我在设计的时候引入了修复桶的概念所有修复操作先写到内存里的一个临时diff列表再统一落实。这样做的原因有两个。第一是可以批量执行撤销如果某一处语义快照校验失败可以精准回滚那一条改动。第二是方便在落盘之前做一次幂等性校验——也就是说把修复后的文件再跑一遍检查如果仍然有同类问题说明修复不彻底应该标记为失败而不是继续覆盖。幂等性校验听起来简单做起来很容易忽略。我刚开始没有这一步结果同一个文件被重复跑了多次检查每一次都修一点到了第三次才稳定。后来我把修复后重检做成强制流程如果一轮修复之后问题数没有降到零就说明存在规则冲突或者修复函数不收敛工具会直接中止并输出冲突原因。这样做虽然稍微增加了运行时间但换来了稳定可靠的行为。3.4 性能优化缓存和增量扫描一个代码检查工具如果跑得太慢最后一定会被团队放弃这是我在项目初期就预感到的。为了让全量检查时间可接受我做了两层优化。第一层是对文件解析结果做缓存。每个文件的AST和语义快照会以内容哈希为key存到临时目录里只要文件内容不变、依赖解析器版本不变就直接复用。第二层是增量扫描impeccable会自动读取版本控制系统里的变更文件列表支持只检查changed files以及被它们依赖的部分模块。这两层优化叠加后效果非常明显。一个大约两万行代码的中等规模仓库首次全量扫描大约需要8秒之后如果只改了一个小文件增量扫描能在0.3秒内完成。再加上我使用了进程池来并行解析多个文件整体速度还能进一步提升。性能这个东西不到大规模代码库不会体会到有多重要但等团队开始每天跑一百多次检查时你就知道这8秒和0.3秒的区别就是大家愿不愿意用的区别。4. 接入版本控制钩子之后踩过的坑工具的核心流程稳定以后我开始把它接入到团队的工作流中。这一步远比我想象的惊险因为工具要真正影响每个人的日常提交动作任何一个小Bug都会被无限放大。我在这里踩了三个比较有代表性的坑每一个都花了我不少时间才定位到根因。4.1 与pre-commit钩子集成的正确姿势最开始我想得很简单在commit之前跑一次全量扫描有问题就不让提交。这个方案上线第一天团队就有人提交不了代码原因是他的分支上有一个历史遗留的警告信息一直没有处理。全量扫描面对这种情况非常不友好因为警告是旧代码留下的跟他本次的改动无关但钩子把账全算到了他头上。后来我把策略改成只检查本次变更涉及的文件。没有用全量扫描而是用版本控制系统提供的变更文件列表去扫描实际被修改的部分。这样旧债不会被反复追讨新引入的问题也能被及时拦截。更重要的是我在钩子里区分了两种等级error级问题直接阻止提交warn级问题只打印提示允许提交。这样既不放过硬伤又不会让团队因为格式强迫症而暴走。4.2 一次误报危机的完整排查链路某天开始团队里陆续有人反馈impeccable把一段线性且没有任何问题的代码标成了函数参数过多。我起初以为是规则写得太激进就把阈值调高但奇怪的是同样的代码在有的机器上完全正常在另外两台机器上就会误报。我花了三个小时排查这条链路先对比了触发误报的环境和正常环境的区别发现差异集中在解析器版本上又检查了impeccable的依赖安装方式发现其中一台机器使用了旧版解析器的缓存最后定位到规则处理器在解析装饰器语法时把对象字面量中的一个展开字段当成了函数参数的部分导致数量计算错误。根本原因是新版解析器对通配展开的支持发生了变化而我的规则没有考虑这个语法节点类型。修复方式是在规则里增加对展开字段的判断并且在语义快照里加入解析器版本作为缓存因子。这次排查给我上了一课工具的依赖锁定和缓存失效策略直接决定了它的可信度。从那以后我把所有的解析器依赖都写入统一的锁文件并且要求每次升级都跑一遍全量的回归用例确保不会出现某些机器新、某些机器旧的分叉问题。4.3 自动修复改坏逻辑的惨痛教训这是我整个项目里印象最深的一次事故。当时我设计了一条把import语句按字母序排序的规则并且非常自信地把它标记成了绿色安全级别。上线之后它确实能自动重新排序import某次自动修复后有个同事发现页面白屏了。排查后才发现被排序的import里有一个副作用调用它的执行顺序原本是有意义的必须先加载A模块再加载B模块而B模块在加载时会默认读取A模块挂载的全局属性。我的排序规则把所有import按字符串顺序排列完全没考虑副作用依赖直接改变了模块初始化顺序最终导致了运行时报错。这个事故让我把很多看起来纯格式的规则也重新归类为黄色甚至红色。只要一条规则的操作对象里包含可能具有执行顺序语义的语句它就不能被无脑自动应用。我随后在规则里增加了一个sideEffectAware字段如果为true修复前会检查语句块里是否存在函数调用和顶层赋值存在的话直接跳过自动修复。这个教训值回票价虽然过程很痛苦。5. 上线一个月后的实测数据与我的判断项目稳定运行一个月后我拉了一组团队内部的数据来做复盘。这个数据样本不算大大概有八名开发人员、四个主要仓库但趋势已经足够说明问题。我需要提醒的是所有数据都来自我最开始定义的那三类规则如果规则集差异很大数字会有很大浮动所以参考的是变化方向而不是绝对值。5.1 团队内部的一组对比数据我用表格记录了几个关键指标指标接入前接入一个月后变化幅度单次评审平均消耗时长约25分钟约13分钟降低48%格式/风格类评论占比约60%不到15%大幅下降提交前自动修复问题数0约每周320处从纯人工到自动因低级错误导致的CI失败次数每周约9次每周约2次降低约78%新人达到团队规范要求所需评审次数约4到5次约1到2次明显减少最直观的感受是评审时间被释放出来大家终于可以把注意力放在这个方案是否合理而不是这个空行是不是多了。新人上手的时候也不用再看一堆文档去猜模板直接在提交时看impeccable给出的具体提示和修复建议就够了。5.2 impeccable做不到的事情虽然这个工具给我带来了很多便利但我必须站在从业者的角度说清楚它的局限。第一它完全不理解业务意图。代码里为什么这里要特殊处理某个边界条件这类深层次的问题靠规则是永远无法检查的这一层只能靠人。第二规则集一旦过于庞大维护成本也会上升。每条规则都需要有人负责定期根据团队变化和代码语言版本升级而调整。如果一个团队没有固定的维护者规则库会慢慢腐化最终变成新工具里的老负担。第三自动修复并不总是节省时间。对于复杂重构修复建议往往需要开发者在编辑器里手动确认这个过程如果做得不够顺滑反而会打断开发状态。我的解决方案是把修复建议输出为可点击的diff尽量减少人工操作但对极其复杂的场景依然难免需要动手。所以任何工具的核心目标都应该是降低重复劳动而不是消灭思考。5.3 自研工具值不值我的判断标准经常有人问我这种东西直接用开源工具不就行了吗为什么非得自己造一个轮子我的回答很直接如果你的痛点只是缺少某条规则那就给社区工具写一个插件如果你发现自己需要重新定义检查流程本身那自研才是合理的。在我这里判断标准有三条。第一条现有工具是否能在两个小时内完成你想要的核心改动如果不能自研的收益就可能高于成本。第二条你是否需要一个特殊的修复引擎来配合团队内部的代码结构而不是只在输出报告层面做文章这是自研最有价值的地方。第三条团队是否愿意为这个维护成本长期买单如果只是一时兴起那开源插件永远是更安全的选择。impeccable对我个人来说是一次非常好的锻炼它逼着我从解析器的底层细节一直考虑到开发者的日常流程让我学会站在使用者的角度去设计一个可靠且不打扰的工具。如果你也有类似的计划我建议你从一条最让你痛苦的规则开始哪怕只做这一件事把它做成自动化的也已经值回投资。最后分享一个小技巧写规则的时候每条规则都强制写一段为什么字段这样未来任何新人来维护规则库的时候看到的不只是怎么做还有为什么这么做这会省掉大量不必要的讨论。