飞书开放平台非官方SDK, 个人开发, 请谨慎使用

支持自定义机器人、长连接机器人、云文档、飞书卡片、消息、群组等API调用。

🎉 v0.6.0 重大更新 - 企业级错误处理系统重构 ⭐

• 🛡️ 企业级错误处理: 全新5大核心模块，提供智能错误分析、自动重试、实时监控
• 🧠 智能错误分析: 技术错误转换为用户友好提示，自动生成修复建议和操作步骤
• 🔄 自动重试机制: 基于错误类型的智能重试策略，指数退避算法避免系统过载
• 📊 实时错误监控: 错误率计算、分类统计、智能告警，支持文件导出和报告生成
• 📝 结构化日志: 多格式输出(JSON/文本/结构化)，彩色控制台，灵活输出目标
• ♻️ 大规模重构完成: 68个文件迁移到owned参数模式，消除2000+个clone调用
• 📚 完整文档体系: 62页最佳实践指南，5个演示程序，完整的技术架构文档

使用

将.env-example文件重命名为.env，并填写相关配置。

快速开始 - 企业级错误处理

use open_lark::prelude::*;
use open_lark::core::{
    error_helper::ErrorHelper,
    error_metrics::ErrorMonitor,
    retry_middleware::{RetryMiddleware, RetryConfig},
    error_logger::{ErrorLogger, LoggerBuilder, LogLevel},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 设置监控和日志
    let monitor = ErrorMonitor::default();
    let logger = LoggerBuilder::new()
        .min_level(LogLevel::Info)
        .json_format()
        .build();

    // 设置智能重试策略
    let retry_middleware = RetryMiddleware::new(
        RetryConfig::new()
            .enabled(true)
            .server_errors_only()
    );

    let client = LarkClient::builder("your_app_id", "your_app_secret").build();

    // 执行API调用（带自动重试）
    let result = retry_middleware.execute(|| async {
        client.im.v1.message.create(&request).await
    }).await;

    // 智能错误处理
    match result {
        Ok(response) => println!("✅ 成功: {:?}", response),
        Err(error) => {
            // 记录错误
            monitor.record_error(error.clone());
            logger.log_api_error(&error);
            
            // 智能错误分析
            println!("❌ {}", error.user_friendly_message());
            let advice = ErrorHelper::handle_error(&error);
            for action in &advice.actions {
                println!("  💡 {}", action);
            }
        }
    }

    // 查看错误统计
    let stats = monitor.get_statistics();
    stats.print_detailed();

    Ok(())
}

快速开始 - 考勤模块

use open_lark::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = LarkClient::builder("your_app_id", "your_app_secret").build();

    // 查询所有班次
    let shifts_req = ListShiftsRequest {
        employee_type: "employee_id".to_string(),
        page_size: Some(20),
        ..Default::default()
    };
    
    let shifts_resp = client.attendance.v1.shift.list(shifts_req, None).await?;
    println!("班次列表: {:?}", shifts_resp.data);

    // 查询打卡记录
    let user_task_req = QueryUserTaskRequest {
        employee_type: "employee_id".to_string(),
        user_ids: vec!["employee_123".to_string()],
        check_date_from: "2024-06-01".to_string(),
        check_date_to: "2024-06-30".to_string(),
        ..Default::default()
    };
    
    let user_task_resp = client.attendance.v1.user_task.query(user_task_req, None).await?;
    println!("打卡记录: {:?}", user_task_resp.data);

    Ok(())
}

考勤事件监听

use open_lark::event::EventDispatcherHandler;

let handler = EventDispatcherHandler::builder()
    .register_p2_attendance_user_task_updated_v1(|event| {
        println!("收到打卡流水事件: {:?}", event);
    })
    .register_p2_attendance_user_task_status_change_v1(|event| {
        println!("收到任务状态变更事件: {:?}", event);
    })
    .build();

已完成

认证与授权

• 自建应用获取 tenant_access_token

自定义机器人

• 发送消息
• 签名验证

长连接机器人

• 接收事件推送

云文档

云空间

• 文件夹
  • 获取我的空间元信息
  • 获取文件夹元信息
  • 新建文件夹
  • 获取文件夹下的清单
• 上传
  • 上传文件
• 下载
  • 下载文件

权限

• 获取云文档权限设置
• 更新云文档权限设置

电子表格

• 表格
  • 创建表格
  • 修改电子表格属性
  • 获取电子表格信息
• 工作表
  • 查询工作表
  • 获取工作表
  • 操作工作表
  • 更新工作表属性
• 行列
  • 增加行列
  • 插入行列
  • 更新行列
  • 移动行列
  • 删除行列
• 单元格
  • 插入数据
  • 追加数据
  • 读取单个范围
  • 向单个范围写入数据
  • 读取多个范围
  • 向多个范围写入数据
  • 设置单元格样式
  • 批量设置单元格样式
  • 写入图片
  • 合并单元格
  • 拆分单元格
  • 查找单元格
  • 替换单元格
• 筛选
  • 获取筛选
  • 创建筛选
  • 更新筛选
  • 删除筛选

多维表格

• 多维表格
  • 获取多维表格元数据
• 字段
  • 列出字段
• 记录
  • 新增记录
  • 查询记录
  • 新增多条记录
  • 更新记录

通讯录

• 用户
  • 搜索用户

飞书卡片

卡片组件

• 卡片回传交互
• 容器
  • 分栏
  • 表单容器
  • 交互容器
  • 折叠面板
• 展示
  • 标题
  • 普通文本
  • 富文本(Markdown)
  • 图片
  • 多图混排
  • 分割线
  • 人员
  • 人员列表
  • 图表
  • 表格
  • 备注
• 交互
  • 输入框
  • 按钮
  • 折叠按钮组
  • 下拉选择-单选
  • 下拉选择-多选
  • 人员选择-单选
  • 人员选择-多选
  • 日期选择器
  • 时间选择器
  • 日期时间选择器
  • 多图选择
  • 勾选器

消息

• 发送消息
• 获取会话历史消息
• 消息内容结构
  • 发送消息内容
    • 文本
    • 富文本
    • 图片
    • 卡片
• 事件
  • 接收消息

群组

• 获取用户或机器人所在的群列表

考勤管理 🎉 v0.5.0 新增

考勤班次

• 创建班次
• 删除班次
• 按 ID 查询班次
• 按名称查询班次
• 查询所有班次

考勤排版

• 创建或修改排班表
• 查询排班表
• 创建或修改临时排班

考勤管理

• 查询考勤组下所有成员
• 创建或修改考勤组
• 删除考勤组
• 按 ID 查询考勤组
• 按名称查询考勤组
• 查询所有考勤组

考勤用户管理

• 修改用户人脸识别信息
• 批量查询用户人脸识别信息
• 上传用户人脸识别照片
• 下载用户人脸识别照片

考勤统计

• 更新统计设置
• 查询统计表头
• 查询统计设置
• 查询统计数据

假勤审批

• 获取审批数据
• 写入审批结果
• 通知审批状态更新

考勤补卡

• 通知补卡审批发起
• 获取可补卡时间
• 获取补卡记录

归档报表

• 查询归档报表表头
• 写入归档报表结果
• 删除归档报表行数据
• 查询所有归档规则

打卡信息管理

• 导入打卡流水
• 查询打卡流水
• 批量查询打卡流水
• 删除打卡流水
• 查询打卡结果

休假管理

• 通过过期时间获取发放记录
• 修改发放记录

考勤事件

• 打卡流水事件处理
• 用户任务状态变更事件处理

📊 功能完成度统计

模块	API数量	完成状态	说明
🔐 认证与授权	1	✅ 100%	应用身份验证
🤖 自定义机器人	2	✅ 100%	消息发送与签名验证
🔗 长连接机器人	1	✅ 100%	事件推送接收
☁️ 云文档-云空间	7	✅ 100%	文件夹管理、上传下载
🛡️ 云文档-权限	2	✅ 100%	权限设置管理
📊 云文档-电子表格	33	✅ 100%	完整表格操作功能
📋 云文档-多维表格	6	✅ 100%	数据表操作
👥 通讯录	1	✅ 100%	用户搜索
🎨 飞书卡片	25	✅ 100%	完整卡片组件系统
💬 消息	4	✅ 100%	消息发送与接收
👥 群组	1	✅ 100%	群组管理
🏢 考勤管理	43	✅ 100%	完整考勤解决方案
🛡️ 错误处理系统	5	✅ 100%	v0.6.0 新增 - 企业级错误管理
📈 总计	131	✅ 100%	覆盖企业应用核心功能

🎯 v0.6.0 企业级错误处理系统亮点

• 5大核心模块 错误监控、重试中间件、日志系统、智能分析、错误码支持
• 30+ 业务错误码 覆盖飞书生态全域，语义化分类管理
• 24个单元测试 100%通过率，确保系统稳定性
• 智能化体验 从技术错误到用户友好，AI级别的错误分析和建议
• 企业级特性 实时监控、自动重试、结构化日志、告警系统

🎯 v0.5.0 考勤模块特性

• 41个API 覆盖班次、排班、统计、审批等全业务流程
• 2个事件处理器 支持实时考勤数据监听
• 43个示例 每个功能都有完整的使用演示
• 企业级特性 支持复杂的考勤规则和业务场景

📚 文档和资源

错误处理系统文档

• 错误处理最佳实践 (62页) - 完整的开发指导和最佳实践
• 错误处理功能介绍 - 快速上手指南和功能概览
• 项目完成报告 - 详细的技术架构和成果总结

示例程序

• comprehensive_error_codes_demo.rs - 扩展错误码系统演示
• enhanced_error_handling.rs - 增强错误处理演示
• permission_owned_demo.rs - owned参数模式演示

API文档

• API参考文档 - 完整的API文档
• 示例代码集合 - 24个完整的演示程序

🚀 特性优势

企业级错误处理

• 零配置使用 - 开箱即用的合理默认配置
• 类型安全 - Rust强类型系统防止错误，统一的SDKResult<T>类型
• 并发安全 - Arc/Mutex确保多线程环境安全
• 模块化设计 - 每个模块可独立使用和扩展

性能优化

• 异步处理 - 全面使用async/await，零阻塞操作
• 内存效率 - 消除2000+个不必要的clone调用
• 智能缓存 - 自动token缓存管理
• 零开销抽象 - 编译时优化，运行时高效

开发体验

• 用户友好 - 智能错误分析，自动生成修复建议
• 完整文档 - 62页最佳实践指南，24个示例程序
• 类型提示 - 完整的类型定义和IDE支持
• 测试覆盖 - 24个错误处理测试，100%通过率