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

aury/boot/commands/templates/project/aury_docs/14-mq.md.tpl

@@ -0,0 +1,102 @@
+# 消息队列（MQ）
+
+支持 `redis` 和 `rabbitmq` 后端的消息队列，用于异步任务解耦。
+
+## 14.1 基本用法
+
+```python
+from aury.boot.infrastructure.mq import MQManager
+
+# 获取实例
+mq = MQManager.get_instance()
+
+# Redis 后端
+await mq.initialize(backend="redis", url="redis://localhost:6379/0")
+
+# RabbitMQ 后端
+await mq.initialize(backend="rabbitmq", url="amqp://guest:guest@localhost:5672/")
+```
+
+## 14.2 生产者
+
+```python
+# 发送消息
+await mq.publish(
+    queue="orders",
+    message={{"order_id": "123", "action": "created"}}
+)
+
+# 批量发送
+await mq.publish_batch(
+    queue="orders",
+    messages=[
+        {{"order_id": "1", "action": "created"}},
+        {{"order_id": "2", "action": "updated"}},
+    ]
+)
+```
+
+## 14.3 消费者
+
+**文件**: `{package_name}/workers/order_worker.py`
+
+```python
+from aury.boot.infrastructure.mq import MQManager
+from aury.boot.common.logging import logger
+
+mq = MQManager.get_instance()
+
+
+async def process_order(message: dict):
+    \"\"\"处理订单消息。\"\"\"
+    logger.info(f"处理订单: {{message['order_id']}}")
+    # 业务逻辑...
+
+
+async def start_consumer():
+    \"\"\"启动消费者。\"\"\"
+    await mq.consume("orders", process_order)
+
+
+# 带确认的消费
+async def process_with_ack(message: dict, ack, nack):
+    try:
+        await process_order(message)
+        await ack()
+    except Exception:
+        await nack(requeue=True)
+
+await mq.consume("orders", process_with_ack, auto_ack=False)
+```
+
+## 14.4 多实例
+
+```python
+# 不同用途的 MQ 实例
+orders_mq = MQManager.get_instance("orders")
+notifications_mq = MQManager.get_instance("notifications")
+
+# 分别初始化
+await orders_mq.initialize(backend="rabbitmq", url="amqp://localhost:5672/orders")
+await notifications_mq.initialize(backend="redis", url="redis://localhost:6379/5")
+```
+
+## 14.5 环境变量
+
+```bash
+# 默认实例
+MQ_BACKEND=redis
+MQ_URL=redis://localhost:6379/0
+
+# 多实例（格式：MQ_{{INSTANCE}}_{{FIELD}}）
+MQ_DEFAULT_BACKEND=redis
+MQ_DEFAULT_URL=redis://localhost:6379/4
+MQ_ORDERS_BACKEND=rabbitmq
+MQ_ORDERS_URL=amqp://guest:guest@localhost:5672/
+MQ_ORDERS_PREFETCH_COUNT=10
+```
+
+## 14.6 与异步任务（Dramatiq）的区别
+
+- **MQ**：轻量级消息传递，适合简单的生产者-消费者模式
+- **Dramatiq（TaskManager）**：功能更丰富，支持重试、延迟、优先级等

aury/boot/commands/templates/project/aury_docs/15-events.md.tpl

@@ -0,0 +1,147 @@
+# 事件总线（Events）
+
+支持 `memory`、`redis`、`rabbitmq` 后端的事件发布订阅系统。
+
+## 15.1 定义事件
+
+**文件**: `{package_name}/events/__init__.py`
+
+```python
+from aury.boot.infrastructure.events import Event
+
+
+class OrderCreatedEvent(Event):
+    \"\"\"订单创建事件。\"\"\"
+    order_id: str
+    amount: float
+    user_id: str
+    
+    @property
+    def event_name(self) -> str:
+        return "order.created"
+
+
+class UserRegisteredEvent(Event):
+    \"\"\"用户注册事件。\"\"\"
+    user_id: str
+    email: str
+    
+    @property
+    def event_name(self) -> str:
+        return "user.registered"
+```
+
+### 15.1.1 事件初始化
+
+事件类基于 Pydantic BaseModel，支持以下初始化方式：
+
+```python
+# 方式 1：关键字参数（推荐）
+event = OrderCreatedEvent(
+    order_id="order-123",
+    amount=99.99,
+    user_id="user-456",
+)
+
+# 方式 2：字典解包
+event = OrderCreatedEvent(**{{
+    "order_id": "order-123",
+    "amount": 99.99,
+    "user_id": "user-456",
+}})
+
+# 方式 3：从实体创建
+event = OrderCreatedEvent(
+    order_id=str(order.id),
+    amount=order.amount,
+    user_id=str(order.user_id),
+)
+```
+
+## 15.2 订阅事件
+
+```python
+from aury.boot.infrastructure.events import EventBusManager
+
+bus = EventBusManager.get_instance()
+
+
+@bus.subscribe(OrderCreatedEvent)
+async def on_order_created(event: OrderCreatedEvent):
+    \"\"\"处理订单创建事件。\"\"\"
+    logger.info(f"订单创建: {{event.order_id}}, 金额: {{event.amount}}")
+    # 发送通知、更新统计等...
+
+
+@bus.subscribe(UserRegisteredEvent)
+async def send_welcome_email(event: UserRegisteredEvent):
+    \"\"\"发送欢迎邮件。\"\"\"
+    await email_service.send_welcome(event.email)
+```
+
+## 15.3 发布事件
+
+```python
+from {package_name}.events import OrderCreatedEvent
+
+@router.post("/orders")
+async def create_order(request: OrderCreateRequest):
+    # 创建订单
+    order = await order_service.create(request)
+    
+    # 发布事件
+    await bus.publish(OrderCreatedEvent(
+        order_id=order.id,
+        amount=order.amount,
+        user_id=order.user_id
+    ))
+    
+    return BaseResponse(code=200, message="订单创建成功", data=order)
+```
+
+## 15.4 多实例（EventBusManager）
+
+```python
+from aury.boot.infrastructure.events import EventBusManager
+
+# 获取实例
+bus = EventBusManager.get_instance()
+domain_bus = EventBusManager.get_instance("domain")
+
+# Memory 后端（单进程）
+await bus.initialize(backend="memory")
+
+# Redis Pub/Sub 后端
+await bus.initialize(
+    backend="redis",
+    url="redis://localhost:6379/0",
+    channel_prefix="events:",
+)
+
+# RabbitMQ 后端
+await bus.initialize(
+    backend="rabbitmq",
+    url="amqp://guest:guest@localhost:5672/",
+    exchange_name="app.events",
+)
+```
+
+## 15.5 环境变量
+
+```bash
+# 默认实例
+EVENT_BACKEND=memory
+
+# 多实例（格式：EVENT_{{INSTANCE}}_{{FIELD}}）
+EVENT_DEFAULT_BACKEND=redis
+EVENT_DEFAULT_URL=redis://localhost:6379/5
+EVENT_DOMAIN_BACKEND=rabbitmq
+EVENT_DOMAIN_URL=amqp://guest:guest@localhost:5672/
+EVENT_DOMAIN_EXCHANGE_NAME=domain.events
+```
+
+## 15.6 最佳实践
+
+1. **事件应该是不可变的** - 使用 Pydantic 的 `frozen=True`
+2. **订阅者应该快速完成** - 耗时操作使用任务队列
+3. **避免循环事件** - 不要在订阅者中发布相同类型的事件

aury/boot/commands/templates/project/config.py.tpl

@@ -5,7 +5,7 @@
 环境变量示例：
     DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb
     CACHE_TYPE=redis
-    CACHE_REDIS_URL=redis://localhost:6379/0
+    CACHE_URL=redis://localhost:6379/0
     LOG_LEVEL=INFO
 """
 

aury/boot/commands/templates/project/env.example.tpl

@@ -25,8 +25,10 @@ SERVICE_NAME={project_name_snake}
 # =============================================================================
 # 数据库配置 (DATABASE_)
 # =============================================================================
-# 数据库连接字符串（默认 SQLite）
+# 支持多实例配置，格式: DATABASE_{{INSTANCE}}_{{FIELD}}
+# 默认实例 (default):
 # DATABASE_URL=sqlite+aiosqlite:///./dev.db
+# DATABASE_DEFAULT_URL=sqlite+aiosqlite:///./dev.db
 # PostgreSQL: postgresql+asyncpg://user:pass@localhost:5432/{project_name_snake}
 # MySQL: mysql+aiomysql://user:pass@localhost:3306/{project_name_snake}
 
@@ -43,15 +45,25 @@ SERVICE_NAME={project_name_snake}
 # 是否输出 SQL 语句（调试用）
 # DATABASE_ECHO=false
 
+# 多实例示例 (readonly):
+# DATABASE_READONLY_URL=postgresql+asyncpg://user:pass@replica:5432/{project_name_snake}
+# DATABASE_READONLY_POOL_SIZE=10
+
 # =============================================================================
 # 缓存配置 (CACHE_)
 # =============================================================================
+# 支持多实例配置，格式: CACHE_{{INSTANCE}}_{{FIELD}}
 # 缓存类型: memory / redis / memcached
 # CACHE_TYPE=memory
-# Redis/Memcached URL
 # CACHE_URL=redis://localhost:6379/0
 # 内存缓存最大大小
 # CACHE_MAX_SIZE=1000
+# 默认 TTL（秒）
+# CACHE_DEFAULT_TTL=300
+#
+# 多实例示例 (session):
+# CACHE_SESSION_TYPE=redis
+# CACHE_SESSION_URL=redis://localhost:6379/2
 
 # =============================================================================
 # 日志配置 (LOG_)
@@ -138,13 +150,69 @@ SERVICE_NAME={project_name_snake}
 # 任务超时时间（秒）
 # TASK_TIMEOUT=3600
 
+# =============================================================================
+# 流式通道配置 (CHANNEL_) - SSE/实时通信
+# =============================================================================
+# 支持多实例配置，格式: CHANNEL_{{INSTANCE}}_{{FIELD}}
+# 后端类型: memory / redis
+# CHANNEL_BACKEND=memory
+# CHANNEL_DEFAULT_BACKEND=memory
+#
+# Redis 后端配置:
+# CHANNEL_DEFAULT_BACKEND=redis
+# CHANNEL_DEFAULT_URL=redis://localhost:6379/3
+# CHANNEL_DEFAULT_KEY_PREFIX=channel:
+# CHANNEL_DEFAULT_TTL=86400
+#
+# 多实例示例 (notifications):
+# CHANNEL_NOTIFICATIONS_BACKEND=redis
+# CHANNEL_NOTIFICATIONS_URL=redis://localhost:6379/3
+
+# =============================================================================
+# 消息队列配置 (MQ_)
+# =============================================================================
+# 支持多实例配置，格式: MQ_{{INSTANCE}}_{{FIELD}}
+# 后端类型: redis / rabbitmq
+# MQ_BACKEND=redis
+# MQ_DEFAULT_BACKEND=redis
+#
+# Redis 后端配置:
+# MQ_DEFAULT_URL=redis://localhost:6379/4
+# MQ_DEFAULT_MAX_CONNECTIONS=10
+#
+# RabbitMQ 后端配置:
+# MQ_DEFAULT_BACKEND=rabbitmq
+# MQ_DEFAULT_URL=amqp://guest:guest@localhost:5672/
+# MQ_DEFAULT_PREFETCH_COUNT=10
+# MQ_DEFAULT_HEARTBEAT=60
+#
+# 多实例示例 (orders):
+# MQ_ORDERS_BACKEND=rabbitmq
+# MQ_ORDERS_URL=amqp://guest:guest@localhost:5672/orders
+
 # =============================================================================
 # 事件总线配置 (EVENT_)
 # =============================================================================
-# 事件总线代理 URL（如 RabbitMQ）
-# EVENT_BROKER_URL=amqp://guest:guest@localhost:5672/
-# 事件交换机名称
+# 支持多实例配置，格式: EVENT_{{INSTANCE}}_{{FIELD}}
+# 后端类型: memory / redis / rabbitmq
+# EVENT_BACKEND=memory
+# EVENT_DEFAULT_BACKEND=memory
+#
+# Redis Pub/Sub 后端:
+# EVENT_DEFAULT_BACKEND=redis
+# EVENT_DEFAULT_URL=redis://localhost:6379/5
+# EVENT_DEFAULT_KEY_PREFIX=events:
+#
+# RabbitMQ 后端:
+# EVENT_DEFAULT_BACKEND=rabbitmq
+# EVENT_DEFAULT_URL=amqp://guest:guest@localhost:5672/
 # EVENT_EXCHANGE_NAME=aury.events
+# EVENT_DEFAULT_EXCHANGE_TYPE=topic
+#
+# 多实例示例 (domain):
+# EVENT_DOMAIN_BACKEND=rabbitmq
+# EVENT_DOMAIN_URL=amqp://guest:guest@localhost:5672/
+# EVENT_DOMAIN_EXCHANGE_NAME=domain.events
 
 # =============================================================================
 # 数据库迁移配置 (MIGRATION_)

aury/boot/commands/templates/project/modules/tasks.py.tpl

@@ -13,7 +13,7 @@
 # from aury.boot.infrastructure.tasks import conditional_task
 #
 #
-# @conditional_task
+# @conditional_task()
 # def example_task():
 #     """示例异步任务。"""
 #     logger.info("异步任务执行中...")

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: