Connections
When a GraphQL field is expected to return a large list of database records, we typically implement a connection adhering to the GraphQL Cursor Connections Specification (with a few enhancements). This connection allows you to perform cursor-based pagination with ease, and is seen as a GraphQL best practice because it leaves space for you to neatly expand your schema with additional functionality, for example adding aggregation support across the connection or exposing join-table fields via the connection edges.
当某个 GraphQL 字段预计会返回大量数据库记录时,我们通常会实现一个遵循 GraphQL Cursor Connections Specification 的 Connection(并附带几项增强特性)。借助 Connection,你可以轻松实现基于 cursor 的游标分页;同时它也被视为 GraphQL 最佳实践,因为它预留了良好的扩展空间——例如在整个 Connection 上添加聚合查询支持,或通过 Connection 的 edge 暴露关联表(join table)字段。
The enhancements that we apply on top of Relay’s connection spec include:
我们在 Relay Connection 规范之上额外提供的增强特性包括:
-
totalCount- the total number of records matching the query (excluding cursor/limit/offset constraints); note that this doescount(*)and thus has a performance overheadtotalCount—— 匹配当前查询条件的总记录数(不包含 cursor、limit、offset 限制);注意这会执行count(*)查询,因此会带来一定的性能开销 -
nodes- just the nodes (noedgewrapper) useful if you don’t need the cursor for every entry and want a simple data structurenodes—— 直接返回节点列表(省去外层edge包装),如果你不需要每条记录对应的 cursor、更青睐简洁的数据结构,这会非常实用 -
PageInfo.startCursorandPageInfo.endCursor- useful for pagination if you usenodes { ... }rather thanedges { cursor, node { ... } }PageInfo.startCursor与PageInfo.endCursor—— 当你使用nodes { ... }而非edges { cursor, node { ... } }进行分页时尤为有用
Many connections (specifically those coming from tables, views and relations) support filtering the return results with a condition.
许多 Connection(特别是基于表、视图和 relation 生成的)都支持按条件过滤返回结果。
Advice使用建议
Connections are a bit more complex than lists and thus have a performance overhead. This is generally a justified trade-off in that it gives you more future flexibility (meaning you can stick to GraphQL’s “versionless schema” ideal) and a feature that regular pagination cannot give you (namely cursor pagination, which is highly effective in infinite scrolling contexts where the underlying data is constantly being added to, such as news feeds). However, if performance is critical to you or if you prefer simple lists over GraphQL connections then you can use behaviors to configure your preferences. To enable lists and disable connections, you might add something like this to your preset:
Connection 的结构比普通列表略微复杂,因此会带来一定的性能开销。但在多数场景下,这种权衡非常划算:它能为未来演进保留更大的灵活性(助你践行 GraphQL“无版本化 schema”的理念),并提供常规分页无法替代的能力——即 cursor 分页,这在信息流等底层数据持续新增的无限滚动场景中尤为高效。不过,如果性能对你至关重要,或者你更偏爱简洁的列表而非 GraphQL Connection,可以通过 behavior 进行调整。要在 preset 中启用列表并禁用 Connection,可以这样配置:
const preset = {
schema: {
defaultBehavior: "-connection +list",
},
};
You can also enable both with +connection +list. You can even configure this
on a per-entity basis with smart tags if you like!
你也可以通过 +connection +list 同时启用两者。如果有需要,甚至还可以利用 smart tag 按单个数据库实体粒度来单独配置!
Benchmarking基准测试
If you’re comparing the performance of two GraphQL servers be sure to make sure
the comparison is fair by using either lists on both or connections on both.
You can have PostGraphile generate lists rather than connections by using the
defaultBehavior setting detailed in the advice above.
如果你在对比两个 GraphQL 服务的性能,务必确保两边同时使用列表或同时使用 Connection,以保证对比公平。你可以参照上文建议中的 defaultBehavior 设置,让 PostGraphile 生成列表而非 Connection。
If you read a research paper comparing performance of different GraphQL servers and they don’t ensure basic equivalence by using either lists on both or connections on both then the results of that research are questionable at best. We advise that you don’t base any decisions on such low effort research.
如果某篇对比不同 GraphQL 服务性能的评测文章没有在列表或 Connection 上保持基本的对等条件,那么其结论的可信度至多存疑。我们建议不要依据这类不够严谨的评测来作任何技术选型决策。
Should you wish to do a fair comparison between PostGraphile and any other software feel free to reach out for advice on how to make the PostGraphile schema as similar as possible to the target schema. PostGraphile is highly configurable and although it uses best practices such as connections by default you can easily change settings to match other offerings which may have defaults that prioritize performance or simplicity over GraphQL best practices.
如果你想在 PostGraphile 与其他方案之间做一次公平的横向对比,欢迎随时联系我们,了解如何把 PostGraphile 生成的 schema 调整得与目标 schema 尽可能一致。PostGraphile 具备极高的可配置性:虽然它默认遵循 Connection 等最佳实践,但你完全可以轻松修改配置去对齐其他方案的默认行为——有些工具出于性能或简洁性考量,默认策略会弱化 GraphQL 最佳实践。