Mud.Feishu 3.0.0-preview3

Mud.Feishu

Mud.Feishu 是飞书服务端 SDK 的 .NET 适配版，提供完整的 HTTP API 客户端能力，支持 .NET Standard 2.0、.NET 6.0、.NET 8.0 和 .NET 10.0 平台。通过类型安全的 API 封装，让开发者能够在 .NET 应用程序中便捷、高效地集成飞书服务端功能。

特性

• 类型安全 - 强类型接口定义，编译时类型检查
• 模块化设计 - 按需注册 API 模块，减少不必要的依赖
• 自动令牌管理 - 智能缓存和刷新，无需手动维护
• 智能重试机制 - 内置重试策略，提高调用成功率
• 多应用支持 - 统一管理多个飞书应用
• 完整 API 覆盖 - 支持组织架构、消息、群聊、审批、任务、云文档、画板、电子表格、多维表格等飞书核心功能

安装

dotnet add package Mud.Feishu

快速开始

1. 配置文件 (appsettings.json)

{
  "FeishuApps": [
    {
      "AppKey": "default",
      "AppId": "your_feishu_app_id",
      "AppSecret": "your_feishu_app_secret",
      "BaseUrl": "https://open.feishu.cn",
      "TimeOut": 30,
      "RetryCount": 3,
      "RetryDelayMs": 1000,
      "EnableLogging": true
    }
  ]
}

2. 服务注册 (Program.cs)

using Mud.Feishu;
using Mud.Feishu.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 注册飞书应用配置
builder.Services.AddFeishuApp(builder.Configuration);

// 方式一：懒人模式 - 注册所有 API 服务
builder.Services.CreateFeishuServicesBuilder()
    .AddAllApis()
    .Build();

// 方式二：建造者模式 - 按需注册
builder.Services.CreateFeishuServicesBuilder()
    .AddOrganizationApi()
    .AddMessageApi()
    .AddChatGroupApi()
    .AddApprovalApi()
    .AddTaskApi()
    .AddCardApi()
    .AddAttendanceApi()
    .AddDriveApi()
    .AddWikiApi()
    .AddDocxApi()
    .AddSpreadsheetsApi()
    .AddBiTableApi()
    .Build();

// 方式三：模块枚举模式
builder.Services.AddFeishuServices(
    FeishuModule.Organization,
    FeishuModule.Message,
    FeishuModule.ChatGroup,
    FeishuModule.Spreadsheets,
    FeishuModule.Bitable
);

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

3. 使用 API 服务

using Mud.Feishu;

public class UserService
{
    private readonly IFeishuV3User_Tenant _userApi;

    public UserService(IFeishuV3User_Tenant userApi)
    {
        _userApi = userApi;
    }

    public async Task<FeishuApiResult<UserInfoResult>?> GetUserAsync(string userId)
    {
        return await _userApi.GetUserInfoByIdAsync(userId);
    }

    public async Task<FeishuApiResult<CreateOrUpdateUserResult>?> CreateUserAsync(CreateUserRequest request)
    {
        return await _userApi.CreateUserAsync(request);
    }
}

API 模块

组织管理 (Organization)

用户管理

继承关系：IFeishuTenantV3User / IFeishuUserV3User → IFeishuV3User

部门管理

继承关系：IFeishuTenantV3Departments / IFeishuUserV3Departments → IFeishuV3Departments

其他组织管理接口

消息服务 (Messages)

继承关系：IFeishuTenantV1Message / IFeishuUserV1Message → IFeishuV1Message

群聊管理 (ChatGroup)

继承关系：IFeishuTenantV1ChatGroup / IFeishuUserV1ChatGroup → IFeishuV1ChatGroup

其他群聊相关接口：

审批流程 (Approval)

租户令牌接口 IFeishuTenantV4Approval 主要 API 函数：

• CreateApprovalAsync - 创建审批定义
• GetApprovalByCodeAsync - 获取审批定义信息
• CreateInstanceAsync - 创建审批实例
• CancelInstanceAsync - 撤回审批实例
• CarbonCopyInstanceAsync - 抄送审批实例
• PreviewInstanceAsync - 预览审批流程
• GetInstanceByIdAsync - 获取审批实例详情

任务管理 (Task)

继承关系：IFeishuTenantV2Task / IFeishuUserV2Task → IFeishuV2Task

其他任务相关接口：

卡片管理 (Card)

考勤管理 (Attendance)

云盘管理 (Drive)

继承关系：IFeishuTenantV1DriveFiles / IFeishuUserV1DriveFiles → IFeishuV1DriveFiles

其他云盘相关接口：

云文档权限管理 (Drive Permissions)

继承关系：IFeishuTenantV1DrivePermissions / IFeishuUserV1DrivePermissions → IFeishuV1DrivePermissions

云文档评论 (Drive Comments)

继承关系：IFeishuTenantV1Comments / IFeishuUserV1Comments → IFeishuV1Comments

云文档事件订阅 (Drive Subscribe)

继承关系：IFeishuTenantV1DriveSubscribe / IFeishuUserV1DriveSubscribe → `IFeishuV1Drive

知识库 (Wiki)

继承关系：IFeishuTenantV2Wiki / IFeishuUserV2Wiki → IFeishuV2Wiki

知识节点接口：

文档管理 (Docx)

IFeishuV1Docx       // 文档基础操作
IFeishuV1DocxBlocks // 文档块操作

功能列表：

• 文档创建和获取
• 文档块读取和更新
• 批量操作文档块
• 内容转换

画板管理 (Board)

继承关系：IFeishuTenantV1Board / IFeishuUserV1Board → IFeishuV1Board

电子表格 (Spreadsheets)

多维表格 (Bitable)

多应用支持

Mud.Feishu 支持在同一个系统中管理多个飞书应用：

// 配置多个应用
builder.Services.AddFeishuApp(configure =>
{
    configure.AddDefaultApp("default", "cli_xxx", "dsk_xxx");
    configure.AddApp("hr-app", "cli_yyy", "dsk_yyy", opt =>
    {
        opt.TimeOut = 45;
        opt.RetryCount = 5;
    });
});

// 使用指定应用
public class MultiAppService
{
    private readonly IFeishuAppManager _appManager;

    public async Task UseSpecificAppAsync()
    {
        // 获取指定应用的 API
        var userApi = _appManager.GetFeishuApi<IFeishuV3User_Tenant>("hr-app");
        var result = await userApi.GetUserInfoByIdAsync("user_123");
    }

    // 使用应用上下文切换器
    public async Task UseContextSwitcherAsync()
    {
        var contextSwitcher = _appManager.GetAppContextSwitcher();
        using (contextSwitcher.UseApp("hr-app"))
        {
            // 在此作用域内，所有 API 调用都使用 hr-app 的凭证
        }
    }
}

配置选项

自定义模块注册

Mud.Feishu 支持自定义模块注册器，方便扩展：

public class CustomModuleRegistrar : IFeishuModuleRegistrar
{
    public FeishuModule Module => FeishuModule.All + 1;

    public void Register(IServiceCollection services)
    {
        services.AddTransient<ICustomApi, CustomApi>();
    }
}

// 注册自定义模块
builder.Services.CreateFeishuServicesBuilder()
    .RegisterModule(new CustomModuleRegistrar())
    .Build();

核心特性

自动令牌管理

SDK 内置了智能的令牌管理机制：

• 自动获取和缓存 access_token
• 令牌即将过期时自动刷新
• 支持应用令牌、租户令牌、用户令牌三种类型
• 高并发场景下的缓存击穿防护

智能重试机制

针对网络不稳定等场景，SDK 提供了可配置的重试策略：

• 可配置重试次数和延迟时间
• 支持指数退避策略
• 自动重试失败的 API 调用

类型安全

所有 API 都通过强类型接口定义：

• 编译时类型检查
• 完整的 XML 文档注释
• 智能提示支持

依赖项

框架支持

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

相关项目

• Mud.Feishu.Abstractions - 事件订阅抽象层
• Mud.Feishu.WebSocket - WebSocket 实时事件订阅
• Mud.Feishu.Webhook - Webhook HTTP 回调事件处理
• Mud.Feishu.Authentication - 用户认证中间件
• Mud.Feishu.Redis - Redis 分布式去重扩展

许可证

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

反馈与贡献

如有问题或建议，欢迎提交 Issue 或 Pull Request。

Mud.Feishu - 让飞书集成变得简单！