Mud.Feishu.EventCallback 3.0.0-preview3

Mud.Feishu.EventCallback

飞书服务端 SDK 的 .NET 适配版，提供事件与回调功能强数据模型封装。

项目简介

Mud.Feishu.EventCallback 是 MudFeishu SDK 的核心组件之一，专门用于处理飞书平台的事件回调。本项目提供了完整的强类型数据模型，帮助开发者轻松处理飞书各种事件推送。

特性

• ✅ 强类型数据模型 - 所有事件数据均有完整的类型定义和 XML 文档注释
• ✅ 自动生成事件处理器 - 使用源代码生成器自动生成事件处理器基类
• ✅ 多框架支持 - 支持 .NET Standard 2.0、.NET 6.0、.NET 8.0、.NET 10.0
• ✅ 完整的事件覆盖 - 覆盖飞书主要业务场景的事件回调
• ✅ 官方文档链接 - 每个事件模型都包含官方文档链接

支持的事件类型

👥 组织架构事件（Organization）

💬 即时通讯事件（IM）

📋 审批事件（Approval）

✅ 任务事件（Task）

☁️ 云盘事件（Drive）

📋 多维表格事件（Bitable）

⏰ 考勤事件（Attendance）

安装

通过 NuGet 安装

dotnet add package Mud.Feishu.EventCallback

支持的目标框架

• .NET Standard 2.0
• .NET 6.0
• .NET 8.0
• .NET 10.0

快速开始

1. 定义事件处理器

继承自动生成的事件处理器基类，实现业务逻辑：

using Mud.Feishu.EventCallback.IM;

public class MyMessageHandler : MessageReceiveEventHandler
{
    private readonly ILogger<MyMessageHandler> _logger;

    public MyMessageHandler(ILogger<MyMessageHandler> logger)
    {
        _logger = logger;
    }

    public override async Task HandleAsync(MessageReceiveResult result, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("收到消息：{MessageId}", result.Message?.MessageId);

        if (result.Message?.Content != null)
        {
            var content = result.Message.Content;
            _logger.LogInformation("消息内容：{Content}", content);
        }

        await Task.CompletedTask;
    }
}

2. 处理审批事件

using Mud.Feishu.EventCallback.Approval;

public class LeaveApprovalHandler : LeaveApprovalEventHandler
{
    private readonly ILogger<LeaveApprovalHandler> _logger;

    public LeaveApprovalHandler(ILogger<LeaveApprovalHandler> logger)
    {
        _logger = logger;
    }

    public override async Task HandleAsync(LeaveApprovalResult result, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation(
            "员工 {EmployeeId} 请假申请：{StartTime} 至 {EndTime}，时长 {Duration} 秒",
            result.EmployeeId,
            result.LeaveStartTime,
            result.LeaveEndTime,
            result.LeaveInterval
        );

        await Task.CompletedTask;
    }
}

3. 处理组织架构事件

using Mud.Feishu.EventCallback.Organization;

public class UserCreatedHandler : UserCreateEventHandler
{
    private readonly ILogger<UserCreatedHandler> _logger;

    public UserCreatedHandler(ILogger<UserCreatedHandler> logger)
    {
        _logger = logger;
    }

    public override async Task HandleAsync(UserCreateResult result, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation(
            "新员工入职：{Name} ({UserId})",
            result.Name,
            result.UserId
        );

        await Task.CompletedTask;
    }
}

数据模型结构

每个事件数据模型都实现了 IEventResult 接口，并包含：

• 完整的属性定义 - 所有字段均有强类型定义
• JSON 序列化特性 - 使用 [JsonPropertyName] 标注字段映射
• XML 文档注释 - 详细的中文注释说明
• 官方文档链接 - 通过 <see href> 链接到官方文档

示例：

/// <summary>
/// 接收消息事件处理器
/// <para>机器人接收到用户发送的消息后触发此事件。</para>
/// <para>事件类型:im.message.receive_v1</para>
/// <para>使用时请继承：<see cref="MessageReceiveEventHandler"/></para>
/// <para>文档地址：<see href="https://open.feishu.cn/document/server-docs/im-v1/message/events/receive"/></para>
/// </summary>
[GenerateEventHandler(EventType = FeishuEventTypes.ReceiveMessage,
                      HandlerNamespace = Consts.HandlerNamespace,
                      InheritedFrom = Consts.InheritedFrom)]
public class MessageReceiveResult : IEventResult
{
    [JsonPropertyName("sender")]
    public MessageSender? Sender { get; set; }

    [JsonPropertyName("message")]
    public MessageContent? Message { get; set; }
}

项目结构

Mud.Feishu.EventCallback/
├── Approval/                          # 审批事件
│   ├── ApprovalApprovalUpdatedEvent/  # 审批定义更新
│   ├── ApprovalCcEvent/              # 审批抄送
│   ├── ApprovalInstanceEvent/        # 审批实例
│   ├── ApprovalInstanceTripGroupUpdateEvent/ # 出差审批
│   ├── ApprovalInstanceRemedyGroupUpdateEvent/ # 补卡审批
│   ├── ApprovalTaskEvent/            # 审批任务
│   ├── LeaveApprovalEvent/           # 请假审批
│   ├── OutApprovalEvent/             # 外出审批
│   ├── ShiftApprovalEvent/           # 换班审批
│   └── WorkApprovalEvent/            # 加班审批
├── Organization/                      # 组织架构事件
│   ├── UserCreateEvent/              # 用户创建
│   ├── UserDeleteEvent/              # 用户删除
│   ├── UserUpdateEvent/              # 用户更新
│   ├── DepartmentCreatedEvent/       # 部门创建
│   ├── DepartmentDeletedEvent/       # 部门删除
│   ├── DepartmentUpdateEvent/        # 部门更新
│   ├── CustomAttrUpdateEvent/        # 自定义属性更新
│   ├── EmployeeTypeEnumCreatedEvent/ # 人员类型创建
│   ├── EmployeeTypeEnumDeleteEvent/  # 人员类型删除
│   ├── EmployeeTypeEnumUpdateEvent/  # 人员类型更新
│   ├── EmployeeTypeEnumActivedEvent/ # 人员类型启用
│   └── EmployeeTypeEnumDeActivedEvent/ # 人员类型禁用
├── IM/                               # 即时通讯事件
│   ├── MessageReceiveEvent/          # 消息接收
│   ├── MessageReadEvent/             # 消息已读
│   ├── MessageRecalledEvent/         # 消息撤回
│   ├── MessageReactionCreatedEvent/  # 表情回应创建
│   ├── MessageReactionDeletedEvent/  # 表情回应删除
│   ├── ChatUpdatedEvent/             # 群聊更新
│   ├── ChatDisbandedEvent/           # 群聊解散
│   ├── ChatMemberUserAddedEvent/     # 用户进群
│   ├── ChatMemberUserDeletedEvent/   # 用户出群
│   ├── ChatMemberUserWithdrawnEvent/ # 撤销拉用户进群
│   ├── ChatMemberBotAddedEvent/      # 机器人进群
│   └── ChatMemberBotDeletedEvent/    # 机器人退群
├── Task/                             # 任务事件
│   ├── TaskUpdatedResult.cs          # 任务更新
│   ├── TaskCommentUpdatedResult.cs   # 任务评论更新
│   └── TaskUpdateTenantResult.cs     # 租户任务更新
├── Drive/                            # 云盘事件
│   ├── DriveFileCreatedEvent/        # 文件创建
│   ├── DriveFileDeletedEvent/        # 文件删除
│   ├── DriveFileEditEvent/           # 文件编辑
│   ├── DriveFileReadEvent/           # 文件已读
│   ├── DriveFileTitleUpdatedEvent/   # 文件标题更新
│   ├── DriveFileTrashedEvent/        # 文件回收站
│   ├── DriveFilePermissionMemberAddedEvent/     # 协作者添加
│   ├── DriveFilePermissionMemberAppliedEvent/   # 协作者权限申请
│   ├── DriveFilePermissionMemberRemovedEvent/   # 协作者移除
│   └── DriveNoticeCommentAddEvent/   # 评论新增
├── Bitable/                          # 多维表格事件
│   ├── BitableFieldChangedEvent/     # 字段变更
│   └── BitableRecordChanged/         # 记录变更
├── Attendance/                       # 考勤事件
│   ├── AttendanceUserFlowCreatedResult.cs   # 考勤流水创建
│   └── AttendanceUserTaskUpdatedResult.cs   # 考勤任务更新
└── GlobalUsings.cs                   # 全局引用

依赖项

• Mud.Feishu.Abstractions - 核心抽象和基础类型
• Mud.HttpUtils.Generator - 源代码生成器（用于自动生成事件处理器）

相关项目

• Mud.Feishu - 核心 HTTP API 客户端
• Mud.Feishu.Abstractions - 事件处理抽象
• Mud.Feishu.Webhook - Webhook 事件处理
• Mud.Feishu.WebSocket - WebSocket 实时事件
• Mud.Feishu.Redis - Redis 分布式去重

文档与资源

• 飞书开放平台文档
• 事件订阅概述
• MudFeishu GitHub 仓库

许可证

本项目采用 MIT 许可证。详见 LICENSE-MIT 文件。

版权声明

版权所有 © Mud Studio 2026。保留所有权利。

Mud.Feishu 项目的版权、商标、专利和其他相关权利均受相应法律法规的保护。使用本项目应遵守相关法律法规和许可证的要求。

本项目主要遵循 MIT 许可证进行分发和使用。许可证位于源代码树根目录中的 LICENSE-MIT 文件。

不得利用本项目从事危害国家安全、扰乱社会秩序、侵犯他人合法权益等法律法规禁止的活动！任何基于本项目开发而产生的一切法律纠纷和责任，我们不承担任何责任！