aury-boot 0.0.36__tar.gz → 0.0.38__tar.gz

{aury_boot-0.0.36 → aury_boot-0.0.38}/PKG-INFO

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

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.36'
-__version_tuple__ = version_tuple = (0, 0, 36)
+__version__ = version = '0.0.38'
+__version_tuple__ = version_tuple = (0, 0, 38)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/application/config/settings.py

@@ -147,13 +147,13 @@ class MQInstanceConfig(MultiInstanceSettings):
     
     环境变量格式: MQ__{INSTANCE}__{FIELD}
     示例:
-        MQ__DEFAULT__BACKEND=redis
+        MQ__DEFAULT__BACKEND=redis_stream
         MQ__DEFAULT__URL=redis://localhost:6379/4
     """
     
     backend: str = Field(
-        default="redis",
-        description="消息队列后端 (redis/rabbitmq)"
+        default="redis_stream",
+        description="消息队列后端 (redis/redis_stream/rabbitmq)"
     )
     url: str | None = Field(
         default=None,
@@ -715,7 +715,7 @@ class AlertSettings(BaseModel):
     
     # 抑制配置
     suppress_seconds: int = Field(
-        default=10,
+        default=300,
         description="告警抑制时间（秒），相同告警在此时间内不重复发送"
     )
     

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/commands/init.py

@@ -707,8 +707,8 @@ def init(
         console.print(f"  [cyan]uv add \"{deps[0]}\"[/cyan]")
         console.print()
     else:
-        # 非交互模式：默认启用 Admin Console
-        with_admin_console = True
+        # 非交互模式：默认禁用 Admin Console
+        with_admin_console = False
         if package_name == ".":
             package_name_snake = None
         elif package_name:

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -169,7 +169,7 @@ class BaseConfig(BaseSettings):
     )
 ```
 
-**环境变量命名规则**：`{SECTION}__{FIELD}`
+**环境变量命名规则**：`{{SECTION}}__{{FIELD}}`
 
 ```bash
 # 示例

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

@@ -0,0 +1,152 @@
+# 消息队列（MQ）
+
+支持 `redis`、`redis_stream` 和 `rabbitmq` 后端的消息队列，用于异步任务解耦。
+
+## 14.1 基本用法
+
+```python
+from aury.boot.infrastructure.mq import MQManager
+
+# 获取实例
+mq = MQManager.get_instance()
+
+# Redis List 后端（简单队列）
+await mq.initialize(backend="redis", url="redis://localhost:6379/0")
+
+# Redis Stream 后端（推荐，支持消费者组）
+await mq.initialize(backend="redis_stream", url="redis://localhost:6379/0")
+
+# RabbitMQ 后端
+await mq.initialize(backend="rabbitmq", url="amqp://guest:guest@localhost:5672/")
+```
+
+## 14.2 后端对比
+
+**Redis List (redis)**:
+- 简单的 FIFO 队列（LPUSH/BRPOP）
+- 适合单消费者场景
+- 消息不持久化（除非开启 AOF）
+
+**Redis Stream (redis_stream)** ⭐ 推荐:
+- 支持消费者组，多实例可并行消费
+- 消息持久化（配合 AOF）
+- 支持消息确认（ACK）和重试
+- 支持消息回放和历史查询
+
+**RabbitMQ (rabbitmq)**:
+- 功能最完整的消息队列
+- 支持多种交换机类型
+- 适合复杂的消息路由场景
+
+## 14.3 生产者
+
+```python
+from aury.boot.infrastructure.mq import MQMessage
+
+# 发送消息
+await mq.send(
+    queue="orders",
+    message={{"order_id": "123", "action": "created"}}
+)
+
+# 使用 MQMessage 对象（可设置 headers）
+msg = MQMessage(
+    body={{"order_id": "123"}},
+    headers={{"priority": "high"}}
+)
+await mq.send("orders", msg)
+```
+
+## 14.4 消费者
+
+**文件**: `{package_name}/workers/order_worker.py`
+
+```python
+from aury.boot.infrastructure.mq import MQManager, MQMessage
+from aury.boot.common.logging import logger
+
+mq = MQManager.get_instance()
+
+
+async def process_order(message: MQMessage):
+    \"\"\"处理订单消息。\"\"\"
+    logger.info(f"处理订单: {{message.body}}")
+    # 业务逻辑...
+
+
+async def start_consumer():
+    \"\"\"启动消费者。\"\"\"
+    # consume 会自动处理 ACK/NACK
+    await mq.consume("orders", process_order)
+```
+
+## 14.5 Redis Stream 特性
+
+```python
+from aury.boot.infrastructure.mq.backends.redis_stream import RedisStreamMQ
+
+# 初始化时指定消费者组
+mq = MQManager.get_instance()
+await mq.initialize(
+    backend="redis_stream",
+    url="redis://localhost:6379/0"
+)
+
+# 获取底层 RedisStreamMQ 实例使用高级特性
+stream_mq: RedisStreamMQ = mq.backend
+
+# 读取所有历史消息（用于重放）
+messages = await stream_mq.read_all("orders", count=100)
+
+# 阻塞读取新消息（用于 SSE/实时推送）
+messages = await stream_mq.read_blocking(
+    "orders",
+    last_id="$",  # 从最新消息开始
+    count=10,
+    block_ms=5000  # 阻塞 5 秒
+)
+
+# 裁剪 Stream（保留最新 1000 条）
+await stream_mq.trim("orders", maxlen=1000)
+
+# 获取 Stream 信息
+info = await stream_mq.stream_info("orders")
+```
+
+## 14.6 多实例配置
+
+框架支持命名多实例，适合不同业务场景使用不同的 MQ：
+
+```python
+# 代码中使用命名实例
+orders_mq = MQManager.get_instance("orders")
+notifications_mq = MQManager.get_instance("notifications")
+
+# 分别初始化
+await orders_mq.initialize(backend="redis_stream", url="redis://localhost:6379/1")
+await notifications_mq.initialize(backend="redis", url="redis://localhost:6379/2")
+```
+
+**环境变量配置**（自动初始化）:
+
+```bash
+# 单实例配置
+MQ__BACKEND=redis_stream
+MQ__URL=redis://localhost:6379/0
+
+# 多实例配置（格式：MQ__{{INSTANCE}}__{{FIELD}}）
+MQ__DEFAULT__BACKEND=redis_stream
+MQ__DEFAULT__URL=redis://localhost:6379/4
+MQ__ORDERS__BACKEND=rabbitmq
+MQ__ORDERS__URL=amqp://guest:guest@localhost:5672/
+```
+
+## 14.7 与异步任务（Dramatiq）的区别
+
+- **MQ**：轻量级消息传递，适合简单的生产者-消费者模式、实时通知、多实例消费
+- **Dramatiq（TaskManager）**：功能更丰富，支持重试、延迟、优先级、Actor 模式
+
+选择建议：
+- 简单的异步解耦 → MQ (redis_stream)
+- 需要重试/延迟/优先级 → Dramatiq
+- 多服务实例并行消费 → MQ (redis_stream) 或 RabbitMQ

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/commands/templates/project/env_templates/messaging.tpl

@@ -19,19 +19,27 @@
 # =============================================================================
 # 消息队列配置 (MQ__)
 # =============================================================================
+# 支持后端: redis | redis_stream (推荐) | rabbitmq
+#
 # 单实例配置:
-# MQ__ENABLED=false
-# MQ__BROKER_URL=redis://localhost:6379/4
-
+# MQ__BACKEND=redis_stream
+# MQ__URL=redis://localhost:6379/4
+#
 # 多实例配置 (格式: MQ__{{INSTANCE}}__{{FIELD}}):
-# MQ__DEFAULT__BACKEND=redis
+# MQ__DEFAULT__BACKEND=redis_stream
 # MQ__DEFAULT__URL=redis://localhost:6379/4
-# MQ__DEFAULT__MAX_CONNECTIONS=10
 #
-# RabbitMQ 后端:
+# Redis List 后端 (简单 FIFO 队列):
+# MQ__SIMPLE__BACKEND=redis
+# MQ__SIMPLE__URL=redis://localhost:6379/4
+#
+# Redis Stream 后端 (推荐，支持消费者组/多实例消费):
+# MQ__TASKS__BACKEND=redis_stream
+# MQ__TASKS__URL=redis://localhost:6379/4
+#
+# RabbitMQ 后端 (复杂消息路由):
 # MQ__ORDERS__BACKEND=rabbitmq
 # MQ__ORDERS__URL=amqp://guest:guest@localhost:5672/orders
-# MQ__ORDERS__PREFETCH_COUNT=10
 
 # =============================================================================
 # 事件总线配置 (EVENT__)

aury_boot-0.0.38/aury/boot/infrastructure/cache/backends.py

@@ -0,0 +1,14 @@
+"""缓存后端实现（兼容层）。
+
+实际实现在 redis.py 和 memory.py 中。
+"""
+
+from .memory import MemcachedCache, MemoryCache
+from .redis import RedisCache
+
+__all__ = [
+    "MemcachedCache",
+    "MemoryCache",
+    "RedisCache",
+]
+

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/infrastructure/cache/base.py

@@ -71,6 +71,44 @@ class ICache(ABC):
     async def close(self) -> None:
         """关闭连接。"""
         pass
+    
+    # ==================== 分布式锁 ====================
+    
+    @abstractmethod
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取分布式锁。
+        
+        Args:
+            key: 锁的键名（已加 lock: 前缀）
+            token: 锁的 token
+            timeout: 锁的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Returns:
+            bool: 是否获取成功
+        """
+        pass
+    
+    @abstractmethod
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放分布式锁。
+        
+        Args:
+            key: 锁的键名（已加 lock: 前缀）
+            token: 获取锁时的 token
+            
+        Returns:
+            bool: 是否成功释放
+        """
+        pass
 
 
 __all__ = [

{aury_boot-0.0.36 → aury_boot-0.0.38}/aury/boot/infrastructure/cache/manager.py

@@ -5,11 +5,15 @@
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Callable
+from contextlib import asynccontextmanager
 from datetime import timedelta
 from functools import wraps
 import hashlib
-from typing import Any, TypeVar
+import time
+from typing import Any, AsyncIterator, TypeVar
+import uuid
 
 from aury.boot.common.logging import logger
 
@@ -328,6 +332,152 @@ class CacheManager:
             self._backend = None
             logger.info("缓存管理器已清理")
     
+    # ==================== 分布式锁 ====================
+    
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        timeout: int = 30,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> str | None:
+        """获取分布式锁。
+        
+        Args:
+            key: 锁的键名
+            timeout: 锁的超时时间（秒），防止死锁
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Returns:
+            str | None: 锁的 token（用于释放），获取失败返回 None
+        """
+        lock_key = f"lock:{key}"
+        token = str(uuid.uuid4())
+        
+        acquired = await self.backend.acquire_lock(
+            lock_key, token, timeout, blocking, blocking_timeout
+        )
+        return token if acquired else None
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放分布式锁。
+        
+        Args:
+            key: 锁的键名
+            token: acquire_lock 返回的 token
+            
+        Returns:
+            bool: 是否成功释放
+        """
+        lock_key = f"lock:{key}"
+        return await self.backend.release_lock(lock_key, token)
+    
+    @asynccontextmanager
+    async def lock(
+        self,
+        key: str,
+        *,
+        timeout: int = 30,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> AsyncIterator[bool]:
+        """分布式锁上下文管理器。
+        
+        Args:
+            key: 锁的键名
+            timeout: 锁的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Yields:
+            bool: 是否成功获取锁
+            
+        示例:
+            async with cache.lock("my_resource") as acquired:
+                if acquired:
+                    # 执行需要互斥的操作
+                    pass
+        """
+        token = await self.acquire_lock(
+            key,
+            timeout=timeout,
+            blocking=blocking,
+            blocking_timeout=blocking_timeout,
+        )
+        try:
+            yield token is not None
+        finally:
+            if token:
+                await self.release_lock(key, token)
+    
+    @asynccontextmanager
+    async def semaphore(
+        self,
+        key: str,
+        max_concurrency: int,
+        *,
+        timeout: int = 300,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> AsyncIterator[bool]:
+        """分布式信号量（限制并发数）。
+        
+        Args:
+            key: 信号量的键名
+            max_concurrency: 最大并发数
+            timeout: 单个槽位的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Yields:
+            bool: 是否成功获取槽位
+            
+        示例:
+            async with cache.semaphore("pdf_ocr", max_concurrency=2) as acquired:
+                if acquired:
+                    # 执行受并发限制的操作
+                    pass
+        """
+        slot_token: str | None = None
+        acquired_slot: int | None = None
+        start_time = time.monotonic()
+        
+        try:
+            while True:
+                # 尝试获取任意一个槽位
+                for slot in range(max_concurrency):
+                    slot_key = f"{key}:slot:{slot}"
+                    token = await self.acquire_lock(
+                        slot_key,
+                        timeout=timeout,
+                        blocking=False,
+                    )
+                    if token:
+                        slot_token = token
+                        acquired_slot = slot
+                        yield True
+                        return
+                
+                if not blocking:
+                    yield False
+                    return
+                
+                # 检查是否超时
+                if blocking_timeout is not None:
+                    elapsed = time.monotonic() - start_time
+                    if elapsed >= blocking_timeout:
+                        yield False
+                        return
+                
+                # 等待后重试
+                await asyncio.sleep(0.1)
+        finally:
+            if slot_token and acquired_slot is not None:
+                slot_key = f"{key}:slot:{acquired_slot}"
+                await self.release_lock(slot_key, slot_token)
+    
     def __repr__(self) -> str:
         """字符串表示。"""
         backend_name = self.backend_type if self._backend else "未初始化"