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

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

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

{aury_boot-0.0.36 → aury_boot-0.0.37}/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.37'
+__version_tuple__ = version_tuple = (0, 0, 37)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.36 → aury_boot-0.0.37}/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.37}/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.37}/aury/boot/commands/templates/project/AGENTS.md.tpl

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

aury_boot-0.0.37/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.37}/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.36/aury/boot/commands/templates/project/aury_docs/14-mq.md.tpl

@@ -1,102 +0,0 @@
-# 消息队列（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）**：功能更丰富，支持重试、延迟、优先级等