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

aury/boot/infrastructure/events/base.py

@@ -0,0 +1,127 @@
+"""事件总线基础接口定义。
+
+提供事件总线的抽象接口，用于模块间解耦通信。
+"""
+
+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, TypeVar
+import uuid
+
+
+class EventBackend(Enum):
+    """事件总线后端类型。"""
+
+    MEMORY = "memory"
+    REDIS = "redis"
+    RABBITMQ = "rabbitmq"
+
+
+@dataclass
+class Event:
+    """事件基类。"""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def event_name(self) -> str:
+        """获取事件名称。"""
+        return self.__class__.__name__
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典。"""
+        return {
+            "id": self.id,
+            "event_name": self.event_name,
+            "timestamp": self.timestamp.isoformat(),
+            "metadata": self.metadata,
+            "data": self._get_data(),
+        }
+
+    def _get_data(self) -> dict[str, Any]:
+        """获取事件数据（子类应重写）。"""
+        # 获取所有非基类的字段
+        base_fields = {"id", "timestamp", "metadata"}
+        return {
+            k: v
+            for k, v in self.__dict__.items()
+            if k not in base_fields and not k.startswith("_")
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Event:
+        """从字典创建事件。"""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            timestamp=datetime.fromisoformat(data["timestamp"])
+            if data.get("timestamp")
+            else datetime.now(),
+            metadata=data.get("metadata", {}),
+        )
+
+
+# 事件处理器类型
+EventHandler = Callable[[Event], Any]
+EventType = TypeVar("EventType", bound=Event)
+
+
+class IEventBus(ABC):
+    """事件总线接口。"""
+
+    @abstractmethod
+    def subscribe(
+        self,
+        event_type: type[Event] | str,
+        handler: EventHandler,
+    ) -> None:
+        """订阅事件。
+
+        Args:
+            event_type: 事件类型或事件名称
+            handler: 事件处理函数
+        """
+        ...
+
+    @abstractmethod
+    def unsubscribe(
+        self,
+        event_type: type[Event] | str,
+        handler: EventHandler,
+    ) -> None:
+        """取消订阅事件。
+
+        Args:
+            event_type: 事件类型或事件名称
+            handler: 事件处理函数
+        """
+        ...
+
+    @abstractmethod
+    async def publish(self, event: Event) -> None:
+        """发布事件。
+
+        Args:
+            event: 事件对象
+        """
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """关闭事件总线。"""
+        ...
+
+
+__all__ = [
+    "Event",
+    "EventBackend",
+    "EventHandler",
+    "EventType",
+    "IEventBus",
+]

aury/boot/infrastructure/events/manager.py

@@ -0,0 +1,224 @@
+"""事件总线管理器 - 命名多实例模式。
+
+提供统一的事件总线管理接口，支持多后端和多实例。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.common.logging import logger
+
+from .backends.memory import MemoryEventBus
+from .backends.rabbitmq import RabbitMQEventBus
+from .backends.redis import RedisEventBus
+from .base import Event, EventBackend, EventHandler, IEventBus
+
+if TYPE_CHECKING:
+    from aury.boot.application.config import EventInstanceConfig
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class EventBusManager:
+    """事件总线管理器（命名多实例）。
+
+    提供统一的事件总线管理接口，支持：
+    - 多实例管理（如 local、distributed 各自独立）
+    - 多后端支持（memory、redis、rabbitmq）
+    - 发布/订阅模式
+
+    使用示例:
+        # 默认实例（内存）
+        events = EventBusManager.get_instance()
+        await events.initialize(backend="memory")
+
+        # 分布式实例
+        distributed = EventBusManager.get_instance("distributed")
+        await distributed.initialize(
+            backend="redis",
+            redis_client=redis_client,
+        )
+
+        # 订阅事件
+        @events.on(MyEvent)
+        async def handle_my_event(event: MyEvent):
+            print(event)
+
+        # 发布事件
+        await events.publish(MyEvent(...))
+    """
+
+    _instances: dict[str, EventBusManager] = {}
+
+    def __init__(self, name: str = "default") -> None:
+        """初始化事件总线管理器。
+
+        Args:
+            name: 实例名称
+        """
+        self.name = name
+        self._backend: IEventBus | None = None
+        self._backend_type: EventBackend | None = None
+        self._initialized: bool = False
+
+    @classmethod
+    def get_instance(cls, name: str = "default") -> EventBusManager:
+        """获取指定名称的实例。
+
+        Args:
+            name: 实例名称，默认为 "default"
+
+        Returns:
+            EventBusManager: 事件总线管理器实例
+        """
+        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: EventBackend | str = EventBackend.MEMORY,
+        *,
+        config: EventInstanceConfig | None = None,
+        redis_client: RedisClient | None = None,
+        url: str | None = None,
+        channel_prefix: str = "events:",
+        exchange_name: str = "events",
+    ) -> EventBusManager:
+        """初始化事件总线（链式调用）。
+
+        Args:
+            backend: 后端类型（当 config 不为 None 时忽略）
+            config: Event 实例配置（推荐，自动根据 backend 初始化）
+            redis_client: Redis 客户端（当 backend=redis 且 config=None 时需要）
+            url: 连接 URL（当 config=None 时需要）
+            channel_prefix: Redis 频道前缀
+            exchange_name: RabbitMQ 交换机名称
+
+        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 = EventBackend(backend.lower())
+            except ValueError:
+                supported = ", ".join(b.value for b in EventBackend)
+                raise ValueError(f"不支持的事件总线后端: {backend}。支持: {supported}")
+
+        self._backend_type = backend
+
+        # 根据后端类型创建实例，参数校验由后端自己处理
+        if backend == EventBackend.MEMORY:
+            self._backend = MemoryEventBus()
+        elif backend == EventBackend.REDIS:
+            self._backend = RedisEventBus(url=url, redis_client=redis_client, channel_prefix=channel_prefix)
+        elif backend == EventBackend.RABBITMQ:
+            self._backend = RabbitMQEventBus(url=url, exchange_name=exchange_name)
+        else:
+            supported = ", ".join(b.value for b in EventBackend)
+            raise ValueError(f"不支持的事件总线后端: {backend}。支持: {supported}")
+
+        self._initialized = True
+        logger.info(f"事件总线管理器 [{self.name}] 初始化完成: {backend.value}")
+        return self
+
+    @property
+    def backend(self) -> IEventBus:
+        """获取事件总线后端。"""
+        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
+
+    def subscribe(
+        self,
+        event_type: type[Event] | str,
+        handler: EventHandler | None = None,
+    ) -> EventHandler | Callable[[EventHandler], EventHandler]:
+        """订阅事件（可作为装饰器使用）。
+
+        Args:
+            event_type: 事件类型或事件名称
+            handler: 事件处理函数（作为装饰器时为 None）
+
+        Returns:
+            EventHandler | Callable: 处理器或装饰器
+        """
+
+        def decorator(fn: EventHandler) -> EventHandler:
+            self.backend.subscribe(event_type, fn)
+            return fn
+
+        if handler is not None:
+            return decorator(handler)
+        return decorator
+
+    # 别名方法
+    on = subscribe
+
+    def unsubscribe(
+        self,
+        event_type: type[Event] | str,
+        handler: EventHandler,
+    ) -> None:
+        """取消订阅事件。"""
+        self.backend.unsubscribe(event_type, handler)
+
+    async def publish(self, event: Event) -> None:
+        """发布事件。"""
+        await self.backend.publish(event)
+
+    # 别名方法
+    emit = publish
+
+    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"<EventBusManager name={self.name} backend={self.backend_type} status={status}>"
+
+
+__all__ = ["EventBusManager"]

aury/boot/infrastructure/mq/__init__.py

@@ -0,0 +1,24 @@
+"""消息队列模块。
+
+提供生产者/消费者模式的消息队列功能，用于异步任务处理、服务间通信等场景。
+
+支持的后端:
+- redis: Redis List 实现
+- rabbitmq: RabbitMQ (aio-pika)
+"""
+
+from .backends import RabbitMQ, RedisMQ
+from .base import IMQ, MQBackend, MQMessage
+from .manager import MQManager
+
+__all__ = [
+    # 接口和类型
+    "IMQ",
+    "MQBackend",
+    # 管理器
+    "MQManager",
+    "MQMessage",
+    # 后端实现
+    "RabbitMQ",
+    "RedisMQ",
+]

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

@@ -0,0 +1,9 @@
+"""消息队列后端实现。"""
+
+from .rabbitmq import RabbitMQ
+from .redis import RedisMQ
+
+__all__ = [
+    "RabbitMQ",
+    "RedisMQ",
+]

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

@@ -0,0 +1,179 @@
+"""RabbitMQ 消息队列后端。
+
+使用 aio-pika 实现 RabbitMQ 消息队列。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+import json
+from typing import Any
+
+from aury.boot.common.logging import logger
+
+from ..base import IMQ, MQMessage
+
+# 延迟导入 aio-pika（可选依赖）
+try:
+    import aio_pika
+    from aio_pika import Message as AioPikaMessage
+    from aio_pika.abc import AbstractChannel, AbstractConnection, AbstractQueue
+
+    _AIO_PIKA_AVAILABLE = True
+except ImportError:
+    _AIO_PIKA_AVAILABLE = False
+    aio_pika = None
+    AioPikaMessage = None
+    AbstractChannel = None
+    AbstractConnection = None
+    AbstractQueue = None
+
+
+class RabbitMQ(IMQ):
+    """RabbitMQ 消息队列实现。
+
+    使用 aio-pika 实现 AMQP 0.9.1 协议的消息队列。
+
+    注意：需要安装 aio-pika: pip install aio-pika
+    """
+
+    def __init__(self, url: str) -> None:
+        """初始化 RabbitMQ 消息队列。
+
+        Args:
+            url: RabbitMQ 连接 URL (amqp://user:pass@host:port/vhost)
+        """
+        if not _AIO_PIKA_AVAILABLE:
+            raise ImportError(
+                "aio-pika 未安装。请安装: pip install aio-pika"
+            )
+        self._url = url
+        self._connection: AbstractConnection | None = None
+        self._channel: AbstractChannel | None = None
+        self._queues: dict[str, AbstractQueue] = {}
+        self._consuming = False
+
+    async def _ensure_connection(self) -> None:
+        """确保连接已建立。"""
+        if self._connection is None or self._connection.is_closed:
+            self._connection = await aio_pika.connect_robust(self._url)
+            self._channel = await self._connection.channel()
+            logger.info("RabbitMQ 连接已建立")
+
+    async def _get_queue(self, queue: str) -> AbstractQueue:
+        """获取或创建队列。"""
+        await self._ensure_connection()
+        if queue not in self._queues:
+            self._queues[queue] = await self._channel.declare_queue(
+                queue, durable=True
+            )
+        return self._queues[queue]
+
+    async def send(self, queue: str, message: MQMessage) -> str:
+        """发送消息到队列。"""
+        await self._ensure_connection()
+        message.queue = queue
+
+        aio_message = AioPikaMessage(
+            body=json.dumps(message.to_dict()).encode(),
+            message_id=message.id,
+            headers=message.headers,
+        )
+
+        await self._channel.default_exchange.publish(
+            aio_message,
+            routing_key=queue,
+        )
+        return message.id
+
+    async def receive(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从队列接收消息。"""
+        queue_obj = await self._get_queue(queue)
+
+        try:
+            if timeout:
+                incoming = await asyncio.wait_for(
+                    queue_obj.get(no_ack=False),
+                    timeout=timeout,
+                )
+            else:
+                incoming = await queue_obj.get(no_ack=False)
+
+            if incoming is None:
+                return None
+
+            data = json.loads(incoming.body.decode())
+            message = MQMessage.from_dict(data)
+            # 存储原始消息用于 ack/nack
+            message.headers["_raw_message"] = incoming
+            return message
+
+        except TimeoutError:
+            return None
+        except Exception as e:
+            logger.error(f"接收消息失败: {e}")
+            return None
+
+    async def ack(self, message: MQMessage) -> None:
+        """确认消息已处理。"""
+        raw_message = message.headers.get("_raw_message")
+        if raw_message:
+            await raw_message.ack()
+
+    async def nack(self, message: MQMessage, requeue: bool = True) -> None:
+        """拒绝消息。"""
+        raw_message = message.headers.get("_raw_message")
+        if raw_message:
+            await raw_message.nack(requeue=requeue)
+
+    async def consume(
+        self,
+        queue: str,
+        handler: Callable[[MQMessage], Any],
+        *,
+        prefetch: int = 1,
+    ) -> None:
+        """消费队列消息。"""
+        await self._ensure_connection()
+        await self._channel.set_qos(prefetch_count=prefetch)
+
+        queue_obj = await self._get_queue(queue)
+        self._consuming = True
+        logger.info(f"开始消费队列: {queue}")
+
+        async with queue_obj.iterator() as queue_iter:
+            async for incoming in queue_iter:
+                if not self._consuming:
+                    break
+
+                try:
+                    data = json.loads(incoming.body.decode())
+                    message = MQMessage.from_dict(data)
+                    message.headers["_raw_message"] = incoming
+
+                    result = handler(message)
+                    if asyncio.iscoroutine(result):
+                        await result
+                    await incoming.ack()
+
+                except Exception as e:
+                    logger.error(f"处理消息失败: {e}")
+                    await incoming.nack(requeue=True)
+
+    async def close(self) -> None:
+        """关闭连接。"""
+        self._consuming = False
+        if self._connection:
+            await self._connection.close()
+            self._connection = None
+            self._channel = None
+            self._queues.clear()
+        logger.debug("RabbitMQ 连接已关闭")
+
+
+__all__ = ["RabbitMQ"]