PostgREST 开源贡献指南从 Issue 报告、开发环境搭建到提交规范的完整工作流【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest导读本文以 PostgREST 仓库根目录的 CONTRIBUTING.md 为骨架系统梳理向 PostgREST 贡献代码的完整路径如何规范地提交 Bug 报告、如何基于 Nix 搭建与官方一致的 Haskell 开发环境、如何运行全套测试与代码质量检查以及如何组织提交信息以通过自动化校验。读完本文你将掌握一套可复现、可验证、可合并的 PostgREST 贡献工作流并结合仓库内的 Nix 工具链nix/tools与测试套件test/深入理解每条规则的底层实现。贡献前的两个基本原则PostgREST 的贡献流程围绕两条硬性红线展开内容来源合规与代码质量可验证。首先是 AI 政策。仓库明确采纳 Gentoo 社区的 AI 政策明令禁止提交任何借助自然语言处理NLP人工智能工具生成的内容并保留根据版权、伦理与质量方面的考量重新评估该政策的权利。这意味着向 PostgREST 提交补丁时代码与文档必须完全由人工撰写。这一条写在 CONTRIBUTING.md 的最前面是参与贡献的前提条件。其次是可验证性。仓库的持续集成CI会在每个 Pull Request 上自动运行测试与代码风格检查所有贡献在合并前都必须通过测试。这两条原则贯穿下面每一个环节。报告 Issue如何高效反馈使用问题与 Bug使用问题与 Bug 报告的分流对于PostgREST 怎么用这类问题仓库建议优先使用 GitHub Discussions 讨论区而不是 Issue 跟踪器。Issue 只留给可复现的缺陷报告。报告 Bug 的四步规范先在最新版本上复现报告前务必同时测试最新的稳定版和最新的 devel开发版发布。Bug 很可能已在开发版中被修复先在两个版本上验证可以避免无效报告。提供完整复现步骤包括你的操作系统版本以及所使用的具体数据库 schema。PostgREST 的行为与数据库 schema 强耦合缺了 schema 就无法复现。附上 SQL 日志对涉及运行时问题的报告需要先开启 PostgreSQL 的记录全部语句log all statements配置再找到对应日志文件把相关 SQL 日志贴进 Issue。排除 schema cache 过期干扰如果 PostgREST 服务运行时数据库 schema 发生过变更应先向服务进程发送SIGUSR1信号或重启服务确保 schema cache 不是陈旧的——很多假 Bug其实源于缓存未刷新。SIGUSR1 与 schema cache 的底层原理为什么SIGUSR1能修复一些看似是 Bug 的现象从源码看PostgREST 需要从数据库系统目录中查询元数据如表、视图、关系、函数签名来构建 REST API 的抽象层这些元数据查询代价高昂因此被缓存为 schema cache见 docs/references/schema_cache.rst。数据库结构一旦变化而缓存未刷新API 行为就会与实际 schema 脱节。手动刷新缓存的命令如下详见 docs/references/schema_cache.rst# 直接对进程发信号 killall -SIGUSR1 postgrest # Docker 环境 docker kill -s SIGUSR1 container # docker-compose 环境 docker-compose kill -s SIGUSR1 service除了信号还可以从数据库内部用NOTIFY触发重载NOTIFY pgrst, reload schema;在测试代码中也能看到这一行为的验证例如 test/io/test_reloading.py 先通过SIGUSR2重载配置再用postgrest.process.send_signal(signal.SIGUSR1)触发 schema cache 重载并等待其完成印证了信号机制的端到端行为。值得注意的是schema cache 重载失败如statement_timeout或连接池超时时PostgREST 仍会以尽力而为的方式继续服务请求不会直接宕机。基于 Nix 的开发环境与 CI 完全一致的可复现工具链PostgREST 采用全 Nix 化的开发环境这是它与其他 Haskell 项目显著不同的地方。Nix 能快速、可靠地重建开发、测试与构建 PostgREST 所需的完整环境见 nix/README.md从而保证本地环境与 CI 环境完全一致杜绝在我机器上能跑的问题。进入开发环境安装 Nix 后在仓库根目录执行$ nix-shell这会进入一个包含正确版本的 GHCGlasgow Haskell Compiler和 Cabal 的新 shell。在nix-shell内可以正常执行 Cabal 命令也可以使用stack --nix让 stack 从 Nix 构建所固定的同一份 Nixpkgs 版本中获取非 Haskell 依赖见 nix/README.md。即装即用的 postgrest-* 工具族PostgREST 将开发工具统一封装为以postgrest-前缀命名的脚本放入nix-shell的 PATH。输入postgrest-后按 Tab 即可补全看到全部工具[nix-shell]$ postgrest-tab postgrest-build postgrest-cabal-update postgrest-check postgrest-clean postgrest-commitlint ...这些工具的 Nix 定义集中在 nix/tools/devTools.nix、nix/tools/tests.nix 与 nix/tools/style.nix 中。一次性执行某个命令可以用# 执行单条命令后退出 $ nix-shell --run postgrest-style # 需要传参时务必加引号 $ nix-shell --run postgrest-foo --bar需要注意nix-shell --run模式下 Tab 补全不可用Nix 尚未求值出可用的工具列表而在nix-shell交互式 shell 中工具可以从仓库内任意目录执行路径一律相对仓库根目录解析见 nix/README.md。构建与运行# 构建开发版二进制产物在 result/bin/postgrest $ nix-build --attr postgrestPackage # 构建静态链接二进制用 ldd 验证非动态可执行文件 $ nix-build --attr postgrestStatic $ ldd result/bin/postgrest $ not a dynamic executable建议配置 PostgREST 的 cachix 二进制缓存cachix use postgrest否则静态构建需要在 Musl 之上重新编译全部依赖耗时极长见 nix/README.md。代码提交的硬性门槛测试、文档与代码风格CONTRIBUTING.md 对代码贡献提出四条硬性要求所有贡献合并前必须通过测试——创建 Pull Request 后代码会被自动测试所有修复或新功能都必须附带证明其改进的测试所有新功能都必须补充文档关键修复若引入了新行为同样必须写文档所有代码必须通过 linter 和 styler 且无警告CI 会在每个 PR 上检查。postgrest-check提交前的本地总检仓库提供了postgrest-check命令做本地检查它与 CI 运行的检查基本一致不含最昂贵的 IO 与内存测试。CONTRIBUTING.md 建议将其挂到.git/hooks/pre-commit实现提交前自动检查nix-shell --run postgrest-check从 nix/tools/devTools.nix 可以看到postgrest-check实际串行执行了spec 测试、observability 测试、doctest、IO 测试、big-schema 测试、replica 测试以及postgrest-lint和postgrest-style-check。测试套件的全景仓库的测试体系可分为五层全部可在nix-shell中一键运行命令定义见 nix/tools/tests.nix测试类型命令说明Haskell spec 测试postgrest-test-spec核心功能测试底层为 hspec支持--match PATTERN按名称过滤IO 测试postgrest-test-io基于 pytest 的黑盒测试将 PostgREST 视为输入/输出黑箱observability 测试postgrest-test-observability可观测性指标、JWT 缓存、schema cache专项测试doctestpostgrest-test-doctests模块文档示例测试内存 / 负载测试postgrest-test-memory/postgrest-loadtest分别检查大请求体的内存阈值与性能不劣化基于 vegeta运行方式见 nix/README.md# 对最新版 PostgreSQL 运行全套 spec 测试 $ nix-shell --run postgrest-test-spec # 对所有受支持的 PostgreSQL 版本运行 $ nix-shell --run postgrest-with-all postgrest-test-spec # 对指定版本运行如 PG 17nix-shell 内 Tab 可补全版本 $ nix-shell --run postgrest-with-pg-17 postgrest-test-spec # pytest 风格的过滤与并行 [nix-shell]$ postgrest-test-io -k config [nix-shell]$ postgrest-test-io -n auto [nix-shell]$ postgrest-test-io -n 8 # 负载测试对 HEAD、对比其他分支、生成 CI 用的 markdown 报告 [nix-shell]$ postgrest-loadtest [nix-shell]$ postgrest-loadtest-against main [nix-shell]$ postgrest-loadtest-reportpostgrest-with-pg-*命令会附带一个临时数据库来运行指定命令不带with前缀的测试默认针对最新版 PostgreSQL。此外postgrest-watch command会在任何源文件变化时自动重跑命令例如postgrest-watch postgrest-with-all postgrest-test-spec会在每次改动后对全部 PostgreSQL 版本重跑全套测试见 nix/tools/devTools.nix。测试代码分别位于 test/specHaskell/hspec与 test/iopytest目录。linter 与 styler风格由 CI 强制代码风格检查由两个工具强制hlintlinter与stylish-haskellstyler。对应命令# Linting同时覆盖 GitHub workflows(actionlint)、Nix(deadnix)、Python(vultureruff)、Haskell(hlint) $ nix-shell --run postgrest-lint # 自动格式化 Haskell、Nix 与 Python 文件 $ nix-shell --run postgrest-style # 若格式化产生任何未提交改动则非零退出主要用于 CI $ nix-shell --run postgrest-style-check从 nix/tools/style.nix 可以看到postgrest-lint的完整检查面actionlint检查 GitHub Actions workflow、deadnix扫描 Nix 未使用代码、vulture与ruff检查 Python、hsie检查 Haskell import 别名一致性、hlint检查 Haskell 代码。postgrest-style则用nixpkgs-fmt格式化 Nix、stylish-haskell格式化 Haskell、black格式化 Python——这正是统一提交者风格的落地实现。覆盖率与 REPL# 运行全部测试并生成 ./coverage 目录浏览器打开 hpc_index.html 查看 [nix-shell]$ postgrest-coverage # 进入 GHCi REPL手动检查 PostgREST 模块 $ postgrest-repl ghci import PostgREST.MediaType ghci decodeMediaType application/json MTApplicationJSON组织 Pull Request 提交可拆分、可追溯、可自动化校验CONTRIBUTING.md 对 PR 分支的提交结构提出了明确要求目的是简化评审、必要时能轻松拆分 PR并保持干净有意义的提交历史。不合规的 PR 会被要求修改。分支与提交结构规则必须能以git merge --ff-only合并源分支必须基于目标分支 rebase保证纯快进合并源分支中不允许有 merge commit每个提交必须自包含每个提交应能当作一个独立 PR 处理每个提交只包含相关的改动一次提交只针对单一问题/目标例如重构必须与实际功能改动拆分为不同提交测试、文档与 CHANGELOG 更新必须与相关代码改动在同一提交内除非这些改动以独立 PR 形式提交。提交信息前缀由 commitlint 强制提交信息必须以 nix/tools/gitTools.nix 中定义的前缀开头。完整的类型枚举如下前缀含义add新增功能amend修订未发布的提交change破坏性变更breaking changeschore更新赞助商、changelog、readme 等ciCI 配置文件与脚本docs文档fix修复 Bugnix与 Nix 相关的改动perf性能改进refactor重构代码remove移除功能或修复test添加测试对应的校验脚本postgrest-commitlint同时执行 commitlint 的完整规则集见 nix/tools/gitTools.nix类型必须在上述枚举内、subject 不允许空、不允许以句号结尾、长度限制在 580 字符、不得使用 PascalCase/StartCase、scope 必须全小写、body 与 subject 之间必须空行。用法示例[nix-shell]$ postgrest-commitlint # 校验 main..HEAD 的提交 [nix-shell]$ postgrest-commitlint --from xxx --to yyy # 自定义区间提交信息的质量要求除了前缀合规提交信息还应包含较长的变更目的描述对于非平凡改动还需描述改动本身。这条规则配合每个提交只包含单一目标的改动使得整个 PR 历史既是评审的最小单元也是日后追溯问题根因的可靠索引。从 Issue 到合并完整贡献路径回顾把以上各环节串起来一次合规的 PostgREST 贡献流程是确认方向使用问题走 Discussions缺陷报告走 Issue 并提供 OS 版本、数据库 schema、SQL 日志与复现步骤搭建环境安装 Nix进入nix-shell获取与 CI 一致的 GHC/Cabal 与postgrest-*工具族编写代码同时准备测试test/spec的 hspec 或test/io的 pytest与文档docs 目录含 postgrest.dict 拼写词典本地验证nix-shell --run postgrest-check跑通全套检查并配置.git/hooks/pre-commit为nix-shell --run postgrest-check实现提交前自动把关组织提交rebase 到目标分支、无 merge commit、提交自包含、信息以规定前缀开头并通过postgrest-commitlint发起 PR由 CI 自动复跑全部测试与风格检查全部通过后方可合并。这套工作流之所以高效根本原因在于 PostgREST 把环境、测试、风格与提交规范全部代码化进了 nix 目录——环境用 Nix 固化检查用checkedShellScript封装提交规范用 commitlint 配置表达。任何贡献者进入仓库都能在完全一致的环境中验证自己的改动这正是大型开源项目维持长期可维护性的工程实践范本。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考