PgDog 配置 crate 的文档注释规范：一份注释同时驱动 Rustdoc 与 JSON Schema

• 数据库
• 后端

PgDog 是一个用 Rust 编写的 PostgreSQL 连接池、负载均衡与分库分表中间件，其全部配置类型集中在独立的pgdog-configcrate 中。本指南围绕 pgdog-config/CONTRIBUTING.md 展开，讲解该 crate 的一套核心工程约定：每一个pub结构体、枚举与字段都必须携带///文档注释，而这份注释会同时被 Rustdoc 与 schemars 读取，分别生成 API 文档和 JSON Schema。读完本文，你将掌握 pgdog-config 文档注释的完整格式规范、字段/结构体/枚举/枚举变体四类注释模板、风格约束，以及如何在实际开发中保持注释与官方文档同步。

为什么一份注释要承担两重使命

在 pgdog-config 中，///注释不是普通的代码注释，而是面向两类消费方的"双重交付物"：

1. Rustdoc：cargo doc会把///注释渲染为 crate 的 API 文档，这是 Rust 生态中最常规的用法。
2. JSON Schema：crate 依赖 schemars 与根 Cargo.toml 中schemars = { version = "1.2.1", ... }），schemars 会读取同一份///注释，将其写入生成 schema 的description字段中。这些 schema 随后出现在编辑器自动补全、schema 校验器以及任何消费该 schema 的工具链里。

从源码结构看，JsonSchemaderive 几乎覆盖了 pgdog-config 的每个配置模块——auth.rs、core.rs、database.rs、general.rs、memory.rs、networking.rs、otel.rs、pool.rs、rewrite.rs、users.rs、vault.rs等均通过use schemars::JsonSchema;引入并派生，模块清单见 pgdog-config/src/lib.rs。

由于同一段文字要同时面向"读 API 文档的开发者"和"读 schema 的机器/工具链"，注释必须满足三个要求：准确（描述必须与真实行为一致）、自包含（脱离上下文也能读懂）、与官方文档保持同步（即 docs.pgdog.dev 上的配置文档）。

字段（Field）注释模板

字段是配置项的最小单元，也是注释规范最严格的对象。标准模板如下：

/// Short description of what this field controls. /// /// **Note:** Any important caveat or warning. /// /// _Default:_ `value` /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/{page}/#{anchor}> pub field_name: Type,

模板由四部分组成，按顺序排列：

• 字段描述：一句话说明该字段控制什么行为；
• **Note:**段落：标注任何重要警告或注意事项（例如"需要重启生效""仅企业版支持""不要在生产环境使用"）；
• _Default:_ \value``：仅当字段存在有意义的默认值时使用，斜体标签 + 反引号值；
• 文档链接：以<https://docs.pgdog.dev/...>形式结尾，指向对应的配置文档页面与锚点；只有那些没有对应文档页面的内部字段才允许省略 URL。

源码中的真实范例

pgdog-config/src/general.rs 中host与port字段是教科书级示范：

/// The IP address of the local network interface PgDog will bind to listen for connections. /// /// **Note:** This setting cannot be changed at runtime. /// /// _Default:_ `0.0.0.0` /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/general/#host> #[serde(default = "General::host")] pub host: String, /// The TCP port PgDog will bind to listen for connections. /// /// **Note:** This setting cannot be changed at runtime. /// /// _Default:_ `6432` /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/general/#port> #[serde(default = "General::port")] pub port: u16,

这里同时展示了注释规范与 serde 属性（#[serde(default = ...)]）的配合——注释中声明的默认值0.0.0.0、6432与Default实现中的取值一致，确保文档、schema 与运行时行为三者对齐。

再看 pgdog-config/src/general.rs 中listen_backlog字段，它示范了"描述要解释底层机制"的写法：注释不仅给出默认值1024，还解释了该值会被传给listen(2)、实际生效值受内核net.core.somaxconn上限约束，并给出调优场景（滚动部署时大量客户端同时重连）。这种细节正是"自包含"的体现——schemars 会把整段描述写入 schema 的description，IDE 悬浮提示即可呈现完整上下文。

结构体（Struct）注释模板

结构体对应 pgdog.toml 中的一个配置区块，模板为：

/// What this configuration section controls. /// /// **Note:** Any important caveat, if present. /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/{page}/> pub struct Foo { ... }

真实范例见 pgdog-config/src/rewrite.rs，Rewrite结构体的注释还示范了如何用行内 Markdown 链接补充关键背景：

/// Controls PgDog's automatic SQL rewrites for sharded databases. It affects sharding key updates and multi-tuple inserts. /// /// **Note:** Consider enabling [two-phase commit](https://docs.pgdog.dev/features/sharding/2pc/) when either feature is set to `rewrite`. Without it, rewrites are committed shard-by-shard and can leave partial changes if a transaction fails. /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/rewrite/> #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)] #[serde(deny_unknown_fields)] pub struct Rewrite { ... }

注意这里的**Note:**承担了关键的工程提示：当shard_key或split_inserts设置为rewrite时建议启用两阶段提交，否则分片逐个提交可能在事务失败时留下部分更改。这类"警告"信息经由 schema 的description字段传递给使用方，能在配置阶段就预警风险。

枚举（Enum）与枚举变体注释模板

枚举的注释使用名词短语描述枚举代表的语义，模板为：

/// Noun phrase describing what the enum represents. /// /// <https://docs.pgdog.dev/configuration/pgdog.toml/{page}/#{anchor}> pub enum Bar { ... }

枚举变体只需一行说明，且不在变体上重复 URL——枚举级别的链接已覆盖全部变体：

/// One line: what this variant means or does. VariantName,

pgdog-config/src/vault.rs 中的VaultAuthMethod是完整范例：

/// How PgDog authenticates to Vault. #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash, JsonSchema)] #[serde(rename_all = "snake_case")] pub enum VaultAuthMethod { /// Kubernetes auth: log in with the pod's service account JWT. Kubernetes, /// AppRole auth: log in with a role ID and secret ID. Approle, }

pgdog-config/src/rewrite.rs 中的RewriteMode则示范了变体注释如何承载默认值与行为语义：

pub enum RewriteMode { /// Forward the query unchanged. Ignore, /// Return an error to the client (default). #[default] Error, /// Automatically rewrite the query and execute it. Rewrite, /// Rewrite only for omnisharded tables. RewriteOmni, /// Rewrite only for omnisharded tables and use global sequence instead of unique ID. RewriteOmniGlobal, }

同样，pgdog-config/src/general.rs 的LogFormat枚举给出了带#[default]标注变体的写法，且三个变体分别对应text、json、json_flattened三种日志格式（serde(rename_all = "snake_case")负责 TOML 中的命名映射）。

风格规则（Style Rules）

除模板结构外，CONTRIBUTING 文档还明确了统一的风格约束：

• 允许行内 Markdown 链接：在能补充上下文时使用，例如[two-phase commit](https://docs.pgdog.dev/features/sharding/2pc/)；
• _Default:_ \value``：斜体标签 + 反引号值，不可写成其他形式；
• **Note:**：加粗标签，不使用 blockquote>；
• 标题不要尾随标点；不要使用冠词开头；名词性标题一律小写；
• 不要重复类型已表达的信息——例如不要在布尔字段上写"a boolean that enables…"，因为pub enabled: bool的类型已经说明它是开关。

注释如何变成 JSON Schema：生成链路

文档注释到 JSON Schema 的转换由仓库中的独立工具完成。入口位于 scripts/jsonschema/src/main.rs，核心逻辑只有两步：

use schemars::{Schema, schema_for}; use pgdog_config::Config; use pgdog_config::Users; write_schema("pgdog", schema_for!(Config))?; write_schema("users", schema_for!(Users))?;

schema_for!宏在编译期基于JsonSchemaderive 生成 schema 对象，随后被serde_json::to_writer_pretty写入工作区根目录下的.schema/pgdog.schema.json与.schema/users.schema.json（见 scripts/jsonschema/src/main.rs）。也就是说：

• Config（pgdog.toml 的全部配置）→pgdog.schema.json；
• Users（users.toml 的全部配置）→users.schema.json。

这份 schema 的description字段即来自每个字段/结构体/枚举的///注释——这就是为什么"注释必须准确、自包含、与官方文档同步"是硬性要求：任何一处注释错误都会同时污染 API 文档、schema 校验提示与 IDE 自动补全。

保持与官方文档同步的工作流

CONTRIBUTING 文档为贡献者定义了明确的双向同步流程：

当修改字段行为或新增字段时：

1. 查看 docs.pgdog.dev 上对应的配置页面；
2. 更新///注释以反映当前真实行为；
3. 若标题（heading）变更，同步更新 URL 锚点。

当官方文档站点独立更新时：

• 注释需要相应更新以保持一致。

这一流程与注释模板中的文档链接要求一脉相承：每个注释末尾的<https://docs.pgdog.dev/configuration/pgdog.toml/{page}/#{anchor}>就是代码与文档之间的"跟踪指针"，锚点变更时注释必须跟上，否则链接会失效。

同步技巧与常见误区

结合源码中的真实注释，可以总结出几条实用经验：

• 默认值必须与Default实现一致：注释写_Default:_ \0.0.0.0`，代码中的General::host默认函数就必须返回0.0.0.0`（见 pgdog-config/src/general.rs）。schema 消费方可能据此生成默认配置，不一致会造成运行时行为与文档不符；
• 警告优先用**Note:**承载：例如 pgdog-config/src/vault.rs 中approle_secret_id_file的注释会提示"若未设置，secret ID 将从VAULT_SECRET_ID环境变量读取"，这类信息对运维排障价值极高；
• 内部字段可以省略 URL：没有对应文档页面的内部字段不必强行伪造链接，但描述仍要完整（例如 pgdog-config/src/users.rs 中插件config字段只给描述不给 URL）；
• 不要写"a boolean that enables…"式的冗余描述：类型本身已经表达了语义，注释应聚焦"控制什么、默认什么、注意什么"。

结语

pgdog-config 的注释规范把"写文档"变成了"写一份同时被三种工具消费的元数据"：Rustdoc 面向开发者、schemars 面向工具链、docs.pgdog.dev 面向最终用户。理解这套规范的模板与同步流程，是向该 crate 贡献代码或消费其配置 schema 的前提。对需要为Config/Users之外的配置类型添加 schema 覆盖、或希望在自己项目中复刻"注释驱动文档 + schema"模式的开发者，scripts/jsonschema/src/main.rs 与 pgdog-config/Cargo.toml 就是最直接的参考起点。

• 数据库
• 后端