freehire 贡献者开发环境搭建完全指南：Make 命令、sqlc 再生成与 Pre-Commit 检查清单

【免费下载链接】freehirefreehire — the open-source search engine for job seekers项目地址https://gitcode.com/GitHub_Trending/fr/freehire点击查看免费下载freehire 是一个开源的工作搜索引擎job search engine从数百个 ATS 招聘平台持续抓取职位提供面状筛选、申请跟踪与 AI 分析能力。这篇指南帮助新贡献者从零搭起本地开发环境涵盖最实用的make命令速查、sqlc代码再生成流程以及一套与 CI 完全对齐的 pre-commit 检查清单。一、安装前置依赖在动手之前先确认本机具备以下工具详见 CONTRIBUTING.md 与 AGENTS.md工具用途说明Go 1.26后端编译与测试go.mod 声明go 1.26.9Docker 或 Podman启动本地全套服务Makefile 会自动探测docker 缺失时回退 podman也可用make DOCKERpodman up手动指定Node.js pnpm前端web/、design-system/构建与检查浏览器扩展extension/使用 npmlefthook、golangci-lint、gitleakspre-commit 钩子govulncheck可选缺失时仅告警克隆仓库并进入根目录git clone https://gitcode.com/gh_mirrors/fr/freehire cd freehire 约定俗成的第一条规则你必须理解自己提交的代码。小 PR 评审最快架构级改动建议先开 issue 对齐方案。二、make up 一键启动本地环境freehire 的所有本地服务Postgres Meilisearch Redis S3 API 前端都由 docker-compose.yml 编排一条命令即可拉起make up # 等价于 docker compose up --build -d curl localhost:8080/health curl localhost:8080/api/v1/jobs各服务与端口一览服务镜像默认端口dbPostgres 18 pgvectorpgvector/pgvector:pg185432meilisearch全文/面状搜索getmeili/meilisearch:v1.49.07700redis限流redis:7-alpine6379s3简历存储 mockadobe/s3mock:5.2.39000appGo API本地构建8080webSvelteKit SSR本地构建8090首次初始化卷时migrations/目录会挂载进/docker-entrypoint-initdb.d全部迁移自动执行。启动成功后本地职位列表页面长这样两个高频运维命令make down # 停止并移除容器 make logs # 跟踪应用日志compose logs -f app⚠️注意修改已存在的迁移文件不会重新应用到已有卷上。需要重置数据库时执行docker compose down -v make up或对已有卷手动补跑make migrate。三、两种本地开发模式全 Docker 模式make up前后端全部跑在容器里适合快速验证功能。宿主机进程模式数据库仍用容器服务器跑在宿主机上调试体验更好docker compose up -d db # 只启动数据库 make run # 宿主机上运行 server读取 DATABASE_URL宿主机模式下把 .env.example 复制为.env按需调整——JWT_SECRET是必填项缺失或不足 32 字节时服务器直接拒绝启动OAuth 与 LLM 凭据均为可选项不配置时对应功能自动降级为禁用。如果服务器跑在宿主机上部分功能还需要这些可执行文件在PATH中二进制包用途pdftotextpoppler-utilsCV 文本提取缺失时上传会报模糊的 invalid PDFtypst0.15.0静态发行版CV 的 PDF 导出缺失时 PDF 端点返回 501google-chrome/chromium可选仅自动投递等无头浏览器场景需要启动整套服务后你可以像真实用户一样体验 freehire 的面状筛选与保存过滤器四、Make 命令速查表Makefile 提供了完整开发工作流执行make help可随时查看全部命令命令作用make up/make down启动 / 停止全套容器make run在宿主机运行 API 服务器make build编译出bin/hire二进制make sqlc通过容器从 SQL 再生成数据库代码无需本地安装 sqlcmake reindex从 Postgres 全量重建 Meilisearch 职位索引make psql直接进入数据库容器的 psqlmake migrate对已有卷手动补跑迁移make tidygo mod tidy整理依赖make mail-preview渲染全部出站邮件并在浏览器打开预览make gen-contracts从 Go 契约类型再生成web/src/lib/generated/contracts.tsmake gen-cities从 GeoNames 数据再生成城市表make cv-previews从 CV 模板再生成 SVG 预览需 typstmake cover/cover-html单元测试覆盖率报告make cover-integration集成标签测试覆盖率需 Docker testcontainers五、sqlc 代码再生成流程freehire 用 sqlc 实现类型安全的数据库访问你不写 ORM你写 SQLGo 代码由 sqlc 生成。关键路径查询源文件internal/platform/db/queries/每个领域一张.sql文件模式来源migrations/生成物已提交入库internal/platform/db/sqlc.yaml 将模式指向migrations、查询指向internal/platform/db/queries输出到internal/platform/db驱动为pgx/v5。贡献者的铁律永远编辑queries/*.sql不要手改internal/platform/db/下的生成代码每次修改查询或迁移后立即执行make sqlc并提交再生成结果——该命令通过容器运行固定版本1.31.1的 sqlc团队之间零版本漂移永远不要修改已应用的迁移一律新增迁移文件expand/contract 策略。make sqlc # 一行完成docker run sqlc generatepre-commit 阶段有专门的sqlc-drift钩子替你兜底它会重新执行make sqlc如果发现 internal/platform/db/ 下出现未暂存的漂移包括从未提交的新文件直接拦截提交——改了查询却没再生成这种事故在本地就会被拦下。六、安装 pre-commit 钩子lefthook钩子配置集中在 lefthook.yml每个克隆只需安装一次go install github.com/evilmartians/lefthooklatest lefthook install主要检查项按职责分组钩子检查内容特点go-fmt/go-vet暂存的 Go 文件格式与静态检查基础卫生golangci-lint静态分析棘轮模式只对本次改动引入的新问题失败历史欠债不阻塞govulncheckGo 标准库/依赖漏洞当前仅告警warn-onlysqlc-drift生成代码是否过期自动再生成并比对sql-migrations新增迁移的 squawk 检查由 scripts/check-migrations.mjs 执行只查本次新增的迁移doc-links全仓库相对 Markdown 链接可达性scripts/check-doc-links.mjs防止文档链接悄悄失效gitleaks暂存区密钥扫描唯一预防而非报告的钩子未安装时直接失败拒绝假装扫描过web-lint/extension-lint前端 eslint分别覆盖web/与extension/design-system-*设计系统 lint / check / test / dist / tokens对齐design-systemCI 的快速检查 棘轮策略与 CI 完全一致所以本地通过 ≈ CI 通过gitleaks与 CI 的gitleaksworkflow 是两道闸门、两个时刻--no-verify跳过本地钩子后CI 仍会扫描全部历史。七、提交前自检清单与 CI 对齐改完代码、推送之前把这组命令跑一遍摘自 CONTRIBUTING.mdgofmt -l . # 必须无输出 go build ./... go vet ./... go test ./... # 单元测试无外部依赖 go vet -tagsintegration ./... # 廉价守卫编译带 integration 标签的文件秒级如果改动涉及 Docker 依赖行为查询、schema、handler再跑完整集成套件go test -tagsintegration ./... # 需要 Dockertestcontainers⚠️go test ./...不会编译任何//go:build integration文件——只改签名也能骗过前三条命令vet -tagsintegration是防漏网的最便宜保险建议每次推送前都执行。前端改动web/则按顺序构建design-system 必须先于消费方cd design-system pnpm install pnpm build cd ../web pnpm install pnpm run check pnpm run build提交前再生成清单——源变了产物必须一起提交改了internal/platform/db/queries/*.sql或migrations/→ 执行make sqlc改了 Go 契约类型 → 执行make gen-contracts八、常见问题速答8080 端口被占用换宿主机端口再启动HIRE_HOST_PORT8090 make upDB_HOST_PORT、MEILI_HOST_PORT同理。改了迁移但数据库没生效已初始化的卷不会重放迁移docker compose down -v make up重置或make migrate手动补跑。钩子报 Generated code was stale说明make sqlc刚替你修好了漂移把结果git add进本次提交即可。能用--no-verify跳过钩子吗能但 CI 会重新检查并扫描完整历史——本地跳过只是让红色结果来得更早一点。环境就绪后从一个小 PR 开始修一个 typo、补一个测试、给 cmd/ 下某个 worker 加文档都是被欢迎的贡献方式。祝提交顺利 赞分享【免费下载链接】freehirefreehire — the open-source search engine for job seekers项目地址https://gitcode.com/GitHub_Trending/fr/freehire点击查看免费下载相关推荐Tuist生成器开发环境搭建贡献者指南Tuist生成器开发环境搭建贡献者指南 作为一款用于管理Xcode项目的开源工具Tuist发音为toist已经被多家知名企业采用包括Monday.开发工具CLI后端云原生Citra 3DS 模拟器教程从安装到调参图形后端怎么选一次讲清Citra 3DS 模拟器教程从安装到调参图形后端怎么选一次讲清 Citra 是一款免费开源的 3DS 模拟器能把 .cia、.3ds 游戏文件完整搬到向Autoprompt贡献代码开发环境搭建、契约再生成与PR流程完全指南向Autoprompt贡献代码开发环境搭建、契约再生成与PR流程完全指南 Autoprompt 是一个 coding agent skill能将 agent上一篇端侧多模态新王之争MiniCPM-V 4.7、Qwen2.5-Omni 与 4.6谁配得上国产小钢炮下一篇从.pt到.om一条命令:Yolov11-ACC的ONNX→ATC导出链路与三方代理验证法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考