Subscription

这一课你将能做到

1. 为本站「判题结果实时通知」设计并实现一条 Subscription
2. 说清楚 graphql-ws 与 SSE 两条传输路线的选型依据
3. 用 @defer / @stream 做增量交付，并理解它和 Subscription 的本质区别

为什么要学

判题是典型的异步场景：用户提交代码，后台队列判题，3 秒后出结果。轮询方案每 2 秒打一次接口，一万个在线用户就是每秒 5000 次无效请求；WebSocket 推送方案是服务端在结果就绪的那一刻主动告诉那一个人。Subscription 就是把「推送」纳入 GraphQL 类型系统的官方方式。

人话：Query 是「你去问」，Subscription 是「有消息我喊你」。

先建立图像

订阅的生命周期：

客户端                               服务端
  │  subscription { submissionStatusChanged(id:"s1") { status } }
  │ ────────────────────────────────────────────────────────────> 建立 WebSocket 连接，注册监听
  │                                                                │
  │            （判题机消费队列，状态变更，发布事件）                  │
  │  <──────────────────────────────────────────────────────────── 推送 { status: "RUNNING" }
  │  <──────────────────────────────────────────────────────────── 推送 { status: "ACCEPTED" }
  │  complete / 客户端断开                                          │ 关闭流

三种「实时」手段对比：

方案	底层	适用
Subscription over WebSocket	graphql-ws 协议	高频双向、事件流
Subscription over SSE	HTTP 长连接	服务端单向推、要穿代理
@defer / @stream	HTTP 分块传输	一次性查询的「先给骨架后补慢字段」

跟着做

步骤 1：定义订阅类型

type Subscription {
  "指定提交记录的状态变化（仅提交者本人可订阅）"
  submissionStatusChanged(submissionId: ID!): Submission!
  "我所在路线的公告"
  trackAnnouncement(trackSlug: String!): Announcement!
}

type Announcement { id: ID!, content: String!, publishedAt: DateTime! }

惯例：Subscription 字段的 resolver 返回一个事件流（Publisher/AsyncIterator），每次事件产出后，再按客户端声明的字段集走正常字段解析。

步骤 2：服务端发布事件（以 graphql-yoga 为例）

// 用进程内 PubSub 演示；生产换 Redis Pub/Sub 或 MQ
const pubsub = createPubSub()

const resolvers = {
  Mutation: {
    async judgeCallback(_, { submissionId, status }, { db }) {
      const sub = await db.submission.update({ where: { id: submissionId }, data: { status } })
      pubsub.publish('submission:changed', submissionId, sub)   // 事件触发
      return { submission: sub }
    }
  },
  Subscription: {
    submissionStatusChanged: {
      subscribe: (_, { submissionId }) =>
        pubsub.subscribe('submission:changed', submissionId),   // 返回 AsyncIterable
      resolve: (payload) => payload                              // 事件载荷 → 字段解析入口
    }
  }
}