aury-boot 0.0.21__tar.gz → 0.0.23__tar.gz

{aury_boot-0.0.21 → aury_boot-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.21
+Version: 0.0.23
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.21'
-__version_tuple__ = version_tuple = (0, 0, 21)
+__version__ = version = '0.0.23'
+__version_tuple__ = version_tuple = (0, 0, 23)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/application/app/base.py

@@ -11,10 +11,10 @@ from contextlib import asynccontextmanager
 import sys
 from typing import Any, ClassVar
 
-from fastapi import FastAPI, HTTPException, Request, status
+from fastapi import FastAPI, Request, status
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
-from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.exceptions import HTTPException
 from starlette.middleware import Middleware as StarletteMiddleware
 
 from aury.boot.application.config import BaseConfig
@@ -282,9 +282,8 @@ class FoundationApp(FastAPI):
         )
 
         # 异常处理：显式注册以覆盖 FastAPI/Starlette 默认处理器，确保统一响应格式
-        self.add_exception_handler(RequestValidationError, global_exception_handler)  # 422
-        self.add_exception_handler(HTTPException, global_exception_handler)  # 4xx/5xx
-        self.add_exception_handler(StarletteHTTPException, global_exception_handler)  # Starlette 异常
+        self.add_exception_handler(RequestValidationError, global_exception_handler)  # 422 参数校验
+        self.add_exception_handler(HTTPException, global_exception_handler)  # 4xx/5xx HTTP 异常
         self.add_exception_handler(Exception, global_exception_handler)  # 其他未处理异常
 
         # 设置路由

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/application/errors/handlers.py

@@ -8,11 +8,12 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
-from fastapi import HTTPException, Request, status
+from fastapi import Request, status
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+from starlette.exceptions import HTTPException
 
 from aury.boot.common.exceptions import FoundationError
 from aury.boot.common.logging import logger
@@ -149,23 +150,31 @@ class BaseErrorHandler(ErrorHandler):
 
 
 class HTTPExceptionHandler(ErrorHandler):
-    """FastAPI HTTP异常处理器。"""
+    """HTTP 异常处理器。
+    
+    处理 FastAPI 和 Starlette 的 HTTPException（包括 404、401、403 等）。
+    """
     
     def can_handle(self, exception: Exception) -> bool:
-        """判断是否为HTTP异常。"""
+        """判断是否为 HTTP 异常。"""
+        # Starlette HTTPException 是 FastAPI HTTPException 的基类
         return isinstance(exception, HTTPException)
     
     async def handle(self, exception: HTTPException, request: Request) -> JSONResponse:
-        """处理HTTP异常。"""
-        logger.warning(f"HTTP异常: {exception.status_code} - {exception.detail}")
+        """处理 HTTP 异常。"""
+        # 获取错误信息：Starlette 用 detail，FastAPI 也用 detail
+        detail = getattr(exception, "detail", str(exception))
+        status_code = exception.status_code
+        
+        logger.warning(f"HTTP 异常 [{request.method} {request.url.path}]: {status_code} - {detail}")
         
         response = ResponseBuilder.fail(
-            message=exception.detail,
-            code=exception.status_code,
+            message=detail if isinstance(detail, str) else str(detail),
+            code=status_code,
         )
         
         return JSONResponse(
-            status_code=exception.status_code,
+            status_code=status_code,
             content=response.model_dump(mode="json"),
         )
 

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/commands/templates/project/aury_docs/13-channel.md.tpl

@@ -71,12 +71,51 @@ async def sse_stream(user_id: str):
 
 @router.post("/notify/{{user_id}}")
 async def send_notification(user_id: str, message: str):
-    \"\"\"\u53d1\u9001\u901a\u77e5\u3002\"\"\"
+    \"\"\"发送通知。\"\"\"
     await sse_channel.publish(f"user:{{user_id}}", {{"message": message}})
     return {{"status": "sent"}}
 ```
 
-## 13.4 应用场景示例
+## 13.4 模式订阅（psubscribe）
+
+使用通配符订阅多个通道，适合一个 SSE 连接接收多种事件的场景。
+
+```python
+@router.get("/spaces/{{space_id}}/events")
+async def space_events(space_id: str):
+    \"\"\"订阅空间下所有事件。\"\"\"
+    async def event_generator():
+        # 使用 psubscribe 订阅 space:{id}:* 下所有事件
+        async for msg in sse_channel.psubscribe(f"space:{{space_id}}:*"):
+            yield msg.to_sse()  # 自动转换为 SSE 格式
+    
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream"
+    )
+
+
+# 后端发布不同类型的事件
+await sse_channel.publish(f"space:{{space_id}}:file_analyzed", {{
+    "file_id": "abc",
+    "status": "done"
+}}, event="file_analyzed")
+
+await sse_channel.publish(f"space:{{space_id}}:comment_added", {{
+    "comment_id": "xyz",
+    "content": "..."
+}}, event="comment_added")
+```
+
+**通配符说明**：
+- `*` 匹配任意字符
+- `?` 匹配单个字符
+- `[seq]` 匹配 seq 中的任意字符
+- 示例：`space:123:*` 匹配 `space:123:file_analyzed`、`space:123:comment_added` 等
+
+Redis 后端使用 Redis 原生 `PSUBSCRIBE`，内存后端使用 `fnmatch` 实现。
+
+## 13.5 应用场景示例
 
 ```python
 # 不同业务场景使用不同的命名实例
@@ -90,7 +129,7 @@ await chat_channel.initialize(backend="redis", redis_client=redis_client)  # 需
 await notify_channel.initialize(backend="redis", redis_client=redis_client)
 ```
 
-## 13.5 环境变量
+## 13.6 环境变量
 
 ```bash
 # 默认实例

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/channel/backends/memory.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import AsyncIterator
 import contextlib
+import fnmatch
 
 from aury.boot.common.logging import logger
 
@@ -31,12 +32,15 @@ class MemoryChannel(IChannel):
         self._max_subscribers = max_subscribers
         # channel -> list of queues
         self._subscribers: dict[str, list[asyncio.Queue[ChannelMessage]]] = {}
+        # pattern -> list of queues (用于 psubscribe)
+        self._pattern_subscribers: dict[str, list[asyncio.Queue[ChannelMessage]]] = {}
         self._lock = asyncio.Lock()
 
     async def publish(self, channel: str, message: ChannelMessage) -> None:
         """发布消息到通道。"""
         message.channel = channel
         async with self._lock:
+            # 精确匹配订阅者
             subscribers = self._subscribers.get(channel, [])
             for queue in subscribers:
                 try:
@@ -44,6 +48,15 @@ class MemoryChannel(IChannel):
                 except asyncio.QueueFull:
                     logger.warning(f"通道 [{channel}] 订阅者队列已满，消息被丢弃")
 
+            # 模式匹配订阅者
+            for pattern, queues in self._pattern_subscribers.items():
+                if fnmatch.fnmatch(channel, pattern):
+                    for queue in queues:
+                        try:
+                            queue.put_nowait(message)
+                        except asyncio.QueueFull:
+                            logger.warning(f"模式 [{pattern}] 订阅者队列已满，消息被丢弃")
+
     async def subscribe(self, channel: str) -> AsyncIterator[ChannelMessage]:
         """订阅通道。"""
         queue: asyncio.Queue[ChannelMessage] = asyncio.Queue(maxsize=100)
@@ -67,6 +80,35 @@ class MemoryChannel(IChannel):
                     if not self._subscribers[channel]:
                         del self._subscribers[channel]
 
+    async def psubscribe(self, pattern: str) -> AsyncIterator[ChannelMessage]:
+        """模式订阅通道。
+
+        使用 fnmatch 风格的通配符：
+        - `*` 匹配任意字符
+        - `?` 匹配单个字符
+        - `[seq]` 匹配 seq 中的任意字符
+        """
+        queue: asyncio.Queue[ChannelMessage] = asyncio.Queue(maxsize=100)
+
+        async with self._lock:
+            if pattern not in self._pattern_subscribers:
+                self._pattern_subscribers[pattern] = []
+            if len(self._pattern_subscribers[pattern]) >= self._max_subscribers:
+                raise RuntimeError(f"模式 [{pattern}] 订阅者数量已达上限")
+            self._pattern_subscribers[pattern].append(queue)
+
+        try:
+            while True:
+                message = await queue.get()
+                yield message
+        finally:
+            async with self._lock:
+                if pattern in self._pattern_subscribers:
+                    with contextlib.suppress(ValueError):
+                        self._pattern_subscribers[pattern].remove(queue)
+                    if not self._pattern_subscribers[pattern]:
+                        del self._pattern_subscribers[pattern]
+
     async def unsubscribe(self, channel: str) -> None:
         """取消订阅通道（清除所有订阅者）。"""
         async with self._lock:
@@ -77,6 +119,7 @@ class MemoryChannel(IChannel):
         """关闭通道，清理所有订阅。"""
         async with self._lock:
             self._subscribers.clear()
+            self._pattern_subscribers.clear()
         logger.debug("内存通道已关闭")
 
 

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/channel/backends/redis.py

@@ -72,6 +72,48 @@ class RedisChannel(IChannel):
             await pubsub.unsubscribe(channel)
             await pubsub.close()
 
+    async def psubscribe(self, pattern: str) -> AsyncIterator[ChannelMessage]:
+        """模式订阅（通配符）。
+        
+        Args:
+            pattern: 通道模式，支持 * 和 ? 通配符
+                - * 匹配任意字符
+                - ? 匹配单个字符
+                - 示例: "space:123:*" 订阅 space:123 下所有事件
+        
+        Yields:
+            ChannelMessage: 接收到的消息
+        """
+        pubsub = self._client.connection.pubsub()
+        await pubsub.psubscribe(pattern)
+
+        try:
+            async for raw_message in pubsub.listen():
+                # psubscribe 的消息类型是 "pmessage"
+                if raw_message["type"] == "pmessage":
+                    try:
+                        data = json.loads(raw_message["data"])
+                        # pmessage 包含实际匹配的通道名
+                        actual_channel = raw_message.get("channel")
+                        if isinstance(actual_channel, bytes):
+                            actual_channel = actual_channel.decode("utf-8")
+                        
+                        message = ChannelMessage(
+                            data=data.get("data"),
+                            event=data.get("event"),
+                            id=data.get("id"),
+                            channel=actual_channel or data.get("channel"),
+                            timestamp=datetime.fromisoformat(data["timestamp"])
+                            if data.get("timestamp")
+                            else datetime.now(),
+                        )
+                        yield message
+                    except (json.JSONDecodeError, KeyError) as e:
+                        logger.warning(f"解析通道消息失败: {e}")
+        finally:
+            await pubsub.punsubscribe(pattern)
+            await pubsub.close()
+
     async def unsubscribe(self, channel: str) -> None:
         """取消订阅通道。"""
         if self._pubsub:

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/channel/base.py

@@ -70,6 +70,21 @@ class IChannel(ABC):
         """
         ...
 
+    async def psubscribe(self, pattern: str) -> AsyncIterator[ChannelMessage]:
+        """模式订阅（通配符）。
+
+        Args:
+            pattern: 通道模式，如 "space:123:*" 订阅 space:123 下所有事件
+
+        Yields:
+            ChannelMessage: 接收到的消息
+        
+        注意：内存后端默认回退到普通 subscribe，Redis 后端支持真正的模式匹配。
+        """
+        # 默认实现：回退到普通订阅（子类可覆盖）
+        async for msg in self.subscribe(pattern):
+            yield msg
+
     @abstractmethod
     async def unsubscribe(self, channel: str) -> None:
         """取消订阅通道。

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/channel/manager.py

@@ -178,6 +178,29 @@ class ChannelManager:
         async for message in self.backend.subscribe(channel):
             yield message
 
+    async def psubscribe(self, pattern: str) -> AsyncIterator[ChannelMessage]:
+        """模式订阅（通配符）。
+
+        Args:
+            pattern: 通道模式，支持 * 和 ? 通配符
+                - "space:123:*" 订阅 space:123 下所有事件
+                - "user:*:notification" 订阅所有用户的通知
+
+        Yields:
+            ChannelMessage: 接收到的消息
+        
+        示例:
+            # SSE 路由中订阅某个空间的所有事件
+            async for msg in channel.psubscribe(f"space:{{space_id}}:*"):
+                yield msg.to_sse()
+            
+            # 发布不同类型的事件
+            await channel.publish(f"space:{{space_id}}:file_analyzed", {{...}})
+            await channel.publish(f"space:{{space_id}}:comment_added", {{...}})
+        """
+        async for message in self.backend.psubscribe(pattern):
+            yield message
+
     async def unsubscribe(self, channel: str) -> None:
         """取消订阅通道。
 

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/events/backends/redis.py

@@ -17,10 +17,17 @@ if TYPE_CHECKING:
     from aury.boot.infrastructure.clients.redis import RedisClient
 
 
+# 框架默认前缀
+DEFAULT_CHANNEL_PREFIX = "aury:event:"
+
+
 class RedisEventBus(IEventBus):
     """Redis 事件总线实现。
 
     使用 Redis Pub/Sub 实现跨进程的事件发布/订阅。
+    
+    频道命名格式：{channel_prefix}{event_name}
+    默认：aury:event:user.created
     """
 
     def __init__(
@@ -28,14 +35,14 @@ class RedisEventBus(IEventBus):
         url: str | None = None,
         *,
         redis_client: RedisClient | None = None,
-        channel_prefix: str = "events:",
+        channel_prefix: str = DEFAULT_CHANNEL_PREFIX,
     ) -> None:
         """初始化 Redis 事件总线。
 
         Args:
             url: Redis 连接 URL（当 redis_client 为 None 时必须提供）
             redis_client: RedisClient 实例（可选，优先使用）
-            channel_prefix: 频道名称前缀
+            channel_prefix: 频道名称前缀，默认 "aury:event:"
         
         Raises:
             ValueError: 当 url 和 redis_client 都为 None 时

{aury_boot-0.0.21 → aury_boot-0.0.23}/aury/boot/infrastructure/events/manager.py

@@ -97,8 +97,8 @@ class EventBusManager:
         config: EventInstanceConfig | None = None,
         redis_client: RedisClient | None = None,
         url: str | None = None,
-        channel_prefix: str = "events:",
-        exchange_name: str = "events",
+        channel_prefix: str | None = None,
+        exchange_name: str = "aury.events",
     ) -> EventBusManager:
         """初始化事件总线（链式调用）。
 
@@ -107,8 +107,8 @@ class EventBusManager:
             config: Event 实例配置（推荐，自动根据 backend 初始化）
             redis_client: Redis 客户端（当 backend=redis 且 config=None 时需要）
             url: 连接 URL（当 config=None 时需要）
-            channel_prefix: Redis 频道前缀
-            exchange_name: RabbitMQ 交换机名称
+            channel_prefix: Redis 频道前缀，默认 "aury:event:"
+            exchange_name: RabbitMQ 交换机名称，默认 "aury.events"
 
         Returns:
             self: 支持链式调用
@@ -136,7 +136,11 @@ class EventBusManager:
         if backend == EventBackend.MEMORY:
             self._backend = MemoryEventBus()
         elif backend == EventBackend.REDIS:
-            self._backend = RedisEventBus(url=url, redis_client=redis_client, channel_prefix=channel_prefix)
+            # channel_prefix 为 None 时使用 RedisEventBus 的默认值
+            kwargs = {"url": url, "redis_client": redis_client}
+            if channel_prefix is not None:
+                kwargs["channel_prefix"] = channel_prefix
+            self._backend = RedisEventBus(**kwargs)
         elif backend == EventBackend.RABBITMQ:
             self._backend = RabbitMQEventBus(url=url, exchange_name=exchange_name)
         else: