Mud.Feishu.DataModels 3.0.0

Mud.Feishu.DataModels

飞书 HTTP API 强类型数据模型库，为 Mud.Feishu 核心 HTTP API 客户端提供完整的请求/响应数据模型定义。

项目简介

Mud.Feishu.DataModels 是 MudFeishu SDK 的数据模型层，专门用于封装飞书开放平台所有 HTTP API 的请求参数和响应结果。项目采用强类型设计，所有模型均带有完整的 XML 文档注释和 JSON 序列化特性标注，帮助开发者在编译时获得类型安全保障，并通过智能提示快速了解字段含义。

💡 本项目是 Mud.Feishu 的隐式依赖，安装 Mud.Feishu 后将自动引入，通常无需单独安装。

特性

• ✅ 强类型数据模型 - 所有 API 的请求参数和响应结果均有完整类型定义
• ✅ 完整 JSON 标注 - 使用 [JsonPropertyName] 精确映射飞书 API 字段
• ✅ XML 文档注释 - 每个公共属性均有中文文档注释，支持智能提示
• ✅ 按模块组织 - 数据模型按飞书 API 模块分目录组织，结构清晰
• ✅ 请求/响应分离 - 每个模块下 RequestModel 和 ResponseModel 独立管理
• ✅ 公共模型复用 - Common 命名空间提供分页、通用筛选等共享模型
• ✅ 多框架支持 - 支持 .NET Standard 2.0、.NET 6.0、.NET 8.0、.NET 10.0，兼容 .NET Framework 4.6.1+
• ✅ 原生 AOT 支持 - 全量 DTO 由源生成 JsonSerializerContext 覆盖，net8.0+ 一等公民支持 Native AOT 发布

数据模型模块总览

命名规范

数据模型按以下约定组织：

Mud.Feishu.DataModels/
├── {Module}/                    # API 模块（如 Approval、Organization）
│   ├── {SubModule}/             # 子模块（如 ApprovalTask、ApprovalQuery）
│   │   ├── Common/              # 子模块公共模型
│   │   ├── RequestModel/        # 请求参数模型
│   │   └── ResponseModel/       # 响应结果模型
│   └── {SharedModel}.cs         # 模块级共享模型
└── Common/                      # 全局共享模型
    ├── PageRequest.cs           # 分页请求基类
    ├── PageListResult.cs        # 分页结果基类
    └── ...

模型命名约定

安装

dotnet add package Mud.Feishu.DataModels

💡 通常无需单独安装，Mud.Feishu 已包含本项目作为依赖。

使用示例

1. 配合 Mud.Feishu API 接口使用

using Mud.Feishu.DataModels.Organization;
using Mud.Feishu.DataModels.Messages;

public class UserService
{
    private readonly IFeishuTenantV3User _userApi;

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

    // 使用请求模型创建用户
    public async Task<CreateOrUpdateUserResult?> CreateUserAsync()
    {
        var request = new CreateUserRequest
        {
            UserId = "test_user_id",
            Name = "张三",
            Email = "zhangsan@example.com",
            Mobile = "13800138000",
            DepartmentIds = new List<string> { "dept_001" }
        };

        var result = await _userApi.CreateUserAsync(request);
        return result?.Data;
    }
}

2. 使用分页请求模型

using Mud.Feishu.DataModels.Common;

public class DepartmentService
{
    private readonly IFeishuTenantV3Departments _deptApi;

    // 使用分页请求获取子部门列表
    public async Task GetSubDepartmentsAsync(string parentId)
    {
        var result = await _deptApi.GetDepartmentsByParentIdAsync(
            parentId,
            page_size: 50,
            page_token: null);

        // FeishuApiPageListResult<T> 包含分页信息和数据
        if (result?.Code == 0)
        {
            var departments = result.Data.Items;
            var nextPageToken = result.Data.PageToken;
        }
    }
}

3. 使用消息请求模型发送卡片消息

using Mud.Feishu.DataModels.Messages;

public class MessageService
{
    private readonly IFeishuTenantV1Message _messageApi;

    public async Task SendTextMessageAsync(string receiveId)
    {
        var request = new SendMessageRequest
        {
            ReceiveId = receiveId,
            MsgType = "text",
            Content = """{"text":"Hello from Mud.Feishu!"}"""
        };

        // receive_id_type 是 SendMessageAsync 的查询参数（默认 open_id），
        // 不是请求体属性；如需显式指定，通过方法参数传入
        var result = await _messageApi.SendMessageAsync(request, receive_id_type: "open_id");
    }
}

公共模型

Mud.Feishu.DataModels.Common 命名空间提供以下共享模型：

框架支持

• .NET Standard 2.0（兼容 .NET Framework 4.6.1+、.NET Core 2.0+）
• .NET 6.0
• .NET 8.0
• .NET 10.0

依赖项

相关项目

• Mud.Feishu - 核心 HTTP API 客户端库
• Mud.Feishu.Abstractions - 事件处理抽象层
• Mud.Feishu.EventCallback - 事件回调强类型数据模型
• Mud.Feishu.WebSocket - WebSocket 实时事件订阅
• Mud.Feishu.Webhook - Webhook HTTP 回调事件处理

许可证

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

Mud.Feishu.DataModels - 强类型数据模型，让飞书 API 调用更安全！