Windmill 变更验证检查矩阵：一份面向贡献者的完整开发验证指南

Windmill 变更验证检查矩阵一份面向贡献者的完整开发验证指南【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill导读本文是一份面向 Windmill 开源仓库贡献者的变更验证检查矩阵Validation Check Matrix实战指南全面解读仓库 docs/validation.md 中规定的后端 Rust、前端 Svelte、跨层联动与性能验证四大类检查流程。读完本文你将掌握针对不同后端改动类型核心代码、Enterprise 门控、Kafka、DuckDB、Parquet、native trigger 等选择精确的cargo check --features组合理解 Windmill 打补丁的sqlx及其专属防回归测试为何是编译通过也无法发现的坑学会在前端check:fast与check之间取舍、在 API 变更后正确驱动 openapi 客户端生成并掌握何时该写测试、何时该跑EXPLAIN ANALYZE的性能验证红线。一、验证检查矩阵是什么一条改完必须过检的硬性纪律Windmill 是一个代码量极大的单体仓库monorepo后端是包含 40 workspace member 的 Rust 工作区见 backend/Cargo.toml前端是 2800 个.svelte/.ts文件的 SvelteKit 应用见 frontend/src两者通过 OpenAPI 生成的客户端代码强耦合。在这样的仓库里改完代码本地能编译远远不够——编译通过可能掩盖 feature 门控代码从未被检查、迁移脚本从未在真实数据库上跑过、打补丁的依赖悄悄失效等问题。docs/validation.md把做完变更定义为运行与该次变更匹配的检查命令并修复全部错误之后工作才算完成。它以三张检查表 两条决策清单何时写测试、何时查性能的形式把这一纪律落成可执行的命令矩阵。本文按原文档骨架逐节展开并深入到仓库源码层解释为什么必须这么查。二、后端检查按改了什么选择精确的 feature 组合后端检查的核心思想是按改动类型选取最小的 feature 集合而不是无脑全量编译。原因在于 Windmill 的 Cargo 特性开关极多仅 backend/Cargo.toml 的[features]一节就声明了private、enterprise、license、kafka、duckdb、native_trigger、parquet等几十个独立特性还有oss_core、ce、ee等元特性。特性门控的代码只在对应特性开启时才参与编译不开特性就编译等于这部分代码完全没被检查过。2.1 后端检查速查表改动内容命令说明核心代码无特性门控cargo check默认的完整工作区检查Enterprise 代码*_ee.rscargo check --features enterprise,private同时要走 EE PR 流程见 docs/enterprise.mdEnterprise license 门控代码cargo check --features enterprise,private,license当该特性需要有效 license key 时Kafka trigger 代码cargo check --features kafkaDuckDB 执行器代码cargo check -p windmill-worker --features duckdbduckdb_executor.rs及其#[cfg(test)]测试只在开启该 flag 时编译——普通 check/test 会静默跳过它们Native trigger 代码cargo check --features native_triggerParquet 代码cargo check --features parquet多个门控模块cargo check --features enterprise,parquet只组合你真正需要的 flagAPI 路由变更cargo check然后更新openapi.yaml并运行npm run generate-backend-client数据库迁移cargo check用sqlx migrate run验证迁移能干净应用sqlx依赖变更版本升级、[patch.crates-io]条目、fork rebasecargo test -p windmill-common --test sqlx_begin_cancel_safe -- --ignoredWindmill 使用打过补丁的sqlx上游Pool::begin在 Postgres 上不具备 cancel-safe 语义被取消的事务会毒化连接池连接长达 30 分钟。丢掉补丁仍然能编译所以只有这个 ignored 测试能发现回归。细节见backend/Cargo.toml2.2 三条铁律绝不使用--features all_sqlx_features它会编译所有东西非常慢。应查阅 backend/Cargo.toml 中[features]定义来找到正确的 flag。从定义可以看到all_sqlx_features聚合了all_languages、enterprise、kafka、tantivy、stripe等全部特性用于 CI 全量链路不适合日常迭代。绝不使用SQLX_OFFLINEtrueWindmill 开发环境中始终有可用的实时数据库离线模式会绕过真实数据库的校验。所有代码变更完成后在backend/下运行./update_sqlx.sh重新生成离线查询缓存offline query cache。该脚本内容见 backend/update_sqlx.sh非 macOS 上会执行cargo sqlx prepare --workspace -- --workspace --all-targets --features all_sqlx_features,ee,deno_core,private,enterprise,mcp即用全特性集重新捕获所有sqlx::query!宏的校验结果。2.3 源码级佐证为什么 改 sqlx 补丁 必须跑 ignored 测试Windmill 对sqlx的处理在 Rust 生态里属于相当特殊的运维实践。在 backend/Cargo.toml 的[patch.crates-io]一节中sqlx被整体替换为 windmill-labs 维护的 forksqlx-core、sqlx-macros、sqlx-postgres等全家必须一起移动否则会出现两个不兼容的sqlx-core导致Postgres不再实现宏所期望的Databasetrait补丁动机上游Pool::begin在 Postgres 上不具备 cancel-safe 语义——被取消的调用方断开的 API 客户端、timeout、被 abort 的任务会在BEGIN往返之后留下一个无人结束的事务连接池把这条连接再次分发出去后后续每个查询都会以25P02失败直到max_lifetime在 30 分钟后回收它。该问题 2022 年已上报上游launchbadge/sqlx#2054上游只修了 SQLite0.9.0 仍存在。关键结论正如注释所写改变这些东西——版本升级、fork rebase、删除这几行——仍然能干净编译。所以仓库专门准备了防回归测试 backend/windmill-common/tests/sqlx_begin_cancel_safe.rs它被标记为#[ignore]第 16 行默认不运行仅在--ignored时执行cargo test -p windmill-common --test sqlx_begin_cancel_safe -- --ignored测试逻辑第 17-71 行非常有代表性构造一个max_connections(1)的连接池确保被检查的会话就是那个被取消的 begin 所使用的会话用pool.begin_with(BEGIN; SELECT pg_sleep(2);)加宽BEGIN的往返时间再包一层 300ms 的tokio::time::timeout从而可靠地触发begin 中途被取消断言 begin 确实超时失败cancelled.is_err()用一条独立的观测连接轮询pg_stat_activity等会话不再 active核心断言会话状态不能是idle in transaction否则说明连接被归还池中时仍处于事务内——补丁失效了最后用SELECT 1验证池子仍能正常服务查询。这正是文档说Losing the patch still compiles, so this ignored test is the only thing that notices的源码级证据编译器无法发现语义回归只有行为级测试能。2.4 源码级佐证为什么 DuckDB 代码要单独-p windmill-worker --features duckdbDuckDB 执行器在整个工作区中是一个典型的特性门控模块。从 backend/windmill-worker/src/lib.rs 可见#[cfg(feature duckdb)] mod duckdb_executor;而 backend/windmill-worker/src/worker.rs 中use crate::duckdb_executor::do_duckdb;同样位于#[cfg(feature duckdb)]之下第 191 行。这意味着不加--features duckdb时duckdb_executor.rs整个模块不参与编译其内的#[cfg(test)]测试也一并被跳过加-p windmill-worker是为了把检查范围限定在真正承载该模块的 crateworkspace 默认cargo check会检查全部 member而这里明确只查 worker既保证覆盖率又控制编译时间。所以在文档中plain check/test silently skips them绝非夸张——这是 Rustcfg语义的直接结果也是本矩阵强调按改动类型选 flag的根本原因。2.5 迁移脚本的验证数据库迁移类改动在cargo check之外还必须用sqlx migrate run在真实数据库上验证迁移能干净应用。这与本仓库的迁移文件体系对应backend/migrations/下每个迁移都有成对的.up.sql/.down.sql例如20230429082953_add_drafts.up.sql/20230429082953_add_drafts.down.sql而sqlx migrate run正是逐条应用这些文件的官方机制。仓库也为此保留了若干自定义迁移见 backend/custom_migrations提醒迁移不仅要能跑还要考虑已有生产数据的兼容性。三、前端检查迭代用 fast合入用全量3.1 前端检查速查表时机命令耗时迭代期间npm run check:fast~2s最终 PR 校验npm run check~50s后端 API 变更之后先npm run generate-backend-client这两个脚本的实际定义在 frontend/package.jsoncheck:fast: bun --bun svelte-fast-check --no-svelte-warnings --incremental, check: svelte-kit sync svelte-check --tsconfig ./tsconfig.json --threshold warning,可以推断check:fast基于 bun 驱动svelte-fast-check的增量模式牺牲完整性换取 ~2 秒的即时反馈适合写代码过程中的高频自检check先执行svelte-kit sync同步 SvelteKit 生成的类型与路由声明再以--threshold warning跑完整的svelte-check任何 warning 及以上级别的问题都会导致失败因此 PR 合入前必须以它为准。3.2 API 变更后的客户端再生后端改了 API 路由后前端的第一步不是跑 check而是先重新生成客户端。该命令在 frontend/package.json 中定义为generate-backend-client: openapi-ts --input ../backend/windmill-api/openapi.yaml --output ./src/lib/gen --useOptions --enums javascript --format false它把 backend/windmill-api/openapi.yaml 作为唯一事实源用openapi-ts生成frontend/src/lib/gen下的类型与请求封装。如果跳过这一步前端会继续引用旧 API 签名类型检查自然失败反之如果不更新openapi.yaml就重新生成客户端类型与真实后端行为就会漂移。这正是文档API route changes → update openapi.yaml → npm run generate-backend-client的顺序在工具链层面的落实。四、跨层检查接口、Flow 结构、Schema 与 EE 伴生 PR情形额外步骤新增/修改了 API 端点更新 backend/windmill-api/openapi.yaml重新生成客户端修改了 Flow 结构还要更新 openflow.openapi.yaml改了 DB schema必要时更新 backend/summarized_schema.txtEnterprise 文件变更在windmill-ee-private提伴生 PR见 docs/enterprise.md改了.claude/hooks/中的某个 hook运行bash .claude/hooks/test-hooks.sh——它固定了哪些命令会触发提示其中改 hook 要跑 hook 测试是本仓库很独特的一条纪律.claude/hooks/目录存放了 Claude Code 的 PreToolUse 安全守卫例如guard-rm-outside-tmp.sh限制rm只能作用于 /tmp 与 scratch 目录、allow-fileops-in-tmp.sh限制文件操作边界、guard-main-branch.sh、format-backend.sh等。查看 .claude/hooks/test-hooks.sh 可以看到它是一个覆盖上百条命令用例的决策表测试对每条候选命令含 heredoc、管道、cd链、命令替换、包装器env -i/sudo等对抗性写法断言守卫应当返回allow、ask还是none任何不匹配都计为 FAIL 并以非零退出码结束。它的注释明确写道what this pins is theaskcolumn: a matcher change that turns one into a no-decision drops that commands only prompt——即一个匹配规则的改动若把某条命令从ask变成无决策会静默移除该命令唯一的安全提示。因为守卫脚本本身就在仓库里、且是权限相关逻辑改动它比改动普通代码更危险所以必须用整套用例回归。五、何时写测试一套按改动类型的决策规则场景测试策略在windmill-common中新增工具函数总是加单元测试新增带复杂逻辑的 API 端点加集成测试修复非显而易见的 bug加回归测试纯 UI 改动无需测试依赖类型检查重构确保既有测试通过不新增测试这条规则与仓库测试布局一致windmill-common是共享基础库如sqlx::query!宏的离线缓存就大量集中在 backend/windmill-common/src/assets.rs 等文件中其工具函数被全工作区复用回归风险面最大所以总是加单元测试而 API 端点属于跨进程行为文档要求走集成测试——仓库为此保留了 backend/windmill-api-integration-tests 这样的集成测试 crate。上一节提到的sqlx_begin_cancel_safe就是非显而易见 bug 需要回归测试的教科书案例。六、何时检查性能查询热路径的 EXPLAIN ANALYZE 红线当你的改动触及以下区域时文档要求在新增/修改的查询上运行EXPLAIN ANALYZE作业队列表v2_job、v2_job_completed热路径查询轮询、调度增删了索引v2_job_completed确实存在于仓库代码中例如 backend/windmill-common/src/bench.rs 的基准代码就对该表执行FROM v2_job_completed的聚合查询第 231 行 还有DELETE FROM v2_job_completed WHERE workspace_id admins的清理语句。作业队列是 Windmill 作为工作流引擎的核心竞争点队列表上的查询质量直接决定调度与轮询的端到端延迟因此这类改动必须用执行计划验证而不是靠直觉合入。七、把矩阵固化为习惯推荐的改动提交前自检顺序综合全文档一次合规的 Windmill 贡献在合入前应当依次确认后端按 2.1 表选中与你改动匹配的 feature 组合跑cargo check改到门控模块DuckDB/Parquet/Kafka/native trigger/EE时绝不用默认命令代替sqlx 相关改动跑cargo test -p windmill-common --test sqlx_begin_cancel_safe -- --ignored确认补丁语义仍在迁移改动sqlx migrate run验证干净应用最后在backend/下运行./update_sqlx.sh刷新离线查询缓存API 变更更新 backend/windmill-api/openapi.yamlFlow 结构变更则同时更新 openflow.openapi.yaml再npm run generate-backend-client前端迭代期用npm run check:fastPR 前用npm run check全量校验数据库 schema 变更必要时同步 backend/summarized_schema.txt性能敏感改动对队列表与热路径查询跑EXPLAIN ANALYZE测试按第五节的决策规则补齐或确认测试EE 与 hookEE 文件走伴生 PR改了.claude/hooks/就运行bash .claude/hooks/test-hooks.sh。把这张清单变成肌肉记忆后你提交的每个 PR 都能以编译正确 门控覆盖 语义防回归 数据库与性能可验证的标准交付这也是 Windmill 在超大规模 monorepo 下能长期保持高质量演进的根本原因。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考