alun_task/
storage.rs

1//! 任务持久化 trait —— 由业务方实现的自定义存储接口
2//!
3//! 插件不持有任何 SQL 语句、表名、字段名。所有持久化逻辑完全由调用方通过实现此 trait 控制。
4//! 业务方可以自由选择存储后端（PostgreSQL / MySQL / MongoDB / 文件 ……）。
5
6use async_trait::async_trait;
7use serde::{Deserialize, Serialize};
8
9use crate::types::{TaskConfig, TaskStatus, SubmitTaskParams};
10
11/// 扫描到的可重试任务
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct RetryableTask {
14    /// 任务 ID
15    pub task_id: String,
16    /// 任务类型标识
17    pub task_type: i16,
18    /// 当前已重试次数
19    pub retry_count: i64,
20    /// 最大允许重试次数
21    pub max_retries: i64,
22    /// 任务载荷（JSON 格式）
23    pub payload: serde_json::Value,
24}
25
26/// 任务持久化接口
27///
28/// 业务方实现此 trait，定义任务数据的存储方式。
29/// 所有方法均返回 `Result<(), String>`，失败原因通过 `Err(String)` 传递。
30#[async_trait]
31pub trait TaskStorage: Send + Sync {
32    /// 持久化任务日志（提交任务时调用）
33    ///
34    /// 接收完整的任务提交参数与配置，由实现方决定如何存储（表名、字段映射）。
35    async fn save_task_log(
36        &self,
37        task_id: &str,
38        task_type: i16,
39        priority: i16,
40        config: &TaskConfig,
41        params: &SubmitTaskParams,
42    ) -> Result<(), String>;
43
44    /// 持久化任务队列记录（提交任务时调用）
45    ///
46    /// 记录任务已入队，供外部查询队列状态。
47    async fn save_task_queue(
48        &self,
49        task_id: &str,
50        topic: &str,
51        priority: i16,
52    ) -> Result<(), String>;
53
54    /// 更新任务状态
55    ///
56    /// 状态变更时机：提交后 Pending → Worker 拾取 Processing → 成功 Completed / 失败 Failed / DLQ DeadLetter
57    async fn update_task_status(
58        &self,
59        task_id: &str,
60        status: TaskStatus,
61    ) -> Result<(), String>;
62
63    /// 获取当前重试次数
64    async fn get_retry_count(&self, task_id: &str) -> Result<i64, String>;
65
66    /// 更新重试信息
67    ///
68    /// 失败后递增 retry_count，同时将状态重置为 Pending 等待 RetryScanner 重新推送。
69    async fn update_retry(&self, task_id: &str, retry_count: i64) -> Result<(), String>;
70
71    /// 保存任务执行结果（成功或失败后的输出）
72    async fn save_task_result(
73        &self,
74        task_id: &str,
75        output: &serde_json::Value,
76    ) -> Result<(), String>;
77
78    /// 记录执行日志
79    ///
80    /// 每次执行（含重试）都记录一条，供审计和排障。
81    async fn log_execution(
82        &self,
83        task_id: &str,
84        status: TaskStatus,
85        error: Option<&str>,
86        elapsed_ms: i64,
87    ) -> Result<(), String>;
88
89    /// 扫描需要重试的任务
90    ///
91    /// 返回当前所有 status=Failed 且 retry_count < max_retries 的任务。
92    /// RetryScanner 定期调用此方法获取待重试列表。
93    async fn scan_retryable_tasks(
94        &self,
95        task_types: &[i16],
96        limit: usize,
97    ) -> Result<Vec<RetryableTask>, String>;
98}
alun_task/storage.rs

alun_task/
storage.rs
