用 Fleet 的 pre-push Git Hook 在推送前拦截代码问题:编译、Schema 与 Lint 一体化工作流
用 Fleet 的 pre-push Git Hook 在推送前拦截代码问题:编译、Schema 与 Lint 一体化工作流
导读
本文以 Fleet 开源仓库中 git-hooks/README.md 为核心骨架,讲解如何在开发工作流中引入 Git Hook,把本地验证前置到每次 git push 之前。读完本文,你将掌握 Fleet 仓库自带的 pre-push 钩子脚本的安装方式、可扩展的 hook 编排机制,以及 compile-go、db-schema、lint-go 三个后端检查脚本各自的底层实现(对应 Makefile 中的构建、Schema 生成与静态检查目标),并能够按需定制自己的检查清单。
Git Hook 是什么,为什么要在推送前运行
Git Hook 是 Git 在特定事件(如 commit、push)之前或之后自动执行的脚本。Fleet 仓库的 git-hooks/README.md 明确聚焦于 push 钩子,即提交代码被推送到远端之前的拦截阶段。它带来三方面收益:
- 减少等待时间:设想你把一个带有小问题(比如
make lint-go未通过)的提交推上去,随后才发现问题,被迫重启整个 CI 流水线,而 Fleet 的测试完整跑完可能需要约 30 分钟。本地前置检查可以把这类问题拦截在 30 分钟循环之外。 - 精简工作流:缩短反馈回路,让开发者能在几十秒内拿到结果,辅助快速迭代开发。
- 节省 CI 资源:减少失败构建的数量,把 CI 资源留给真正需要的任务。
本质上,这是把"质量门禁"从远端 CI 前移到开发者本地,让最便宜、最快的检查最先执行。
快速上手:安装 pre-push 钩子
1. 复制脚本并赋予可执行权限
Fleet 仓库在 git-hooks/backend/setup/pre-push 提供了现成的钩子脚本,安装方式如下:
cp ./git-hooks/backend/setup/pre-push ./.git/hooks/
chmod +x ./.git/hooks/pre-push
说明:Git 只会执行
.git/hooks/目录下具有可执行权限且命名与钩子事件匹配的脚本。pre-push会在git push即将发送对象、且远端引用已更新之前被调用。
2. 编辑 USED_HOOKS 清单指定要运行的检查
安装后打开 .git/hooks/pre-push,通过 USED_HOOKS 数组声明要执行的脚本。文件名必须与 ./git-hooks/backend/hooks/ 目录下的脚本一一对应,且数组顺序即执行顺序:
declare -a USED_HOOKS=(
"compile-go"
"db-schema"
"lint-go"
)
该数组位于 pre-push 的第 9~13 行,默认即包含上面三个后端检查。你可以增删条目或调整顺序,例如只保留 lint-go,或增加自定义脚本。
pre-push 脚本的工作原理
查看 pre-push 源码可以发现,整个钩子是一个轻量级的"调度器":
- 定义钩子目录:
HOOK_DIRECTORY="./git-hooks/backend/hooks"; - 遍历该目录下的所有文件(
for SCRIPT in "$HOOK_DIRECTORY"/*),用basename取出文件名; - 与
USED_HOOKS数组中的目标逐个比对;命中的脚本通过bash "$SCRIPT"执行——这正是 hooks 目录中的脚本无需chmod +x的原因(见 git-hooks/README.md 的 Contributing 一节); - 检查执行退出码:
if [[ $? -ne 0 ]]; then exit 1; fi——任何脚本以非零码退出都会立即中断 push,从而拦截提交。
这种"声明式清单 + 遍历执行"的设计让新增检查非常简单:往 hooks/ 目录丢一个 bash 脚本,再把它写进 USED_HOOKS 即可,无需修改调度逻辑。
三个内置检查脚本的底层实现
compile-go:一次完整的 Go 构建
compile-go 内容极简:
#!/bin/bash
make
这里执行的 make 对应 Makefile 中的 all: build 目标,而 build 依赖 $(BINS_TO_BUILD),其值为 fleet fleetctl(Makefile)。也就是说,该检查会实际编译 Fleet 的两个核心命令行工具:
fleet:Fleet 服务端二进制(部署用的主程序);fleetctl:Fleet 命令行管理工具。
以真实编译替代 go vet 级别的静态扫描,能提前暴露类型不匹配、未导入包、链接错误等问题,确保推上去的代码至少是可构建的。
db-schema:数据库 Schema 是否与迁移一致
db-schema 是一个带开关的检查脚本,核心逻辑如下:
#!/bin/bash
## DB Schema Dump
if [[ $DB_SCHEMA_DUMP ]]; then
make dump-test-schema
if [[ $(git diff-files --patch server/datastore/mysql/schema.sql) ]]; then
echo "❌ fail: uncommited changes in schema.sql"
echo "please run 'make dump-test-schema' and commit the changes"
exit 1
fi
fi
关键设计点:
-
通过环境变量
DB_SCHEMA_DUMP启用:默认不执行,只有显式设置该变量(如DB_SCHEMA_DUMP=1 git push)才会运行,避免每次推送都付出生成 Schema 的代价。 -
make dump-test-schema在 Makefile 中定义为:test-schema: go run ./tools/dbutils ./server/datastore/mysql/schema.sql dump-test-schema: test-schema它会根据当前迁移文件重新生成
server/datastore/mysql/schema.sql。 -
随后用
git diff-files --patch检测该文件是否有未提交的改动;若有,则输出❌ fail: uncommited changes in schema.sql,提示开发者运行make dump-test-schema并提交改动,然后以非零码退出。
这保证了"迁移代码"与"生成的 Schema 快照"始终保持同步,防止出现迁移已改而 schema.sql 未更新的遗漏。
lint-go:全量 Go 静态检查
lint-go 同样是一行:
#!/bin/bash
make lint-go
对应的 Makefile 目标为:
lint-go: check-no-testing-in-prod check-nilaway-func-size
golangci-lint run --allow-serial-runners --timeout 15m
ifndef SKIP_INCREMENTAL
$(MAKE) lint-go-incremental
endif
它由三层组成:
- 前置门禁:
check-no-testing-in-prod:通过 tools/check-no-testing-in-prod 检查从cmd/fleet、cmd/fleetctl、orbit/cmd/orbit可达的 Fleet 自有包是否误引了testing;check-nilaway-func-size:通过 tools/check-nilaway-func-size 检查是否存在 CFG 块过多、超出 nilaway 分析能力的函数。
- 全量扫描:
golangci-lint run(超时 15 分钟)跑仓库级静态检查。 - 增量检查:默认执行
lint-go-incremental(可用SKIP_INCREMENTAL跳过),基于--new-from-merge-base=origin/main只对本次改动的新代码做增量 lint,兼顾全面性与速度。
贡献新 Hook 的约定
如果你要往 Fleet 的钩子体系里新增检查(或为 Fork 自用),git-hooks/README.md 给出了两条硬性约定:
- 退出码语义:
hooks/目录下的脚本"需要以非零码退出才能正确失败"(need to exit a non-zero code in order to fail properly)。pre-push调度器正是依据退出码决定是否放行。 - 无需可执行权限:因为统一由
pre-push以bash $SCRIPT_NAME方式调用,所以新脚本不必chmod +x。
所有相关代码集中在 git-hooks 目录。README 还列出了两条可选的贡献方向:更新或新增 hooks 目录下的脚本、搭建尚未成形的 ./git-hooks/frontend/ 前端检查体系(前端代码可参考 frontend 目录,如 make lint-js 对应的 eslint 检查)。
小结:把质量门禁搬到推送前
Fleet 的这套 pre-push 钩子给出了一个可复制、可扩展的本地检查范式:以一份 USED_HOOKS 声明清单编排检查顺序,以非零退出码作为统一失败信号,把最昂贵的 CI 资源留给真正需要跑完整测试集的改动。对 Fleet 开发者而言,compile-go 保证可构建、db-schema 保证迁移与 Schema 快照一致、lint-go 保证代码风格与静态质量——三者加在一起,显著压缩"推送→发现失败→重推"的循环成本。