企业官网建设流程全解析

• 后端
• API网关

本文以 PostGraphile v5 官方文档 connections.md 为骨架，结合仓库内presets/v4.ts、presets/relay.ts、behavior 文档与测试用例等源码级证据展开。读完你将掌握：为什么 PostGraphile 默认用 Connection 而非纯列表、它对 Relay 游标规范的增强点（totalCount/nodes/PageInfo）、如何用 behavior 体系在连接与列表之间切换、以及如何做公平的基准测试对比。

为什么 PostGraphile 默认返回 Connection 而不是数组

当一个 GraphQL 字段预期返回大量数据库记录时，PostGraphile 默认不会返回一个朴素的数组（list），而是实现一个符合 GraphQL Cursor Connections Specification 的连接（connection），并在此基础上做少量增强。这在 GraphQL 社区被视为最佳实践，原因在于连接形态为 Schema 的后续演进留下了空间：

• 可以在连接层面扩展聚合（aggregation）能力，例如aggregates、groupedAggregates字段；
• 可以通过edges暴露连接本身携带的元信息（例如多对多连接表上的字段）；
• 游标分页在“数据不断新增”的无限滚动场景（如新闻流）中表现稳定，是普通分页无法提供的特性。

从源码结构看，连接相关行为由 graphile-build 系列插件的 behavior 系统驱动，behavior.md 中列出了connection、resource:connection、resource:connection:filter、resource:connection:order、resource:connection:backwards等核心行为片段，PostGraphile 正是通过这些行为决定是否为一个资源生成连接字段。

PostGraphile 在 Relay 连接规范之上的三项增强

除了 Relay 规范标准的edges、pageInfo、first/last/before/after之外，PostGraphile 的连接额外提供：

一个典型的查询示例：

query UsersPage($first: Int!, $after: Cursor) { users(first: $first, after: $after) { totalCount nodes { id username } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } }

仓库的测试用例中随处可见对这三项增强的验证，例如postgraphile/postgraphile/__tests__/queries/polymorphic/目录下的*.test.graphql文件就包含totalCount字段的查询断言（如person-app-vulns.app-totalCount.test.graphql、returns-setof.test.graphql），而edges { ... }的标准遍历方式同样有大量测试覆盖（如person-log-entries.after-caroline.test.graphql）。测试输入文件.json5、预期 SQL 与 mermaid 执行计划图与之一一对应，是研究连接如何被解析为数据库查询的一手资料。

连接与过滤：condition参数

来自表、视图和关系的多数连接都支持过滤（filtering），即通过condition参数按等值条件筛选结果，例如：

query UsersByCategory($category: ArticleCategory!) { users(condition: { category: $category }) { nodes { id username category } } }

过滤的详细用法见 filtering.md。需要特别注意的是，默认情况下 PostGraphile（非 V4 preset）不允许按未建立索引的列进行过滤；若要强制某列出现在过滤选项中，可对该列施加@behavior filterBy智能标签，用@behavior -filterBy则可强制移除。在 v4.ts 的entityBehavior中可以看到类似逻辑：tsvector/tsquery、数组/范围类型以及二进制类型会被自动加上-condition:attribute:filterBy，以保证过滤行为不会对未索引或不适合过滤的列生效。

性能建议：Connection 还是 List？

连接比纯列表更复杂，因此带有一定的性能开销。PostGraphile 官方文档的立场是：这通常是值得的权衡，因为连接带来的未来扩展空间（版本无关 Schema 理想）和游标分页能力，是普通分页无法替代的。但如果你对性能极其敏感，或更喜欢简单列表，完全可以通过 behaviors 配置偏好。

全局关闭连接、开启列表

在graphile.config.mjs中设置defaultBehavior：

const preset = { schema: { defaultBehavior: "-connection +list", }, }; export default preset;

效果：PostGraphile 生成列表（list）字段而不再生成连接（connection）字段。

同时保留两者

如果希望两种形态并存，可配置为：

const preset = { schema: { defaultBehavior: "+connection +list", }, };

按实体粒度精确控制

你还可以通过 智能标签 smart tags 对单个表、视图、列甚至虚拟约束进行@behavior覆盖（详见 smart-tags.md 中@behavior一节，它支持comment on table ... is '...'这样的数据库注释形式）。这意味着“全局默认连接、个别实体改列表”或反之都完全可行。

从源码看 behavior 如何落地

defaultBehavior是全局默认行为，优先级低于实体自身行为；最终行为字符串由“插件默认行为 → 全局默认行为 → 插件推断行为 → 实体行为”逐级拼接，越靠后的优先级越高（见 behavior.md 的“Determining entity behavior”一节）。

仓库中的两个 preset 是很好的对照样本：

• v4.ts 中的 V4 兼容插件把旧的simpleCollections选项（"only" | "both" | "omit"）翻译成行为字符串："only"对应-connection -resource:connection list resource:list，"both"对应两者都开启，"omit"则偏好连接并禁用列表。这是从 V4 迁移到 V5 时控制集合形态的便捷入口。
• relay.ts 中的实验性PgRelayPlugin则通过globalBehavior设置了connection、-list等行为，让 Schema 更贴合 Relay 的习惯（如将id作为 nodeId 字段名、优先连接而非列表）。

排查某实体最终行为时，官方提供了一条调试命令：

npx graphile behavior debug

它由utils/graphile/src/cli.ts注册（见 cli.ts），子命令实现位于 utils/graphile/src/commands/behavior/debug/cli.ts，可传入实体类型、标识与过滤字符串，快速确认是哪些行为片段胜出及其原因。

基准测试：务必保证对比公平

文档特别强调：比较两个 GraphQL 服务器性能时，必须保证双方要么都用列表、要么都用连接，否则对比毫无意义。PostGraphile 默认采用连接（最佳实践），而许多其他实现默认返回列表，二者在生成 SQL 与执行计划上的差异会直接污染测试结果。

如果你看到某篇研究论文在对比不同 GraphQL 服务器性能时没有做到这种基本等价性，那么它的结论至少是存疑的，官方建议不要依据这类低质量研究做任何决策。

若要与其他软件进行公平对比，可以参考以下思路：

1. 通过上文defaultBehavior: "-connection +list"让 PostGraphile 生成列表；
2. 或通过 V4 兼容插件的simpleCollections: "only"（对应 v4.ts 的选项）快速切换到纯列表模式；
3. 目标 schema 若有其他差异（如命名、过滤参数、空值策略），PostGraphile 高度可配置，可进一步调整使其与目标 schema 尽可能相似——这正是文档所承诺的：虽然默认使用连接等最佳实践，但你可以轻松更改设置以匹配那些以性能或简洁性优先的其它方案。

小结

PostGraphile v5 的连接机制围绕 Relay 游标分页规范构建，并附加totalCount、nodes、PageInfo.startCursor/endCursor三项实用增强；默认行为可以在defaultBehavior、插件globalBehavior与实体级智能标签三个层面灵活调节，兼顾最佳实践与性能诉求。无论是构造带过滤的分页查询、在连接与列表间切换，还是设计公平的基准测试，理解本文所述的 behavior 体系与源码对应关系，都能让你更精准地驾驭 PostGraphile 的 Schema 形态。

延伸阅读（仓库内相关文档）

• 过滤（Filtering）：condition参数的完整说明与高级过滤方案
• 行为系统（Behavior）：行为字符串语法、优先级与核心行为清单
• 智能标签（Smart Tags）：@behavior等标签的数据库注释写法
• 关系（Relations）：多对一/一对多关系字段与连接的配合

• 后端
• API网关