alun_task/
lib.rs

1//! 异步任务框架
2//!
3//! 基于 Kafka 消息队列的任务分发与处理框架。
4//! 插件本身**不持有任何 SQL 或表结构**——所有持久化通过 `TaskStorage` trait 委托给业务方实现。
5//!
6//! ## 核心能力
7//!
8//! - 任务提交（Kafka 消息 + 通过 `TaskStorage` 持久化）
9//! - 处理器注册（按 `task_type` 分发到不同业务 Handler）
10//! - 重试机制（固定延迟/线性增长/指数退避）+ 死信队列
11//! - 任务生命周期标记（PENDING → PROCESSING → COMPLETED/FAILED/CANCELLED/DEAD_LETTER）
12//! - `alun_core::Plugin` 集成（通过 `PluginManager` 统一启动/停止）
13//! - `#[task_handler]` 宏注解自动发现 Handler（编译期 linkme 收集）
14//! - **配置从配置文件 `[task]` section 读取**（`TaskWorkerConfig` 实现 Deserialize）
15//!
16//! ## 使用方式
17//!
18//! ```ignore
19//! // 1. 实现 TaskStorage（内部通过 db() 全局函数操作数据库）
20//! struct DbTaskStorage;
21//! impl TaskStorage for DbTaskStorage { ... }
22//!
23//! // 2. 从配置文件读取配置，创建插件 → 注册到 App
24//! let task_cfg: TaskWorkerConfig = cfg().custom.get("task")...unwrap_or_default();
25//! let plugin = TaskPlugin::new(
26//!     task_cfg,
27//!     Arc::new(DbTaskStorage),
28//!     HandlerRegistry::new().from_discovered(),
29//! )?;
30//! app.plugin(plugin).scan().start().await
31//! ```
32
33mod types;
34mod storage;
35mod handler;
36mod registry;
37mod producer;
38mod worker;
39mod retry;
40mod metrics;
41mod plugin;
42
43pub use types::*;
44pub use storage::{TaskStorage, RetryableTask};
45pub use handler::TaskHandler;
46pub use registry::HandlerRegistry;
47pub use producer::TaskProducer;
48pub use worker::TaskWorker;
49pub use retry::{RetryScanner, compute_retry_delay};
50pub use metrics::TaskMetrics;
51pub use plugin::TaskPlugin;
52
53/// 任务处理器注册条目 —— 编译期由 `#[task_handler]` 宏收集
54///
55/// 与 linkme distributed_slice 配合使用，实现编译期自动发现。
56#[derive(Debug, Clone)]
57pub struct TaskHandlerEntry {
58    /// 任务类型标识
59    pub task_type: i16,
60    /// 处理器构建函数（返回 Box<dyn TaskHandler>）
61    pub handler_fn: fn() -> Box<dyn TaskHandler>,
62    /// 任务配置
63    pub config_fn: fn() -> TaskConfig,
64}
65
66/// 任务处理器分布式切片 —— `#[task_handler]` 宏注解的 handler 在此汇集
67///
68/// 使用 linkme 在链接期自动收集所有被注解的 handler，
69/// 启动时通过 `HandlerRegistry::from_discovered()` 一键注册。
70#[linkme::distributed_slice]
71pub static TASK_HANDLERS: [TaskHandlerEntry] = [..];
alun_task/lib.rs

alun_task/
lib.rs
