Mud.Feishu.WebSocket 1.0.6

飞书WebSocket客户端服务

企业级飞书事件订阅WebSocket客户端，提供可靠的连接管理、自动重连和策略模式事件处理。

🚀 新特性：极简API - 一行代码完成服务注册，开箱即用！

✨ 核心特性

• 🚀 极简API - 一行代码完成服务注册，开箱即用
• 🔄 智能连接管理 - 自动重连、心跳检测、状态监控
• 🫀 心跳消息处理 - 支持飞书 heartbeat 消息类型，实时连接状态监控
• 🚀 高性能消息处理 - 异步处理、消息队列、并行执行
• 🎯 策略模式事件处理 - 可扩展的事件处理器架构
• 🛡️ 企业级稳定性 - 完善的错误处理、资源管理、日志记录
• ⚙️ 灵活配置 - 支持配置文件、代码配置和建造者模式
• 📊 监控友好 - 详细的事件通知、性能指标、心跳统计

🚀 快速开始

1. 安装NuGet包

dotnet add package Mud.Feishu.WebSocket

2. 最简配置（一行代码）

在 Program.cs 中：

using Mud.Feishu.WebSocket;

var builder = WebApplication.CreateBuilder(args);

// 一行代码注册WebSocket服务
builder.Services.AddFeishuWebSocketServiceBuilder(builder.Configuration);

var app = builder.Build();
app.Run();

3. 完整配置（添加事件处理器）

// 从配置文件注册并添加事件处理器
builder.Services.AddFeishuWebSocketServiceBuilder(builder.Configuration)
    .AddHandler<ReceiveMessageEventHandler>()
    .AddHandler<UserCreatedEventHandler>()
    .UseMultiHandler();

var app = builder.Build();
app.Run();

4. 配置选项

{
  "Feishu": {
    "AppId": "your_app_id",
    "AppSecret": "your_app_secret",
    "WebSocket": {
      "AutoReconnect": true,
      "MaxReconnectAttempts": 5,
      "ReconnectDelayMs": 5000,
      "HeartbeatIntervalMs": 30000,
      "EnableLogging": true
    }
  }
}

🏗️ 架构设计

组件化架构

飞书WebSocket客户端采用组件化设计，将复杂功能拆分为专门的组件，提高代码的可维护性和扩展性。

架构设计

核心组件

消息处理器

架构优势

• 🎯 单一职责 - 每个组件专注特定功能，代码清晰易懂
• 🔧 代码复用性提升 - 组件化设计，各组件可独立使用
• 🧪 测试友好 - 每个组件可独立测试，依赖清晰
• 🚀 扩展性提升 - 新功能通过添加组件实现，配置灵活

自定义消息处理器

// 创建自定义消息处理器
public class CustomMessageHandler : JsonMessageHandler
{
    public override bool CanHandle(string messageType)
        => messageType == "custom_type";

    public override async Task HandleAsync(string message, CancellationToken cancellationToken = default)
    {
        var data = SafeDeserialize<CustomMessage>(message);
        // 处理逻辑...
    }
}

// 注册到消息路由器
client.RegisterMessageProcessor(customMessageHandler);

文件结构

Mud.Feishu.WebSocket/
├── Core/                           # 核心组件
│   ├── WebSocketConnectionManager.cs  # 连接管理
│   ├── AuthenticationManager.cs      # 认证管理  
│   ├── MessageRouter.cs             # 消息路由
│   └── BinaryMessageProcessor.cs    # 二进制处理
├── Handlers/                       # 消息处理器
│   ├── IMessageHandler.cs          # 处理器接口
│   ├── EventMessageHandler.cs       # 事件消息处理
│   └── BasicMessageHandler.cs     # 基础消息处理
├── SocketEventArgs/                # 事件参数类
├── DataModels/                    # 数据模型
├── FeishuWebSocketClient.cs       # 主客户端
└── Examples/                      # 使用示例

🏗️ 服务注册方式

🚀 最简注册（推荐）

// 一行代码完成基础配置
builder.Services.AddFeishuWebSocketServiceBuilder(builder.Configuration);

// 添加事件处理器
builder.Services.AddFeishuWebSocketServiceBuilder(builder.Configuration)
    .AddHandler<ReceiveMessageEventHandler>()
    .AddHandler<UserCreatedEventHandler>()
    .UseMultiHandler();

⚙️ 代码配置

builder.Services.AddFeishuWebSocketServiceBuilder(options =>
{
    options.AppId = "your_app_id";
    options.AppSecret = "your_app_secret";
    options.AutoReconnect = true;
    options.HeartbeatIntervalMs = 30000;
});

🔧 高级配置（建造者模式）

builder.Services.AddFeishuWebSocketBuilder()
    .ConfigureFrom(configuration)
    .UseMultiHandler()
    .EnableMetrics()
    .AddHandler<ReceiveMessageEventHandler>()
    .Build();

🎯 事件处理器（策略模式）

内置事件处理器

创建自定义事件处理器

public class CustomEventHandler : IFeishuEventHandler
{
    private readonly ILogger<CustomEventHandler> _logger;

    public CustomEventHandler(ILogger<CustomEventHandler> logger)
        => _logger = logger ?? throw new ArgumentNullException(nameof(logger));

    public string SupportedEventType => "custom.event.example_v1";

    public async Task HandleAsync(EventData eventData, CancellationToken cancellationToken = default)
    {
        if (eventData == null) throw new ArgumentNullException(nameof(eventData));

        _logger.LogInformation("🎯 处理自定义事件: {EventType}", eventData.EventType);
        
        // 实现你的业务逻辑
        await ProcessBusinessLogicAsync(eventData);
    }

    private async Task ProcessBusinessLogicAsync(EventData eventData)
    {
        // 数据库操作、外部API调用等
        await Task.CompletedTask;
    }
}

注册自定义处理器

// 注册处理器（多种方式）
builder.Services.AddFeishuWebSocketServiceBuilder(builder.Configuration)
    .UseMultiHandler()
    .AddHandler<CustomEventHandler>()                    // 类型注册
    .AddHandler(sp => new FactoryEventHandler(           // 工厂注册
        sp.GetService<ILogger<FactoryEventHandler>>()))
    .AddHandler(new InstanceEventHandler());               // 实例注册

// 或使用建造者模式
builder.Services.AddFeishuWebSocketBuilder()
    .UseMultiHandler()
    .AddHandler<CustomEventHandler>()
    .Build();

运行时动态注册

public class ServiceManager
{
    private readonly IFeishuEventHandlerFactory _factory;
    private readonly ILogger<ServiceManager> _logger;
    
    public ServiceManager(IFeishuEventHandlerFactory factory, ILogger<ServiceManager> logger)
    {
        _factory = factory;
        _logger = logger;
    }

    public void RegisterHandler()
    {
        var customHandler = new CustomEventHandler(_logger);
        _factory.RegisterHandler(customHandler);
        _logger.LogInformation("已注册自定义处理器: {HandlerType}", typeof(CustomEventHandler).Name);
    }
}

⚙️ 配置选项

WebSocket配置

⚙️ 配置选项

主要配置项

🎯 高级用法

多环境配置

var webSocketBuilder = builder.Services.AddFeishuWebSocketServiceBuilder(configuration);

if (builder.Environment.IsDevelopment())
{
    webSocketBuilder.ConfigureOptions(options => {
        options.EnableLogging = true;
        options.HeartbeatIntervalMs = 15000;
    });
}
else
{
    webSocketBuilder.ConfigureFrom(configuration, "Production:WebSocket");
}

webSocketBuilder.UseMultiHandler()
    .AddHandler<DevEventHandler>()
    .AddHandler<ProdEventHandler>()
    .Build();

条件性处理器注册

builder.Services.AddFeishuWebSocketServiceBuilder(configuration)
    .UseMultiHandler()
    .AddHandler<BaseEventHandler>()
    .Apply(webSocketBuilder => {
        if (configuration.GetValue<bool>("Features:EnableAudit"))
            webSocketBuilder.AddHandler<AuditEventHandler>();
        
        if (configuration.GetValue<bool>("Features:EnableAnalytics"))
            webSocketBuilder.AddHandler<AnalyticsEventHandler>();
    })
    .Build();

🔧 高级功能

手动连接控制

public class ConnectionService
{
    private readonly IFeishuWebSocketManager _manager;

    public ConnectionService(IFeishuWebSocketManager manager)
        => _manager = manager;

    // 连接管理
    public async Task StartAsync() => await _manager.StartAsync();
    public async Task StopAsync() => await _manager.StopAsync();
    public async Task ReconnectAsync() => await _manager.ReconnectAsync();
    
    // 消息操作
    public async Task SendMessageAsync(string message) 
        => await _manager.SendMessageAsync(message);
    
    // 事件订阅
    public void SubscribeEvents()
    {
        _manager.Connected += OnConnected;
        _manager.Disconnected += OnDisconnected;
        _manager.HeartbeatReceived += OnHeartbeat;
    }
}

📋 支持的事件类型

WebSocket 消息类型

• ping / pong - 连接保活
• heartbeat - 心跳消息
• event - 业务事件
• auth - 认证响应

主要业务事件

• 消息: im.message.receive_v1, im.message.message_read_v1
• 群聊: im.chat.member.user_added_v1, im.chat.member.user_deleted_v1
• 用户: contact.user.created_v3, contact.user.updated_v3, contact.user.deleted_v3
• 部门: contact.department.*_v3
• 审批: approval.approval.*_v1
• 日程: calendar.event.updated_v4
• 会议: meeting.meeting.*_v1

📄 许可证

本项目遵循 MIT 许可证进行分发和使用。

🚀 立即开始使用飞书WebSocket客户端，构建稳定可靠的事件处理系统！