pgrust 的 todo_guard如何用编译期检查保证代码质量【免费下载链接】pgrustPostgres rewritten in Rust, now faster than Postgres and Clickhouse项目地址: https://gitcode.com/GitHub_Trending/pg/pgrustpgrust 是一个用 Rust 重写 PostgreSQL 的开源项目目标是与 Postgres 18.3 完全兼容并跑通 46000 条回归查询。在这样一个体量庞大、动辄上千个 crate 的代码库里如何防止todo!()、unimplemented!()这类半成品标记悄悄混进主干代码pgrust 团队给出的答案是一个专门用于编译期检查的 crate——todo_guard。本文带你从零看懂它的设计思路与实现原理。为什么 todo!() 是代码质量的隐形杀手在 Rust 中todo!()和unimplemented!()是标准库提供的两个宏一旦程序在运行时执行到它们会直接触发 panic。它们的本意是此处功能尚未实现方便开发时占位但危险也正在于此隐患说明运行时崩溃用户触发到未实现分支直接 panic无任何兜底悄悄蔓延开发者习惯性用它先跑通再说之后忘记回来补回归风险大重构后旧占位代码可能被搬运进新的代码路径难以发现写进注释或字符串里的todo!()会干扰人工排查对一个追求更快、更稳、兼容 Postgres的项目来说这种隐患必须被自动化拦截——这正是pgrust 编译期检查要解决的核心问题。todo_guard 是什么一个零依赖的看门狗todo_guard是 pgrust 工作区里的一个独立 crate位于crates/_support/todo_guard/。它的定位非常纯粹扫描整个仓库找出所有真实存在的todo!()和unimplemented!()宏调用并在测试阶段报告甚至拦截。它的两个关键文件是lib.rs实现核心扫描逻辑对外只暴露scan_workspace()和workspace_root()两个函数no_todo.rs测试闸门让检查在cargo test --workspace时自动运行。更妙的是它的 Cargo.toml 特意声明了零依赖Intentionally has NO dependencies so it builds fast and in isolation。这意味着它编译极快、不会拖累整个工作区的构建也不存在传递依赖带来的安全或维护风险——一个检查工具越轻越好。核心扫描原理如何区分真的和假的 todo判断代码里有没有todo!()并不难难的是不要误报。字符串、注释、文档里出现todo!()再正常不过比如 SQL 示例文本、报错信息、注释里的说明。todo_guard的核心价值就是写了一个不依赖编译器、纯文本级的状态机扫描器。它在scan_text()中逐字节遍历.rs文件并维护以下几种状态从而把非代码区域跳过要跳过的区域处理方式行注释//、///、//!跳过到行尾块注释/* ... */支持 Rust 的嵌套注释用深度计数器匹配普通字符串...、字节串b...正确处理\转义原始字符串r#...#、br#...#按#数量匹配收尾引号字符字面量x、\同时避开生命周期标注a的误判只有真正落在代码区、且以todo!/unimplemented!完整标识符出现的宏调用才会被记录为一次Hit并带上文件路径与行号。字符串和注释里的伪装者全部被过滤掉。三个值得借鉴的设计细节1. 边界情况的严谨处理扫描器对标识符做了词法边界判断mytodo!()、todone这类包含todo子串的标识符不会被误伤a这类生命周期标记也不会被当成字符字面量而破坏扫描状态。这些细节在 lib.rs 的测试模块里都有对应的单元测试覆盖。2. 不依赖编译器但足够可靠选择纯文本扫描而非cargo check或rust-analyzer的原因很实际快。它不需要编译任何东西读取源码文件即可完成全仓库扫描可以高频运行在 CI 的每个环节。对于拦截 todo 回归这种简单判定这已经足够。3. 闸门设计成可渐进式收紧no_todo.rs 里有两个测试设计思路非常巧妙report_todo_count永远运行、永不失败只打印当前代码库中真实todo!()的数量和位置清单让团队随时掌握清理进度no_todo_or_unimplemented_in_tree真正强制的闸门目前因历史遗留标记了#[ignore]等计数归零后去掉#[ignore]它就立即升级为发现一个就失败的硬约束。这种先报告、后拦截的渐进式策略让大型项目可以安全地推进清理而不是一夜之间让 CI 全红。如何运行这个编译期检查在 pgrust 仓库根目录下你可以这样使用它# 查看当前 todo!() / unimplemented!() 的真实数量与位置不会失败 cargo test -p no-todo-guard -- --nocapture # 运行被忽略的强约束闸门当前预期会失败用于查看完整清单 cargo test -p no-todo-guard -- --ignored # 整个工作区测试时报告测试会自动附带运行 cargo test --workspace整个扫描只需要 cargo 的标准测试设施不需要额外安装任何工具开箱即用。小结编译期检查让半成品无处遁形从 pgrust 的todo_guard身上我们可以看到高质量开源项目在工程质量上的用心一个看似不起眼的检查工具却精准解决了占位代码悄悄回归这个真实痛点。它零依赖、扫描快、误报低、可渐进收紧还能把进度可视化地报告给团队——这套思路完全可以迁移到任何大型 Rust 项目中。如果你也想为自己的仓库加一道编译期检查防线不妨直接参考crates/_support/todo_guard/下的实现先写一个只读不报错的扫描器再配一个可开关的强制闸门最后用测试让它随工作区自动运行。代码质量往往就赢在这些不起眼的细节里。【免费下载链接】pgrustPostgres rewritten in Rust, now faster than Postgres and Clickhouse项目地址: https://gitcode.com/GitHub_Trending/pg/pgrust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考