SignalR 实时通信

SignalR 原理

SignalR 是 ASP.NET Core 的实时通信库，它会自动选择最优传输协议：优先 WebSocket，降级为 Server-Sent Events（SSE），最后降级为 Long Polling。开发者无需关心底层协议细节。

定义 Hub

// 强类型 Hub：通过接口定义客户端方法（推荐）
public interface IChatClient
{
    Task ReceiveMessage(ChatMessage message);
    Task UserJoined(string userName);
    Task UserLeft(string userName);
}

public record ChatMessage(string Sender, string Content, DateTimeOffset SentAt);

[Authorize]
public class ChatHub(IUserService userService) : Hub<IChatClient>
{
    // 客户端调用服务端方法
    public async Task SendMessage(string roomId, string content)
    {
        var userName = Context.User!.FindFirstValue(ClaimTypes.Name)!;
        var msg = new ChatMessage(userName, content, DateTimeOffset.UtcNow);

        // 广播给房间所有成员（包括发送者）
        await Clients.Group(roomId).ReceiveMessage(msg);
    }

    public async Task JoinRoom(string roomId)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, roomId);
        var userName = Context.User!.FindFirstValue(ClaimTypes.Name)!;

        // 通知房间其他成员（排除发送者）
        await Clients.OthersInGroup(roomId).UserJoined(userName);
    }

    public async Task LeaveRoom(string roomId)
    {
        await Groups.RemoveFromGroupAsync(Context.ConnectionId, roomId);
        var userName = Context.User!.FindFirstValue(ClaimTypes.Name)!;
        await Clients.Group(roomId).UserLeft(userName);
    }

    // 连接/断开回调
    public override async Task OnConnectedAsync()
    {
        await userService.SetOnlineAsync(Context.UserIdentifier!);
        await base.OnConnectedAsync();
    }

    public override async Task OnDisconnectedAsync(Exception? ex)
    {
        await userService.SetOfflineAsync(Context.UserIdentifier!);
        await base.OnDisconnectedAsync(ex);
    }
}

注册与配置

// Program.cs
builder.Services.AddSignalR(options =>
{
    options.EnableDetailedErrors    = builder.Environment.IsDevelopment();
    options.HandshakeTimeout        = TimeSpan.FromSeconds(15);
    options.KeepAliveInterval       = TimeSpan.FromSeconds(15);
    options.ClientTimeoutInterval   = TimeSpan.FromSeconds(30);
    options.MaximumReceiveMessageSize = 64 * 1024;  // 64KB
});

// 映射 Hub 端点
app.MapHub<ChatHub>("/hubs/chat");
app.MapHub<NotificationHub>("/hubs/notifications");

// JWT 认证在 WebSocket 中需要特殊处理（Token 在 Query String）
builder.Services.AddAuthentication().AddJwtBearer(options =>
{
    options.Events = new JwtBearerEvents
    {
        OnMessageReceived = ctx =>
        {
            var token = ctx.Request.Query["access_token"];
            var path  = ctx.HttpContext.Request.Path;
            if (!string.IsNullOrEmpty(token) && path.StartsWithSegments("/hubs"))
                ctx.Token = token;
            return Task.CompletedTask;
        }
    };
});

服务端主动推送（IHubContext）

// 在任意服务中向客户端推送消息
public class OrderNotificationService(IHubContext<ChatHub, IChatClient> hubContext)
{
    public async Task NotifyOrderCompletedAsync(string userId, Order order)
    {
        var msg = new ChatMessage(
            "System",
            $"您的订单 #{order.Id} 已完成，共 {order.Total:C}",
            DateTimeOffset.UtcNow
        );

        // 向特定用户推送（可能有多个连接）
        await hubContext.Clients.User(userId).ReceiveMessage(msg);
    }

    public async Task BroadcastSystemAlertAsync(string alert)
    {
        // 广播给所有连接的客户端
        await hubContext.Clients.All.ReceiveMessage(
            new ChatMessage("System", alert, DateTimeOffset.UtcNow));
    }
}

Redis Backplane：横向扩展

单实例 SignalR 的连接信息（哪个用户在哪个连接上）只存在于该进程内存中。当你有多个服务器实例时，用户 A 连接到 Server 1，用户 B 连接到 Server 2，Server 1 无法直接向 Server 2 上的用户 B 推送消息。Redis Backplane 通过 Redis 的发布订阅机制解决这个问题：所有服务器实例订阅同一 Redis 频道，广播消息时发布到 Redis，所有实例都会收到并转发给本地连接的客户端。

// 安装：dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis

builder.Services.AddSignalR()
    .AddStackExchangeRedis(
        builder.Configuration.GetConnectionString("Redis")!,
        options => options.Configuration.ChannelPrefix = RedisChannel.Literal("chat-app")
    );

JavaScript 客户端

// 安装: npm install @microsoft/signalr
import * as signalR from "@microsoft/signalr";

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/chat", {
        accessTokenFactory: () => getAuthToken()  // JWT 令牌
    })
    .withAutomaticReconnect([0, 2000, 10000, 30000])  // 自动重连间隔
    .configureLogging(signalR.LogLevel.Information)
    .build();

// 监听服务端事件
connection.on("ReceiveMessage", (msg) => {
    appendMessage(msg.sender, msg.content, msg.sentAt);
});

connection.on("UserJoined", (userName) => {
    showNotification(`${userName} 加入了房间`);
});

// 启动连接
await connection.start();

// 调用服务端方法
await connection.invoke("JoinRoom", roomId);
await connection.invoke("SendMessage", roomId, messageText);

// 断开时清理
await connection.stop();