Crate openlark_client 

🚀 OpenLark Client Library

现代化的飞书开放平台 Rust SDK，提供简洁、类型安全的 API 访问 集成 CoreError 企业级错误处理系统，提供全面的错误管理和恢复建议

普通用户请优先使用根 crate openlark。

openlark-client 保留为高级入口：适合只想复用统一客户端层，或明确需要直接控制客户端 feature 组合的场景。

Canonical 公开入口约定：

• 运行时入口优先使用 Client / ClientBuilder
• 导入优先使用 openlark_client::prelude::*
• 业务调用优先从 client.<domain> 字段链开始

普通用户请优先使用根 crate openlark；本 crate 保留为高级入口。

核心特性

• 🎯 Feature-driven: 基于编译时功能标志的模块化设计
• ⚡ 零配置: 支持从环境变量自动配置客户端
• 🔒 类型安全: 完全编译时验证的 API 调用
• 🚀 异步优先: 完全异步的客户端实现
• 🏗️ 现代构建器: 流畅的构建器模式 API
• 🔍 能力诊断: 编译期能力 catalog（字段唯一 / 禁用 feature 不产字段，trybuild 保证）
• 🛡️ 企业级: 基于 CoreError 的高级错误处理、重试和监控支持
• 🌐 中文优先: 100% 中文错误消息和文档，专为中国开发者优化

快速开始

基础用法

use openlark_client::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 从环境变量创建客户端（推荐）
    let client = Client::from_env()?;

    // 单入口：meta 链式字段访问（需要对应 feature）
    // - 通讯：client.communication.im...
    // - 文档：client.docs.config()...
    // - 认证：client.auth.app / client.auth.user / client.auth.oauth

    Ok(())
}

构建器模式

use openlark_client::prelude::*;
use std::time::Duration;

fn main() -> Result<()> {
    let _client = Client::builder()
        .app_id("your_app_id")
        .app_secret("your_app_secret")
        .base_url("<https://open.feishu.cn>")
        .timeout(Duration::from_secs(30))
        .enable_log(true)
        .build()?;
    Ok(())
}

Endpoint 切换

OpenLark 默认使用国内飞书 endpoint：https://open.feishu.cn。 如果你的应用运行在国际版 Lark，请将 base_url 切换为 https://open.larksuite.com。

use openlark_client::prelude::*;

fn main() -> Result<()> {
    let _client = Client::builder()
        .app_id("your_app_id")
        .app_secret("your_app_secret")
        .base_url("<https://open.larksuite.com>")
        .build()?;
    Ok(())
}

环境变量配置

设置以下环境变量：

export OPENLARK_APP_ID="your_app_id"
export OPENLARK_APP_SECRET="your_app_secret"
export OPENLARK_BASE_URL="<https://open.feishu.cn>"  # 可选，国际版请改为 <https://open.larksuite.com>
export OPENLARK_TIMEOUT="30"  # 可选，秒
export OPENLARK_ENABLE_LOG="true"  # 可选

功能标志

客户端使用 Rust 功能标志进行模块化编译：

[dependencies]
openlark-client = { version = "0.1", features = [
    "communication",  # 通讯服务
    "hr",           # 人力资源服务
    "docs",         # 文档服务
    "ai",           # AI 服务
    "auth",         # 认证服务
    "websocket",    # WebSocket 支持
]}

服务访问

每个启用功能都提供对应的 meta 链式入口（字段访问）：

use openlark_client::prelude::*;

fn main() -> Result<()> {
let client = Client::from_env()?;

// 通讯入口（communication feature）
#[cfg(feature = "communication")]
let _comm = &client.communication;

// 文档入口（docs feature）
#[cfg(feature = "docs")]
let _docs = &client.docs;

// 认证入口（auth feature）
#[cfg(feature = "auth")]
let _auth = &client.auth;
Ok(())
}

高级用法

自定义配置

use openlark_client::prelude::*;
use std::time::Duration;

fn main() -> Result<()> {
    let _client = Client::builder()
        .app_id("app_id")
        .app_secret("app_secret")
        .base_url("<https://open.feishu.cn>")
        .timeout(Duration::from_secs(60))
        .retry_count(3)
        .enable_log(true)
        .build()?;
    Ok(())
}

错误处理

客户端基于 CoreError 提供企业级错误处理，包含详细的错误分析、恢复建议和中文友好的错误消息：

use openlark_client::prelude::*;

match Client::from_env() {
    Ok(client) => {
        println!("客户端创建成功");
        // 使用客户端...
    },
    Err(error) => {
        // 用户友好的错误消息（中文）
        eprintln!("❌ {}", error.user_message().unwrap_or("未知错误"));

        // 获取错误恢复建议
        eprintln!("💡 建议: {}", error.suggestion());

        // 获取详细的恢复步骤
        for (i, step) in error.recovery_steps().iter().enumerate() {
            eprintln!("{}. {}", i + 1, step);
        }

        // 获取完整的错误分析报告
        eprintln!("\n{}", ErrorAnalyzer::new(&error).detailed_report());

        // 根据错误类型进行特定处理
        if error.is_validation_error() {
            eprintln!("请检查配置参数是否正确");
        } else if error.is_network_error() {
            eprintln!("请检查网络连接并稍后重试");
        } else if error.is_auth_error() {
            eprintln!("请检查应用凭据是否有效");
        }
    }
}

错误类型和处理

use openlark_client::prelude::*;

// 捕获和处理特定类型的错误
async fn send_message_with_error_handling() -> Result<()> {
    let client = Client::from_env()?;

    // 单入口：meta 链式字段访问。这里演示“拿到入口 + 挂上错误上下文”的模式。
    #[cfg(feature = "communication")]
    let _comm = &client.communication;

    // 具体 API 调用请使用 openlark-communication 的强类型请求/构建器并在 `.await` 处处理 Result。
    Ok(())
}

Re-exports

pub use client::Client;

pub use client::ClientBuilder;

pub use error::Error;

pub use error::Result;

pub use error::ClientErrorExt;

pub use error::ErrorAnalyzer;

pub use error::with_context;

pub use error::with_operation_context;

pub use error::api_error;

pub use error::authentication_error;

pub use error::business_error;

pub use error::configuration_error;

pub use error::internal_error;

pub use error::network_error;

pub use error::rate_limit_error;

pub use error::serialization_error;

pub use error::service_unavailable_error;

pub use error::timeout_error;

pub use error::validation_error;

pub use client::AuthClient;

Modules

client

OpenLark Client - 全新简化架构

error

OpenLark Client 错误类型定义

info

🏷️ 库信息

prelude

🚀 预导出模块 - 包含最常用的类型和特征

utils

🔧 实用工具函数

Structs

CommunicationClient

Communication 链式入口：communication.im / communication.contact / communication.moments

CoreConfig

零拷贝配置共享实现

Enums

CoreError

轻量版核心错误

ErrorCode

标准错误码枚举

ErrorSeverity

错误严重程度

ErrorType

错误类型分类

Traits

ErrorTrait

核心错误特征

Type Aliases

CoreResult

SDK 操作结果类型别名

SDKResult

🚨 SDK 结果类型别名（与 Core 系统兼容）