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

aury/boot/common/logging/setup.py

@@ -0,0 +1,214 @@
+"""日志配置和初始化。
+
+提供 setup_logging 和 register_log_sink 功能。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from loguru import logger
+
+from aury.boot.common.logging.context import (
+    ServiceContext,
+    _to_service_context,
+    get_service_context,
+    get_trace_id,
+    set_service_context,
+)
+from aury.boot.common.logging.format import create_console_sink, format_message
+
+# 全局日志配置状态
+_log_config: dict[str, Any] = {
+    "log_dir": "logs",
+    "rotation": "00:00",
+    "retention_days": 7,
+    "file_format": "",
+    "initialized": False,
+}
+
+
+def register_log_sink(
+    name: str,
+    *,
+    filter_key: str | None = None,
+    level: str = "INFO",
+    sink_format: str | None = None,
+) -> None:
+    """注册自定义日志 sink。
+    
+    使用 logger.bind() 标记的日志会写入对应文件。
+    
+    Args:
+        name: 日志文件名前缀（如 "access" -> access_2024-01-01.log）
+        filter_key: 过滤键名，日志需要 logger.bind(key=True) 才会写入
+        level: 日志级别
+        sink_format: 自定义格式（默认使用简化格式）
+    
+    使用示例:
+        # 注册 access 日志
+        register_log_sink("access", filter_key="access")
+        
+        # 写入 access 日志
+        logger.bind(access=True).info("GET /api/users 200 0.05s")
+    """
+    if not _log_config["initialized"]:
+        raise RuntimeError("请先调用 setup_logging() 初始化日志系统")
+    
+    log_dir = _log_config["log_dir"]
+    rotation = _log_config["rotation"]
+    retention_days = _log_config["retention_days"]
+    
+    default_format = (
+        "{time:YYYY-MM-DD HH:mm:ss} | "
+        "{extra[trace_id]} | "
+        "{message}"
+    )
+    
+    # 创建 filter
+    if filter_key:
+        def sink_filter(record, key=filter_key):
+            return record["extra"].get(key, False)
+    else:
+        sink_filter = None
+    
+    logger.add(
+        os.path.join(log_dir, f"{name}_{{time:YYYY-MM-DD}}.log"),
+        rotation=rotation,
+        retention=f"{retention_days} days",
+        level=level,
+        format=sink_format or default_format,
+        encoding="utf-8",
+        enqueue=True,
+        delay=True,
+        filter=sink_filter,
+    )
+    
+    logger.debug(f"注册日志 sink: {name} (filter_key={filter_key})")
+
+
+def setup_logging(
+    log_level: str = "INFO",
+    log_dir: str | None = None,
+    service_type: ServiceContext | str = ServiceContext.API,
+    enable_file_rotation: bool = True,
+    rotation_time: str = "00:00",
+    retention_days: int = 7,
+    rotation_size: str = "50 MB",
+    enable_console: bool = True,
+) -> None:
+    """设置日志配置。
+
+    日志文件按服务类型分离：
+    - {service_type}_info_{date}.log  - INFO/WARNING/DEBUG 日志
+    - {service_type}_error_{date}.log - ERROR/CRITICAL 日志
+    
+    轮转策略：
+    - 文件名包含日期，每天自动创建新文件
+    - 单文件超过大小限制时，会轮转产生 .1, .2 等后缀
+    
+    可通过 register_log_sink() 注册额外的日志文件（如 access.log）。
+
+    Args:
+        log_level: 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）
+        log_dir: 日志目录（默认：./logs）
+        service_type: 服务类型（app/scheduler/worker）
+        enable_file_rotation: 是否启用日志轮转
+        rotation_time: 每日轮转时间（默认：00:00）
+        retention_days: 日志保留天数（默认：7 天）
+        rotation_size: 单文件大小上限（默认：50 MB）
+        enable_console: 是否输出到控制台
+    """
+    log_level = log_level.upper()
+    log_dir = log_dir or "logs"
+    os.makedirs(log_dir, exist_ok=True)
+    
+    # 滚动策略：基于大小轮转（文件名已包含日期，每天自动新文件）
+    rotation = rotation_size if enable_file_rotation else None
+
+    # 标准化服务类型
+    service_type_enum = _to_service_context(service_type)
+
+    # 清理旧的 sink，避免重复日志（idempotent）
+    logger.remove()
+
+    # 保存全局配置（供 register_log_sink 使用）
+    _log_config.update({
+        "log_dir": log_dir,
+        "rotation": rotation,
+        "retention_days": retention_days,
+        "initialized": True,
+    })
+
+    # 设置默认服务上下文
+    set_service_context(service_type_enum)
+
+    # 配置 patcher，确保每条日志都有 service 和 trace_id
+    logger.configure(patcher=lambda record: (
+        record["extra"].update({
+            "trace_id": get_trace_id(),
+            # 记录字符串值，便于过滤器比较
+            "service": get_service_context().value,
+        })
+    ))
+
+    # 控制台输出（使用 Java 风格堆栈）
+    if enable_console:
+        logger.add(
+            create_console_sink(),
+            format="{message}",  # 简单格式，避免解析 <module> 等函数名
+            level=log_level,
+            colorize=False,  # 颜色在 sink 内处理
+        )
+
+    # 为 app 和 scheduler 分别创建日志文件（通过 ContextVar 区分）
+    # API 模式下会同时运行嵌入式 scheduler，需要两个文件
+    contexts_to_create: list[str] = [service_type_enum.value]
+    # API 模式下也需要 scheduler 日志文件
+    if service_type_enum is ServiceContext.API:
+        contexts_to_create.append(ServiceContext.SCHEDULER.value)
+    
+    for ctx in contexts_to_create:
+        # INFO 级别文件（使用 Java 风格堆栈）
+        info_file = os.path.join(
+            log_dir,
+            f"{ctx}_info_{{time:YYYY-MM-DD}}.log" if enable_file_rotation else f"{ctx}_info.log"
+        )
+        logger.add(
+            info_file,
+            format=lambda record: format_message(record),
+            rotation=rotation,
+            retention=f"{retention_days} days",
+            level=log_level,  # >= INFO 都写入（包含 WARNING/ERROR/CRITICAL）
+            encoding="utf-8",
+            enqueue=True,
+            filter=lambda record, c=ctx: (
+                record["extra"].get("service") == c
+                and not record["extra"].get("access", False)
+            ),
+        )
+
+        # ERROR 级别文件（使用 Java 风格堆栈）
+        error_file = os.path.join(
+            log_dir,
+            f"{ctx}_error_{{time:YYYY-MM-DD}}.log" if enable_file_rotation else f"{ctx}_error.log"
+        )
+        logger.add(
+            error_file,
+            format=lambda record: format_message(record),
+            rotation=rotation,
+            retention=f"{retention_days} days",
+            level="ERROR",
+            encoding="utf-8",
+            enqueue=True,
+            filter=lambda record, c=ctx: record["extra"].get("service") == c,
+        )
+
+    logger.info(f"日志系统初始化完成 | 服务: {service_type} | 级别: {log_level} | 目录: {log_dir}")
+
+
+__all__ = [
+    "register_log_sink",
+    "setup_logging",
+]

aury/boot/contrib/admin_console/auth.py

@@ -5,7 +5,6 @@ from typing import Any
 
 from starlette.requests import Request
 
-
 try:  # pragma: no cover
     from sqladmin.authentication import AuthenticationBackend as _SQLAdminAuthenticationBackend
 except Exception:  # pragma: no cover
@@ -14,7 +13,7 @@ except Exception:  # pragma: no cover
 
 def _require_sqladmin():
     try:
-        from sqladmin.authentication import AuthenticationBackend  # noqa: F401
+        from sqladmin.authentication import AuthenticationBackend
     except Exception as exc:  # pragma: no cover
         raise ImportError(
             "未安装 sqladmin。请先安装: uv add \"aury-boot[admin]\" 或 uv add sqladmin"
@@ -118,7 +117,7 @@ def wrap_authenticate(
     from sqladmin.authentication import AuthenticationBackend
 
     class _Wrapped(AuthenticationBackend):
-        async def login(self, request: Request) -> bool:  # noqa: D401
+        async def login(self, request: Request) -> bool:
             # 默认不提供登录页逻辑；用户可自己实现更复杂版本
             return False
 

aury/boot/contrib/admin_console/install.py

@@ -14,7 +14,7 @@ from .utils import import_from_string
 
 def _require_sqladmin():
     try:
-        from sqladmin import Admin  # noqa: F401
+        from sqladmin import Admin
     except Exception as exc:  # pragma: no cover
         raise ImportError(
             "未安装 sqladmin。请先安装: uv add \"aury-boot[admin]\" 或 uv add sqladmin"

aury/boot/domain/models/mixins.py

@@ -119,7 +119,54 @@ class AuditableStateMixin:
 
 
 class VersionMixin:
-    """乐观锁版本控制 Mixin"""
+    """乐观锁版本控制 Mixin。
+    
+    用于防止并发更新冲突。每次更新时会检查 version 是否一致，
+    如果不一致则抛出 VersionConflictError。
+    
+    工作原理:
+    1. 读取记录时获取当前 version
+    2. 更新时检查 version 是否与读取时一致
+    3. 如果一致，version + 1 并完成更新
+    4. 如果不一致，抛出 VersionConflictError
+    
+    使用场景:
+    - 库存管理（防止超卖）
+    - 订单状态更新（防止重复支付）
+    - 文档编辑（防止覆盖他人修改）
+    
+    示例:
+        class Product(IDMixin, VersionMixin, Base):
+            __tablename__ = "products"
+            name: Mapped[str]
+            stock: Mapped[int]
+        
+        # 更新时自动检查版本
+        product = await repo.get(1)  # version=1
+        product.stock -= 1
+        await repo.update(product)  # version 自动变为 2
+        
+        # 并发更新时抛出异常
+        # 线程 A: product.version = 1, 准备更新
+        # 线程 B: 已经更新，version = 2
+        # 线程 A: await repo.update(product) -> VersionConflictError
+    
+    异常处理:
+        from aury.boot.domain.exceptions import VersionConflictError
+        
+        try:
+            await repo.update(product)
+        except VersionConflictError as e:
+            # 重新加载数据并重试
+            product = await repo.get(product.id)
+            # ... 重新应用业务逻辑 ...
+            await repo.update(product)
+    
+    注意:
+    - 乐观锁适用于读多写少的场景
+    - 高并发写入场景建议使用悲观锁 (QueryBuilder.for_update())
+    - BaseRepository.update() 已自动支持乐观锁检查
+    """
 
     version: Mapped[int] = mapped_column(
         Integer,

aury/boot/domain/pagination/__init__.py

@@ -75,10 +75,104 @@ class SortParams(BaseModel):
     """排序参数。
     
     定义排序的字段和方向。
+    
+    支持两种语法：
+    - 简洁语法: "-created_at" (前缀 - 表示降序)
+    - 完整语法: "created_at:desc"
+    
+    示例:
+        # 从字符串解析
+        sort_params = SortParams.from_string("-created_at,priority")
+        sort_params = SortParams.from_string("created_at:desc,priority:asc")
+        
+        # 带白名单验证
+        sort_params = SortParams.from_string(
+            "-created_at",
+            allowed_fields={"id", "created_at", "priority"}
+        )
+        
+        # 程序化构建
+        sort_params = SortParams(sorts=[("-created_at",), ("priority", "asc")])
     """
     
     sorts: list[tuple[str, str]] = Field(default_factory=list, description="排序字段列表")
     
+    @classmethod
+    def from_string(
+        cls,
+        sort_str: str | None,
+        *,
+        allowed_fields: set[str] | None = None,
+        default_direction: str = "desc",
+    ) -> SortParams:
+        """从字符串解析排序参数。
+        
+        支持两种语法：
+        - 简洁语法: "-created_at" (前缀 - 表示降序)
+        - 完整语法: "created_at:desc"
+        
+        Args:
+            sort_str: 排序字符串，如 "-created_at,priority" 或 "created_at:desc,priority:asc"
+            allowed_fields: 允许的字段白名单（可选，用于安全校验）
+            default_direction: 默认排序方向（当不指定方向时使用）
+            
+        Returns:
+            SortParams: 排序参数对象
+            
+        Raises:
+            ValueError: 字段不在白名单中 或 方向无效
+            
+        示例:
+            >>> SortParams.from_string("-created_at,priority")
+            SortParams(sorts=[('created_at', 'desc'), ('priority', 'desc')])
+            
+            >>> SortParams.from_string("created_at:desc,priority:asc")
+            SortParams(sorts=[('created_at', 'desc'), ('priority', 'asc')])
+            
+            >>> SortParams.from_string("-id", allowed_fields={"id", "name"})
+            SortParams(sorts=[('id', 'desc')])
+            
+            >>> SortParams.from_string("-invalid", allowed_fields={"id", "name"})
+            ValueError: 不允许的排序字段: invalid，允许的字段: id, name
+        """
+        if not sort_str:
+            return cls(sorts=[])
+        
+        sorts = []
+        for part in sort_str.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            
+            # 解析字段和方向
+            if part.startswith("-"):
+                # 简洁语法: -created_at
+                field = part[1:]
+                direction = "desc"
+            elif ":" in part:
+                # 完整语法: created_at:desc
+                field, direction = part.split(":", 1)
+            else:
+                # 无方向指示，使用默认
+                field = part
+                direction = default_direction
+            
+            field = field.strip()
+            direction = direction.strip().lower()
+            
+            # 字段白名单校验
+            if allowed_fields and field not in allowed_fields:
+                allowed_list = ", ".join(sorted(allowed_fields))
+                raise ValueError(f"不允许的排序字段: {field}，允许的字段: {allowed_list}")
+            
+            # 方向校验
+            if direction not in ("asc", "desc"):
+                raise ValueError(f"排序方向必须是 'asc' 或 'desc'，得到: {direction}")
+            
+            sorts.append((field, direction))
+        
+        return cls(sorts=sorts)
+    
     def add_sort(self, field: str, direction: str = "asc") -> None:
         """添加排序字段。
         

aury/boot/domain/repository/impl.py

@@ -17,7 +17,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from aury.boot.common.logging import logger
 from aury.boot.domain.exceptions import VersionConflictError
 from aury.boot.domain.models import GUID, Base
-from aury.boot.domain.transaction import _transaction_depth
 from aury.boot.domain.pagination import (
     PaginationParams,
     PaginationResult,
@@ -25,6 +24,7 @@ from aury.boot.domain.pagination import (
 )
 from aury.boot.domain.repository.interface import IRepository
 from aury.boot.domain.repository.query_builder import QueryBuilder
+from aury.boot.domain.transaction import _transaction_depth
 
 if TYPE_CHECKING:
     from typing import Self

aury/boot/domain/repository/interface.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
-from aury.boot.domain.models import Base, GUID
+from aury.boot.domain.models import GUID, Base
 from aury.boot.domain.pagination import PaginationParams, PaginationResult, SortParams
 
 if TYPE_CHECKING:

aury/boot/domain/transaction/__init__.py

@@ -9,9 +9,9 @@
 
 from __future__ import annotations
 
-import contextvars
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
+import contextvars
 from functools import wraps
 from inspect import signature
 from typing import Any
@@ -24,9 +24,9 @@ from aury.boot.domain.exceptions import TransactionRequiredError
 # 用于跟踪嵌套事务的上下文变量
 _transaction_depth: contextvars.ContextVar[int] = contextvars.ContextVar("transaction_depth", default=0)
 
-# 用于存储 on_commit 回调的上下文变量
-_on_commit_callbacks: contextvars.ContextVar[list[Callable[[], Any] | Callable[[], Awaitable[Any]]]] = (
-    contextvars.ContextVar("on_commit_callbacks", default=[])
+# 用于存储 on_commit 回调的上下文变量（不设置 default，避免可变对象问题）
+_on_commit_callbacks: contextvars.ContextVar[list[Callable[[], Any] | Callable[[], Awaitable[Any]]] | None] = (
+    contextvars.ContextVar("on_commit_callbacks", default=None)
 )
 
 
@@ -51,8 +51,7 @@ def on_commit(callback: Callable[[], Any] | Callable[[], Awaitable[Any]]) -> Non
         - 嵌套事务中注册的回调，只在最外层事务提交后执行
     """
     callbacks = _on_commit_callbacks.get()
-    # 创建新列表避免修改默认值
-    if not callbacks:
+    if callbacks is None:
         callbacks = []
         _on_commit_callbacks.set(callbacks)
     callbacks.append(callback)
@@ -65,7 +64,7 @@ async def _execute_on_commit_callbacks() -> None:
         return
     
     # 清空回调列表
-    _on_commit_callbacks.set([])
+    _on_commit_callbacks.set(None)
     
     for callback in callbacks:
         try:
@@ -106,7 +105,7 @@ async def transactional_context(session: AsyncSession, auto_commit: bool = True)
     
     # 最外层事务初始化回调列表
     if is_outermost:
-        _on_commit_callbacks.set([])
+        _on_commit_callbacks.set(None)
     
     try:
         yield session
@@ -121,7 +120,7 @@ async def transactional_context(session: AsyncSession, auto_commit: bool = True)
         if is_outermost:
             await session.rollback()
             # 回滚时清空回调列表（不执行）
-            _on_commit_callbacks.set([])
+            _on_commit_callbacks.set(None)
             logger.error(f"事务回滚: {exc}")
         raise
     finally:

aury/boot/infrastructure/__init__.py

@@ -6,7 +6,11 @@
 - 存储管理
 - 调度器
 - 任务队列
-- 日志
+- 消息队列
+- 通道 (SSE/PubSub)
+- 事件总线
+- Redis 客户端
+- RabbitMQ 客户端
 """
 
 # 数据库
@@ -20,16 +24,49 @@ from .cache import (
     MemoryCache,
     RedisCache,
 )
+
+# 通道 (SSE/PubSub)
+from .channel import (
+    ChannelBackend,
+    ChannelManager,
+    ChannelMessage,
+    IChannel,
+    MemoryChannel,
+    RedisChannel,
+)
+
+# RabbitMQ 客户端
+from .clients.rabbitmq import RabbitMQClient, RabbitMQConfig
+
+# Redis 客户端
+from .clients.redis import RedisClient, RedisConfig
 from .database import DatabaseManager
 
-# 日志（已迁移到 common 层）
-# 从 common.logging 导入
+# 依赖注入
+from .di import Container, Lifetime, Scope, ServiceDescriptor
 
-# 调度器（可选依赖）
-try:
-    from .scheduler import SchedulerManager
-except ImportError:
-    SchedulerManager = None  # type: ignore[assignment, misc]
+# 事件总线
+from .events import (
+    Event,
+    EventBackend,
+    EventBusManager,
+    EventHandler,
+    EventType,
+    IEventBus,
+    MemoryEventBus,
+    RabbitMQEventBus,
+    RedisEventBus,
+)
+
+# 消息队列
+from .mq import (
+    IMQ,
+    MQBackend,
+    MQManager,
+    MQMessage,
+    RabbitMQ,
+    RedisMQ,
+)
 
 # 存储（基于 aury-sdk-storage）
 from .storage import (
@@ -44,45 +81,67 @@ from .storage import (
     UploadResult,
 )
 
+# 调度器（可选依赖）
+try:
+    from .scheduler import SchedulerManager
+except ImportError:
+    SchedulerManager = None  # type: ignore[assignment, misc]
+
 # 任务队列（可选依赖）
 try:
-    from .tasks import TaskManager, TaskProxy, conditional_actor
+    from .tasks import TaskManager, TaskProxy, conditional_task
 except ImportError:
     TaskManager = None  # type: ignore[assignment, misc]
     TaskProxy = None  # type: ignore[assignment, misc]
-    conditional_actor = None  # type: ignore[assignment, misc]
-
-# 事件总线
-# 依赖注入
-from .di import Container, Lifetime, Scope, ServiceDescriptor
-from .events import (
-    EventBus,
-    EventConsumer,
-    EventLoggingMiddleware,
-    EventMiddleware,
-)
+    conditional_task = None  # type: ignore[assignment, misc]
 
 __all__ = [
+    # 消息队列
+    "IMQ",
+    # 缓存
     "CacheBackend",
     "CacheFactory",
-    # 缓存
     "CacheManager",
+    # 通道
+    "ChannelBackend",
+    "ChannelManager",
+    "ChannelMessage",
     # 依赖注入
     "Container",
     # 数据库
     "DatabaseManager",
     # 事件总线
-    "EventBus",
-    "EventConsumer",
-    "EventLoggingMiddleware",
-    "EventMiddleware",
+    "Event",
+    "EventBackend",
+    "EventBusManager",
+    "EventHandler",
+    "EventType",
     "ICache",
+    "IChannel",
+    "IEventBus",
+    # 存储
     "IStorage",
     "Lifetime",
     "LocalStorage",
+    "MQBackend",
+    "MQManager",
+    "MQMessage",
     "MemcachedCache",
     "MemoryCache",
+    "MemoryChannel",
+    "MemoryEventBus",
+    "RabbitMQ",
+    # RabbitMQ 客户端
+    "RabbitMQClient",
+    "RabbitMQConfig",
+    "RabbitMQEventBus",
     "RedisCache",
+    "RedisChannel",
+    # Redis 客户端
+    "RedisClient",
+    "RedisConfig",
+    "RedisEventBus",
+    "RedisMQ",
     "S3Storage",
     # 调度器
     "SchedulerManager",
@@ -92,13 +151,11 @@ __all__ = [
     "StorageConfig",
     "StorageFactory",
     "StorageFile",
-    # 存储
     "StorageManager",
-    "UploadResult",
     # 任务队列
     "TaskManager",
     "TaskProxy",
-    "conditional_actor",
-    # 日志（已迁移到 common 层，请从 common.logging 导入）
+    "UploadResult",
+    "conditional_task",
 ]