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

aury/boot/commands/templates/project/aury_docs/13-channel.md.tpl

@@ -0,0 +1,104 @@
+# 流式通道（Channel）
+
+用于 SSE（Server-Sent Events）和实时通信。支持 memory 和 redis 后端。
+
+## 核心概念
+
+- **ChannelManager**：管理器，支持命名多实例（如 sse、notification 独立管理）
+- **channel 参数**：通道名/Topic，用于区分不同的消息流（如 `user:123`、`order:456`）
+
+## 13.1 基本用法
+
+```python
+from aury.boot.infrastructure.channel import ChannelManager
+
+# 命名多实例（推荐）- 不同业务场景使用不同实例
+sse_channel = ChannelManager.get_instance("sse")
+notification_channel = ChannelManager.get_instance("notification")
+
+# Memory 后端（单进程）
+await sse_channel.initialize(backend="memory")
+
+# Redis 后端（多进程/分布式）
+from aury.boot.infrastructure.clients.redis import RedisClient
+redis_client = RedisClient.get_instance()
+await redis_client.initialize(url="redis://localhost:6379/0")
+await notification_channel.initialize(backend="redis", redis_client=redis_client)
+```
+
+## 13.2 发布和订阅（Topic 管理）
+
+```python
+# 发布消息到指定 Topic
+await sse_channel.publish("user:123", {{"event": "message", "data": "hello"}})
+await sse_channel.publish("order:456", {{"status": "shipped"}})
+
+# 发布到多个用户
+for user_id in user_ids:
+    await sse_channel.publish(f"user:{{user_id}}", notification)
+```
+
+## 13.3 SSE 端点示例
+
+**文件**: `{package_name}/api/sse.py`
+
+```python
+import json
+from fastapi import APIRouter
+from fastapi.responses import StreamingResponse
+from aury.boot.infrastructure.channel import ChannelManager
+
+router = APIRouter(tags=["SSE"])
+
+# 获取命名实例（在 app 启动时已初始化）
+sse_channel = ChannelManager.get_instance("sse")
+
+
+@router.get("/sse/{{user_id}}")
+async def sse_stream(user_id: str):
+    \"\"\"SSE 实时消息流。\"\"\"
+    async def event_generator():
+        # user_id 作为 Topic，区分不同用户的消息流
+        async for message in sse_channel.subscribe(f"user:{{user_id}}"):
+            yield f"data: {{json.dumps(message)}}\n\n"
+    
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={{"Cache-Control": "no-cache", "Connection": "keep-alive"}}
+    )
+
+
+@router.post("/notify/{{user_id}}")
+async def send_notification(user_id: str, message: str):
+    \"\"\"\u53d1\u9001\u901a\u77e5\u3002\"\"\"
+    await sse_channel.publish(f"user:{{user_id}}", {{"message": message}})
+    return {{"status": "sent"}}
+```
+
+## 13.4 应用场景示例
+
+```python
+# 不同业务场景使用不同的命名实例
+sse_channel = ChannelManager.get_instance("sse")           # 前端 SSE 推送
+chat_channel = ChannelManager.get_instance("chat")         # 聊天消息
+notify_channel = ChannelManager.get_instance("notify")     # 系统通知
+
+# 分别初始化（可使用不同后端）
+await sse_channel.initialize(backend="memory")  # 单进程即可
+await chat_channel.initialize(backend="redis", redis_client=redis_client)  # 需要跨进程
+await notify_channel.initialize(backend="redis", redis_client=redis_client)
+```
+
+## 13.5 环境变量
+
+```bash
+# 默认实例
+CHANNEL__BACKEND=memory
+
+# 多实例（格式：CHANNEL__{{INSTANCE}}__{{FIELD}}）
+CHANNEL__DEFAULT__BACKEND=redis
+CHANNEL__DEFAULT__URL=redis://localhost:6379/3
+CHANNEL__NOTIFICATIONS__BACKEND=redis
+CHANNEL__NOTIFICATIONS__URL=redis://localhost:6379/4
+```

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. **避免循环事件** - 不要在订阅者中发布相同类型的事件