企业官网建设流程全解析

• 数据库
• 后端

本指南以仓库根目录 CONTRIBUTING.md 为主体，系统讲解 PgDog（PostgreSQL 连接池、负载均衡与分库分表代理）项目从零开始的本地开发环境搭建、必装工具链（cargo-nextest / cargo-watch）、PostgreSQL 测试库初始化，以及单元测试与多语言集成测试的完整运行流程。读完本文，你将掌握如何在本仓库中完成编译、跑通全部测试套件，并遵循项目编码规范提交高质量代码。

贡献流程概览

PgDog 采用基于 issue 与 fork 分支的贡献模式。官方指引明确：

• 发现 Bug 或希望请求新功能，请创建 issue；
• 提交 Bug 修复时，请 fork 仓库并给出你的分支链接；
• Pull Request 目前仅对项目贡献者开放，外部贡献者需通过 issue/分支形式参与。

从源码结构看，这是一个以 pgdog/Cargo.toml（version 0.1.61，edition 2024）为主包、附带pgdog-config、pgdog-plugin、pgdog-stats、pgdog-vector、pgdog-macros、pgdog-postgres-types等多个子 crate 的 Rust workspace。贡献者提交前需要确保自己的改动不会破坏这个多 crate 协作体系。

必装工具链：cargo-nextest 与 cargo-watch

为什么必须安装这两个工具

CONTRIBUTING.md 明确要求通过cargo install <name>安装两个 cargo 插件：

• cargo-nextest：PgDog 的测试运行器。仓库的测试基础设施深度依赖它——pgdog/src/test_utils.rs 中直接写明“Our test suite requires cargo-nextest, which uses a process-per-test model”（测试套件要求 cargo-nextest 的“每测试一个进程”模型），因此代码中才敢使用env::set_var这类在并发测试中不安全的 API。用普通cargo test替代会导致测试行为不可靠甚至并发污染。
• cargo-watch：文件变更监听器，配合integration/dev-server.sh实现“改代码自动重编译并重启 PgDog”的开发循环。

安装方式

cargo install cargo-nextest cargo install cargo-watch

如果使用了mise作为开发工具版本管理，可以直接在仓库根目录执行：

mise install

仓库根目录的 mise.toml 已经声明了工具依赖：

[tools] "rust" = { version = "1.96.0" } "cargo:cargo-nextest" = "latest" "cargo:cargo-watch" = "latest"

同时 rust-toolchain.toml 固定了 Rust 工具链版本并启用了 rustfmt 与 clippy 组件：

[toolchain] channel = "1.96" components = ["rustfmt", "clippy"] profile = "default"

注意：cargo install方式与 mise 方式二选一即可，二者最终都会把插件二进制放入 cargo bin 目录。

开发环境搭建（六步走）

CONTRIBUTING.md 给出的开发环境搭建步骤如下，结合仓库脚本可展开为以下完整流程：

第 1 步：编译项目

cargo build

建议直接构建带测试的二进制，后续单元测试会更快：

cargo build --tests

第 2 步：安装 PostgreSQL

要求安装 PostgreSQL（官方说明支持“所有 Pg 版本”，即 all Pg versions supported）。从 integration/ci/setup.sh 看，CI 环境甚至升级到了 PostgreSQL 18；而 integration/setup.sh 使用psql命令行连接本地127.0.0.1:5432，所以本地开发时请确保 PostgreSQL 监听在本机 5432 端口。

第 3 步：创建 pgdog 用户

psql -c "CREATE USER pgdog LOGIN SUPERUSER PASSWORD 'pgdog'"

密码为pgdog。实际上 integration/setup.sh 会自动创建 4 个测试角色：pgdog、pgdog1、pgdog2、pgdog3，全部使用密码pgdog，因此这一步通常可以由第 4 步的脚本代劳。

第 4 步：运行环境初始化脚本

bash integration/setup.sh

这是最关键的一步。该脚本做三件事：

（1）校验并调整 PostgreSQL 服务端参数。脚本用psql -tAc "SELECT current_setting(...)"读取当前值，不满足最小值则执行ALTER SYSTEM SET ...，修改后_pg_needs_restart置为 true 并退出。需要的参数如下：

⚠️ 脚本注释明确：ALTER SYSTEM 不能在函数/DO 块内执行，所以检查用 bash 完成。如果脚本检测到任何参数被修改，会打印 “PostgreSQL settings changed. Restart PostgreSQL and re-run this script.” 并exit 1——此时必须重启 PostgreSQL，然后重新运行脚本，才能继续后续步骤。

（2）重建测试数据库与角色。脚本会依次DROP/CREATE用户pgdog pgdog1 pgdog2 pgdog3以及数据库pgdog shard_0 shard_1 shard_2 shard_3，并在每个数据库里创建分片测试表（sharded、sharded_omni、sharded_varchar、sharded_uuid、sharded_list*、sharded_range*、sharded_mapping_hierarchy等），最后执行 pgdog/src/backend/schema/setup.sql 安装pgdogschema 下的分片辅助函数与触发器（next_id_seq、install_trigger、install_shard_id等）。

（3）准备 toxiproxy（故障注入工具）。若本机没有toxiproxy-server/toxiproxy-cli，脚本会自动从 GitHub Releases 下载 v2.12.0 对应平台二进制到integration/目录，用于故障切换类集成测试。

GitHub Actions 环境下脚本还会额外执行ALTER USER "$(id -un)" PASSWORD 'pgdog' LOGIN;，这是 “GitHub fix”，保证 CI runner 用户也能以pgdog密码登录。

第 5 步：运行单元测试

cargo nextest run

如果某个测试失败，官方建议直接单独运行该测试（“try running it directly”），例如：

cargo nextest run <test_name>

单元测试分布在主 crate 与各子 crate 中，例如 pgdog/src/main.rs 在#[cfg(test)]下引入test_utils与tests模块，auth、admin、backend、api 等模块也都内嵌了大量#[cfg(test)] mod tests。

第 6 步：运行集成测试

bash integration/run.sh

或只跑某一门语言的集成测试，例如：

bash integration/go/run.sh

集成测试体系详解

总入口与子套件

integration/run.sh 是总入口，但它只分发 4 个套件：

bash python/run.sh bash ruby/run.sh bash java/run.sh bash sql/run.sh

而 integration/common.sh 是共享基础设施：定义NODE_ID=pgdog-dev-1，提供run_pgdog()（负责cargo build并以后台进程启动target/debug/pgdog --config integration/pgdog.toml --users integration/users.toml）、wait_for_pgdog()（用pg_isready -h 127.0.0.1 -p 6432 -U pgdog -d pgdog轮询就绪）、stop_pgdog()（发 SIGTERM，30 秒后强制 SIGKILL）等函数。因此每个子套件的 run.sh 都遵循同一模式：启动 PgDog → 等待就绪 → 跑测试 → 停止 PgDog。典型例子见 integration/rust/run.sh：

#!/bin/bash set -e SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) source ${SCRIPT_DIR}/../common.sh run_pgdog wait_for_pgdog bash ${SCRIPT_DIR}/dev.sh stop_pgdog

集成测试套件覆盖多种语言与场景（仓库integration/下可见）：go（go_pgx / go_pq / go_gorm）、rust（sqlx / tokio_postgres）、python（asyncpg / psycopg / sqlalchemy）、ruby、java、js、elixir、haskell、php，以及load_balancer、prefer_primary、failover、resharding、two_pc、toxi、complex、mirror、plugins、schema_sync、copy_data、vault、dry_run、pgbench等功能套件。各套件均有自己的run.sh，例如 integration/complex/run.sh 依次运行passthrough_auth、cancel_query、session_listen、protocol_version四个子场景。

Rust 集成测试与测试分片

integration/rust/dev.sh 展示了集成 profile 的用法与 CI 分片支持：

cargo nextest run --profile integration ${NEXTEST_SHARD:+--partition count:${NEXTEST_SHARD} --no-fail-fast}

• --profile integration：使用 Cargo 中定义的 integration 测试 profile；
• NEXTEST_SHARD：CI 多机并行时按count:N分片，--no-fail-fast保证一个分片失败不中断其他分片。

CI 环境对照

本地流程与 CI 基本一致。CI 前置脚本 integration/ci/install-deps.sh 会在 runner 上安装 mold、gdb、psql 18 客户端、固定版本（默认 0.9.78）的 cargo-nextest、cargo-llvm-cov 与 cmake；integration/ci/setup.sh 则负责启动 PostgreSQL 集群、以--with-toxi可选参数挂载 toxiproxy，然后调用同一个 integration/setup.sh。这意味着本地只需跑通 setup.sh，环境即与 CI 对齐。

开发热循环：cargo-watch 的正确用法

CONTRIBUTING.md 安装 cargo-watch 的目的在 integration/dev-server.sh 中体现得淋漓尽致：

#!/bin/bash set -e THIS_SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) source ${THIS_SCRIPT_DIR}/setup.sh source ${THIS_SCRIPT_DIR}/toxi/setup.sh pushd ${THIS_SCRIPT_DIR}/../ export NODE_ID=pgdog-dev-1 CMD="cargo run -- --config ${THIS_SCRIPT_DIR}/pgdog.toml --users ${THIS_SCRIPT_DIR}/users.toml" if [[ -z "$1" ]]; then cargo watch --shell "${CMD}" else ${CMD} fi popd

用法：

# 监听文件变化，自动重新编译并重启 PgDog（默认模式） bash integration/dev-server.sh # 传任意参数则只启动一次，不监听 bash integration/dev-server.sh once

注意该脚本会先source setup.sh与toxi/setup.sh（toxiproxy 代理 5435–5438 端口到 5432，见 integration/toxi/setup.sh），再以--config integration/pgdog.toml --users integration/users.toml启动。integration/pgdog.toml是一个覆盖连接池、负载均衡、分片表映射、TLS、admin 等配置的开发用完整配置，integration/users.toml则定义了pgdog、pgdog_2pc、pgdog_session、pgdog_pass等测试用户（含 SCRAM 密码哈希、session 模式、two_phase_commit 等特性）。

编码规范：fmt、clippy 与测试义务

CONTRIBUTING.md 的 “Coding” 部分给出三条硬性要求：

1. 代码必须用cargo fmt格式化；
2. 尽量运行cargo clippy；
3. 必须编写并包含测试——官方原话是 “This is production software used in one of the most important areas of the stack.”（这是运行在技术栈最关键位置的线上软件）。

主 crate 的 clippy 要求可以从 pgdog/src/main.rs 看到具体约束：#![deny(clippy::print_stdout)]禁止直接打印 stdout（日志必须走 tracing），#![warn(clippy::large_futures)]提醒关注大 future。此外测试分配器也做了专门处理：非测试构建使用 jemalloc，测试构建切换为stats_alloc::INSTRUMENTED_SYSTEM（pgdog/src/main.rs），便于统计测试内存行为。

常见问题与排错清单

结合脚本逻辑，整理出本地开发最常遇到的几个问题：

总结

一套可复现的 PgDog 开发流程可以浓缩为三条命令：

cargo build # 编译 bash integration/setup.sh # 配置 PostgreSQL 参数并重建测试库（参数变更后需重启 PG 再跑一次） cargo nextest run # 单元测试 bash integration/run.sh # 集成测试（或 bash integration/<lang>/run.sh 跑单套件）

在此基础上，用cargo watch（bash integration/dev-server.sh）做热重载开发，提交前执行cargo fmt与cargo clippy，并为每个改动补上测试——这就是 PgDog 贡献者的标准工作流。所有细节均可对照仓库中的 CONTRIBUTING.md、integration/setup.sh、integration/run.sh 与 integration/common.sh 进一步验证。

• 数据库
• 后端