Realtime on PlumePHP

gRPC流式通信实战：双向流、服务端推送与实时数据处理

Sun, 08 Mar 2026 11:00:00 +0800

引言

gRPC不仅支持传统的请求-响应模式，还提供了强大的流式通信能力。流式RPC在实时数据推送、大文件传输、双向通信等场景中具有显著优势。

gRPC四种通信模式

gRPC通信模式对比：
┌─────────────────────────────────────────┐
│ 1. Unary RPC（一元RPC） │
│ Client ──── Request ────▶ Server │
│ Client ◀─── Response ──── Server │
│ 最常用，类似HTTP请求 │
│ │
│ 2. Server Streaming（服务端流） │
│ Client ──── Request ────▶ Server │
│ Client ◀─── Stream ────── Server │
│ 服务端持续推送数据 │
│ │
│ 3. Client Streaming（客户端流） │
│ Client ──── Stream ─────▶ Server │
│ Client ◀─── Response ──── Server │
│ 客户端持续上传数据 │
│ │
│ 4. Bidirectional Streaming（双向流） │
│ Client ◀──▶ Stream ◀──▶ Server │
│ 双方独立地读写流 │
│ 最灵活，最复杂 │
└─────────────────────────────────────────┘

Protocol Buffer定义

syntax = "proto3";

package streamservice;

option go_package = "github.com/example/streamservice";

// 一元RPC
service ChatService {
 rpc SendMessage(Message) returns (MessageAck);
 
 // 服务端流：订阅频道消息
 rpc SubscribeChannel(ChannelRequest) returns (stream Message);
 
 // 客户端流：批量发送消息
 rpc SendMessages(stream Message) returns (BatchAck);
 
 // 双向流：实时聊天
 rpc Chat(stream Message) returns (stream Message);
}

// 日志服务
service LogService {
 // 服务端流：实时日志
 rpc StreamLogs(LogRequest) returns (stream LogEntry);
 
 // 客户端流：批量上报日志
 rpc UploadLogs(stream LogEntry) returns (UploadResult);
}

// 文件服务
service FileService {
 // 客户端流：上传文件
 rpc UploadFile(stream FileChunk) returns (UploadResult);
 
 // 服务端流：下载文件
 rpc DownloadFile(FileRequest) returns (stream FileChunk);
 
 // 双向流：断点续传
 rpc TransferFile(stream FileTransferMsg) returns (stream FileTransferMsg);
}

message Message {
 string id = 1;
 string channel_id = 2;
 string user_id = 3;
 string content = 4;
 int64 timestamp = 5;
 MessageType type = 6;
}

enum MessageType {
 TEXT = 0;
 IMAGE = 1;
 FILE = 2;
 SYSTEM = 3;
}

message MessageAck {
 string message_id = 1;
 bool success = 2;
 string error = 3;
}

message BatchAck {
 int32 total_received = 1;
 int32 total_success = 2;
 repeated string failed_ids = 3;
}

message ChannelRequest {
 string channel_id = 1;
 string user_id = 2;
 int64 since_timestamp = 3;
}

message LogRequest {
 string service_name = 1;
 LogLevel min_level = 2;
 string pattern = 3;
}

enum LogLevel {
 DEBUG = 0;
 INFO = 1;
 WARN = 2;
 ERROR = 3;
}

message LogEntry {
 string service_name = 1;
 LogLevel level = 2;
 string message = 3;
 int64 timestamp = 4;
 map<string, string> metadata = 5;
}

message UploadResult {
 bool success = 1;
 int64 total_received = 2;
 string file_id = 3;
}

message FileChunk {
 string file_id = 1;
 int64 offset = 2;
 bytes data = 3;
 bool is_last = 4;
 FileMeta meta = 5;
}

message FileMeta {
 string filename = 1;
 int64 total_size = 2;
 string content_type = 3;
 string checksum = 4;
}

message FileRequest {
 string file_id = 1;
 int64 offset = 2;
 int32 chunk_size = 3;
}

message FileTransferMsg {
 oneof payload {
 TransferRequest request = 1;
 FileChunk chunk = 2;
 TransferAck ack = 3;
 TransferComplete complete = 4;
 }
}

message TransferRequest {
 string file_id = 1;
 int64 offset = 2;
 Direction direction = 3;
}

enum Direction {
 UPLOAD = 0;
 DOWNLOAD = 1;
}

message TransferAck {
 int64 received_offset = 1;
 bool success = 2;
}

message TransferComplete {
 string file_id = 1;
 string checksum = 2;
}

服务端流实现

实时消息订阅

package server

import (
 "fmt"
 "log"
 "sync"
 "time"
 
 pb "github.com/example/streamservice/proto"
 "google.golang.org/grpc/codes"
 "google.golang.org/grpc/status"
)

type ChatServer struct {
 pb.UnimplementedChatServiceServer
 
 mu sync.RWMutex
 channels map[string][]chan *pb.Message
 messageStore map[string][]*pb.Message
}

func NewChatServer() *ChatServer {
 return &ChatServer{
 channels: make(map[string][]chan *pb.Message),
 messageStore: make(map[string][]*pb.Message),
 }
}

// 服务端流：订阅频道消息
func (s *ChatServer) SubscribeChannel(req *pb.ChannelRequest, stream pb.ChatService_SubscribeChannelServer) error {
 channelID := req.ChannelId
 userID := req.UserId
 
 log.Printf("User %s subscribing to channel %s", userID, channelID)
 
 // 创建消息通道
 msgChan := make(chan *pb.Message, 100)
 
 s.mu.Lock()
 s.channels[channelID] = append(s.channels[channelID], msgChan)
 s.mu.Unlock()
 
 // 确保退出时清理
 defer func() {
 s.mu.Lock()
 chans := s.channels[channelID]
 for i, ch := range chans {
 if ch == msgChan {
 s.channels[channelID] = append(chans[:i], chans[i+1:]...)
 break
 }
 }
 s.mu.Unlock()
 close(msgChan)
 log.Printf("User %s unsubscribed from channel %s", userID, channelID)
 }()
 
 // 先发送历史消息
 s.mu.RLock()
 if messages, ok := s.messageStore[channelID]; ok {
 for _, msg := range messages {
 if msg.Timestamp > req.SinceTimestamp {
 if err := stream.Send(msg); err != nil {
 s.mu.RUnlock()
 return err
 }
 }
 }
 }
 s.mu.RUnlock()
 
 // 持续监听新消息
 for {
 select {
 case msg, ok := <-msgChan:
 if !ok {
 return nil
 }
 if err := stream.Send(msg); err != nil {
 return err
 }
 case <-stream.Context().Done():
 return stream.Context().Err()
 }
 }
}

// 发送消息（会触发流推送）
func (s *ChatServer) SendMessage(ctx context.Context, msg *pb.Message) (*pb.MessageAck, error) {
 msg.Id = generateID()
 msg.Timestamp = time.Now().UnixMilli()
 
 // 存储消息
 s.mu.Lock()
 s.messageStore[msg.ChannelId] = append(s.messageStore[msg.ChannelId], msg)
 
 // 广播给所有订阅者
 if chans, ok := s.channels[msg.ChannelId]; ok {
 for _, ch := range chans {
 select {
 case ch <- msg:
 default:
 log.Printf("Warning: subscriber channel full, dropping message")
 }
 }
 }
 s.mu.Unlock()
 
 return &pb.MessageAck{
 MessageId: msg.Id,
 Success: true,
 }, nil
}

实时日志流

type LogServer struct {
 pb.UnimplementedLogServiceServer
 
 logCollector *LogCollector
}

func (s *LogServer) StreamLogs(req *pb.LogRequest, stream pb.LogService_StreamLogsServer) error {
 serviceName := req.ServiceName
 minLevel := req.MinLevel
 pattern := req.Pattern
 
 log.Printf("Streaming logs for service=%s, minLevel=%v, pattern=%s",
 serviceName, minLevel, pattern)
 
 // 创建日志过滤器
 filter := &LogFilter{
 ServiceName: serviceName,
 MinLevel: minLevel,
 Pattern: pattern,
 }
 
 // 订阅日志流
 logChan := s.logCollector.Subscribe(filter)
 defer s.logCollector.Unsubscribe(filter, logChan)
 
 for {
 select {
 case entry := <-logChan:
 if err := stream.Send(entry); err != nil {
 return err
 }
 case <-stream.Context().Done():
 return nil
 }
 }
}

type LogCollector struct {
 mu sync.RWMutex
 subscribers map[*LogFilter]chan *pb.LogEntry
}

type LogFilter struct {
 ServiceName string
 MinLevel pb.LogLevel
 Pattern string
}

func (c *LogCollector) Subscribe(filter *LogFilter) chan *pb.LogEntry {
 c.mu.Lock()
 defer c.mu.Unlock()
 
 ch := make(chan *pb.LogEntry, 256)
 c.subscribers[filter] = ch
 return ch
}

func (c *LogCollector) Unsubscribe(filter *LogFilter, ch chan *pb.LogEntry) {
 c.mu.Lock()
 defer c.mu.Unlock()
 
 delete(c.subscribers, filter)
 close(ch)
}

func (c *LogCollector) Collect(entry *pb.LogEntry) {
 c.mu.RLock()
 defer c.mu.RUnlock()
 
 for filter, ch := range c.subscribers {
 if matchesFilter(entry, filter) {
 select {
 case ch <- entry:
 default:
 // 通道满，丢弃
 }
 }
 }
}

func matchesFilter(entry *pb.LogEntry, filter *LogFilter) bool {
 if filter.ServiceName != "" && entry.ServiceName != filter.ServiceName {
 return false
 }
 if entry.Level < filter.MinLevel {
 return false
 }
 if filter.Pattern != "" {
 matched, _ := regexp.MatchString(filter.Pattern, entry.Message)
 return matched
 }
 return true
}

客户端流实现

批量消息发送

func (s *ChatServer) SendMessages(stream pb.ChatService_SendMessagesServer) error {
 var totalReceived int32
 var totalSuccess int32
 var failedIDs []string
 
 for {
 msg, err := stream.Recv()
 if err == io.EOF {
 return stream.SendAndClose(&pb.BatchAck{
 TotalReceived: totalReceived,
 TotalSuccess: totalSuccess,
 FailedIds: failedIDs,
 })
 }
 if err != nil {
 return err
 }
 
 totalReceived++
 
 // 处理消息
 msg.Id = generateID()
 msg.Timestamp = time.Now().UnixMilli()
 
 if err := s.processMessage(msg); err != nil {
 failedIDs = append(failedIDs, msg.Id)
 log.Printf("Failed to process message: %v", err)
 continue
 }
 
 totalSuccess++
 }
}

日志批量上传

func (s *LogServer) UploadLogs(stream pb.LogService_UploadLogsServer) error {
 var totalReceived int64
 batch := make([]*pb.LogEntry, 0, 100)
 
 for {
 entry, err := stream.Recv()
 if err == io.EOF {
 // 处理剩余的批次
 if len(batch) > 0 {
 if err := s.flushBatch(batch); err != nil {
 log.Printf("Failed to flush final batch: %v", err)
 }
 }
 
 return stream.SendAndClose(&pb.UploadResult{
 Success: true,
 TotalReceived: totalReceived,
 })
 }
 if err != nil {
 return err
 }
 
 totalReceived++
 batch = append(batch, entry)
 
 // 达到批次大小，刷盘
 if len(batch) >= 100 {
 if err := s.flushBatch(batch); err != nil {
 log.Printf("Failed to flush batch: %v", err)
 }
 batch = batch[:0]
 }
 }
}

func (s *LogServer) flushBatch(batch []*pb.LogEntry) error {
 // 批量写入数据库或Elasticsearch
 return s.logStorage.BulkInsert(batch)
}

文件上传

func (s *FileServer) UploadFile(stream pb.FileService_UploadFileServer) error {
 var fileID string
 var file *os.File
 var totalBytes int64
 var meta *pb.FileMeta
 
 for {
 chunk, err := stream.Recv()
 if err == io.EOF {
 file.Close()
 
 // 验证文件大小
 if meta != nil && totalBytes != meta.TotalSize {
 os.Remove(file.Name())
 return status.Errorf(codes.DataLoss,
 "file size mismatch: expected %d, got %d",
 meta.TotalSize, totalBytes)
 }
 
 // 验证校验和
 if meta != nil && meta.Checksum != "" {
 actualChecksum := calculateChecksum(file.Name())
 if actualChecksum != meta.Checksum {
 os.Remove(file.Name())
 return status.Errorf(codes.DataLoss,
 "checksum mismatch: expected %s, got %s",
 meta.Checksum, actualChecksum)
 }
 }
 
 return stream.SendAndClose(&pb.UploadResult{
 Success: true,
 TotalReceived: totalBytes,
 FileId: fileID,
 })
 }
 if err != nil {
 return err
 }
 
 // 第一个chunk包含文件元信息
 if file == nil {
 fileID = chunk.FileId
 if fileID == "" {
 fileID = generateID()
 }
 
 if chunk.Meta != nil {
 meta = chunk.Meta
 }
 
 filePath := fmt.Sprintf("/storage/files/%s", fileID)
 file, err = os.Create(filePath)
 if err != nil {
 return status.Errorf(codes.Internal, "failed to create file: %v", err)
 }
 }
 
 // 写入数据
 n, err := file.WriteAt(chunk.Data, chunk.Offset)
 if err != nil {
 file.Close()
 os.Remove(file.Name())
 return status.Errorf(codes.Internal, "failed to write chunk: %v", err)
 }
 
 totalBytes += int64(n)
 
 if chunk.IsLast {
 file.Close()
 return stream.SendAndClose(&pb.UploadResult{
 Success: true,
 TotalReceived: totalBytes,
 FileId: fileID,
 })
 }
 }
}

双向流实现

实时聊天

func (s *ChatServer) Chat(stream pb.ChatService_ChatServer) error {
 // 获取用户信息（从metadata）
 md, ok := metadata.FromIncomingContext(stream.Context())
 if !ok {
 return status.Error(codes.Unauthenticated, "missing metadata")
 }
 
 userID := md.Get("user_id")[0]
 channelID := md.Get("channel_id")[0]
 
 log.Printf("User %s joined chat in channel %s", userID, channelID)
 
 // 注册到频道
 msgChan := make(chan *pb.Message, 100)
 s.mu.Lock()
 s.channels[channelID] = append(s.channels[channelID], msgChan)
 s.mu.Unlock()
 
 // 发送加入通知
 joinMsg := &pb.Message{
 Id: generateID(),
 ChannelId: channelID,
 UserId: "system",
 Content: fmt.Sprintf("User %s joined the chat", userID),
 Timestamp: time.Now().UnixMilli(),
 Type: pb.MessageType_SYSTEM,
 }
 
 s.broadcastToChannel(channelID, joinMsg)
 
 // 退出时清理
 defer func() {
 s.mu.Lock()
 chans := s.channels[channelID]
 for i, ch := range chans {
 if ch == msgChan {
 s.channels[channelID] = append(chans[:i], chans[i+1:]...)
 break
 }
 }
 s.mu.Unlock()
 close(msgChan)
 
 // 发送离开通知
 leaveMsg := &pb.Message{
 Id: generateID(),
 ChannelId: channelID,
 UserId: "system",
 Content: fmt.Sprintf("User %s left the chat", userID),
 Timestamp: time.Now().UnixMilli(),
 Type: pb.MessageType_SYSTEM,
 }
 s.broadcastToChannel(channelID, leaveMsg)
 
 log.Printf("User %s left chat in channel %s", userID, channelID)
 }()
 
 // 双向通信
 errChan := make(chan error, 2)
 
 // 接收消息
 go func() {
 for {
 msg, err := stream.Recv()
 if err != nil {
 errChan <- err
 return
 }
 
 msg.Id = generateID()
 msg.UserId = userID
 msg.Timestamp = time.Now().UnixMilli()
 
 s.broadcastToChannel(channelID, msg)
 }
 }()
 
 // 发送消息
 go func() {
 for msg := range msgChan {
 if err := stream.Send(msg); err != nil {
 errChan <- err
 return
 }
 }
 }()
 
 // 等待错误或上下文取消
 select {
 case err := <-errChan:
 if err == io.EOF {
 return nil
 }
 return err
 case <-stream.Context().Done():
 return stream.Context().Err()
 }
}

客户端调用示例

订阅消息流

package main

import (
 "context"
 "io"
 "log"
 
 pb "github.com/example/streamservice/proto"
 "google.golang.org/grpc"
)

func subscribeMessages() {
 conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
 if err != nil {
 log.Fatal(err)
 }
 defer conn.Close()
 
 client := pb.NewChatServiceClient(conn)
 
 stream, err := client.SubscribeChannel(context.Background(), &pb.ChannelRequest{
 ChannelId: "general",
 UserId: "user123",
 SinceTimestamp: 0,
 })
 if err != nil {
 log.Fatal(err)
 }
 
 for {
 msg, err := stream.Recv()
 if err == io.EOF {
 break
 }
 if err != nil {
 log.Printf("Error receiving message: %v", err)
 break
 }
 
 fmt.Printf("[%s] %s: %s\n", 
 time.UnixMilli(msg.Timestamp).Format("15:04:05"),
 msg.UserId,
 msg.Content)
 }
}

双向聊天客户端

func chatClient() {
 conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
 if err != nil {
 log.Fatal(err)
 }
 defer conn.Close()
 
 client := pb.NewChatServiceClient(conn)
 
 ctx := metadata.AppendToOutgoingContext(context.Background(),
 "user_id", "user123",
 "channel_id", "general")
 
 stream, err := client.Chat(ctx)
 if err != nil {
 log.Fatal(err)
 }
 
 // 接收消息
 go func() {
 for {
 msg, err := stream.Recv()
 if err != nil {
 log.Printf("Error: %v", err)
 return
 }
 fmt.Printf("[%s] %s: %s\n",
 time.UnixMilli(msg.Timestamp).Format("15:04:05"),
 msg.UserId, msg.Content)
 }
 }()
 
 // 发送消息（从stdin读取）
 scanner := bufio.NewScanner(os.Stdin)
 for scanner.Scan() {
 msg := &pb.Message{
 Content: scanner.Text(),
 Type: pb.MessageType_TEXT,
 }
 if err := stream.Send(msg); err != nil {
 log.Printf("Send error: %v", err)
 break
 }
 }
}

流式通信最佳实践

流式通信最佳实践：
┌─────────────────────────────────────────┐
│ 1. 背压控制 │
│ - 使用带缓冲的channel │
│ - 监控发送队列长度 │
│ - 队列满时丢弃或断开连接 │
│ │
│ 2. 心跳保活 │
│ - 定期发送ping/pong │
│ - 检测连接是否存活 │
│ - 超时自动断开 │
│ │
│ 3. 流量控制 │
│ - 使用gRPC窗口大小控制 │
│ - 限制单个消息大小 │
│ - 限制并发流数量 │
│ │
│ 4. 错误处理 │
│ - 优雅处理stream关闭 │
│ - 支持断线重连 │
│ - 记录详细的错误日志 │
│ │
│ 5. 资源清理 │
│ - 使用defer确保资源释放 │
│ - 监控活跃流数量 │
│ - 设置合理的超时时间 │
│ │
│ 6. 消息确认 │
│ - 重要消息需要ACK │
│ - 支持消息重传 │
│ - 记录消息序列号 │
└─────────────────────────────────────────┘

总结

gRPC流式通信选型

模式	适用场景	复杂度	性能
Unary	简单请求-响应	低	高
Server Stream	实时推送、日志流	中	高
Client Stream	批量上传、数据采集	中	高
Bidirectional	聊天、协作编辑	高	中

关键原则

选择合适的模式：不要过度使用双向流
实现背压控制：防止慢消费者拖垮系统
心跳保活：检测并清理死连接
优雅关闭：确保资源正确释放
监控指标：跟踪活跃流数量、消息吞吐量
错误恢复：支持断线重连和消息重传

GraphQL订阅与实时更新：构建响应式数据流架构

Wed, 18 Feb 2026 14:30:00 +0800

引言

GraphQL订阅为应用提供了实时数据推送能力，相比传统轮询方式更高效、更及时。本文将深入讲解GraphQL订阅的架构设计与实战实现。

GraphQL订阅核心概念

GraphQL订阅工作流：
┌─────────┐ ┌─────────┐
│ Client │ │ Server │
└────┬────┘ └────┬────┘
 │ │
 │ 1. WebSocket连接建立 │
 │ ─────────────────────────▶ │
 │ │
 │ 2. 发送订阅请求 │
 │ subscription { │
 │ messageAdded { │
 │ id content userId │
 │ } │
 │ } │
 │ ─────────────────────────▶ │
 │ │
 │ 3. 服务器确认订阅 │
 │ ◀───────────────────────── │
 │ │
 │ 4. 数据变更时推送 │
 │ { data: { │
 │ messageAdded: {...} │
 │ }} │
 │ ◀───────────────────────── │
 │ │
 │ 5. 继续推送... │
 │ ◀───────────────────────── │
 │ │
 │ 6. 客户端取消订阅 │
 │ ─────────────────────────▶ │
 │ │
 │ 7. 关闭连接 │
 │ ─────────────────────────▶ │

Apollo Server实现

基础订阅设置

// schema.js
const { gql } = require('apollo-server');

const typeDefs = gql`
 type Message {
 id: ID!
 content: String!
 userId: ID!
 createdAt: String!
 }

 type Query {
 messages(channelId: ID!): [Message!]!
 }

 type Mutation {
 addMessage(channelId: ID!, content: String!): Message!
 }

 type Subscription {
 messageAdded(channelId: ID!): Message!
 userTyping(channelId: ID!): User!
 channelUpdated(channelId: ID!): Channel!
 }
`;

module.exports = typeDefs;

// resolvers.js
const { PubSub } = require('graphql-subscriptions');

const pubsub = new PubSub();

const MESSAGE_ADDED = 'MESSAGE_ADDED';
const USER_TYPING = 'USER_TYPING';
const CHANNEL_UPDATED = 'CHANNEL_UPDATED';

const resolvers = {
 Query: {
 messages: async (_, { channelId }, { dataSources }) => {
 return dataSources.messageAPI.getMessagesByChannel(channelId);
 },
 },

 Mutation: {
 addMessage: async (_, { channelId, content }, { user, dataSources }) => {
 const message = await dataSources.messageAPI.createMessage({
 channelId,
 content,
 userId: user.id,
 });

 // 发布事件
 pubsub.publish(`${MESSAGE_ADDED}.${channelId}`, {
 messageAdded: message,
 });

 return message;
 },
 },

 Subscription: {
 messageAdded: {
 subscribe: (_, { channelId }, { user }) => {
 // 权限检查
 if (!user.hasAccessToChannel(channelId)) {
 throw new Error('Unauthorized');
 }

 return pubsub.asyncIterator([`${MESSAGE_ADDED}.${channelId}`]);
 },
 },

 userTyping: {
 subscribe: (_, { channelId }) => {
 return pubsub.asyncIterator([`${USER_TYPING}.${channelId}`]);
 },
 },
 },
};

module.exports = resolvers;

服务器配置

// server.js
const { ApolloServer } = require('apollo-server-express');
const { createServer } = require('http');
const { execute, subscribe } = require('graphql');
const { SubscriptionServer } = require('subscriptions-transport-ws');
const express = require('express');

const typeDefs = require('./schema');
const resolvers = require('./resolvers');

async function startServer() {
 const app = express();
 
 const server = new ApolloServer({
 typeDefs,
 resolvers,
 context: ({ req, connection }) => {
 // HTTP请求上下文
 if (req) {
 return {
 user: getUserFromToken(req.headers.authorization),
 };
 }
 // WebSocket连接上下文
 if (connection) {
 return {
 user: connection.context.user,
 };
 }
 },
 });

 await server.start();
 server.applyMiddleware({ app });

 const httpServer = createServer(app);

 // WebSocket服务器
 SubscriptionServer.create(
 {
 schema: server.schema,
 execute,
 subscribe,
 onConnect: (connectionParams, webSocket) => {
 // 验证连接
 if (connectionParams.authToken) {
 const user = validateToken(connectionParams.authToken);
 return { user };
 }
 throw new Error('Missing auth token');
 },
 onDisconnect: (webSocket, context) => {
 console.log('Client disconnected');
 },
 },
 {
 server: httpServer,
 path: server.graphqlPath,
 }
 );

 const PORT = process.env.PORT || 4000;
 httpServer.listen(PORT, () => {
 console.log(`🚀 Server ready at http://localhost:${PORT}${server.graphqlPath}`);
 console.log(`🚀 Subscriptions ready at ws://localhost:${PORT}${server.graphqlPath}`);
 });
}

startServer();

Redis PubSub扩展

分布式PubSub

// redis-pubsub.js
const { RedisPubSub } = require('graphql-redis-subscriptions');
const Redis = require('ioredis');

const options = {
 host: process.env.REDIS_HOST || 'localhost',
 port: process.env.REDIS_PORT || 6379,
 retryStrategy: (times) => {
 return Math.min(times * 50, 2000);
 },
};

const pubsub = new RedisPubSub({
 publisher: new Redis(options),
 subscriber: new Redis(options),
});

module.exports = pubsub;

// 使用Redis PubSub
const pubsub = require('./redis-pubsub');

const MESSAGE_ADDED = 'MESSAGE_ADDED';

const resolvers = {
 Subscription: {
 messageAdded: {
 subscribe: (_, { channelId }) => {
 // 使用模式匹配订阅多个频道
 return pubsub.asyncIterator([
 `${MESSAGE_ADDED}.${channelId}`,
 ]);
 },
 resolve: (payload) => {
 return payload.messageAdded;
 },
 },
 },
};

Go实现

GraphQL订阅服务器

package main

import (
 "context"
 "log"
 "net/http"
 "sync"
 
 "github.com/99designs/gqlgen/graphql/handler"
 "github.com/99designs/gqlgen/graphql/handler/transport"
 "github.com/99designs/gqlgen/graphql/playground"
 "github.com/gorilla/websocket"
)

type PubSub struct {
 mu sync.RWMutex
 subscribers map[string][]chan interface{}
}

func NewPubSub() *PubSub {
 return &PubSub{
 subscribers: make(map[string][]chan interface{}),
 }
}

func (ps *PubSub) Subscribe(topic string) chan interface{} {
 ps.mu.Lock()
 defer ps.mu.Unlock()
 
 ch := make(chan interface{}, 10)
 ps.subscribers[topic] = append(ps.subscribers[topic], ch)
 return ch
}

func (ps *PubSub) Unsubscribe(topic string, ch chan interface{}) {
 ps.mu.Lock()
 defer ps.mu.Unlock()
 
 subs := ps.subscribers[topic]
 for i, sub := range subs {
 if sub == ch {
 ps.subscribers[topic] = append(subs[:i], subs[i+1:]...)
 close(ch)
 break
 }
 }
}

func (ps *PubSub) Publish(topic string, data interface{}) {
 ps.mu.RLock()
 defer ps.mu.RUnlock()
 
 for _, ch := range ps.subscribers[topic] {
 select {
 case ch <- data:
 default:
 // 频道已满，跳过
 }
 }
}

// Resolver实现
type Resolver struct {
 pubsub *PubSub
}

func (r *Resolver) MessageAdded(ctx context.Context, channelID string) (<-chan *Message, error) {
 ch := r.pubsub.Subscribe("message_added." + channelID)
 
 messageCh := make(chan *Message, 10)
 
 go func() {
 defer close(messageCh)
 for {
 select {
 case <-ctx.Done():
 r.pubsub.Unsubscribe("message_added."+channelID, ch)
 return
 case data := <-ch:
 if msg, ok := data.(*Message); ok {
 messageCh <- msg
 }
 }
 }
 }()
 
 return messageCh, nil
}

func (r *Resolver) AddMessage(ctx context.Context, channelID, content string) (*Message, error) {
 user := getUserFromContext(ctx)
 
 msg := &Message{
 ID: generateID(),
 Content: content,
 UserID: user.ID,
 CreatedAt: time.Now(),
 }
 
 // 保存到数据库
 if err := saveMessage(msg); err != nil {
 return nil, err
 }
 
 // 发布事件
 r.pubsub.Publish("message_added."+channelID, msg)
 
 return msg, nil
}

// 服务器启动
func main() {
 pubsub := NewPubSub()
 resolver := &Resolver{pubsub: pubsub}
 
 srv := handler.New(gqlgen.NewExecutableSchema(gqlgen.Config{
 Resolvers: resolver,
 }))
 
 // 添加WebSocket传输
 srv.AddTransport(&transport.Websocket{
 Upgrader: websocket.Upgrader{
 CheckOrigin: func(r *http.Request) bool {
 return true
 },
 },
 InitFunc: func(ctx context.Context, initPayload *transport.InitPayload) (context.Context, error) {
 // 验证连接
 token := initPayload.Get("authToken")
 user, err := validateToken(token)
 if err != nil {
 return ctx, err
 }
 return context.WithValue(ctx, "user", user), nil
 },
 })
 
 srv.AddTransport(transport.POST{})
 
 http.Handle("/", playground.Handler("GraphQL", "/query"))
 http.Handle("/query", srv)
 
 log.Println("Server running on :8080")
 log.Fatal(http.ListenAndServe(":8080", nil))
}

客户端实现

React + Apollo Client

// client.js
import { ApolloClient, InMemoryCache, split, HttpLink } from '@apollo/client';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';
import { getMainDefinition } from '@apollo/client/utilities';

const httpLink = new HttpLink({
 uri: 'http://localhost:4000/graphql',
});

const wsLink = new GraphQLWsLink(
 createClient({
 url: 'ws://localhost:4000/graphql',
 connectionParams: {
 authToken: localStorage.getItem('token'),
 },
 })
);

const splitLink = split(
 ({ query }) => {
 const definition = getMainDefinition(query);
 return (
 definition.kind === 'OperationDefinition' &&
 definition.operation === 'subscription'
 );
 },
 wsLink,
 httpLink
);

const client = new ApolloClient({
 link: splitLink,
 cache: new InMemoryCache(),
});

// MessageList.jsx
import { useSubscription, useQuery, gql } from '@apollo/client';

const GET_MESSAGES = gql`
 query GetMessages($channelId: ID!) {
 messages(channelId: $channelId) {
 id
 content
 userId
 createdAt
 }
 }
`;

const MESSAGE_ADDED = gql`
 subscription MessageAdded($channelId: ID!) {
 messageAdded(channelId: $channelId) {
 id
 content
 userId
 createdAt
 }
 }
`;

function MessageList({ channelId }) {
 const { data, loading } = useQuery(GET_MESSAGES, {
 variables: { channelId },
 });

 useSubscription(MESSAGE_ADDED, {
 variables: { channelId },
 onData: ({ data: { messageAdded } }) => {
 // 更新缓存
 client.cache.modify({
 fields: {
 messages(existingMessages = []) {
 const newMessageRef = client.cache.writeFragment({
 data: messageAdded,
 fragment: gql`
 fragment NewMessage on Message {
 id
 content
 userId
 createdAt
 }
 `,
 });
 return [...existingMessages, newMessageRef];
 },
 },
 });
 },
 });

 if (loading) return <div>Loading...</div>;

 return (
 <div className="message-list">
 {data.messages.map((message) => (
 <div key={message.id} className="message">
 <p>{message.content}</p>
 <span>{message.createdAt}</span>
 </div>
 ))}
 </div>
 );
}

高级特性

事件过滤

// 带过滤的订阅
const resolvers = {
 Subscription: {
 messageAdded: {
 subscribe: withFilter(
 (_, { channelId }) => pubsub.asyncIterator([MESSAGE_ADDED]),
 (payload, variables) => {
 // 只推送给特定频道的订阅者
 return payload.messageAdded.channelId === variables.channelId;
 }
 ),
 },

 // 多条件过滤
 notificationReceived: {
 subscribe: withFilter(
 () => pubsub.asyncIterator([NOTIFICATION]),
 (payload, variables, context) => {
 const notification = payload.notificationReceived;
 return (
 notification.userId === context.user.id &&
 notification.type === variables.type
 );
 }
 ),
 },
 },
};

订阅认证与授权

// 中间件认证
const authMiddleware = async (resolve, parent, args, context, info) => {
 if (!context.user) {
 throw new AuthenticationError('Must authenticate');
 }

 // 检查用户是否有权限订阅
 const hasPermission = await checkPermission(
 context.user,
 info.fieldName,
 args
 );

 if (!hasPermission) {
 throw new ForbiddenError('Not authorized');
 }

 return resolve(parent, args, context, info);
};

// 应用中间件
const resolvers = {
 Subscription: {
 messageAdded: {
 subscribe: authMiddleware,
 },
 },
};

总结

GraphQL订阅最佳实践

场景	推荐方案	原因
聊天应用	WebSocket + Redis PubSub	实时性高，支持多实例
实时通知	事件过滤 + 权限控制	精准推送，安全可控
协作编辑	CRDT + 订阅	冲突解决，实时同步
数据仪表板	节流 + 批量更新	减少推送频率

关键原则

使用分布式PubSub：Redis/Kafka支持多实例部署
实现认证授权：WebSocket连接和订阅都需要验证
事件过滤：避免无关数据推送
连接管理：监控活跃连接数，防止资源耗尽
错误处理：优雅处理连接断开和重连
性能优化：节流、批量更新、连接复用

实时通信架构：WebSocket、SSE与长轮询的设计与实践

Thu, 08 Jan 2026 10:00:00 +0800

引言

实时通信是现代应用的核心需求，从聊天系统到协作工具、股票行情到IoT设备监控，都需要服务端主动向客户端推送数据。本文将系统对比三大实时通信技术，并提供生产级实现方案。

Realtime on PlumePHP

gRPC流式通信实战：双向流、服务端推送与实时数据处理

引言

gRPC四种通信模式

Protocol Buffer定义

服务端流实现

实时消息订阅

实时日志流

客户端流实现

批量消息发送

日志批量上传

文件上传

双向流实现

实时聊天

客户端调用示例

订阅消息流

双向聊天客户端

流式通信最佳实践

总结

gRPC流式通信选型

关键原则

延伸阅读

GraphQL订阅与实时更新：构建响应式数据流架构

引言

GraphQL订阅核心概念

Apollo Server实现

基础订阅设置

服务器配置

Redis PubSub扩展

分布式PubSub

Go实现

GraphQL订阅服务器

客户端实现

React + Apollo Client

高级特性

事件过滤

订阅认证与授权

总结

GraphQL订阅最佳实践

关键原则

延伸阅读

实时通信架构：WebSocket、SSE与长轮询的设计与实践

引言