Bark Rust 客户端

一个功能完整的 Bark 推送服务 Rust 客户端库，采用清晰的模块化设计，支持所有官方 API 参数。

🏗️ 架构设计

三层架构

1. 消息构建层 (BarkMessage) - 统一的消息构建，同步异步通用
2. 同步客户端 (SyncBarkClient) - 专门处理同步发送，零运行时依赖
3. 异步客户端 (AsyncBarkClient) - 专门处理异步发送，可选功能

设计优势

• 🧩 模块分离: 消息构建与发送客户端完全分离
• 🔄 灵活复用: 同一个消息可以用不同客户端发送
• 📦 按需引入: tokio 是可选依赖，只在需要异步功能时引入
• 🚫 无冲突: 同步和异步客户端各司其职，不会相互干扰

功能特性

• 🚀 默认同步 - 无需外部运行时，开箱即用
• ⚡ 可选异步 - 通过 feature 启用异步功能
• 🛠️ Builder 模式 - 链式调用，易于使用
• 📱 完整 API 支持 - 支持所有 Bark API 参数
• 🔄 批量推送 - 支持向多个设备同时发送
• 🛡️ 完整错误处理 - 详细的错误类型和处理
• ✅ 全面测试 - 包含完整的测试用例

安装

[dependencies]
# 只使用同步功能（默认使用 native-tls）
bark_rs = "0.1.2"

# 启用异步功能
bark_rs = { version = "0.1.2", features = ["async"] }

# 使用 rustls 替代 native-tls（更轻量，纯 Rust 实现）
bark_rs = { version = "0.1.2", default-features = false, features = ["rustls"] }

# 同时启用异步和 rustls
bark_rs = { version = "0.1.2", default-features = false, features = ["async", "rustls"] }

快速开始

同步使用（推荐）

use bark_rs::{SyncBarkClient, Level};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建同步客户端
    let client = SyncBarkClient::with_device_key("https://api.day.app", "your_device_key");

    // 发送推送
    let response = client
        .message()
        .title("测试标题")
        .body("这是一个测试消息")
        .send()?;

    println!("推送成功: {}", response.message);
    Ok(())
}

异步使用

// Cargo.toml: bark_rs = { version = "0.1.0", features = ["async"] }
use bark_rs::{AsyncBarkClient, Level};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AsyncBarkClient::with_device_key("https://api.day.app", "your_device_key");

    let response = client
        .message()
        .title("异步测试")
        .body("这是一个异步消息")
        .send()
        .await?;

    println!("异步推送成功: {}", response.message);
    Ok(())
}

消息构建与发送分离

use bark_rs::{SyncBarkClient, BarkMessage, Level};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 构建消息（与发送客户端无关）
    let message = BarkMessage::builder()
        .title("独立消息")
        .body("消息构建与发送完全分离")
        .level(Level::Critical)
        .sound("alarm")
        .badge(1)
        .build();

    // 创建同步客户端并发送
    let sync_client = SyncBarkClient::with_device_key("https://api.day.app", "your_key");
    let response = sync_client.send(&message)?;
    
    println!("发送成功: {}", response.message);
    Ok(())
}

高级功能

完整参数演示

use bark_rs::{SyncBarkClient, Level};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SyncBarkClient::with_device_key("https://api.day.app", "your_device_key");

    let response = client
        .message()
        .title("重要通知")
        .subtitle("系统警告")
        .body("服务器负载过高，请立即检查！")
        .level(Level::Critical)           // 重要警告级别
        .volume(10)                       // 最大音量
        .badge(1)                         // 应用角标
        .call(true)                       // 重复播放铃声
        .auto_copy(true)                  // 自动复制内容
        .sound("alarm")                   // 警报铃声
        .icon("https://example.com/alert.png") // 自定义图标
        .group("系统监控")                 // 消息分组
        .is_archive(true)                 // 保存到历史
        .url("https://monitor.example.com") // 点击跳转链接
        .id("server_alert_001")           // 消息ID
        .send()?;

    println!("推送成功: {}", response.message);
    Ok(())
}

批量推送

let response = client
    .message()
    .device_keys(vec![
        "device_key_1".to_string(),
        "device_key_2".to_string(),
        "device_key_3".to_string(),
    ])
    .title("批量通知")
    .body("这是一个发送给多个设备的消息")
    .level(Level::TimeSensitive)
    .send()?;

混合使用场景

use bark_rs::{SyncBarkClient, AsyncBarkClient, BarkMessage, Level};

// 构建一个消息
let message = BarkMessage::builder()
    .title("共享消息")
    .body("这个消息可以被不同客户端使用")
    .level(Level::Active)
    .build();

// 同步发送
let sync_client = SyncBarkClient::new("https://api.day.app");
sync_client.send(&message)?;

// 异步发送（需要 async feature）
#[cfg(feature = "async")]
{
    let async_client = AsyncBarkClient::new("https://api.day.app");
    async_client.send(&message).await?;
}

API 参考

客户端类型

• SyncBarkClient - 同步客户端，默认可用
• AsyncBarkClient - 异步客户端，需要 async feature

消息构建

• BarkMessage::builder() - 创建消息构建器
• BarkMessage::new() - 同上，别名方法

支持的参数

• 基础参数: title, subtitle, body, device_key, device_keys
• 通知级别: level (critical/active/timeSensitive/passive)
• 音效控制: volume, badge, call, sound
• 复制功能: autoCopy, copy
• 外观定制: icon, group
• 行为控制: isArchive, url, action
• 消息管理: id, delete
• 加密支持: ciphertext

错误处理

use bark_rs::{SyncBarkClient, BarkError};

match client.message().body("测试").send() {
    Ok(response) => println!("成功: {}", response.message),
    Err(BarkError::RequestError(e)) => println!("网络错误: {}", e),
    Err(BarkError::MissingDeviceKey) => println!("缺少设备密钥"),
    Err(BarkError::InvalidUrl) => println!("无效的URL"),
    Err(BarkError::SerializationError(e)) => println!("序列化错误: {}", e),
}

运行示例

# 同步示例
cargo run --example sync_client
cargo run --example message_builder
cargo run --example batch_push
cargo run --example error_handling

# 异步示例（需要 async feature）
cargo run --features async --example async_client

# 混合使用
cargo run --features async --example mixed_usage

Features

• async - 启用异步功能和 AsyncBarkClient
• native-tls - 使用系统原生TLS实现（默认启用）
• rustls - 使用pure-Rust的rustls TLS实现，更轻量且无需系统依赖

TLS 选择指南

该库支持两种TLS实现，您可以根据需求选择：

native-tls（默认）

• 使用系统原生的TLS库（如OpenSSL、Secure Transport等）
• 兼容性好，适合大多数环境
• 需要系统安装相应的TLS库

rustls

• 纯Rust实现，无需外部依赖
• 编译产物更小，启动更快
• 适合容器环境和嵌入式系统
• 推荐用于新项目

# 使用rustls的示例配置
[dependencies]
bark_rs = { version = "0.1.2", default-features = false, features = ["rustls"] }

测试

# 测试同步功能
cargo test

# 测试异步功能
cargo test --features async

设计理念

这个库遵循以下设计原则：

1. 关注点分离: 消息构建与发送逻辑完全分离
2. 按需引入: 异步功能是可选的，不强制依赖 tokio
3. 类型安全: 编译时确保参数正确性
4. 易于使用: Builder 模式提供良好的开发体验
5. 灵活扩展: 模块化设计便于未来功能扩展

通知级别说明

• Level::Critical: 重要警告，在静音模式下也会响铃
• Level::Active: 默认值，系统会立即亮屏显示通知
• Level::TimeSensitive: 时效性通知，可在专注状态下显示
• Level::Passive: 仅添加到通知列表，不会亮屏提醒

许可证

MIT License