后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载PostGraphile当前位于 Graphile Crystal Monorepo 中为 GraphQL API 提供了一整套可定制的实时Realtime能力核心内置了基于事件的Subscriptions订阅与处于实验阶段的响应式Live Queries实时查询其余能力通过插件自由组合。本文将围绕 version-4/realtime.md 的核心脉络逐一解析两种实时模型的适用场景、GraphQL 写法、启用方式与底层实现帮助你为应用选择并落地正确的实时方案。一、实时能力的两大模型事件驱动 vs 响应式PostGraphile 的实时能力分为两类理解它们的本质区别是选型的第一步维度Subscriptions订阅Live Queries实时查询模型事件驱动Event-based响应式Reactive触发条件服务端特定事件发生查询结果集发生变化GraphQL 规范属于最新 GraphQL 规范客户端生态支持良好尚不属于规范仍在演进各后端实现方式不一服务端开销相对较低可扩展性强较高结果需反复重算核心适用场景明确知道什么事件会触发更新、关注事件本身关注状态变化、希望页面自动保持最新PostGraphile 的设计哲学是可定制、可扩展核心提供基线级别的订阅与实时查询能力其余通过官方插件、社区插件或内部自研插件组合实现因此你可以根据需求自由选择最适合的技术栈来为 PostGraphile 提供实时特性而不是接受一刀切的方案。二、Subscriptions基于事件的订阅Subscriptions 是当服务端某个特定事件发生时主动向客户端推送一条新消息的机制。2.1 一个典型的订阅请求subscription { chatMessageAdded(channel: 27) { id message author { id name avatarUrl } timestamp } }上面的示例订阅会在频道27新增消息时触发一次新的响应。需要注意的是普通订阅只在事件发生即聊天消息被添加时触发——它不会在消息被编辑、或作者更换头像时触发。2.2 何时使用 Subscriptions你确切知道哪些事件会触发更新你关注的是事件本身例如广播而不是状态的改变性能与可扩展性是强诉求时它的服务端开销远低于实时查询。2.3 启用与实现路径在 PostGraphile 中启用订阅的入口是--subscriptions标志库模式下为subscriptions: true。从当前仓库源码看该选项在 presets/v4.ts 中被定义为V4Options的布尔选项并映射为 grafserv 的websockets: options.subscriptions配置presets/v4.ts即开启 WebSocket 端点CLI 侧对应--subscriptions选项描述为若 schema 支持则通过 WebSocket 启用 GraphQL 订阅cli.ts。订阅字段本身由插件提供。官方推荐的实时提供插件是graphile/pg-pubsub它基于 PostgreSQL 内置的LISTEN/NOTIFY实现生产环境推荐并支持两种用法自定义订阅Custom Subscriptions通过makeExtendSchemaPlugin结合pgSubscription(topic: ...)指令按需定义精确的订阅字段与载荷类型例如根据 JWT 中的用户 ID 动态计算 topic简单订阅Simple Subscriptions通过--simple-subscriptions标志暴露一个通用的listen(topic: String!): ListenPayload字段可用任意 PostgreSQL topic 直接触发无需提前规划。从当前仓库源码可见简单订阅的实现在 PgV4SimpleSubscriptionsPlugin.ts 中listen字段通过 grafast 的listen($pgSubscriber, $derivedTopic, jsonParse, $initialEvent)步骤订阅 topic并将 topic 统一加上postgraphile:前缀(topic) \postgraphile:${topic}见 [PgV4SimpleSubscriptionsPlugin.ts](https://link.gitcode.com/i/d16f68d5e5827d2f9e7a11590c667a3a#L51-L54)以避免与应用使用的其他 topic 冲突ListenPayload还提供relatedNode/relatedNodeId字段可通过 NOTIFY 消息 JSON 中的node数组表名 主键携带任意记录返回对应的 GraphQL Node。注意 PostgreSQL 频道名默认为 63 字符扣除postgraphile:前缀后 topic 名只剩 50 字符。此外你还可以用subscriptionAuthorizationFunction 指定一个数据库函数对 topic 做鉴权函数返回的字符串对应的 topic 被发布时该订阅会被自动终止。三、Live Queries响应式的实时查询Live Queries实时查询会在查询结果集可能发生任何变化时通知客户端。它是 PostGraphile v4.4.0 提供的实验性功能。3.1 一个典型的实时查询请求subscription { allUsersList(condition: { firstName: Alice }) { id name friendsList { id name } } }只要以下任一情况发生新的结果集就会自动推送给客户端返回的任意一个 Alice 发生变化有 Alice 被添加或删除某个 Alice 新增或失去朋友某个 Alice 的朋友改了名字——即任何会导致原始响应结果改变的变化都会触发推送。3.2 与规范的关系及兼容性策略Live queries 尚未被纳入 GraphQL 规范截至文档撰写时各后端实现方式各不相同。PostGraphile 刻意使用标准的subscription操作类型来最大化与你现有工具链的兼容性而不是采用基于指令directive的方案——客户端完全无法区分订阅与实时查询因为这是服务端关心的事。3.3 何时使用 Live Queries希望服务端数据一变页面就自动更新例如股票价格的实时走势图希望把多次更新批量合并推送给客户端例如客户端被过多事件淹没时有一个小查询需要监控——实时查询的查询越小越好因为每次变化都会重新计算并发送整个结果集这与普通 GraphQL 恰恰相反想要充分感受 GraphQL 的表达能力。3.4 启用方式与实时提供插件启用实时查询需要两个条件详见 live-queries.mdx传递--live库模式为live: true提供一个能向 PostGraphile 报告实时数据变化的实时提供插件realtime provider plugin。官方首个实时提供插件是graphile/subscriptions-lds它通过 PostgreSQL 的逻辑解码Logical Decoding特性即逻辑复制槽技术与 PostgreSQL 只读副本保持主库同步所用的机制类似高效地获取数据变更流从而在不过度增加数据库负载的前提下判断相关变化。当变化发生时若影响任何实时查询PostGraphile 会重新执行该查询并推送结果从而始终尊重数据库权限RLS并避免缓存导致的陈旧数据。数据库侧准备修改postgresql.confwal_level logical max_wal_senders 10 max_replication_slots 10并安装wal2json扩展通常不到 10 秒git clone https://github.com/eulerto/wal2json.git cd wal2json USE_PGXS1 make USE_PGXS1 make installCLI 启用复制接口权限很强因此除普通连接串外还需提供一个具有提升权限的--owner-connection数据库属主/超级用户连接串若你本就以超级用户/属主运行 PostGraphile 且未使用 RLS 等则可省略postgraphile \ --connection postgres://postgraphile_user:postgraphile_passhost/db \ --live \ --owner-connection postgres://db_owner:db_owner_passhost/db \ --append-plugins graphile/subscriptions-lds \ ...库模式启用app.use( postgraphile(process.env.AUTH_DATABASE_URL, SCHEMA, { // ... live: true, // Enable live support in PostGraphile ownerConnectionString: process.env.ROOT_DATABASE_URL, // elevated privileges for logical decoding appendPlugins: [ //... require(graphile/subscriptions-lds).default, ], }), );把查询变成实时查询启用后只需把普通查询的操作类型改为subscription{ allPeople { nodes { name } } }改为subscription { allPeople { nodes { name } } }3.5 关键环境变量配置环境变量默认值作用与调优建议LD_WAIT125每多少毫秒检查一次数据库变化。调小更新更及时但开销增加调大更高效但每个批次处理更久可能拖慢 Node.js 事件循环LIVE_THROTTLE500同一订阅两次实时更新之间的最小间隔毫秒。服务器过载时调大、应用响应不及时则调小节流在首尾沿都会触发因此调小只影响连续更新不影响首次更新LD_TABLE_PATTERN\*.\*例如设为app_public.*只监控指定 schema 的表对应 wal2json 的filter-tables参数通过忽略无关数据提升性能3.6 性能、扩展与已知限制成本高昂实时查询远比普通订阅昂贵——服务端要监控返回的每条记录还要监控集合的新增/移除含过滤条件且变化来源多、频率高。务必让查询尽量小因为结果内任何变化都会触发整条查询重算。惊群效应thundering herd若上千用户订阅同一数据数据更新时会同时向数据库发起上千条 SQL 查询。可通过让实时查询只覆盖一部分用户来缓解PostGraphile 为每个客户端提供独立的节流回调使回调错峰。调优建议白名单限制可用的实时查询用小而不重叠的查询20 个小查询优于 1 个大查询与普通查询相反用LD_TABLE_PATTERN忽略无关数据调大LIVE_THROTTLE/LD_WAIT可将逻辑解码系统移至专用服务器。扩展多实例部署时可用LDS_URL指向共享的专用实时解码服务器LDS即graphile/lds项目由它统一消费复制槽。字段命名默认实时字段与Query类型同名且会经过liveinflector可通过 inflection 系统定制。限制graphile/subscriptions-lds目前无法检测视图、函数、计算列computed columns产生的变化计算列仅在表更新触发订阅时被重算被监控的表必须有主键且主键建议为int或uuid——bigint/bigserial在 JSON 序列化为数字时可能因JSON.parse精度丢失而导致数据发散。Amazon RDS需在 AWS 参数组中将rds.logical_replication设为1并重启数据库再以超级用户执行grant rds_replication to DB_OWNER;DB_OWNER为建库角色名注意 RDS 自带的wal2json版本略旧。四、Subscriptions 还是 Live Queries选型建议综合来看两种方案各有明确的使用边界追求性能与规模化优先使用 Subscriptions它是 GraphQL 规范的一部分客户端支持成熟服务端只需响应明确的事件关注状态而非事件、或希望批量合并更新选择 Live Queries但要控制查询规模、注意惊群问题大规模线上部署官方目前不建议面向百万级并发用户的场景大规模使用实时查询每个用户订阅同一数据时重算成本极高更推荐使用 Subscriptions或把实时查询限制在应用的极小范围内。PostGraphile 对两者都做了不少成本优化但实时查询仍有演进空间。设计实时功能时应当先明确业务事件边界再决定是事件驱动还是响应式必要时两者可以组合用 Subscriptions 处理明确的业务事件如新消息、权限变更用 Live Queries 处理需要自动保持最新的小型结果集。五、深入阅读Realtime 总览本文依据Subscriptions 详解含自定义订阅、简单订阅、topic 前缀、安全与完整演练Live Queries 详解含逻辑解码、环境变量、性能与 RDS 配置PostGraphile v4 配置项源码subscriptions/simpleSubscriptions选项定义简单订阅插件源码listen字段与postgraphile:前缀实现CLI 选项源码--subscriptions定义赞分享后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载相关推荐RedwoodJS GraphQL Realtime 实战指南Subscriptions、Live Queries 与 Defer/Stream 指令RedwoodJS GraphQL Realtime 实战指南Subscriptions、Live Queries 与 Defer/Stream 指令 导读后端前端Web框架开发工具Crystal PostGraphile实时订阅与Live Queries完全指南打造即时更新的GraphQL APICrystal PostGraphile实时订阅与Live Queries完全指南打造即时更新的GraphQL API Crystal 是 Graphi后端API网关FreeTodo高级技巧自定义AI提示词提升任务处理效率FreeTodo高级技巧自定义AI提示词提升任务处理效率 FreeTodo是一款强大的AI驱动任务管理工具能够自动管理个人任务上下文帮助用户更高效地处理日人工智能AI 应用大模型AI AgentRAG后端前端桌面应用上一篇FXGL 开源项目常见问题解决方案下一篇Damselfly未来路线图探索下一代AI驱动的照片管理体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考