用 Fleet 的 pre-push Git Hook 在推送前拦截代码问题:编译、Schema 与 Lint 一体化工作流

原创2026-09-19 20:08:471,878 阅读

用 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 源码可以发现,整个钩子是一个轻量级的"调度器":

  1. 定义钩子目录:HOOK_DIRECTORY="./git-hooks/backend/hooks";
  2. 遍历该目录下的所有文件(for SCRIPT in "$HOOK_DIRECTORY"/*),用 basename 取出文件名;
  3. 与 USED_HOOKS 数组中的目标逐个比对;命中的脚本通过 bash "$SCRIPT" 执行——这正是 hooks 目录中的脚本无需 chmod +x 的原因(见 git-hooks/README.md 的 Contributing 一节);
  4. 检查执行退出码: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

它由三层组成:

  1. 前置门禁:
    • 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 分析能力的函数。
  2. 全量扫描:golangci-lint run(超时 15 分钟)跑仓库级静态检查。
  3. 增量检查:默认执行 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 保证代码风格与静态质量——三者加在一起,显著压缩"推送→发现失败→重推"的循环成本。

登录后查看全文