V0.31 (#9)

mic1on · web-flow · commit 825141498028 · 2025-07-25T17:17:56.000+08:00
* feat(rabbitmq): 添加上下文管理器支持并修复连接泄漏问题

实现上下文管理器接口，支持with语法自动资源清理
重构连接和通道关闭逻辑，确保线程安全和正确关闭顺序
添加连接泄漏测试脚本和示例代码
更新文档说明推荐使用上下文管理器模式
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python Debugger: Current File",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/src"
+      }
+    }
+  ]
+}
diff --git a/README.md b/README.md
@@ -20,6 +20,8 @@
 - 线程安全设计
 - 完善的错误处理和日志记录
 - 支持消息确认机制
+- **修复连接泄漏问题**，确保生产环境稳定性
+- 支持上下文管理器，自动资源清理
 
 ## 安装
 
@@ -37,6 +39,29 @@ poetry add use-rabbitmq
 
 ### 基本使用
 
+#### 推荐方式：使用上下文管理器
+
+```python
+from use_rabbitmq import RabbitMQStore
+
+# 推荐：使用上下文管理器，自动清理资源
+with RabbitMQStore(
+    host="localhost",
+    port=5672,
+    username="guest",
+    password="guest"
+) as rmq:
+    # 发送消息
+    rmq.send(queue_name="test_queue", message="Hello, RabbitMQ!")
+    
+    # 获取消息数量
+    count = rmq.get_message_counts("test_queue")
+    print(f"队列中有 {count} 条消息")
+# 连接会自动关闭，避免连接泄漏
+```
+
+#### 传统方式：手动管理资源
+
 ```python
 from use_rabbitmq import RabbitMQStore
 
@@ -48,14 +73,18 @@ rmq = RabbitMQStore(
     password="guest"
 )
 
-# 发送消息
-rmq.send(queue_name="test_queue", message="Hello, RabbitMQ!")
-
-# 使用装饰器监听队列
-@rmq.listener(queue_name="test_queue")
-def process_message(message):
-    print(f"收到消息: {message.body}")
-    message.ack()  # 确认消息已处理
+try:
+    # 发送消息
+    rmq.send(queue_name="test_queue", message="Hello, RabbitMQ!")
+    
+    # 使用装饰器监听队列
+    @rmq.listener(queue_name="test_queue")
+    def process_message(message):
+        print(f"收到消息: {message.body}")
+        message.ack()  # 确认消息已处理
+finally:
+    # 重要：手动关闭连接，避免连接泄漏
+    rmq.shutdown()
 ```
 
 ### 使用别名
@@ -146,13 +175,50 @@ def process_batch(message):
     message.ack()
 ```
 
+## 连接管理和资源清理
+
+### 重要提醒：避免连接泄漏
+
+在生产环境中，**强烈建议**使用以下方式之一来确保连接被正确关闭：
+
+#### 方式1：上下文管理器（推荐）
+
+```python
+with RabbitMQStore() as rmq:
+    # 你的代码
+    pass
+# 连接自动关闭
+```
+
+#### 方式2：显式调用shutdown
+
+```python
+rmq = RabbitMQStore()
+try:
+    # 你的代码
+    pass
+finally:
+    rmq.shutdown()  # 确保连接被关闭
+```
+
+### 连接泄漏修复
+
+本版本修复了以下连接泄漏问题：
+
+- ✅ 线程安全的连接管理
+- ✅ 异常情况下的资源清理
+- ✅ 正确的连接和通道关闭顺序
+- ✅ 消费者停止机制优化
+- ✅ 析构函数异常处理
+
 ## 异常处理
 
 该库内置了自动重试和重连机制:
 
 - 连接错误自动重试
 - 发送消息失败自动重试
 - 消费者断线自动重连
+- 资源清理异常处理
 
 ## 贡献
 
diff --git a/example/example_context_manager.py b/example/example_context_manager.py
@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+使用上下文管理器的RabbitMQ示例
+
+这个示例展示了如何使用上下文管理器模式来确保RabbitMQ连接被正确关闭，
+避免连接泄漏问题。
+"""
+
+import logging
+from use_rabbitmq import RabbitMQStore
+
+logging.basicConfig(level=logging.INFO)
+
+def example_with_context_manager():
+    """使用上下文管理器的示例"""
+    print("=== 使用上下文管理器 ===")
+    
+    # 推荐的使用方式：使用上下文管理器
+    with RabbitMQStore(
+        host="localhost",
+        port=5672,
+        username="guest",
+        password="guest"
+    ) as mq:
+        # 声明队列
+        mq.declare_queue("test_queue", durable=True)
+        
+        # 发送消息
+        message = "Hello from context manager!"
+        mq.send("test_queue", message)
+        print(f"发送消息: {message}")
+        
+        # 获取消息数量
+        count = mq.get_message_counts("test_queue")
+        print(f"队列中的消息数量: {count}")
+        
+        # 清空队列
+        mq.flush_queue("test_queue")
+        print("队列已清空")
+    
+    # 连接会在这里自动关闭
+    print("连接已自动关闭")
+
+def example_manual_cleanup():
+    """手动清理的示例"""
+    print("\n=== 手动清理资源 ===")
+    
+    mq = RabbitMQStore(
+        host="localhost",
+        port=5672,
+        username="guest",
+        password="guest"
+    )
+    
+    try:
+        # 声明队列
+        mq.declare_queue("test_queue2", durable=True)
+        
+        # 发送消息
+        message = "Hello from manual cleanup!"
+        mq.send("test_queue2", message)
+        print(f"发送消息: {message}")
+        
+        # 获取消息数量
+        count = mq.get_message_counts("test_queue2")
+        print(f"队列中的消息数量: {count}")
+        
+    except Exception as e:
+        print(f"操作失败: {e}")
+    finally:
+        # 手动清理资源
+        mq.shutdown()
+        print("连接已手动关闭")
+
+def example_multiple_operations():
+    """多个操作的示例"""
+    print("\n=== 多个操作示例 ===")
+    
+    with RabbitMQStore(
+        host="localhost",
+        port=5672,
+        username="guest",
+        password="guest"
+    ) as mq:
+        # 创建多个队列
+        queues = ["queue1", "queue2", "queue3"]
+        
+        for queue_name in queues:
+            mq.declare_queue(queue_name, durable=True)
+            
+            # 发送多条消息
+            for i in range(3):
+                message = f"Message {i+1} to {queue_name}"
+                mq.send(queue_name, message)
+                print(f"发送到 {queue_name}: {message}")
+            
+            # 检查消息数量
+            count = mq.get_message_counts(queue_name)
+            print(f"{queue_name} 中有 {count} 条消息")
+            
+            # 清空队列
+            mq.flush_queue(queue_name)
+            print(f"{queue_name} 已清空")
+    
+    print("所有操作完成，连接已自动关闭")
+
+def example_error_handling():
+    """错误处理示例"""
+    print("\n=== 错误处理示例 ===")
+    
+    try:
+        with RabbitMQStore(
+            host="localhost",
+            port=5672,
+            username="guest",
+            password="guest"
+        ) as mq:
+            # 正常操作
+            mq.declare_queue("error_test_queue", durable=True)
+            mq.send("error_test_queue", "Test message")
+            
+            # 模拟错误（这里故意引发异常）
+            # raise ValueError("模拟的错误")
+            
+            print("操作成功完成")
+            
+    except Exception as e:
+        print(f"捕获到异常: {e}")
+        print("即使出现异常，连接也会被正确关闭")
+
+if __name__ == "__main__":
+    print("RabbitMQ 上下文管理器示例")
+    print("=" * 50)
+    
+    try:
+        example_with_context_manager()
+        example_manual_cleanup()
+        example_multiple_operations()
+        example_error_handling()
+        
+        print("\n" + "=" * 50)
+        print("所有示例完成！")
+        print("建议使用上下文管理器模式以确保资源正确清理")
+        while True:
+            pass
+        
+    except Exception as e:
+        print(f"示例运行出错: {e}")
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "use-rabbitmq"
-version = "0.2.5"
+version = "0.2.6"
 description = ""
 authors = ["miclon <jcnd@163.com>"]
 readme = "README.md"
diff --git a/src/use_rabbitmq/__init__.py b/src/use_rabbitmq/__init__.py
