Mud.Feishu.EventCallback 3.1.0

Mud.Feishu.EventCallback

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

项目简介

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

特性

• ✅ 强类型数据模型 - 所有事件数据均有完整的类型定义和 XML 文档注释
• ✅ 自动生成事件处理器 - 使用源代码生成器自动生成事件处理器基类
• ✅ 多框架支持 - 支持 .NET Standard 2.0、.NET 6.0、.NET 8.0、.NET 10.0
• ✅ 原生 AOT 支持 - net8.0+ 一等公民支持 Native AOT 发布，事件回调 JSON 全部走源生成上下文
• ✅ 完整的事件覆盖 - 覆盖飞书主要业务场景的事件回调
• ✅ 官方文档链接 - 每个事件模型都包含官方文档链接

支持的事件类型

共 206 个事件、25 个业务域。下表由源码中的 [GenerateEventHandler] 标注直接汇总。

👥 组织架构事件（Organization）

💬 即时通讯事件（IM）

📋 审批事件（Approval）

✅ 任务事件（Task）

☁️ 云盘事件（Drive）

📊 多维表格事件（Bitable）

📅 日历事件（Calendar）

⏰ 考勤事件（Attendance）

🎥 视频会议事件（VideoConferencing）

📧 邮箱事件（Mail）

🧑‍💼 招聘事件（Hire）

📈 绩效事件（Performance）

🚪 智能门禁事件（Acs）

🎧 服务台事件（Helpdesk）

🧩 应用信息事件（Application）

🔐 认证授权事件（Auth）

🏢 会议室事件（MeetingRoom）

🧑‍🏫 飞书人事（标准版）事件（CoreHr）

🏫 飞书人事（企业版）事件（CoreHrV2）

🌈 公司圈事件（Moments）

🎓 eLearning 事件（ELearning）

🛡️ 安全合规事件（SecurityCompliance）

💵 Payroll 事件（Payroll）

💰 薪酬事件（Compensation）

🎴 卡片事件回调（Card）

卡片事件回调与常规事件订阅不同：它由卡片交互触发、经 Webhook 投递，且业务服务器必须在 3 秒内响应。 请求体模型见 CardActionTriggerResult（operator / token / action / host / delivery_type / context）， 响应体模型见 CardCallbackResponse（toast + card，card.data 支持 raw 与 template 两种形态）。 详见飞书卡片事件回调文档。

📌 说明

• meeting_room.meeting_room.status_changed_v1（RoomStatusChangedEventHandler）按存量实现归属 Calendar 域，即会议室事件分布在 Calendar 与 MeetingRoom 两个域。
• approval_instance / approval_task / approval_cc / leave_approval* / work_approval* / out_approval / shift_approval 等为飞书旧版审批事件，官方已标注历史版本；SDK 保留以兼容存量用户代码，新接入推荐使用 v4 形态（如 approval.task.status_changed_v4）。
• attendance.* 与部分旧版审批事件不在官方「事件列表」页内，属其他文档章节来源。
• 敏感数据域（Payroll 薪酬、Compensation 薪资档案、Moments 公司圈 UGC、SecurityCompliance 设备信息）的事件体含薪资与个人信息：处理器实现中禁止输出事件体原文，日志只能记结构化字段并脱敏截断（AGENTS.md D5 日志最小暴露）。

安装

通过 NuGet 安装

dotnet add package Mud.Feishu.EventCallback

支持的目标框架

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

快速开始

1. 定义事件处理器

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

注意：

• 生成的处理器基类 HandleAsync(EventData, CancellationToken) 已声明为 sealed（内置事件反序列化与业务层幂等保护），不可重写；业务逻辑的唯一扩展点是 ProcessBusinessLogicAsync。
• 生成的处理器构造函数签名为 (IFeishuEventDeduplicator, ILogger, IAppKeyAccessor?)，派生类必须显式声明构造函数并调用 base(businessDeduplicator, logger)（IAppKeyAccessor 为可选参数，用于多应用去重隔离）。
• 事件模型显式声明了 HeaderType = nameof(FeishuEventHeader) 时，生成的处理器继承双泛型参数基类，应重写带 header 参数的 ProcessBusinessLogicAsync 重载；未声明时继承单泛型参数基类，应重写不带 header 参数的重载。

using Mud.Feishu.Abstractions;
using Mud.Feishu.Abstractions.Services;
using Mud.Feishu.EventCallback;
using Mud.Feishu.EventCallback.IM;

public class MyMessageHandler : MessageReceiveEventHandler
{
    public MyMessageHandler(IFeishuEventDeduplicator businessDeduplicator, ILogger<MyMessageHandler> logger)
        : base(businessDeduplicator, logger)
    {
    }

    protected override async Task ProcessBusinessLogicAsync(
        EventData eventData,
        MessageReceiveResult? eventEntity,
        FeishuEventHeader? header,
        CancellationToken cancellationToken = default)
    {
        if (eventEntity?.Message is null)
        {
            return;
        }

        _logger.LogInformation("收到消息：{MessageId}", eventEntity.Message.MessageId);

        if (eventEntity.Message.Content is not null)
        {
            _logger.LogInformation("消息内容：{Content}", eventEntity.Message.Content);
        }

        await Task.CompletedTask;
    }
}

2. 处理审批事件

using Mud.Feishu.Abstractions;
using Mud.Feishu.Abstractions.Services;
using Mud.Feishu.EventCallback;
using Mud.Feishu.EventCallback.Approval;

public class LeaveApprovalHandler : LeaveApprovalEventHandler
{
    public LeaveApprovalHandler(IFeishuEventDeduplicator businessDeduplicator, ILogger<LeaveApprovalHandler> logger)
        : base(businessDeduplicator, logger)
    {
    }

    // leave_approval 未声明 HeaderType，生成的处理器继承 IdempotentFeishuEventHandler<LeaveApprovalResult>，
    // 因此重写不带 header 参数的重载
    protected override async Task ProcessBusinessLogicAsync(
        EventData eventData,
        LeaveApprovalResult? eventEntity,
        CancellationToken cancellationToken = default)
    {
        if (eventEntity is null)
        {
            return;
        }

        _logger.LogInformation(
            "员工 {EmployeeId} 请假申请：{StartTime} 至 {EndTime}，时长 {Duration} 秒",
            eventEntity.EmployeeId,
            eventEntity.LeaveStartTime,
            eventEntity.LeaveEndTime,
            eventEntity.LeaveInterval);

        await Task.CompletedTask;
    }
}

3. 处理组织架构事件

using Mud.Feishu.Abstractions;
using Mud.Feishu.Abstractions.Services;
using Mud.Feishu.EventCallback;
using Mud.Feishu.EventCallback.Organization;

public class UserCreatedHandler : UserCreateEventHandler
{
    public UserCreatedHandler(IFeishuEventDeduplicator businessDeduplicator, ILogger<UserCreatedHandler> logger)
        : base(businessDeduplicator, logger)
    {
    }

    protected override async Task ProcessBusinessLogicAsync(
        EventData eventData,
        UserCreateResult? eventEntity,
        FeishuEventHeader? header,
        CancellationToken cancellationToken = default)
    {
        if (eventEntity is null)
        {
            return;
        }

        _logger.LogInformation(
            "新员工入职：{Name} ({UserId})",
            eventEntity.Name,
            eventEntity.UserId);

        await Task.CompletedTask;
    }
}

4. 处理卡片事件回调

卡片事件回调（card.action.trigger）由卡片交互触发、经 Webhook 投递，业务服务器必须在 3 秒内响应。 处理器内可读取交互数据，响应体用 CardCallbackResponse 构造后写回 HTTP 响应（不得返回 3xx 重定向）：

using System.Text.Json;
using Mud.Feishu.Abstractions;
using Mud.Feishu.Abstractions.Services;
using Mud.Feishu.Abstractions.Utilities;
using Mud.Feishu.EventCallback;
using Mud.Feishu.EventCallback.Card;

public class MyCardActionHandler : CardActionTriggerEventHandler
{
    public MyCardActionHandler(IFeishuEventDeduplicator businessDeduplicator, ILogger<MyCardActionHandler> logger)
        : base(businessDeduplicator, logger)
    {
    }

    protected override async Task ProcessBusinessLogicAsync(
        EventData eventData,
        CardActionTriggerResult? eventEntity,
        FeishuEventHeader? header,
        CancellationToken cancellationToken = default)
    {
        var action = eventEntity?.Action;
        _logger.LogInformation("卡片交互：tag={Tag}, operator={OpenId}", action?.Tag, eventEntity?.Operator?.OpenId);

        // 构造响应：Toast 提示 + 更新卡片（raw 或 template）
        var response = new CardCallbackResponse
        {
            Toast = new CardCallbackToast
            {
                Type = "success",
                Content = "处理成功",
                I18n = new CardCallbackToastI18n { ZhCn = "处理成功", EnUs = "Success" }
            },
            Card = CardCallbackCard.Template("AAqi6xJ8rabcd", "1.0.0",
                new Dictionary<string, object?> { ["open_id"] = eventEntity?.Operator?.OpenId })
        };

        // 由宿主把响应写回 HTTP 响应体（AOT 安全入口）
        var json = FeishuJsonAot.Serialize(response, FeishuJsonDefaults.SerializerOptions);

        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,
                      HeaderType = nameof(FeishuEventHeader))]
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   # 考勤任务更新
├── Hire/                             # 招聘事件
│   ├── ApplicationDeletedEvent/                      # 投递删除
│   ├── ApplicationStageChangedEvent/                # 投递阶段变更
│   ├── OfferStatusChangedEvent/                     # Offer 状态变更
│   ├── EhrImportTaskImportedEvent/                  # 导入 e-HR
│   ├── EhrImportTaskForInternshipOfferImportedEvent/# 实习 Offer 导入 e-HR
│   ├── TalentTagSubscriptionEvent/                  # 人才标签订阅
│   ├── TalentDeletedEvent/                          # 人才删除
│   ├── EcoAccountCreatedEvent/                      # 账号创建
│   ├── EcoBackgroundCheckCreatedEvent/              # 背调创建
│   ├── EcoBackgroundCheckCanceledEvent/             # 背调取消
│   ├── EcoExamCreatedEvent/                         # 创建笔试
│   └── ReferralAccountAssetsUpdateEvent/            # 内推账户余额变更
├── Performance/                      # 绩效事件
│   ├── StageTaskOpenResultEvent/     # 绩效结果开通
│   └── ReviewDataChangedEvent/       # 绩效数据变更
├── Acs/                              # 智能门禁事件
│   ├── UserUpdatedEvent/             # 用户信息变更
│   └── AccessRecordCreatedEvent/     # 通行记录创建
├── Helpdesk/                         # 服务台事件
│   ├── Common/                       # 工单等共用模型
│   ├── TicketCreatedEvent/           # 工单创建
│   ├── TicketUpdatedEvent/           # 工单更新
│   ├── TicketMessageCreatedEvent/    # 工单消息创建
│   └── NotificationApproveEvent/     # 推送审批通知
├── Card/                             # 卡片事件回调（请求回调）
│   ├── CardActionTriggerEvent/       # 卡片交互回调（operator/action/context 等）
│   ├── CardCallbackResponse.cs       # 回调响应体（toast + card）
│   ├── CardCallbackToast.cs          # Toast 弹窗
│   ├── CardCallbackToastI18n.cs      # Toast 多语言
│   ├── CardCallbackCard.cs           # 响应卡片（raw / template）
│   └── CardCallbackTemplateData.cs   # 模板卡片数据
└── GlobalUsings.cs                   # 全局引用

依赖项

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

相关项目

• Mud.Feishu - 核心 HTTP API 客户端
• Mud.Feishu.DataModels - HTTP API 强类型数据模型
• Mud.Feishu.Abstractions - 事件处理抽象
• Mud.Feishu.Authentication - 用户认证中间件
• Mud.Feishu.Webhook - Webhook 事件处理
• Mud.Feishu.WebSocket - WebSocket 实时事件
• Mud.Feishu.Redis - Redis 分布式去重
• Mud.Feishu.OpenTelemetry - OpenTelemetry 可观测性扩展

文档与资源

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

许可证

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

版权声明

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

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

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

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