Crate open_lark

Source

Expand description

§飞书开放平台非官方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%通过率

Modules§

card
client
core
custom_bot
event
prelude
service

Macros§

impl_api_response: 使用宏简化APIResponseTrait实现
impl_executable_builder: 核心宏：为Builder类型自动实现ExecutableBuilder trait
impl_executable_builder_config: 为直接使用Config参数的独立函数实现ExecutableBuilder trait
impl_executable_builder_owned: 为使用值类型参数的Builder实现ExecutableBuilder trait

Crate open_larkCopy item path

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

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

§使用

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

§快速开始 - 考勤模块

§考勤事件监听

§已完成

§认证与授权

§自定义机器人

§长连接机器人

§云文档

§云空间

§权限

§电子表格

§多维表格

§通讯录

§飞书卡片

§卡片组件

§消息

§群组

§考勤管理 🎉 v0.5.0 新增

§考勤班次

§考勤排版

§考勤管理

§考勤用户管理

§考勤统计

§假勤审批

§考勤补卡

§归档报表

§打卡信息管理

§休假管理

§考勤事件

§📊 功能完成度统计

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

§🎯 v0.5.0 考勤模块特性

§📚 文档和资源

§错误处理系统文档

§示例程序

§API文档

§🚀 特性优势

§企业级错误处理

§性能优化

§开发体验

Modules§

Macros§

Crate open_lark