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

aury/boot/infrastructure/events/bus.py

@@ -0,0 +1,362 @@
+"""事件总线实现。
+
+提供事件发布/订阅机制，支持本地和分布式模式。
+
+**架构说明**：
+本模块不依赖具体的 domain.events 实现，而是通过接口和类型变量来保持通用性。
+事件总线作为 infrastructure 组件只需要事件对象能够被序列化。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any
+
+from kombu import Connection, Exchange
+
+from aury.boot.common.logging import logger
+
+from .config import EventConfig
+from .consumer import EventConsumer
+from .models import Event, EventHandler, EventType
+
+
+class EventBus:
+    """事件总线（单例模式）。
+    
+    职责：
+    1. 管理事件订阅者
+    2. 分发事件（支持本地和分布式模式）
+    3. 异步事件处理
+    
+    模式：
+    - 本地模式：内存中的观察者模式（默认，无需消息队列）
+    - 分布式模式：使用 Kombu 消息队列（需要配置 broker_url）
+    
+    使用示例:
+        # 本地模式（内存）
+        event_bus = EventBus.get_instance()
+        
+        @event_bus.subscribe(MyEvent)
+        async def on_my_event(event: MyEvent):
+            print(f"Event {event.event_name} received!")
+        
+        await event_bus.publish(MyEvent(...))
+        
+        # 分布式模式（Kombu）
+        await event_bus.initialize(broker_url="redis://localhost:6379/0")
+        await event_bus.publish(MyEvent(...))  # 通过消息队列发布
+    """
+    
+    _instance: EventBus | None = None
+    
+    def __init__(self, settings: EventConfig | None = None) -> None:
+        """私有构造函数，使用 get_instance() 获取实例。
+        
+        Args:
+            settings: 事件总线配置（如果为 None 则使用默认配置）
+        """
+        if EventBus._instance is not None:
+            raise RuntimeError("EventBus 是单例类，请使用 get_instance() 获取实例")
+        
+        self._settings = settings or EventConfig()
+        self._handlers: dict[type[Event], list[EventHandler]] = {}
+        self._event_history: list[Event] = []
+        
+        # Kombu 相关
+        self._connection: Any = None  # Connection | None
+        self._exchange: Any = None  # Exchange | None
+        self._producer: Any = None  # Producer | None
+        self._consumer: Any = None  # EventConsumer | None
+        self._consumer_task: Any = None  # asyncio.Task | None
+        self._initialized: bool = False
+        self._use_distributed: bool = False
+        self._broker_url: str | None = None
+        
+        logger.debug("事件总线已创建（本地模式）")
+    
+    @classmethod
+    def get_instance(cls) -> EventBus:
+        """获取单例实例。"""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+    
+    async def initialize(
+        self,
+        broker_url: str | None = None,
+        *,
+        exchange_name: str | None = None,
+        queue_prefix: str | None = None,
+    ) -> None:
+        """初始化分布式事件总线（使用 Kombu）。
+        
+        Args:
+            broker_url: 消息队列 URL（如 "redis://localhost:6379/0" 或 "amqp://guest:guest@localhost:5672//"）
+                        如果不指定则使用配置中的值
+            exchange_name: 交换机名称，如果不指定则使用配置中的值
+            queue_prefix: 队列名称前缀，如果不指定则使用配置中的值
+        """
+        if self._initialized:
+            logger.warning("事件总线已初始化，跳过")
+            return
+        
+        # 使用提供的参数或配置中的值
+        final_broker_url = broker_url or self._settings.broker_url
+        final_exchange_name = exchange_name or self._settings.exchange_name
+        final_queue_prefix = queue_prefix or self._settings.queue_prefix
+        
+        if not final_broker_url:
+            logger.info("未提供 broker_url，使用本地模式（内存）")
+            self._use_distributed = False
+            self._initialized = True
+            return
+        
+        try:
+            self._broker_url = final_broker_url
+            self._connection = Connection(final_broker_url)
+            self._exchange = Exchange(final_exchange_name, type="topic", durable=True)
+            
+            # 创建生产者
+            self._producer = self._connection.Producer(
+                exchange=self._exchange,
+                serializer="json",
+            )
+            
+            # 启动消费者（在后台任务中）
+            self._consumer = EventConsumer(
+                connection=self._connection,
+                exchange=self._exchange,
+                queue_prefix=final_queue_prefix,
+                handlers=self._handlers,
+            )
+            
+            # 在后台启动消费者
+            self._consumer_task = asyncio.create_task(self._start_consumer())
+            
+            self._use_distributed = True
+            self._initialized = True
+            logger.info(f"事件总线已初始化（分布式模式，broker: {broker_url}）")
+        except Exception as exc:
+            logger.error(f"事件总线初始化失败: {exc}")
+            raise
+    
+    async def _start_consumer(self) -> None:
+        """启动消费者（在后台运行）。"""
+        if self._consumer:
+            try:
+                # 在事件循环中运行消费者
+                loop = asyncio.get_event_loop()
+                await loop.run_in_executor(None, self._consumer.run)
+            except Exception as exc:
+                logger.error(f"事件消费者运行失败: {exc}")
+    
+    def subscribe(
+        self,
+        event_type: type[EventType],
+        handler: EventHandler | None = None,
+    ) -> EventHandler | Callable[[EventHandler], EventHandler]:
+        """订阅事件。
+        
+        可以作为装饰器使用：
+            @event_bus.subscribe(MyEvent)
+            async def handler(event):
+                pass
+        
+        或直接调用：
+            event_bus.subscribe(MyEvent, handler)
+        
+        Args:
+            event_type: 事件类型
+            handler: 事件处理器
+            
+        Returns:
+            EventHandler | Callable: 处理器或装饰器
+        """
+        def decorator(fn: EventHandler) -> EventHandler:
+            if event_type not in self._handlers:
+                self._handlers[event_type] = []
+            
+            self._handlers[event_type].append(fn)
+            logger.debug(f"订阅事件: {event_type.__name__} -> {fn.__name__}")
+            
+            # 如果使用分布式模式，需要注册队列
+            if self._use_distributed and self._consumer:
+                self._consumer.register_event_type(event_type)
+            
+            return fn
+        
+        if handler is not None:
+            return decorator(handler)
+        return decorator
+    
+    def unsubscribe(self, event_type: type[EventType], handler: EventHandler) -> None:
+        """取消订阅事件。
+        
+        Args:
+            event_type: 事件类型
+            handler: 事件处理器
+        """
+        if event_type in self._handlers:
+            try:
+                self._handlers[event_type].remove(handler)
+                logger.debug(f"取消订阅事件: {event_type.__name__} -> {handler.__name__}")
+            except ValueError:
+                pass
+    
+    async def publish(self, event: EventType) -> None:
+        """发布事件。
+        
+        Args:
+            event: 事件对象
+        """
+        logger.info(f"发布事件: {event}")
+        
+        # 记录事件历史
+        self._add_to_history(event)
+        
+        if self._use_distributed:
+            # 分布式模式：通过消息队列发布
+            await self._publish_distributed(event)
+        else:
+            # 本地模式：直接调用处理器
+            await self._publish_local(event)
+    
+    async def _publish_local(self, event: EventType) -> None:
+        """本地模式：直接调用处理器。"""
+        handlers = self._handlers.get(type(event), [])
+        if not handlers:
+            logger.debug(f"事件 {event.event_name} 没有订阅者")
+            return
+        
+        # 执行处理器
+        for handler in handlers:
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    await handler(event)
+                else:
+                    handler(event)
+                logger.debug(f"事件处理成功: {handler.__name__}")
+            except Exception as exc:
+                logger.error(f"事件处理失败: {handler.__name__}, 错误: {exc}")
+    
+    async def _publish_distributed(self, event: EventType) -> None:
+        """分布式模式：通过消息队列发布。"""
+        if not self._producer:
+            logger.warning("生产者未初始化，回退到本地模式")
+            await self._publish_local(event)
+            return
+        
+        try:
+            # 序列化事件（使用 model_dump 而不是 model_dump_json，因为 kombu 会自动序列化）
+            event_data = event.model_dump()
+            routing_key = event.event_name.lower().replace("event", "")
+            
+            # 发布到消息队列
+            self._producer.publish(
+                event_data,
+                routing_key=routing_key,
+                declare=[self._exchange],
+            )
+            logger.debug(f"事件已发布到消息队列: {routing_key}")
+        except Exception as exc:
+            logger.error(f"发布事件到消息队列失败: {exc}")
+            # 失败时回退到本地模式
+            await self._publish_local(event)
+    
+    async def publish_many(self, events: list[Event]) -> None:
+        """批量发布事件。
+        
+        Args:
+            events: 事件列表
+        """
+        for event in events:
+            await self.publish(event)
+    
+    def _add_to_history(self, event: Event) -> None:
+        """添加事件到历史记录。
+        
+        Args:
+            event: 事件对象
+        """
+        # 检查是否启用了历史记录
+        if not self._settings.enable_history:
+            return
+        
+        self._event_history.append(event)
+        
+        # 限制历史记录大小
+        if (
+            self._settings.max_history_size is not None
+            and len(self._event_history) > self._settings.max_history_size
+        ):
+            self._event_history = self._event_history[-self._settings.max_history_size:]
+    
+    def get_history(
+        self,
+        event_type: type[EventType] | None = None,
+        limit: int = 100,
+    ) -> list[Event]:
+        """获取事件历史。
+        
+        Args:
+            event_type: 事件类型（可选，不指定则返回所有事件）
+            limit: 返回数量限制
+            
+        Returns:
+            list[Event]: 事件列表
+        """
+        if event_type is None:
+            return self._event_history[-limit:]
+        
+        filtered = [e for e in self._event_history if isinstance(e, event_type)]
+        return filtered[-limit:]
+    
+    def clear_history(self) -> None:
+        """清空事件历史。"""
+        self._event_history.clear()
+        logger.debug("事件历史已清空")
+    
+    def clear_handlers(self) -> None:
+        """清空所有事件处理器。"""
+        self._handlers.clear()
+        logger.debug("事件处理器已清空")
+    
+    def get_handler_count(self, event_type: type[EventType] | None = None) -> int:
+        """获取处理器数量。
+        
+        Args:
+            event_type: 事件类型（可选）
+            
+        Returns:
+            int: 处理器数量
+        """
+        if event_type is None:
+            return sum(len(handlers) for handlers in self._handlers.values())
+        return len(self._handlers.get(event_type, []))
+    
+    async def cleanup(self) -> None:
+        """清理资源。"""
+        if self._consumer:
+            self._consumer.should_stop = True
+        
+        if self._connection:
+            self._connection.close()
+        
+        self._initialized = False
+        self._use_distributed = False
+        logger.info("事件总线已清理")
+    
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        event_count = len(self._handlers)
+        history_size = len(self._event_history)
+        mode = "distributed" if self._use_distributed else "local"
+        return f"<EventBus mode={mode} events={event_count} history={history_size}>"
+
+
+__all__ = [
+    "EventBus",
+]
+

aury/boot/infrastructure/events/config.py

@@ -0,0 +1,52 @@
+"""事件总线配置。
+
+提供事件系统的配置管理。
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class EventConfig(BaseSettings):
+    """事件总线基础设施配置。
+    
+    Infrastructure 层直接使用的事件总线配置。
+    
+    环境变量前缀: EVENT_
+    示例: EVENT_BROKER_URL, EVENT_EXCHANGE_NAME, EVENT_QUEUE_PREFIX, EVENT_MAX_HISTORY_SIZE
+    """
+    
+    broker_url: str | None = Field(
+        default=None,
+        description="消息队列 URL（如 redis://localhost:6379/0 或 amqp://guest:guest@localhost:5672//），为空时使用本地模式"
+    )
+    exchange_name: str = Field(
+        default="events",
+        description="交换机名称"
+    )
+    queue_prefix: str = Field(
+        default="event",
+        description="队列名称前缀"
+    )
+    max_history_size: int | None = Field(
+        default=1000,
+        description="事件历史记录最大条数（None 表示不限制，生产环境建议设置或禁用历史记录）"
+    )
+    enable_history: bool = Field(
+        default=True,
+        description="是否启用事件历史记录（生产环境建议关闭以节省内存）"
+    )
+    
+    model_config = SettingsConfigDict(
+        env_prefix="EVENT_",
+        case_sensitive=False,
+    )
+
+
+__all__ = [
+    "EventConfig",
+]
+
+

aury/boot/infrastructure/events/consumer.py

@@ -0,0 +1,134 @@
+"""事件消费者实现。
+
+基于 Kombu ConsumerMixin 实现消息队列事件消费。
+
+**架构说明**：
+本模块使用通用的 Any 类型而非直接导入 domain.events，保持 infrastructure 层的独立性。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from kombu import Queue
+from kombu.mixins import ConsumerMixin
+
+from aury.boot.common.logging import logger
+
+
+class EventConsumer(ConsumerMixin):
+    """事件消费者（基于 Kombu ConsumerMixin）。
+    
+    在后台消费消息队列中的事件并调用本地处理器。
+    """
+    
+    def __init__(
+        self,
+        connection: Any,  # Connection
+        exchange: Any,  # Exchange
+        queue_prefix: str,
+        handlers: dict[Any, list[Any]],  # dict[type[EventType], list[EventHandler]]
+    ) -> None:
+        """初始化事件消费者。
+        
+        Args:
+            connection: Kombu 连接
+            exchange: 交换机
+            queue_prefix: 队列名称前缀
+            handlers: 事件处理器字典 {事件类型: [处理器列表]}
+        """
+        self.connection = connection
+        self._exchange = exchange
+        self._queue_prefix = queue_prefix
+        self._handlers = handlers
+        self._queues: dict[str, Any] = {}  # dict[str, Queue]
+        self._event_types: dict[str, Any] = {}  # dict[str, type[EventType]]
+    
+    def register_event_type(self, event_type: Any) -> None:
+        """注册事件类型（创建对应的队列）。
+        
+        Args:
+            event_type: 事件类型（应实现 __name__ 和 model_validate()）
+        """
+        event_name = event_type.__name__
+        routing_key = event_name.lower().replace("event", "")
+        
+        if routing_key not in self._queues:
+            queue_name = f"{self._queue_prefix}.{routing_key}"
+            queue = Queue(
+                queue_name,
+                exchange=self._exchange,
+                routing_key=routing_key,
+                durable=True,
+            )
+            self._queues[routing_key] = queue
+            self._event_types[routing_key] = event_type
+            logger.debug(f"注册事件队列: {queue_name} -> {routing_key}")
+    
+    def get_consumers(self, consumer_class: type, channel: Any) -> list:
+        """获取消费者列表。
+        
+        Args:
+            consumer_class: Kombu Consumer 类
+            channel: 消息通道
+            
+        Returns:
+            list: 消费者列表
+        """
+        consumers = []
+        for _routing_key, queue in self._queues.items():
+            consumer = consumer_class(
+                queues=[queue],
+                callbacks=[self.on_message],
+                accept=["json"],
+            )
+            consumers.append(consumer)
+        return consumers
+    
+    def on_message(self, body: dict[str, Any], message: Any) -> None:
+        """处理接收到的消息。
+        
+        Args:
+            body: 消息体
+            message: 消息对象
+        """
+        try:
+            routing_key = message.delivery_info.get("routing_key", "")
+            event_type = self._event_types.get(routing_key)
+            
+            if not event_type:
+                logger.warning(f"未知的事件类型: {routing_key}")
+                message.ack()
+                return
+            
+            # 反序列化事件
+            event = event_type.model_validate(body)
+            
+            # 获取处理器
+            handlers = self._handlers.get(event_type, [])
+            
+            # 在事件循环中执行处理器
+            loop = asyncio.get_event_loop()
+            for handler in handlers:
+                try:
+                    if asyncio.iscoroutinefunction(handler):
+                        task = loop.create_task(handler(event))
+                        # 保存任务引用以避免警告
+                        _ = task
+                    else:
+                        handler(event)
+                    logger.debug(f"事件处理成功: {handler.__name__}")
+                except Exception as exc:
+                    logger.error(f"事件处理失败: {handler.__name__}, 错误: {exc}")
+            
+            message.ack()
+        except Exception as exc:
+            logger.error(f"处理事件消息失败: {exc}")
+            message.reject(requeue=False)
+
+
+__all__ = [
+    "EventConsumer",
+]
+

aury/boot/infrastructure/events/middleware.py

@@ -0,0 +1,51 @@
+"""事件中间件实现。
+
+提供事件拦截、转换、日志记录等功能。
+
+**架构说明**：
+本模块使用通用的 Any 类型而非直接导入 domain.events，保持 infrastructure 层的独立性。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from aury.boot.common.logging import logger
+
+
+class EventMiddleware:
+    """事件中间件基类。
+    
+    可用于实现事件拦截、转换、日志记录等功能。
+    注意：这是一个抽象接口，用于扩展事件总线的功能。
+    """
+    
+    async def process(self, event: Any, next_handler: Callable) -> None:
+        """处理事件。
+        
+        Args:
+            event: 事件对象
+            next_handler: 下一个处理器
+        """
+        await next_handler(event)
+
+
+class EventLoggingMiddleware(EventMiddleware):
+    """事件日志中间件。
+    
+    记录事件的详细信息，包括事件处理前后。
+    """
+    
+    async def process(self, event: Any, next_handler: Callable) -> None:
+        """记录事件日志。"""
+        logger.info(f"[EventMiddleware] 处理事件: {event}")
+        await next_handler(event)
+        logger.info(f"[EventMiddleware] 事件处理完成: {event}")
+
+
+__all__ = [
+    "EventLoggingMiddleware",
+    "EventMiddleware",
+]
+

aury/boot/infrastructure/events/models.py

@@ -0,0 +1,63 @@
+"""事件模型定义 - 独立文件避免循环导入。
+
+提供事件基类、类型变量、处理器定义等基础数据结构。
+此模块不依赖任何其他 infrastructure 模块，可被安全导入。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Coroutine
+from datetime import datetime
+from typing import Any, ClassVar, TypeVar
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+# 事件类型定义（基础数据结构）
+EventType = TypeVar("EventType", bound="Event")
+EventHandler = (
+    Callable[[EventType], None] |
+    Callable[[EventType], Coroutine[Any, Any, None]]
+)
+
+
+class Event(BaseModel, ABC):
+    """事件基类（Pydantic）。
+    
+    所有业务事件应继承此类。
+    Pydantic 提供自动验证和序列化功能。
+    
+    Attributes:
+        event_id: 事件ID（自动生成UUID）
+        timestamp: 事件时间戳
+        metadata: 事件元数据
+    """
+    
+    event_id: str = Field(default_factory=lambda: str(uuid4()), description="事件ID")
+    timestamp: datetime = Field(default_factory=datetime.now, description="事件时间戳")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="事件元数据")
+    
+    @property
+    @abstractmethod
+    def event_name(self) -> str:
+        """事件名称（子类必须实现）。"""
+        pass
+    
+    class Config:
+        """Pydantic配置。"""
+        json_encoders: ClassVar[dict] = {
+            datetime: lambda v: v.isoformat(),
+        }
+    
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        return f"<{self.__class__.__name__} id={self.event_id} time={self.timestamp}>"
+
+
+__all__ = [
+    "Event",
+    "EventHandler",
+    "EventType",
+]
+