aury-boot 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

aury/boot/infrastructure/mq/backends/redis.py

@@ -0,0 +1,167 @@
+"""Redis 消息队列后端。
+
+使用 Redis List 实现简单的消息队列。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+import json
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.common.logging import logger
+
+from ..base import IMQ, MQMessage
+
+if TYPE_CHECKING:
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class RedisMQ(IMQ):
+    """Redis 消息队列实现。
+
+    使用 Redis List (LPUSH/BRPOP) 实现可靠的消息队列。
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        redis_client: RedisClient | None = None,
+        prefix: str = "mq:",
+    ) -> None:
+        """初始化 Redis 消息队列。
+
+        Args:
+            url: Redis 连接 URL（当 redis_client 为 None 时必须提供）
+            redis_client: RedisClient 实例（可选，优先使用）
+            prefix: 队列名称前缀
+        
+        Raises:
+            ValueError: 当 url 和 redis_client 都为 None 时
+        """
+        if redis_client is None and url is None:
+            raise ValueError("Redis 消息队列需要提供 url 或 redis_client 参数")
+        
+        self._url = url
+        self._client = redis_client
+        self._prefix = prefix
+        self._consuming = False
+        self._owns_client = False  # 是否自己创建的客户端
+    
+    async def _ensure_client(self) -> None:
+        """确保 Redis 客户端已初始化。"""
+        if self._client is None and self._url:
+            from aury.boot.infrastructure.clients.redis import RedisClient
+            self._client = RedisClient()
+            await self._client.initialize(url=self._url)
+            self._owns_client = True
+
+    def _queue_key(self, queue: str) -> str:
+        """获取队列的 Redis key。"""
+        return f"{self._prefix}{queue}"
+
+    def _processing_key(self, queue: str) -> str:
+        """获取处理中队列的 Redis key。"""
+        return f"{self._prefix}{queue}:processing"
+
+    async def send(self, queue: str, message: MQMessage) -> str:
+        """发送消息到队列。"""
+        await self._ensure_client()
+        message.queue = queue
+        data = json.dumps(message.to_dict())
+        await self._client.connection.lpush(self._queue_key(queue), data)
+        return message.id
+
+    async def receive(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从队列接收消息。"""
+        await self._ensure_client()
+        timeout_int = int(timeout) if timeout else 0
+        result = await self._client.connection.brpop(
+            self._queue_key(queue),
+            timeout=timeout_int,
+        )
+        if result is None:
+            return None
+
+        _, data = result
+        try:
+            msg_dict = json.loads(data)
+            message = MQMessage.from_dict(msg_dict)
+            # 将消息放入处理中队列
+            await self._client.connection.hset(
+                self._processing_key(queue),
+                message.id,
+                data,
+            )
+            return message
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.error(f"解析消息失败: {e}")
+            return None
+
+    async def ack(self, message: MQMessage) -> None:
+        """确认消息已处理。"""
+        if message.queue:
+            await self._client.connection.hdel(
+                self._processing_key(message.queue),
+                message.id,
+            )
+
+    async def nack(self, message: MQMessage, requeue: bool = True) -> None:
+        """拒绝消息。"""
+        if message.queue:
+            # 从处理中队列移除
+            await self._client.connection.hdel(
+                self._processing_key(message.queue),
+                message.id,
+            )
+            if requeue and message.retry_count < message.max_retries:
+                # 重新入队
+                message.retry_count += 1
+                await self.send(message.queue, message)
+
+    async def consume(
+        self,
+        queue: str,
+        handler: Callable[[MQMessage], Any],
+        *,
+        prefetch: int = 1,
+    ) -> None:
+        """消费队列消息。"""
+        self._consuming = True
+        logger.info(f"开始消费队列: {queue}")
+
+        while self._consuming:
+            try:
+                message = await self.receive(queue, timeout=1.0)
+                if message is None:
+                    continue
+
+                try:
+                    result = handler(message)
+                    if asyncio.iscoroutine(result):
+                        await result
+                    await self.ack(message)
+                except Exception as e:
+                    logger.error(f"处理消息失败: {e}")
+                    await self.nack(message, requeue=True)
+
+            except Exception as e:
+                logger.error(f"消费消息异常: {e}")
+                await asyncio.sleep(1)
+
+    async def close(self) -> None:
+        """关闭连接。"""
+        self._consuming = False
+        if self._owns_client and self._client:
+            await self._client.close()
+            self._client = None
+        logger.debug("Redis 消息队列已关闭")
+
+
+__all__ = ["RedisMQ"]

aury/boot/infrastructure/mq/base.py

@@ -0,0 +1,143 @@
+"""消息队列基础接口定义。
+
+提供消息队列的抽象接口，用于异步任务处理、服务间通信等场景。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+import uuid
+
+
+class MQBackend(Enum):
+    """消息队列后端类型。"""
+
+    REDIS = "redis"
+    RABBITMQ = "rabbitmq"
+
+
+@dataclass
+class MQMessage:
+    """消息队列消息。"""
+
+    body: Any
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    queue: str | None = None
+    headers: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)
+    retry_count: int = 0
+    max_retries: int = 3
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典。"""
+        return {
+            "id": self.id,
+            "body": self.body,
+            "queue": self.queue,
+            "headers": self.headers,
+            "timestamp": self.timestamp.isoformat(),
+            "retry_count": self.retry_count,
+            "max_retries": self.max_retries,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MQMessage:
+        """从字典创建消息。"""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            body=data["body"],
+            queue=data.get("queue"),
+            headers=data.get("headers", {}),
+            timestamp=datetime.fromisoformat(data["timestamp"])
+            if data.get("timestamp")
+            else datetime.now(),
+            retry_count=data.get("retry_count", 0),
+            max_retries=data.get("max_retries", 3),
+        )
+
+
+class IMQ(ABC):
+    """消息队列接口。"""
+
+    @abstractmethod
+    async def send(self, queue: str, message: MQMessage) -> str:
+        """发送消息到队列。
+
+        Args:
+            queue: 队列名称
+            message: 消息对象
+
+        Returns:
+            str: 消息 ID
+        """
+        ...
+
+    @abstractmethod
+    async def receive(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从队列接收消息。
+
+        Args:
+            queue: 队列名称
+            timeout: 超时时间（秒），None 表示阻塞等待
+
+        Returns:
+            MQMessage | None: 消息对象，超时返回 None
+        """
+        ...
+
+    @abstractmethod
+    async def ack(self, message: MQMessage) -> None:
+        """确认消息已处理。
+
+        Args:
+            message: 消息对象
+        """
+        ...
+
+    @abstractmethod
+    async def nack(self, message: MQMessage, requeue: bool = True) -> None:
+        """拒绝消息。
+
+        Args:
+            message: 消息对象
+            requeue: 是否重新入队
+        """
+        ...
+
+    @abstractmethod
+    async def consume(
+        self,
+        queue: str,
+        handler: Callable[[MQMessage], Any],
+        *,
+        prefetch: int = 1,
+    ) -> None:
+        """消费队列消息。
+
+        Args:
+            queue: 队列名称
+            handler: 消息处理函数
+            prefetch: 预取数量
+        """
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """关闭连接。"""
+        ...
+
+
+__all__ = [
+    "IMQ",
+    "MQBackend",
+    "MQMessage",
+]

aury/boot/infrastructure/mq/manager.py

@@ -0,0 +1,239 @@
+"""消息队列管理器 - 命名多实例模式。
+
+提供统一的消息队列管理接口，支持多后端和多实例。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.common.logging import logger
+
+from .backends.rabbitmq import RabbitMQ
+from .backends.redis import RedisMQ
+from .base import IMQ, MQBackend, MQMessage
+
+if TYPE_CHECKING:
+    from aury.boot.application.config import MQInstanceConfig
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class MQManager:
+    """消息队列管理器（命名多实例）。
+
+    提供统一的消息队列管理接口，支持：
+    - 多实例管理（如 tasks、notifications 各自独立）
+    - 多后端支持（redis、rabbitmq）
+    - 生产者/消费者模式
+
+    使用示例:
+        # 默认实例
+        mq = MQManager.get_instance()
+        await mq.initialize(backend="redis", redis_client=redis_client)
+
+        # 命名实例
+        task_mq = MQManager.get_instance("tasks")
+        notification_mq = MQManager.get_instance("notifications")
+
+        # 发送消息
+        await mq.send("orders", MQMessage(body={"order_id": 123}))
+
+        # 消费消息
+        await mq.consume("orders", handler=process_order)
+    """
+
+    _instances: dict[str, MQManager] = {}
+
+    def __init__(self, name: str = "default") -> None:
+        """初始化消息队列管理器。
+
+        Args:
+            name: 实例名称
+        """
+        self.name = name
+        self._backend: IMQ | None = None
+        self._backend_type: MQBackend | None = None
+        self._initialized: bool = False
+
+    @classmethod
+    def get_instance(cls, name: str = "default") -> MQManager:
+        """获取指定名称的实例。
+
+        Args:
+            name: 实例名称，默认为 "default"
+
+        Returns:
+            MQManager: 消息队列管理器实例
+        """
+        if name not in cls._instances:
+            cls._instances[name] = cls(name)
+        return cls._instances[name]
+
+    @classmethod
+    def reset_instance(cls, name: str | None = None) -> None:
+        """重置实例（仅用于测试）。
+
+        Args:
+            name: 要重置的实例名称。如果为 None，则重置所有实例。
+
+        注意：调用此方法前应先调用 cleanup() 释放资源。
+        """
+        if name is None:
+            cls._instances.clear()
+        elif name in cls._instances:
+            del cls._instances[name]
+
+    async def initialize(
+        self,
+        backend: MQBackend | str = MQBackend.REDIS,
+        *,
+        config: MQInstanceConfig | None = None,
+        redis_client: RedisClient | None = None,
+        url: str | None = None,
+        prefix: str = "mq:",
+    ) -> MQManager:
+        """初始化消息队列（链式调用）。
+
+        Args:
+            backend: 后端类型（当 config 不为 None 时忽略）
+            config: MQ 实例配置（推荐，自动根据 backend 初始化）
+            redis_client: Redis 客户端（当 backend=redis 且 config=None 时需要）
+            url: 连接 URL（当 config=None 时需要）
+            prefix: Redis 队列名称前缀
+
+        Returns:
+            self: 支持链式调用
+        """
+        if self._initialized:
+            logger.warning(f"消息队列管理器 [{self.name}] 已初始化，跳过")
+            return self
+
+        # 使用配置对象时，从配置中提取参数
+        if config is not None:
+            backend = config.backend
+            url = config.url
+
+        # 处理字符串类型的 backend
+        if isinstance(backend, str):
+            try:
+                backend = MQBackend(backend.lower())
+            except ValueError:
+                supported = ", ".join(b.value for b in MQBackend)
+                raise ValueError(f"不支持的消息队列后端: {backend}。支持: {supported}")
+
+        self._backend_type = backend
+
+        # 根据后端类型创建实例，参数校验由后端自己处理
+        if backend == MQBackend.REDIS:
+            self._backend = RedisMQ(url=url, redis_client=redis_client, prefix=prefix)
+        elif backend == MQBackend.RABBITMQ:
+            self._backend = RabbitMQ(url=url)
+        else:
+            supported = ", ".join(b.value for b in MQBackend)
+            raise ValueError(f"不支持的消息队列后端: {backend}。支持: {supported}")
+
+        self._initialized = True
+        logger.info(f"消息队列管理器 [{self.name}] 初始化完成: {backend.value}")
+        return self
+
+    @property
+    def backend(self) -> IMQ:
+        """获取消息队列后端。"""
+        if self._backend is None:
+            raise RuntimeError(
+                f"消息队列管理器 [{self.name}] 未初始化，请先调用 initialize()"
+            )
+        return self._backend
+
+    @property
+    def backend_type(self) -> str:
+        """获取当前后端类型。"""
+        return self._backend_type.value if self._backend_type else "unknown"
+
+    @property
+    def is_initialized(self) -> bool:
+        """检查是否已初始化。"""
+        return self._initialized
+
+    async def send(
+        self,
+        queue: str,
+        message: MQMessage | dict | Any,
+        *,
+        headers: dict[str, Any] | None = None,
+    ) -> str:
+        """发送消息到队列。
+
+        Args:
+            queue: 队列名称
+            message: 消息内容（MQMessage、字典或其他可序列化对象）
+            headers: 消息头
+
+        Returns:
+            str: 消息 ID
+        """
+        if isinstance(message, MQMessage):
+            msg = message
+        elif isinstance(message, dict):
+            msg = MQMessage(body=message, headers=headers or {})
+        else:
+            msg = MQMessage(body=message, headers=headers or {})
+
+        return await self.backend.send(queue, msg)
+
+    async def receive(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从队列接收消息。
+
+        Args:
+            queue: 队列名称
+            timeout: 超时时间（秒）
+
+        Returns:
+            MQMessage | None: 消息对象
+        """
+        return await self.backend.receive(queue, timeout)
+
+    async def ack(self, message: MQMessage) -> None:
+        """确认消息已处理。"""
+        await self.backend.ack(message)
+
+    async def nack(self, message: MQMessage, requeue: bool = True) -> None:
+        """拒绝消息。"""
+        await self.backend.nack(message, requeue)
+
+    async def consume(
+        self,
+        queue: str,
+        handler: Callable[[MQMessage], Any],
+        *,
+        prefetch: int = 1,
+    ) -> None:
+        """消费队列消息。
+
+        Args:
+            queue: 队列名称
+            handler: 消息处理函数
+            prefetch: 预取数量
+        """
+        await self.backend.consume(queue, handler, prefetch=prefetch)
+
+    async def cleanup(self) -> None:
+        """清理资源，关闭连接。"""
+        if self._backend:
+            await self._backend.close()
+            self._backend = None
+            self._initialized = False
+            logger.info(f"消息队列管理器 [{self.name}] 已关闭")
+
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        status = "initialized" if self._initialized else "not initialized"
+        return f"<MQManager name={self.name} backend={self.backend_type} status={status}>"
+
+
+__all__ = ["MQManager"]

aury/boot/infrastructure/scheduler/manager.py

@@ -117,10 +117,13 @@ class SchedulerManager:
         elif name in cls._instances:
             del cls._instances[name]
     
-    async def initialize(self) -> None:
-        """初始化调度器（已废弃，保留以保持后向兼容）。
+    async def initialize(self) -> SchedulerManager:
+        """初始化调度器（链式调用）。
         
-        调度器现在在 get_instance() 时同步初始化。
+        调度器现在在 get_instance() 时同步初始化，此方法保留以保持后向兼容。
+        
+        Returns:
+            self: 支持链式调用
         """
         if not self._initialized:
             # 如果还未初始化（理论上不会发生），进行初始化
@@ -131,6 +134,7 @@ class SchedulerManager:
             self._scheduler = AsyncIOScheduler()
             self._initialized = True
         logger.debug("调度器已就绪")
+        return self
     
     @property
     def scheduler(self) -> AsyncIOScheduler:

aury/boot/infrastructure/storage/__init__.py

@@ -3,10 +3,6 @@
 本包基于 aury-sdk-storage 提供的实现，对外暴露统一接口与管理器。
 """
 
-from .base import StorageManager
-from .exceptions import StorageBackendError, StorageError, StorageNotFoundError
-from .factory import StorageFactory
-
 # 从 SDK 直接导出核心类型
 from aury.sdk.storage.storage import (
     IStorage,
@@ -18,21 +14,25 @@ from aury.sdk.storage.storage import (
     UploadResult,
 )
 
+from .base import StorageManager
+from .exceptions import StorageBackendError, StorageError, StorageNotFoundError
+from .factory import StorageFactory
+
 __all__ = [
     # SDK 类型
     "IStorage",
     "LocalStorage",
     "S3Storage",
     "StorageBackend",
+    "StorageBackendError",
     "StorageConfig",
+    # 异常
+    "StorageError",
+    "StorageFactory",
     "StorageFile",
-    "UploadResult",
     # 管理器与工厂
     "StorageManager",
-    "StorageFactory",
-    # 异常
-    "StorageError",
-    "StorageBackendError",
     "StorageNotFoundError",
+    "UploadResult",
 ]
 

aury/boot/infrastructure/storage/base.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+from aury.boot.common.logging import logger
 from aury.sdk.storage.storage import (
     IStorage,
     LocalStorage,
@@ -14,8 +15,6 @@ from aury.sdk.storage.storage import (
     StorageFile,
 )
 
-from aury.boot.common.logging import logger
-
 
 class StorageManager:
     """存储管理器（命名多实例）。
@@ -69,8 +68,15 @@ class StorageManager:
         elif name in cls._instances:
             del cls._instances[name]
 
-    async def init(self, config: StorageConfig) -> None:
-        """使用 SDK 的 StorageConfig 初始化存储后端。"""
+    async def initialize(self, config: StorageConfig) -> StorageManager:
+        """初始化存储后端（链式调用）。
+        
+        Args:
+            config: 存储配置对象
+            
+        Returns:
+            self: 支持链式调用
+        """
         self._config = config
         if config.backend == StorageBackend.LOCAL:
             self._backend = LocalStorage(base_path=config.base_path or "./storage")
@@ -78,11 +84,17 @@ class StorageManager:
             # S3/COS/OSS/MinIO 统一走 S3Storage
             self._backend = S3Storage(config)
         logger.info(f"存储管理器初始化完成: {config.backend.value}")
+        return self
 
+    @property
+    def is_initialized(self) -> bool:
+        """检查是否已初始化。"""
+        return self._backend is not None
+    
     @property
     def backend(self) -> IStorage:
         if self._backend is None:
-            raise RuntimeError("存储管理器未初始化，请先调用 init()")
+            raise RuntimeError("存储管理器未初始化，请先调用 initialize()")
         return self._backend
 
     async def upload_file(

aury/boot/infrastructure/storage/factory.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 from typing import ClassVar
 
 from aury.boot.common.logging import logger
-
 from aury.sdk.storage.storage import IStorage, LocalStorage
 
 

aury/boot/infrastructure/tasks/__init__.py

@@ -9,7 +9,7 @@ from .exceptions import (
     TaskExecutionError,
     TaskQueueError,
 )
-from .manager import TaskManager, TaskProxy, conditional_actor
+from .manager import TaskManager, TaskProxy, conditional_task
 
 __all__ = [
     "TaskError",
@@ -19,6 +19,6 @@ __all__ = [
     "TaskQueueError",
     "TaskQueueName",
     "TaskRunMode",
-    "conditional_actor",
+    "conditional_task",
 ]