toms-fast 0.2.1__py3-none-any.whl

tomskit/celery/README.md

@@ -0,0 +1,693 @@
+# Celery Module Guide
+
+该模块提供了基于 Celery 的异步任务执行框架，支持在 Celery 任务中运行异步函数，并自动管理数据库会话。
+
+## 模块概述
+
+Celery 模块扩展了标准 Celery 应用，提供了完整的异步任务支持。主要特性包括：
+
+- ⚡ **异步任务支持**：在 Celery 任务中运行异步函数
+- 🔄 **自动会话管理**：自动创建和关闭数据库会话
+- 🛠️ **配置管理**：支持通过 `from_mapping` 方法配置 Celery
+- 🔧 **上下文管理**：使用 `ContextVar` 管理 Celery 应用上下文
+- 📦 **资源初始化**：在 worker 启动时初始化数据库连接池和 Redis 客户端
+
+**Import Path:**
+```python
+from tomskit.celery import (
+    AsyncCelery,
+    AsyncTaskRunner,
+    CeleryConfig
+)
+```
+
+## 核心类和函数
+
+### AsyncCelery
+
+异步 Celery 应用类，继承自 `Celery`，负责配置管理。该类不自动初始化资源，资源初始化应该由业务代码在 worker 启动时完成。
+
+```python
+class AsyncCelery(Celery):
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+    
+    config: dict[str, Any]
+    app_root_path: Optional[str] = None
+    
+    def set_app_root_path(self, app_root_path: str) -> None: ...
+    
+    def from_mapping(
+        self,
+        mapping: Mapping[str, Any] | None = None,
+        **kwargs: Any
+    ) -> bool: ...
+```
+
+**功能特性：**
+- 继承自标准 Celery 类，兼容所有 Celery 功能
+- 使用 `ContextVar` 管理应用上下文，确保线程安全
+- 支持通过 `from_mapping` 方法配置 Celery（自动提取大写配置项）
+- 不自动初始化资源，需要在 worker 启动时手动初始化
+
+**属性说明：**
+- `config`: 配置字典，存储所有大写配置项
+- `app_root_path`: 应用根路径
+
+**使用示例：**
+```python
+from tomskit.celery import AsyncCelery
+
+# 创建 AsyncCelery 实例
+celery_app = AsyncCelery(
+    'myapp',
+    broker='redis://localhost:6379/0',
+    backend='redis://localhost:6379/0'
+)
+
+# 配置 Celery（只提取大写配置项）
+celery_app.from_mapping(
+    # Celery 配置
+    CELERY_TASK_SERIALIZER='json',
+    CELERY_RESULT_SERIALIZER='json',
+    CELERY_ACCEPT_CONTENT=['json'],
+    CELERY_TIMEZONE='UTC',
+    CELERY_ENABLE_UTC=True,
+    
+    # 数据库配置（用于 worker 初始化）
+    SQLALCHEMY_DATABASE_URI='mysql+aiomysql://user:pass@localhost/db',
+    SQLALCHEMY_ENGINE_OPTIONS={
+        'pool_size': 300,
+        'max_overflow': 10,
+        'pool_recycle': 3600,
+    },
+    
+    # Redis 配置（用于 worker 初始化）
+    REDIS_HOST='localhost',
+    REDIS_PORT=6379,
+    REDIS_DB=0,
+    REDIS_PASSWORD='',
+)
+
+# 设置应用根路径
+celery_app.set_app_root_path('/path/to/app')
+```
+
+### AsyncTaskRunner
+
+异步任务运行器，用于在 Celery 任务中执行异步函数。只负责运行异步函数和自动创建/关闭数据库 session。前提是数据库连接池和 Redis 客户端应该由业务代码在 worker 启动时初始化。
+
+```python
+class AsyncTaskRunner:
+    def __init__(
+        self,
+        async_task: Callable[..., Awaitable[Any]],
+        use_db: bool = True,
+        use_redis: bool = False
+    ) -> None: ...
+    
+    def run(self, *args: Any, **kwargs: Any) -> Any: ...
+```
+
+**功能特性：**
+- 在 Celery 任务中运行异步函数
+- 自动创建和关闭数据库会话（如果启用）
+- 检查 Redis 客户端是否已初始化（如果启用）
+- 使用 `asyncio.run` 执行异步任务
+- 确保资源正确释放，即使发生异常
+
+**参数说明：**
+- `async_task`: 要执行的异步任务函数（必须是协程函数）
+- `use_db`: 是否启用数据库 session 管理，默认为 `True`
+- `use_redis`: 是否检查 Redis 客户端，默认为 `False`（仅检查，不管理）
+
+**使用场景：**
+在需要执行异步数据库操作或其他异步 I/O 操作的 Celery 任务中使用。
+
+**使用示例：**
+```python
+from celery import shared_task
+from tomskit.celery import AsyncTaskRunner
+from tomskit.sqlalchemy.database import db
+from tomskit.sqlalchemy import User
+
+@shared_task(name="user_task_created", queue="mail", ignore_result=False)
+def user_task_created():
+    task = AsyncTaskRunner(async_user_task_created)
+    return task.run()
+
+async def async_user_task_created():
+    print("user_task_created running.")
+    new_user = User(
+        name="username",
+        email="username@gmail.com"
+    )
+    try:
+        db.session.add(new_user)
+        await db.session.commit()
+        print(f"add new user_id = {new_user.name}")
+        await db.session.refresh(new_user)
+        return f"This is new user id {new_user.id}"
+    except Exception as e:
+        await db.session.rollback()
+        return f"This task is fail. {str(e)}"
+```
+
+## 完整使用示例
+
+### 初始化 Celery 应用和 Worker
+
+```python
+from celery.signals import worker_process_init
+from tomskit.celery import AsyncCelery, AsyncTaskRunner
+from tomskit.sqlalchemy.database import db
+from tomskit.redis.redis_pool import RedisClientWrapper
+from tomskit.redis.config import RedisConfig
+
+# 创建 AsyncCelery 实例
+celery_app = AsyncCelery(
+    'myapp',
+    broker='redis://localhost:6379/0',
+    backend='redis://localhost:6379/0'
+)
+
+# 配置 Celery
+celery_app.from_mapping(
+    # Celery 配置
+    CELERY_TASK_SERIALIZER='json',
+    CELERY_RESULT_SERIALIZER='json',
+    CELERY_ACCEPT_CONTENT=['json'],
+    CELERY_TIMEZONE='UTC',
+    CELERY_ENABLE_UTC=True,
+    CELERY_TASK_TRACK_STARTED=True,
+    CELERY_TASK_TIME_LIMIT=30 * 60,  # 30 分钟
+    CELERY_TASK_SOFT_TIME_LIMIT=25 * 60,  # 25 分钟
+    
+    # 数据库配置
+    SQLALCHEMY_DATABASE_URI='mysql+aiomysql://user:pass@localhost/db',
+    SQLALCHEMY_ENGINE_OPTIONS={
+        'pool_size': 300,
+        'max_overflow': 10,
+        'pool_recycle': 3600,
+    },
+    
+    # Redis 配置
+    REDIS_HOST='localhost',
+    REDIS_PORT=6379,
+    REDIS_DB=0,
+    REDIS_PASSWORD='',
+)
+
+# Worker 启动时初始化资源
+@worker_process_init.connect
+def init_worker(sender=None, **kwargs):
+    """在 worker 进程启动时初始化数据库连接池和 Redis 客户端"""
+    # 初始化数据库连接池
+    db.initialize_session_pool(
+        celery_app.config["SQLALCHEMY_DATABASE_URI"],
+        celery_app.config.get("SQLALCHEMY_ENGINE_OPTIONS", {})
+    )
+    
+    # 初始化 Redis 客户端
+    redis_config = RedisConfig(
+        REDIS_HOST=celery_app.config.get("REDIS_HOST", "localhost"),
+        REDIS_PORT=celery_app.config.get("REDIS_PORT", 6379),
+        REDIS_DB=celery_app.config.get("REDIS_DB", 0),
+        REDIS_PASSWORD=celery_app.config.get("REDIS_PASSWORD", ""),
+    )
+    RedisClientWrapper.initialize(redis_config.model_dump())
+```
+
+### 定义异步任务
+
+```python
+from celery import shared_task
+from tomskit.celery import AsyncTaskRunner
+from tomskit.sqlalchemy.database import db
+from tomskit.sqlalchemy import User
+
+@celery_app.task(name="create_user", queue="default")
+def create_user_task(name: str, email: str):
+    """创建用户的 Celery 任务"""
+    task = AsyncTaskRunner(async_create_user)
+    return task.run(name, email)
+
+async def async_create_user(name: str, email: str):
+    """异步创建用户函数"""
+    new_user = User(name=name, email=email)
+    try:
+        db.session.add(new_user)
+        await db.session.commit()
+        await db.session.refresh(new_user)
+        return {
+            "success": True,
+            "user_id": new_user.id,
+            "message": f"User {name} created successfully"
+        }
+    except Exception as e:
+        await db.session.rollback()
+        return {
+            "success": False,
+            "error": str(e)
+        }
+```
+
+### 使用 Redis 的任务
+
+```python
+from celery import shared_task
+from tomskit.celery import AsyncTaskRunner
+from tomskit.redis.redis_pool import redis_client
+from tomskit.sqlalchemy.database import db
+from tomskit.sqlalchemy import User
+
+@celery_app.task(name="cache_user_data", queue="cache")
+def cache_user_data_task(user_id: int):
+    """缓存用户数据的 Celery 任务"""
+    # 启用 Redis 检查
+    task = AsyncTaskRunner(async_cache_user_data, use_db=True, use_redis=True)
+    return task.run(user_id)
+
+async def async_cache_user_data(user_id: int):
+    """异步缓存用户数据函数"""
+    # 从数据库获取用户
+    user = await db.session.get(User, user_id)
+    if user:
+        # 缓存到 Redis
+        await redis_client.setex(
+            f"user:{user_id}",
+            3600,  # 1 小时过期
+            str(user.id)  # 需要序列化
+        )
+        return f"User {user_id} cached successfully"
+    return f"User {user_id} not found"
+```
+
+### 不使用数据库的任务
+
+```python
+@celery_app.task(name="simple_task", queue="default")
+def simple_task(message: str):
+    """简单的异步任务，不使用数据库"""
+    task = AsyncTaskRunner(async_simple_task, use_db=False)
+    return task.run(message)
+
+async def async_simple_task(message: str):
+    """简单的异步函数"""
+    # 只使用 Redis，不使用数据库
+    await redis_client.set("message", message)
+    return f"Message '{message}' stored"
+```
+
+### 带参数和返回值的任务
+
+```python
+@celery_app.task(name="process_data", queue="processing")
+def process_data_task(data_id: int, options: dict = None):
+    """处理数据的 Celery 任务"""
+    task = AsyncTaskRunner(async_process_data)
+    return task.run(data_id, options=options or {})
+
+async def async_process_data(data_id: int, options: dict):
+    """异步处理数据函数"""
+    # 处理逻辑
+    processed_count = 0
+    
+    # 查询数据
+    result = await db.session.execute(
+        db.select(DataItem).where(DataItem.data_id == data_id)
+    )
+    items = result.scalars().all()
+    
+    for item in items:
+        # 处理每个项目
+        await process_item(item, options)
+        processed_count += 1
+    
+    return {
+        "data_id": data_id,
+        "processed_count": processed_count,
+        "status": "completed"
+    }
+```
+
+### 使用环境变量配置
+
+```python
+import os
+from tomskit.celery import AsyncCelery
+from tomskit.sqlalchemy.config import DatabaseConfig
+from tomskit.redis.config import RedisConfig
+
+# 从环境变量创建配置
+db_config = DatabaseConfig()
+redis_config = RedisConfig()
+
+# 创建 Celery 应用
+celery_app = AsyncCelery(
+    'myapp',
+    broker=os.getenv('CELERY_BROKER_URL', 'redis://localhost:6379/0'),
+    backend=os.getenv('CELERY_RESULT_BACKEND', 'redis://localhost:6379/0')
+)
+
+# 配置 Celery
+celery_app.from_mapping(
+    CELERY_TASK_SERIALIZER='json',
+    CELERY_RESULT_SERIALIZER='json',
+    CELERY_ACCEPT_CONTENT=['json'],
+    CELERY_TIMEZONE='UTC',
+    CELERY_ENABLE_UTC=True,
+    
+    # 使用配置对象
+    SQLALCHEMY_DATABASE_URI=db_config.SQLALCHEMY_DATABASE_URI,
+    SQLALCHEMY_ENGINE_OPTIONS=db_config.SQLALCHEMY_ENGINE_OPTIONS,
+    
+    REDIS_HOST=redis_config.REDIS_HOST,
+    REDIS_PORT=redis_config.REDIS_PORT,
+    REDIS_DB=redis_config.REDIS_DB,
+    REDIS_PASSWORD=redis_config.REDIS_PASSWORD,
+)
+```
+
+## 配置说明
+
+### Celery 配置项
+
+通过 `from_mapping` 方法可以配置所有标准的 Celery 配置项：
+
+- `CELERY_TASK_SERIALIZER`: 任务序列化格式（如 'json', 'pickle'）
+- `CELERY_RESULT_SERIALIZER`: 结果序列化格式
+- `CELERY_ACCEPT_CONTENT`: 接受的内容类型
+- `CELERY_TIMEZONE`: 时区设置
+- `CELERY_ENABLE_UTC`: 是否启用 UTC
+- `CELERY_TASK_TRACK_STARTED`: 是否跟踪任务开始
+- `CELERY_TASK_TIME_LIMIT`: 任务硬时间限制（秒）
+- `CELERY_TASK_SOFT_TIME_LIMIT`: 任务软时间限制（秒）
+- `CELERY_BROKER_URL`: Broker URL（如果未在初始化时指定）
+- `CELERY_RESULT_BACKEND`: 结果后端 URL（如果未在初始化时指定）
+
+### 数据库配置项
+
+用于在 worker 启动时初始化数据库连接池：
+
+- `SQLALCHEMY_DATABASE_URI`: 数据库连接 URI
+- `SQLALCHEMY_ENGINE_OPTIONS`: SQLAlchemy 引擎选项字典
+
+### Redis 配置项
+
+用于在 worker 启动时初始化 Redis 客户端：
+
+- `REDIS_HOST`: Redis 主机地址
+- `REDIS_PORT`: Redis 端口
+- `REDIS_DB`: Redis 数据库编号
+- `REDIS_PASSWORD`: Redis 密码
+
+**配置示例：**
+```python
+celery_app.from_mapping(
+    # 序列化配置
+    CELERY_TASK_SERIALIZER='json',
+    CELERY_RESULT_SERIALIZER='json',
+    CELERY_ACCEPT_CONTENT=['json'],
+    
+    # 时区配置
+    CELERY_TIMEZONE='Asia/Shanghai',
+    CELERY_ENABLE_UTC=True,
+    
+    # 任务配置
+    CELERY_TASK_TRACK_STARTED=True,
+    CELERY_TASK_TIME_LIMIT=30 * 60,
+    CELERY_TASK_SOFT_TIME_LIMIT=25 * 60,
+    
+    # 路由配置
+    CELERY_TASK_ROUTES={
+        'tasks.send_email': {'queue': 'mail'},
+        'tasks.process_data': {'queue': 'processing'},
+    },
+    
+    # 数据库配置
+    SQLALCHEMY_DATABASE_URI='mysql+aiomysql://user:pass@localhost/db',
+    SQLALCHEMY_ENGINE_OPTIONS={
+        'pool_size': 300,
+        'max_overflow': 10,
+        'pool_recycle': 3600,
+    },
+    
+    # Redis 配置
+    REDIS_HOST='localhost',
+    REDIS_PORT=6379,
+    REDIS_DB=0,
+)
+```
+
+## 注意事项
+
+1. **资源初始化**：
+   - 数据库连接池和 Redis 客户端必须在 worker 启动时初始化
+   - 使用 `worker_process_init` 信号处理器来初始化资源
+   - 不要在任务中初始化资源，这会导致性能问题和资源泄漏
+
+2. **会话管理**：
+   - `AsyncTaskRunner` 会自动创建和关闭数据库会话
+   - 在异步函数中直接使用 `db.session`，不需要手动创建会话
+   - 会话会在任务完成后自动关闭，即使发生异常也会正确清理
+
+3. **异步函数要求**：
+   - `AsyncTaskRunner` 的 `async_task` 参数必须是协程函数（使用 `async def` 定义）
+   - 在异步函数中必须使用 `await` 调用异步操作
+
+4. **上下文管理**：
+   - `AsyncCelery` 使用 `ContextVar` 管理应用上下文
+   - 确保在创建 `AsyncTaskRunner` 之前已经初始化了 `AsyncCelery` 实例
+
+5. **性能考虑**：
+   - `AsyncTaskRunner.run()` 使用 `asyncio.run()` 执行异步任务
+   - 每个任务都会创建新的事件循环，适合在 Celery worker 中使用
+   - 数据库连接池在 worker 启动时创建，所有任务共享连接池
+
+6. **错误处理**：
+   - 如果 Celery 应用未初始化，会抛出 `RuntimeError`
+   - 如果数据库连接池未初始化，会抛出 `RuntimeError`
+   - 如果 Redis 客户端未初始化且 `use_redis=True`，会抛出 `RuntimeError`
+   - 建议在任务函数中捕获和处理异常，返回错误信息而不是抛出异常
+
+7. **配置项提取**：
+   - `from_mapping` 方法只提取大写的配置项
+   - 小写配置项会被忽略，确保配置项名称使用大写
+
+8. **Redis 使用**：
+   - `use_redis` 参数仅用于检查 Redis 客户端是否已初始化
+   - Redis 客户端本身不需要在任务中管理，它在 worker 启动时初始化
+   - 在异步函数中直接使用 `redis_client` 进行操作
+
+## 工作流程
+
+1. **应用启动**：创建 `AsyncCelery` 实例并配置
+2. **Worker 启动**：在 `worker_process_init` 信号处理器中初始化数据库连接池和 Redis 客户端
+3. **任务执行**：创建 `AsyncTaskRunner` 实例并调用 `run()` 方法
+4. **资源管理**：`AsyncTaskRunner` 自动创建数据库会话，执行异步函数，然后关闭会话
+5. **Worker 关闭**：资源会在进程结束时自动清理
+
+## 相关文档
+
+- [Async Task Guide](../../docs/specs/async_task_guide.md) - 详细的异步任务使用指南
+- [Celery 官方文档](https://docs.celeryq.dev/) - Celery 官方文档
+- [Database Guide](../../docs/specs/database_guide.md) - 数据库使用指南
+- [Redis Guide](../../docs/specs/redis_guide.md) - Redis 使用指南
+
+
+## Celery 配置
+
+### CeleryConfig
+
+Celery 配置类，继承自 `pydantic_settings.BaseSettings`，用于管理 Celery 应用的完整配置。支持 Redis 作为 broker 和 backend，以及将结果存储到数据库。
+
+```python
+class CeleryConfig(BaseSettings):
+    # Redis Broker 配置
+    CELERY_BROKER_REDIS_HOST: str = Field(default="localhost", ...)
+    CELERY_BROKER_REDIS_PORT: PositiveInt = Field(default=6379, ...)
+    CELERY_BROKER_REDIS_USERNAME: Optional[str] = Field(default=None, ...)
+    CELERY_BROKER_REDIS_PASSWORD: Optional[str] = Field(default=None, ...)
+    CELERY_BROKER_REDIS_DB: NonNegativeInt = Field(default=0, ...)
+    
+    # Result Backend 配置
+    CELERY_RESULT_BACKEND_TYPE: str = Field(default="redis", ...)  # 'redis' 或 'database'
+    
+    # Redis Backend 配置（当 CELERY_RESULT_BACKEND_TYPE='redis' 时使用）
+    CELERY_RESULT_BACKEND_REDIS_HOST: str = Field(default="localhost", ...)
+    CELERY_RESULT_BACKEND_REDIS_PORT: PositiveInt = Field(default=6379, ...)
+    CELERY_RESULT_BACKEND_REDIS_USERNAME: Optional[str] = Field(default=None, ...)
+    CELERY_RESULT_BACKEND_REDIS_PASSWORD: Optional[str] = Field(default=None, ...)
+    CELERY_RESULT_BACKEND_REDIS_DB: NonNegativeInt = Field(default=1, ...)
+    
+    # Database Backend 配置（当 CELERY_RESULT_BACKEND_TYPE='database' 时使用）
+    CELERY_RESULT_BACKEND_DATABASE_URI_SCHEME: str = Field(default="mysql", ...)
+    
+    # Celery 任务配置
+    CELERY_TASK_SERIALIZER: str = Field(default="json", ...)
+    CELERY_RESULT_SERIALIZER: str = Field(default="json", ...)
+    CELERY_ACCEPT_CONTENT: list[str] = Field(default=["json"], ...)
+    CELERY_TIMEZONE: str = Field(default="UTC", ...)
+    CELERY_ENABLE_UTC: bool = Field(default=True, ...)
+    CELERY_TASK_TRACK_STARTED: bool = Field(default=True, ...)
+    CELERY_TASK_TIME_LIMIT: Optional[NonNegativeInt] = Field(default=None, ...)
+    CELERY_TASK_SOFT_TIME_LIMIT: Optional[NonNegativeInt] = Field(default=None, ...)
+    CELERY_TASK_IGNORE_RESULT: bool = Field(default=False, ...)
+    CELERY_RESULT_EXPIRES: Optional[NonNegativeInt] = Field(default=None, ...)
+    
+    # 数据库配置（用于 worker 和结果存储）
+    DB_HOST: str = Field(default="localhost", ...)
+    DB_PORT: PositiveInt = Field(default=5432, ...)
+    DB_USERNAME: str = Field(default="", ...)
+    DB_PASSWORD: str = Field(default="", ...)
+    DB_DATABASE: str = Field(default="tomskitdb", ...)
+    # ... 更多数据库配置项
+    
+    # Redis 配置（用于 worker）
+    REDIS_HOST: str = Field(default="localhost", ...)
+    REDIS_PORT: PositiveInt = Field(default=6379, ...)
+    # ... 更多 Redis 配置项
+    
+    @computed_field
+    @property
+    def CELERY_BROKER_URL(self) -> str: ...
+    
+    @computed_field
+    @property
+    def CELERY_RESULT_BACKEND(self) -> str: ...
+    
+    @computed_field
+    @property
+    def SQLALCHEMY_DATABASE_URI(self) -> str: ...
+    
+    def get_celery_config_dict(self) -> dict[str, Any]: ...
+```
+
+**功能特性：**
+- 支持 Redis 作为 broker 和 backend
+- 支持数据库作为结果后端（将结果存储到数据库）
+- 自动生成 broker 和 backend URL
+- 提供完整的 Celery 配置字典
+- 支持通过环境变量配置
+
+**使用示例：**
+
+**使用 Redis 作为结果后端：**
+```python
+from tomskit.celery import AsyncCelery, CeleryConfig
+
+# 创建配置
+config = CeleryConfig(
+    # Redis Broker
+    CELERY_BROKER_REDIS_HOST='localhost',
+    CELERY_BROKER_REDIS_PORT=6379,
+    CELERY_BROKER_REDIS_DB=0,
+    
+    # Redis Backend
+    CELERY_RESULT_BACKEND_TYPE='redis',
+    CELERY_RESULT_BACKEND_REDIS_HOST='localhost',
+    CELERY_RESULT_BACKEND_REDIS_PORT=6379,
+    CELERY_RESULT_BACKEND_REDIS_DB=1,
+    
+    # 数据库配置（用于 worker）
+    DB_USERNAME='user',
+    DB_PASSWORD='password',
+    DB_HOST='localhost',
+    DB_PORT=3306,
+    DB_DATABASE='mydb',
+)
+
+# 创建 Celery 应用
+celery_app = AsyncCelery(
+    'myapp',
+    broker=config.CELERY_BROKER_URL,
+    backend=config.CELERY_RESULT_BACKEND
+)
+
+# 应用配置
+celery_app.from_mapping(config.get_celery_config_dict())
+```
+
+**使用数据库作为结果后端：**
+```python
+from tomskit.celery import AsyncCelery, CeleryConfig
+
+# 创建配置
+config = CeleryConfig(
+    # Redis Broker
+    CELERY_BROKER_REDIS_HOST='localhost',
+    CELERY_BROKER_REDIS_PORT=6379,
+    CELERY_BROKER_REDIS_DB=0,
+    
+    # Database Backend（将结果存储到数据库）
+    CELERY_RESULT_BACKEND_TYPE='database',
+    CELERY_RESULT_BACKEND_DATABASE_URI_SCHEME='mysql',
+    
+    # 数据库配置
+    DB_USERNAME='user',
+    DB_PASSWORD='password',
+    DB_HOST='localhost',
+    DB_PORT=3306,
+    DB_DATABASE='mydb',
+)
+
+# 创建 Celery 应用
+celery_app = AsyncCelery(
+    'myapp',
+    broker=config.CELERY_BROKER_URL,
+    backend=config.CELERY_RESULT_BACKEND  # 自动生成 db+mysql://...
+)
+
+# 应用配置
+celery_app.from_mapping(config.get_celery_config_dict())
+```
+
+**使用环境变量配置：**
+```python
+from tomskit.celery import AsyncCelery, CeleryConfig
+
+# 从环境变量加载配置
+config = CeleryConfig()
+
+# 创建 Celery 应用
+celery_app = AsyncCelery(
+    'myapp',
+    broker=config.CELERY_BROKER_URL,
+    backend=config.CELERY_RESULT_BACKEND
+)
+
+# 应用配置
+celery_app.from_mapping(config.get_celery_config_dict())
+```
+
+**配置属性说明：**
+
+**Redis Broker 配置：**
+- `CELERY_BROKER_REDIS_HOST`: Redis broker 主机地址
+- `CELERY_BROKER_REDIS_PORT`: Redis broker 端口
+- `CELERY_BROKER_REDIS_USERNAME`: Redis broker 用户名（可选）
+- `CELERY_BROKER_REDIS_PASSWORD`: Redis broker 密码（可选）
+- `CELERY_BROKER_REDIS_DB`: Redis broker 数据库编号
+
+**Result Backend 配置：**
+- `CELERY_RESULT_BACKEND_TYPE`: 结果后端类型，`'redis'` 或 `'database'`
+- Redis Backend 相关配置（当 `CELERY_RESULT_BACKEND_TYPE='redis'` 时）
+- Database Backend 相关配置（当 `CELERY_RESULT_BACKEND_TYPE='database'` 时）
+
+**Celery 任务配置：**
+- `CELERY_TASK_SERIALIZER`: 任务序列化格式
+- `CELERY_RESULT_SERIALIZER`: 结果序列化格式
+- `CELERY_ACCEPT_CONTENT`: 接受的内容类型
+- `CELERY_TIMEZONE`: 时区设置
+- `CELERY_ENABLE_UTC`: 是否启用 UTC
+- `CELERY_TASK_TRACK_STARTED`: 是否跟踪任务开始
+- `CELERY_TASK_TIME_LIMIT`: 任务硬时间限制（秒）
+- `CELERY_TASK_SOFT_TIME_LIMIT`: 任务软时间限制（秒）
+- `CELERY_TASK_IGNORE_RESULT`: 是否忽略任务结果
+- `CELERY_RESULT_EXPIRES`: 结果过期时间（秒）
+
+**注意事项：**
+1. 使用数据库作为结果后端时，Celery 会自动创建 `celery_taskmeta` 表来存储任务结果
+2. 确保数据库用户有创建表的权限
+3. Redis broker 和 backend 可以使用不同的 Redis 实例和数据库
+4. 所有配置项都支持通过环境变量设置

tomskit/celery/__init__.py

@@ -0,0 +1,4 @@
+from tomskit.celery.celery import AsyncCelery, AsyncTaskRunner, celery_context
+from tomskit.celery.config import CeleryConfig
+
+__all__ = ["AsyncCelery", "AsyncTaskRunner", "celery_context", "CeleryConfig"]