aury-boot 0.0.19__tar.gz → 0.0.29__tar.gz

{aury_boot-0.0.19 → aury_boot-0.0.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.19
+Version: 0.0.29
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2
@@ -24,13 +24,11 @@ Requires-Dist: sqladmin>=0.16.0; extra == 'admin'
 Provides-Extra: all
 Requires-Dist: aiomysql>=0.3.2; extra == 'all'
 Requires-Dist: aiosqlite>=0.21.0; extra == 'all'
-Requires-Dist: amqp>=5.3.1; extra == 'all'
 Requires-Dist: apscheduler>=3.11.1; extra == 'all'
 Requires-Dist: asyncpg>=0.31.0; extra == 'all'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'all'
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'all'
 Requires-Dist: dramatiq>=1.18.0; extra == 'all'
-Requires-Dist: kombu>=5.6.1; extra == 'all'
+Requires-Dist: pika>=1.3.2; extra == 'all'
 Requires-Dist: redis>=7.1.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
@@ -53,9 +51,7 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'recommended'
 Requires-Dist: apscheduler>=3.11.1; extra == 'recommended'
 Requires-Dist: asyncpg>=0.31.0; extra == 'recommended'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'recommended'
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'recommended'
 Requires-Dist: dramatiq>=1.18.0; extra == 'recommended'
-Requires-Dist: kombu>=5.6.1; extra == 'recommended'
 Requires-Dist: redis>=7.1.0; extra == 'recommended'
 Provides-Extra: redis
 Requires-Dist: redis>=7.1.0; extra == 'redis'
@@ -66,9 +62,8 @@ Requires-Dist: apscheduler>=3.11.1; extra == 'scheduler'
 Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.21.0; extra == 'sqlite'
 Provides-Extra: tasks
-Requires-Dist: dramatiq-kombu-broker>=0.2.2; extra == 'tasks'
 Requires-Dist: dramatiq>=1.18.0; extra == 'tasks'
-Requires-Dist: kombu>=5.6.1; extra == 'tasks'
+Requires-Dist: redis>=7.1.0; extra == 'tasks'
 Description-Content-Type: text/markdown
 
 # Aury Boot

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.19'
-__version_tuple__ = version_tuple = (0, 0, 19)
+__version__ = version = '0.0.29'
+__version_tuple__ = version_tuple = (0, 0, 29)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/application/app/base.py

@@ -12,7 +12,9 @@ import sys
 from typing import Any, ClassVar
 
 from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
 from starlette.middleware import Middleware as StarletteMiddleware
 
 from aury.boot.application.config import BaseConfig
@@ -279,8 +281,10 @@ class FoundationApp(FastAPI):
             **kwargs,
         )
 
-        # 异常处理
-        self.add_exception_handler(Exception, global_exception_handler)
+        # 异常处理：显式注册以覆盖 FastAPI/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)  # 其他未处理异常
 
         # 设置路由
         self.setup_routes()

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/application/app/components.py

@@ -15,6 +15,7 @@ from aury.boot.application.constants import ComponentName, ServiceType
 from aury.boot.application.migrations import MigrationManager
 from aury.boot.common.logging import logger
 from aury.boot.infrastructure.cache import CacheManager
+from aury.boot.infrastructure.channel import ChannelManager
 from aury.boot.infrastructure.database import DatabaseManager
 from aury.boot.infrastructure.events import EventBusManager
 from aury.boot.infrastructure.mq import MQManager
@@ -505,6 +506,49 @@ class MessageQueueComponent(Component):
                 logger.warning(f"消息队列 [{name}] 关闭失败: {e}")
 
 
+class ChannelComponent(Component):
+    """流式通道组件。
+    
+    用于 SSE（Server-Sent Events）和实时通信场景，支持 memory 和 redis 后端。
+    """
+
+    name = ComponentName.CHANNEL
+    enabled = True
+    depends_on: ClassVar[list[str]] = []
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """当配置了 Channel 实例时启用。"""
+        return self.enabled and bool(config.get_channels())
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化流式通道。"""
+        channel_configs = config.get_channels()
+        if not channel_configs:
+            logger.debug("未配置 Channel 实例，跳过通道初始化")
+            return
+        
+        for name, ch_config in channel_configs.items():
+            try:
+                channel_manager = ChannelManager.get_instance(name)
+                if not channel_manager.is_initialized:
+                    await channel_manager.initialize(
+                        backend=ch_config.backend,
+                        url=ch_config.url,
+                    )
+            except Exception as e:
+                logger.warning(f"通道 [{name}] 初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """关闭所有通道实例。"""
+        for name in list(ChannelManager._instances.keys()):
+            try:
+                channel_manager = ChannelManager.get_instance(name)
+                if channel_manager.is_initialized:
+                    await channel_manager.cleanup()
+            except Exception as e:
+                logger.warning(f"通道 [{name}] 关闭失败: {e}")
+
+
 class EventBusComponent(Component):
     """事件总线组件。
     
@@ -555,6 +599,7 @@ FoundationApp.components = [
     StorageComponent,
     TaskComponent,
     MessageQueueComponent,
+    ChannelComponent,
     EventBusComponent,
     SchedulerComponent,
 ]
@@ -563,6 +608,7 @@ FoundationApp.components = [
 __all__ = [
     "AdminConsoleComponent",
     "CacheComponent",
+    "ChannelComponent",
     "DatabaseComponent",
     "EventBusComponent",
     "MessageQueueComponent",

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/application/config/settings.py

@@ -246,6 +246,27 @@ class CacheSettings(BaseModel):
     )
 
 
+class ChannelSettings(BaseModel):
+    """流式通道配置（单实例）。
+    
+    环境变量格式: CHANNEL__{FIELD}
+    示例: CHANNEL__BACKEND, CHANNEL__URL
+    
+    支持的后端类型：
+    - memory: 内存后端（默认，单进程）
+    - redis: Redis Pub/Sub（多进程/分布式）
+    """
+    
+    backend: str = Field(
+        default="",
+        description="通道后端 (memory/redis)，空字符串表示不启用"
+    )
+    url: str | None = Field(
+        default=None,
+        description="Redis URL（当 backend=redis 时需要）"
+    )
+
+
 class StorageSettings(BaseModel):
     """对象存储组件接入配置（Application 层）。
 
@@ -507,10 +528,9 @@ class MessageQueueSettings(BaseModel):
     - Task: 基于 Dramatiq，用于异步任务处理（API + Worker 模式）
     - MQ: 通用消息队列，用于服务间通信、事件驱动架构
     
-    支持的后端（通过 Kombu）：
+    支持的后端：
     - Redis: redis://localhost:6379/0
     - RabbitMQ: amqp://guest:guest@localhost:5672//
-    - Amazon SQS: sqs://
     """
     
     enabled: bool = Field(
@@ -780,6 +800,7 @@ class BaseConfig(BaseSettings):
     # ========== 数据与缓存 ==========
     database: DatabaseSettings = Field(default_factory=DatabaseSettings)
     cache: CacheSettings = Field(default_factory=CacheSettings)
+    channel: ChannelSettings = Field(default_factory=ChannelSettings)
     storage: StorageSettings = Field(default_factory=StorageSettings)
     
     # 迁移配置
@@ -880,10 +901,18 @@ class BaseConfig(BaseSettings):
         """获取所有通道实例配置。
         
         从环境变量解析 CHANNEL__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
         """
         if self._channels is None:
             loader = MultiInstanceConfigLoader("CHANNEL", ChannelInstanceConfig)
             self._channels = loader.load()
+            if not self._channels and self.channel.backend:
+                self._channels = {
+                    "default": ChannelInstanceConfig(
+                        backend=self.channel.backend,
+                        url=self.channel.url,
+                    )
+                }
         return self._channels
     
     def get_mqs(self) -> dict[str, MQInstanceConfig]:
@@ -930,6 +959,7 @@ __all__ = [
     "CacheInstanceConfig",
     "CacheSettings",
     "ChannelInstanceConfig",
+    "ChannelSettings",
     "DatabaseInstanceConfig",
     "DatabaseSettings",
     "EventInstanceConfig",

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/application/constants/components.py

@@ -41,6 +41,9 @@ class ComponentName(str, Enum):
     # 事件总线组件
     EVENT_BUS = "event_bus"
 
+    # 流式通道组件
+    CHANNEL = "channel"
+
     # 迁移组件
     MIGRATIONS = "migrations"
 

{aury_boot-0.0.19 → aury_boot-0.0.29}/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"),
         )
 
@@ -174,6 +183,7 @@ class ValidationErrorHandler(ErrorHandler):
     """验证异常处理器。
     
     处理 Pydantic ValidationError 和 FastAPI RequestValidationError。
+    返回 422 Unprocessable Entity（符合 FastAPI 规范）。
     """
     
     def can_handle(self, exception: Exception) -> bool:
@@ -182,24 +192,38 @@ class ValidationErrorHandler(ErrorHandler):
     
     async def handle(self, exception: Exception, request: Request) -> JSONResponse:
         """处理验证异常。"""
-        logger.warning(f"数据验证失败: {exception}")
-        
         errors = []
         for error in exception.errors():
+            # 构建友好的字段路径：跳过 body 前缀
+            loc = error.get("loc", ())
+            # FastAPI 会在 loc 前加 'body'/'query'/'path' 等，保留第一个作为来源
+            source = str(loc[0]) if loc else ""
+            field_path = ".".join(str(part) for part in loc[1:]) if len(loc) > 1 else str(loc[0]) if loc else ""
+            
             errors.append({
-                "field": ".".join(str(loc) for loc in error["loc"]),
-                "message": error["msg"],
-                "type": error["type"],
+                "field": field_path,
+                "source": source,  # body / query / path / header
+                "message": error.get("msg", ""),
+                "type": error.get("type", ""),
+                "input": error.get("input"),  # 实际输入值（便于调试）
             })
         
+        # 详细日志：方便开发调试
+        error_summary = "; ".join(
+            f"{e['source']}.{e['field']}({e['type']}): {e['message']}" for e in errors
+        )
+        logger.warning(
+            f"参数校验失败 [{request.method} {request.url.path}]: {error_summary}"
+        )
+        
         response = ResponseBuilder.fail(
-            message="数据验证失败",
-            code=400,
+            message="参数校验失败",
+            code=422,
             errors=errors,
         )
         
         return JSONResponse(
-            status_code=status.HTTP_400_BAD_REQUEST,
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
             content=response.model_dump(mode="json"),
         )
 

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/commands/pkg.py

@@ -97,16 +97,16 @@ MODULES: dict[str, ModuleInfo] = {
     "tasks": ModuleInfo(
         name="tasks",
         desc="Dramatiq 任务队列",
-        usage="TaskManager 异步任务时需要",
+        usage="TaskManager 异步任务时需要（默认使用 Redis Broker）",
         category=Category.TASK,
-        deps=["dramatiq", "kombu", "dramatiq-kombu-broker"],
+        deps=["dramatiq", "redis"],
     ),
     "rabbitmq": ModuleInfo(
         name="rabbitmq",
         desc="RabbitMQ 消息队列后端",
         usage="TaskManager/EventBus 使用 RabbitMQ 时需要（需配合 tasks）",
         category=Category.TASK,
-        deps=["amqp"],
+        deps=["pika"],
     ),
     # 调度器
     "scheduler": ModuleInfo(

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -75,6 +75,8 @@ mypy {package_name}/
 2. **[aury_docs/02-repository.md](./aury_docs/02-repository.md)** - Repository 使用
    - BaseRepository API
    - Filters 语法（__gt, __like 等）
+   - Cursor 分页（推荐，性能更优）
+   - 流式查询（大数据处理）
    - 自动提交机制
 
 3. **[aury_docs/03-service.md](./aury_docs/03-service.md)** - Service 编写与事务
@@ -162,15 +164,25 @@ class User(Base): ...
 - 写操作**必须**使用 `@transactional` 装饰器
 - 只读操作可以不加事务装饰器
 - 跨 Service 调用通过共享 session 实现事务共享
+- **后台任务必须**使用 `@isolated_task` 装饰器
 
 ```python
-from aury.boot.domain.transaction import transactional
+from aury.boot.domain.transaction import transactional, isolated_task
 
 class UserService(BaseService):
     @transactional
     async def create(self, data: UserCreate) -> User:
         # 自动事务管理
         return await self.repo.create(data.model_dump())
+
+
+# 后台任务必须加 @isolated_task，否则事务不会提交
+@isolated_task
+async def background_upload(space_id: int, url: str):
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            await repo.update(...)
 ```
 
 ### Manager API 规范

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl

@@ -72,6 +72,37 @@ result = await repo.paginate(
 # - result.has_next: bool      # 是否有下一页
 # - result.has_prev: bool      # 是否有上一页
 
+# === Cursor 分页（推荐，性能更优） ===
+from aury.boot.domain.pagination import CursorPaginationParams
+
+# 第一页
+result = await repo.cursor_paginate(
+    CursorPaginationParams(limit=20),
+    is_active=True,
+)
+
+# 下一页（带上 cursor）
+result = await repo.cursor_paginate(
+    CursorPaginationParams(cursor=result.next_cursor, limit=20),
+    is_active=True,
+)
+
+# CursorPaginationResult 结构：
+# - result.items: list[T]          # 数据列表
+# - result.next_cursor: str | None # 下一页游标
+# - result.prev_cursor: str | None # 上一页游标
+# - result.has_next: bool          # 是否有下一页
+# - result.has_prev: bool          # 是否有上一页
+
+# === 流式查询（大数据处理） ===
+# 逐条流式处理，不会一次性加载到内存
+async for user in repo.stream(batch_size=1000, is_active=True):
+    await process(user)
+
+# 批量流式处理
+async for batch in repo.stream_batches(batch_size=1000):
+    await bulk_sync_to_es(batch)
+
 # === 创建 ===
 user = await repo.create({{"name": "Alice", "email": "a@b.com"}})
 users = await repo.batch_create([{{"name": "A"}}, {{"name": "B"}}])  # 返回实体

{aury_boot-0.0.19 → aury_boot-0.0.29}/aury/boot/commands/templates/project/aury_docs/03-service.md.tpl

@@ -396,3 +396,63 @@ DATABASE_ISOLATION_LEVEL=REPEATABLE READ
 - 大多数场景：`READ COMMITTED`（平衡性能和一致性）
 - 报表/统计查询：`REPEATABLE READ`（保证读取一致性）
 - 金融交易：`SERIALIZABLE`（最强一致性，性能较低）
+
+### 3.12 后台任务事务隔离（重要）
+
+在 `@transactional` 装饰的 Service 方法中 spawn 后台任务时，**必须**使用 `@isolated_task` 或 `isolated_context`，否则事务不会提交。
+
+**问题背景**：
+`asyncio.create_task()` 会继承父协程的 `contextvars`。如果父协程在 `@transactional` 中，子任务会继承事务深度标记，导致：
+- `auto_commit` 失效
+- `transactional_context` 也不会提交
+- session 关闭时数据被 rollback
+
+**解决方案 1：装饰器（推荐）**
+
+```python
+import asyncio
+from aury.boot.domain.transaction import isolated_task, transactional_context
+from aury.boot.infrastructure.database import DatabaseManager
+
+db = DatabaseManager.get_instance()
+
+
+@isolated_task
+async def upload_cover(space_id: int, cover_url: str):
+    """后台任务：上传封面。"""
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            space = await repo.get(space_id)
+            if space:
+                await repo.update(space, {{"cover": cover_url}})
+        # 现在会正常 commit
+
+
+class SpaceService(BaseService):
+    @transactional
+    async def create(self, data: SpaceCreate) -> Space:
+        space = await self.repo.create(data.model_dump())
+        
+        # spawn 后台任务
+        asyncio.create_task(upload_cover(space.id, data.cover_url))
+        
+        return space
+```
+
+**解决方案 2：上下文管理器**
+
+```python
+from aury.boot.domain.transaction import isolated_context
+
+async def background_job():
+    async with isolated_context():
+        async with db.session() as session:
+            async with transactional_context(session):
+                # 正常的事务处理
+                ...
+```
+
+**注意事项**：
+- 后台任务必须新开 session（`db.session()`），不能复用主请求的 `self.session`
+- 后台任务的事务与主请求独立，主请求回滚不影响后台任务