aury-boot 0.0.37__py3-none-any.whl → 0.0.39__py3-none-any.whl

aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.37'
-__version_tuple__ = version_tuple = (0, 0, 37)
+__version__ = version = '0.0.39'
+__version_tuple__ = version_tuple = (0, 0, 39)
 
 __commit_id__ = commit_id = None

aury/boot/application/migrations/setup.py

@@ -102,6 +102,18 @@ load_all_models(_model_modules)
 target_metadata = Base.metadata
 
 
+# === 兼容性处理 ===
+# 过滤 PostgreSQL 15+ 特有的约束参数，确保生成的 migration 兼容旧版本 PG
+_PG15_CONSTRAINT_KWARGS = {{"postgresql_nulls_not_distinct", "postgresql_include"}}
+
+def _render_item(type_, obj, autogen_context):
+    """自定义渲染，过滤不兼容的约束参数。"""
+    if type_ == "unique_constraint" and hasattr(obj, "kwargs"):
+        for key in _PG15_CONSTRAINT_KWARGS:
+            obj.kwargs.pop(key, None)
+    return False  # 使用默认渲染
+
+
 def get_url() -> str:
     """获取数据库 URL（优先环境变量，其次 alembic.ini）。"""
     return os.environ.get("DATABASE_URL") or config.get_main_option("sqlalchemy.url", "")
@@ -117,8 +129,8 @@ def run_migrations_offline() -> None:
         dialect_opts={{"paramstyle": "named"}},
         compare_type=True,
         compare_server_default=True,
-        # 启用 batch 模式以更好地支持 SQLite 等不完整 DDL 的后端
         render_as_batch=True,
+        render_item=_render_item,
     )
     with context.begin_transaction():
         context.run_migrations()
@@ -131,8 +143,8 @@ def _do_run_migrations(connection) -> None:
         target_metadata=target_metadata,
         compare_type=True,
         compare_server_default=True,
-        # 启用 batch 模式以更好地支持 SQLite 等不完整 DDL 的后端
         render_as_batch=True,
+        render_item=_render_item,
     )
     with context.begin_transaction():
         context.run_migrations()

aury/boot/infrastructure/cache/backends.py

@@ -1,428 +1,10 @@
-"""缓存后端实现。
+"""缓存后端实现（兼容层）。
 
-提供 Redis、Memory、Memcached 等缓存后端的实现。
+实际实现在 redis.py 和 memory.py 中。
 """
 
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Callable
-from datetime import timedelta
-import json
-import pickle
-from typing import TYPE_CHECKING, Any
-
-from redis.asyncio import Redis
-
-from aury.boot.common.logging import logger
-
-from .base import ICache
-
-if TYPE_CHECKING:
-    from aury.boot.infrastructure.clients.redis import RedisClient
-
-
-class RedisCache(ICache):
-    """Redis缓存实现。
-    
-    支持两种初始化方式：
-    1. 传入 URL 自行创建连接
-    2. 传入 RedisClient 实例（推荐）
-    """
-    
-    def __init__(
-        self,
-        url: str | None = None,
-        *,
-        redis_client: RedisClient | None = None,
-        serializer: str = "json",
-    ):
-        """初始化Redis缓存。
-        
-        Args:
-            url: Redis连接URL
-            redis_client: RedisClient 实例（推荐）
-            serializer: 序列化方式（json/pickle）
-        """
-        self._url = url
-        self._redis_client = redis_client
-        self._serializer = serializer
-        self._redis: Redis | None = None
-        self._owns_connection = False  # 是否自己拥有连接（需要自己关闭）
-    
-    async def initialize(self) -> None:
-        """初始化连接。"""
-        # 优先使用 RedisClient
-        if self._redis_client is not None:
-            self._redis = self._redis_client.connection
-            self._owns_connection = False
-            logger.info("Redis缓存初始化成功（使用 RedisClient）")
-            return
-        
-        # 使用 URL 创建连接
-        if self._url:
-            try:
-                self._redis = Redis.from_url(
-                    self._url,
-                    encoding="utf-8",
-                    decode_responses=False,
-                    socket_connect_timeout=5,
-                    socket_timeout=5,
-                )
-                await self._redis.ping()
-                self._owns_connection = True
-                logger.info("Redis缓存初始化成功")
-            except Exception as exc:
-                logger.error(f"Redis连接失败: {exc}")
-                raise
-        else:
-            raise ValueError("Redis缓存需要提供 url 或 redis_client 参数")
-    
-    async def get(self, key: str, default: Any = None) -> Any:
-        """获取缓存。"""
-        if not self._redis:
-            return default
-        
-        try:
-            data = await self._redis.get(key)
-            if data is None:
-                return default
-            
-            # 使用函数式编程处理序列化器
-            deserializers: dict[str, Callable[[bytes], Any]] = {
-                "json": lambda d: json.loads(d.decode()),
-                "pickle": pickle.loads,
-            }
-            
-            deserializer = deserializers.get(self._serializer)
-            if deserializer:
-                return deserializer(data)
-            return data.decode()
-        except Exception as exc:
-            logger.error(f"Redis获取失败: {key}, {exc}")
-            return default
-    
-    async def set(
-        self,
-        key: str,
-        value: Any,
-        expire: int | timedelta | None = None,
-    ) -> bool:
-        """设置缓存。"""
-        if not self._redis:
-            return False
-        
-        try:
-            # 使用函数式编程处理序列化器
-            serializers: dict[str, Callable[[Any], bytes]] = {
-                "json": lambda v: json.dumps(v).encode(),
-                "pickle": pickle.dumps,
-            }
-            
-            serializer = serializers.get(self._serializer)
-            if serializer:
-                data = serializer(value)
-            else:
-                data = str(value).encode()
-            
-            # 转换过期时间
-            if isinstance(expire, timedelta):
-                expire = int(expire.total_seconds())
-            
-            await self._redis.set(key, data, ex=expire)
-            return True
-        except Exception as exc:
-            logger.error(f"Redis设置失败: {key}, {exc}")
-            return False
-    
-    async def delete(self, *keys: str) -> int:
-        """删除缓存。"""
-        if not self._redis or not keys:
-            return 0
-        
-        try:
-            return await self._redis.delete(*keys)
-        except Exception as exc:
-            logger.error(f"Redis删除失败: {keys}, {exc}")
-            return 0
-    
-    async def exists(self, *keys: str) -> int:
-        """检查缓存是否存在。"""
-        if not self._redis or not keys:
-            return 0
-        
-        try:
-            return await self._redis.exists(*keys)
-        except Exception as exc:
-            logger.error(f"Redis检查失败: {keys}, {exc}")
-            return 0
-    
-    async def clear(self) -> None:
-        """清空所有缓存。"""
-        if self._redis:
-            await self._redis.flushdb()
-            logger.info("Redis缓存已清空")
-    
-    async def delete_pattern(self, pattern: str) -> int:
-        """按模式删除缓存。
-        
-        Args:
-            pattern: 通配符模式，如 "todo:*"
-            
-        Returns:
-            int: 删除的键数量
-        """
-        if not self._redis:
-            return 0
-        
-        try:
-            # 使用 SCAN 遍历匹配的键（比 KEYS 更安全，不会阻塞）
-            count = 0
-            cursor = 0
-            while True:
-                cursor, keys = await self._redis.scan(cursor, match=pattern, count=100)
-                if keys:
-                    count += await self._redis.delete(*keys)
-                if cursor == 0:
-                    break
-            logger.debug(f"按模式删除缓存: {pattern}, 删除 {count} 个键")
-            return count
-        except Exception as exc:
-            logger.error(f"Redis模式删除失败: {pattern}, {exc}")
-            return 0
-    
-    async def close(self) -> None:
-        """关闭连接（仅当自己拥有连接时）。"""
-        if self._redis and self._owns_connection:
-            await self._redis.close()
-            logger.info("Redis连接已关闭")
-        self._redis = None
-    
-    @property
-    def redis(self) -> Redis | None:
-        """获取Redis客户端。"""
-        return self._redis
-
-
-class MemoryCache(ICache):
-    """内存缓存实现。"""
-    
-    def __init__(self, max_size: int = 1000):
-        """初始化内存缓存。
-        
-        Args:
-            max_size: 最大缓存项数
-        """
-        self._max_size = max_size
-        self._cache: dict[str, tuple[Any, float | None]] = {}
-        self._lock = asyncio.Lock()
-    
-    async def get(self, key: str, default: Any = None) -> Any:
-        """获取缓存。"""
-        async with self._lock:
-            if key not in self._cache:
-                return default
-            
-            value, expire_at = self._cache[key]
-            
-            # 检查过期
-            if expire_at is not None and asyncio.get_event_loop().time() > expire_at:
-                del self._cache[key]
-                return default
-            
-            return value
-    
-    async def set(
-        self,
-        key: str,
-        value: Any,
-        expire: int | timedelta | None = None,
-    ) -> bool:
-        """设置缓存。"""
-        async with self._lock:
-            # 转换过期时间
-            expire_at = None
-            if expire:
-                if isinstance(expire, timedelta):
-                    expire_seconds = expire.total_seconds()
-                else:
-                    expire_seconds = expire
-                expire_at = asyncio.get_event_loop().time() + expire_seconds
-            
-            # 如果超出容量，删除最旧的
-            if len(self._cache) >= self._max_size and key not in self._cache:
-                # 简单策略：删除第一个
-                first_key = next(iter(self._cache))
-                del self._cache[first_key]
-            
-            self._cache[key] = (value, expire_at)
-            return True
-    
-    async def delete(self, *keys: str) -> int:
-        """删除缓存。"""
-        async with self._lock:
-            count = 0
-            for key in keys:
-                if key in self._cache:
-                    del self._cache[key]
-                    count += 1
-            return count
-    
-    async def exists(self, *keys: str) -> int:
-        """检查缓存是否存在。"""
-        async with self._lock:
-            count = 0
-            for key in keys:
-                if key in self._cache:
-                    _value, expire_at = self._cache[key]
-                    # 检查是否过期
-                    if expire_at is None or asyncio.get_event_loop().time() <= expire_at:
-                        count += 1
-            return count
-    
-    async def clear(self) -> None:
-        """清空所有缓存。"""
-        async with self._lock:
-            self._cache.clear()
-            logger.info("内存缓存已清空")
-    
-    async def delete_pattern(self, pattern: str) -> int:
-        """按模式删除缓存。
-        
-        Args:
-            pattern: 通配符模式，支持 * 和 ?
-            
-        Returns:
-            int: 删除的键数量
-        """
-        import fnmatch
-        
-        async with self._lock:
-            keys_to_delete = [
-                key for key in self._cache
-                if fnmatch.fnmatch(key, pattern)
-            ]
-            for key in keys_to_delete:
-                del self._cache[key]
-            logger.debug(f"按模式删除缓存: {pattern}, 删除 {len(keys_to_delete)} 个键")
-            return len(keys_to_delete)
-    
-    async def close(self) -> None:
-        """关闭连接（内存缓存无需关闭）。"""
-        await self.clear()
-    
-    async def size(self) -> int:
-        """获取缓存大小。"""
-        return len(self._cache)
-
-
-class MemcachedCache(ICache):
-    """Memcached缓存实现（可选）。"""
-    
-    def __init__(self, servers: list[str]):
-        """初始化Memcached缓存。
-        
-        Args:
-            servers: Memcached服务器列表，如 ["127.0.0.1:11211"]
-        """
-        self._servers = servers
-        self._client = None
-    
-    async def initialize(self) -> None:
-        """初始化连接。"""
-        try:
-            # 需要安装 python-memcached 或 aiomcache
-            try:
-                import aiomcache
-                self._client = aiomcache.Client(
-                    self._servers[0].split(":")[0],
-                    int(self._servers[0].split(":")[1]) if ":" in self._servers[0] else 11211,
-                )
-                logger.info("Memcached缓存初始化成功")
-            except ImportError:
-                logger.error("请安装 aiomcache: pip install aiomcache")
-                raise
-        except Exception as exc:
-            logger.error(f"Memcached连接失败: {exc}")
-            raise
-    
-    async def get(self, key: str, default: Any = None) -> Any:
-        """获取缓存。"""
-        if not self._client:
-            return default
-        
-        try:
-            data = await self._client.get(key.encode())
-            if data is None:
-                return default
-            return json.loads(data.decode())
-        except Exception as exc:
-            logger.error(f"Memcached获取失败: {key}, {exc}")
-            return default
-    
-    async def set(
-        self,
-        key: str,
-        value: Any,
-        expire: int | timedelta | None = None,
-    ) -> bool:
-        """设置缓存。"""
-        if not self._client:
-            return False
-        
-        try:
-            if isinstance(expire, timedelta):
-                expire = int(expire.total_seconds())
-            
-            data = json.dumps(value).encode()
-            return await self._client.set(key.encode(), data, exptime=expire or 0)
-        except Exception as exc:
-            logger.error(f"Memcached设置失败: {key}, {exc}")
-            return False
-    
-    async def delete(self, *keys: str) -> int:
-        """删除缓存。"""
-        if not self._client or not keys:
-            return 0
-        
-        count = 0
-        for key in keys:
-            try:
-                if await self._client.delete(key.encode()):
-                    count += 1
-            except Exception as exc:
-                logger.error(f"Memcached删除失败: {key}, {exc}")
-        return count
-    
-    async def exists(self, *keys: str) -> int:
-        """检查缓存是否存在。"""
-        if not self._client or not keys:
-            return 0
-        
-        count = 0
-        for key in keys:
-            try:
-                if await self._client.get(key.encode()) is not None:
-                    count += 1
-            except Exception:
-                pass
-        return count
-    
-    async def clear(self) -> None:
-        """清空所有缓存（Memcached不支持）。"""
-        logger.warning("Memcached不支持清空所有缓存")
-    
-    async def delete_pattern(self, pattern: str) -> int:
-        """按模式删除缓存（Memcached 不支持）。"""
-        logger.warning("Memcached 不支持模式删除，请使用 Redis 或 Memory 后端")
-        return 0
-    
-    async def close(self) -> None:
-        """关闭连接。"""
-        if self._client:
-            self._client.close()
-            logger.info("Memcached连接已关闭")
-
+from .memory import MemcachedCache, MemoryCache
+from .redis import RedisCache
 
 __all__ = [
     "MemcachedCache",

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/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 "未初始化"

aury/boot/infrastructure/cache/memory.py

@@ -0,0 +1,306 @@
+"""内存和 Memcached 缓存后端实现。"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import json
+import time
+from datetime import timedelta
+from typing import Any
+
+from aury.boot.common.logging import logger
+
+from .base import ICache
+
+
+class MemoryCache(ICache):
+    """内存缓存实现。"""
+    
+    def __init__(self, max_size: int = 1000):
+        """初始化内存缓存。
+        
+        Args:
+            max_size: 最大缓存项数
+        """
+        self._max_size = max_size
+        self._cache: dict[str, tuple[Any, float | None]] = {}
+        self._lock = asyncio.Lock()
+    
+    async def get(self, key: str, default: Any = None) -> Any:
+        """获取缓存。"""
+        async with self._lock:
+            if key not in self._cache:
+                return default
+            
+            value, expire_at = self._cache[key]
+            
+            # 检查过期
+            if expire_at is not None and asyncio.get_event_loop().time() > expire_at:
+                del self._cache[key]
+                return default
+            
+            return value
+    
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        expire: int | timedelta | None = None,
+    ) -> bool:
+        """设置缓存。"""
+        async with self._lock:
+            # 转换过期时间
+            expire_at = None
+            if expire:
+                if isinstance(expire, timedelta):
+                    expire_seconds = expire.total_seconds()
+                else:
+                    expire_seconds = expire
+                expire_at = asyncio.get_event_loop().time() + expire_seconds
+            
+            # 如果超出容量，删除最旧的
+            if len(self._cache) >= self._max_size and key not in self._cache:
+                # 简单策略：删除第一个
+                first_key = next(iter(self._cache))
+                del self._cache[first_key]
+            
+            self._cache[key] = (value, expire_at)
+            return True
+    
+    async def delete(self, *keys: str) -> int:
+        """删除缓存。"""
+        async with self._lock:
+            count = 0
+            for key in keys:
+                if key in self._cache:
+                    del self._cache[key]
+                    count += 1
+            return count
+    
+    async def exists(self, *keys: str) -> int:
+        """检查缓存是否存在。"""
+        async with self._lock:
+            count = 0
+            for key in keys:
+                if key in self._cache:
+                    _value, expire_at = self._cache[key]
+                    # 检查是否过期
+                    if expire_at is None or asyncio.get_event_loop().time() <= expire_at:
+                        count += 1
+            return count
+    
+    async def clear(self) -> None:
+        """清空所有缓存。"""
+        async with self._lock:
+            self._cache.clear()
+            logger.info("内存缓存已清空")
+    
+    async def delete_pattern(self, pattern: str) -> int:
+        """按模式删除缓存。
+        
+        Args:
+            pattern: 通配符模式，支持 * 和 ?
+            
+        Returns:
+            int: 删除的键数量
+        """
+        async with self._lock:
+            keys_to_delete = [
+                key for key in self._cache
+                if fnmatch.fnmatch(key, pattern)
+            ]
+            for key in keys_to_delete:
+                del self._cache[key]
+            logger.debug(f"按模式删除缓存: {pattern}, 删除 {len(keys_to_delete)} 个键")
+            return len(keys_to_delete)
+    
+    async def close(self) -> None:
+        """关闭连接（内存缓存无需关闭）。"""
+        await self.clear()
+    
+    async def size(self) -> int:
+        """获取缓存大小。"""
+        return len(self._cache)
+    
+    # ==================== 内存锁 ====================
+    
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取内存锁（单进程）。"""
+        start_time = time.monotonic()
+        
+        while True:
+            async with self._lock:
+                # 检查锁是否存在
+                if key not in self._cache:
+                    # 设置锁
+                    expire_at = asyncio.get_event_loop().time() + timeout
+                    self._cache[key] = (token, expire_at)
+                    return True
+                
+                # 检查锁是否过期
+                existing_token, expire_at = self._cache[key]
+                if expire_at is not None and asyncio.get_event_loop().time() > expire_at:
+                    # 锁已过期，重新获取
+                    new_expire_at = asyncio.get_event_loop().time() + timeout
+                    self._cache[key] = (token, new_expire_at)
+                    return True
+            
+            if not blocking:
+                return False
+            
+            # 检查是否超时
+            if blocking_timeout is not None:
+                elapsed = time.monotonic() - start_time
+                if elapsed >= blocking_timeout:
+                    return False
+            
+            # 短暂等待后重试
+            await asyncio.sleep(0.05)
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放内存锁。"""
+        async with self._lock:
+            if key not in self._cache:
+                return False
+            
+            existing_token, _ = self._cache[key]
+            if existing_token == token:
+                del self._cache[key]
+                return True
+            return False
+
+
+class MemcachedCache(ICache):
+    """Memcached缓存实现（可选）。"""
+    
+    def __init__(self, servers: list[str]):
+        """初始化Memcached缓存。
+        
+        Args:
+            servers: Memcached服务器列表，如 ["*********:11211"]
+        """
+        self._servers = servers
+        self._client = None
+    
+    async def initialize(self) -> None:
+        """初始化连接。"""
+        try:
+            # 需要安装 python-memcached 或 aiomcache
+            try:
+                import aiomcache
+                self._client = aiomcache.Client(
+                    self._servers[0].split(":")[0],
+                    int(self._servers[0].split(":")[1]) if ":" in self._servers[0] else 11211,
+                )
+                logger.info("Memcached缓存初始化成功")
+            except ImportError:
+                logger.error("请安装 aiomcache: pip install aiomcache")
+                raise
+        except Exception as exc:
+            logger.error(f"Memcached连接失败: {exc}")
+            raise
+    
+    async def get(self, key: str, default: Any = None) -> Any:
+        """获取缓存。"""
+        if not self._client:
+            return default
+        
+        try:
+            data = await self._client.get(key.encode())
+            if data is None:
+                return default
+            return json.loads(data.decode())
+        except Exception as exc:
+            logger.error(f"Memcached获取失败: {key}, {exc}")
+            return default
+    
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        expire: int | timedelta | None = None,
+    ) -> bool:
+        """设置缓存。"""
+        if not self._client:
+            return False
+        
+        try:
+            if isinstance(expire, timedelta):
+                expire = int(expire.total_seconds())
+            
+            data = json.dumps(value).encode()
+            return await self._client.set(key.encode(), data, exptime=expire or 0)
+        except Exception as exc:
+            logger.error(f"Memcached设置失败: {key}, {exc}")
+            return False
+    
+    async def delete(self, *keys: str) -> int:
+        """删除缓存。"""
+        if not self._client or not keys:
+            return 0
+        
+        count = 0
+        for key in keys:
+            try:
+                if await self._client.delete(key.encode()):
+                    count += 1
+            except Exception as exc:
+                logger.error(f"Memcached删除失败: {key}, {exc}")
+        return count
+    
+    async def exists(self, *keys: str) -> int:
+        """检查缓存是否存在。"""
+        if not self._client or not keys:
+            return 0
+        
+        count = 0
+        for key in keys:
+            try:
+                if await self._client.get(key.encode()) is not None:
+                    count += 1
+            except Exception:
+                pass
+        return count
+    
+    async def clear(self) -> None:
+        """清空所有缓存（Memcached不支持）。"""
+        logger.warning("Memcached不支持清空所有缓存")
+    
+    async def delete_pattern(self, pattern: str) -> int:
+        """按模式删除缓存（Memcached 不支持）。"""
+        logger.warning("Memcached 不支持模式删除，请使用 Redis 或 Memory 后端")
+        return 0
+    
+    async def close(self) -> None:
+        """关闭连接。"""
+        if self._client:
+            self._client.close()
+            logger.info("Memcached连接已关闭")
+    
+    # Memcached 不支持分布式锁
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取锁（Memcached 不支持）。"""
+        logger.warning("Memcached 不支持分布式锁，请使用 Redis 或 Memory 后端")
+        return False
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放锁（Memcached 不支持）。"""
+        return False
+
+
+__all__ = ["MemcachedCache", "MemoryCache"]

aury/boot/infrastructure/cache/redis.py

@@ -0,0 +1,259 @@
+"""Redis 缓存后端实现。"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import pickle
+import time
+from collections.abc import Callable
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from redis.asyncio import Redis
+
+from aury.boot.common.logging import logger
+
+from .base import ICache
+
+if TYPE_CHECKING:
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class RedisCache(ICache):
+    """Redis缓存实现。
+    
+    支持两种初始化方式：
+    1. 传入 URL 自行创建连接
+    2. 传入 RedisClient 实例（推荐）
+    """
+    
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        redis_client: RedisClient | None = None,
+        serializer: str = "json",
+    ):
+        """初始化Redis缓存。
+        
+        Args:
+            url: Redis连接URL
+            redis_client: RedisClient 实例（推荐）
+            serializer: 序列化方式（json/pickle）
+        """
+        self._url = url
+        self._redis_client = redis_client
+        self._serializer = serializer
+        self._redis: Redis | None = None
+        self._owns_connection = False  # 是否自己拥有连接（需要自己关闭）
+    
+    async def initialize(self) -> None:
+        """初始化连接。"""
+        # 优先使用 RedisClient
+        if self._redis_client is not None:
+            self._redis = self._redis_client.connection
+            self._owns_connection = False
+            logger.info("Redis缓存初始化成功（使用 RedisClient）")
+            return
+        
+        # 使用 URL 创建连接
+        if self._url:
+            try:
+                self._redis = Redis.from_url(
+                    self._url,
+                    encoding="utf-8",
+                    decode_responses=False,
+                    socket_connect_timeout=5,
+                    socket_timeout=5,
+                )
+                await self._redis.ping()
+                self._owns_connection = True
+                logger.info("Redis缓存初始化成功")
+            except Exception as exc:
+                logger.error(f"Redis连接失败: {exc}")
+                raise
+        else:
+            raise ValueError("Redis缓存需要提供 url 或 redis_client 参数")
+    
+    async def get(self, key: str, default: Any = None) -> Any:
+        """获取缓存。"""
+        if not self._redis:
+            return default
+        
+        try:
+            data = await self._redis.get(key)
+            if data is None:
+                return default
+            
+            # 使用函数式编程处理序列化器
+            deserializers: dict[str, Callable[[bytes], Any]] = {
+                "json": lambda d: json.loads(d.decode()),
+                "pickle": pickle.loads,
+            }
+            
+            deserializer = deserializers.get(self._serializer)
+            if deserializer:
+                return deserializer(data)
+            return data.decode()
+        except Exception as exc:
+            logger.error(f"Redis获取失败: {key}, {exc}")
+            return default
+    
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        expire: int | timedelta | None = None,
+    ) -> bool:
+        """设置缓存。"""
+        if not self._redis:
+            return False
+        
+        try:
+            # 使用函数式编程处理序列化器
+            serializers: dict[str, Callable[[Any], bytes]] = {
+                "json": lambda v: json.dumps(v).encode(),
+                "pickle": pickle.dumps,
+            }
+            
+            serializer = serializers.get(self._serializer)
+            if serializer:
+                data = serializer(value)
+            else:
+                data = str(value).encode()
+            
+            # 转换过期时间
+            if isinstance(expire, timedelta):
+                expire = int(expire.total_seconds())
+            
+            await self._redis.set(key, data, ex=expire)
+            return True
+        except Exception as exc:
+            logger.error(f"Redis设置失败: {key}, {exc}")
+            return False
+    
+    async def delete(self, *keys: str) -> int:
+        """删除缓存。"""
+        if not self._redis or not keys:
+            return 0
+        
+        try:
+            return await self._redis.delete(*keys)
+        except Exception as exc:
+            logger.error(f"Redis删除失败: {keys}, {exc}")
+            return 0
+    
+    async def exists(self, *keys: str) -> int:
+        """检查缓存是否存在。"""
+        if not self._redis or not keys:
+            return 0
+        
+        try:
+            return await self._redis.exists(*keys)
+        except Exception as exc:
+            logger.error(f"Redis检查失败: {keys}, {exc}")
+            return 0
+    
+    async def clear(self) -> None:
+        """清空所有缓存。"""
+        if self._redis:
+            await self._redis.flushdb()
+            logger.info("Redis缓存已清空")
+    
+    async def delete_pattern(self, pattern: str) -> int:
+        """按模式删除缓存。
+        
+        Args:
+            pattern: 通配符模式，如 "todo:*"
+            
+        Returns:
+            int: 删除的键数量
+        """
+        if not self._redis:
+            return 0
+        
+        try:
+            # 使用 SCAN 遍历匹配的键（比 KEYS 更安全，不会阻塞）
+            count = 0
+            cursor = 0
+            while True:
+                cursor, keys = await self._redis.scan(cursor, match=pattern, count=100)
+                if keys:
+                    count += await self._redis.delete(*keys)
+                if cursor == 0:
+                    break
+            logger.debug(f"按模式删除缓存: {pattern}, 删除 {count} 个键")
+            return count
+        except Exception as exc:
+            logger.error(f"Redis模式删除失败: {pattern}, {exc}")
+            return 0
+    
+    async def close(self) -> None:
+        """关闭连接（仅当自己拥有连接时）。"""
+        if self._redis and self._owns_connection:
+            await self._redis.close()
+            logger.info("Redis连接已关闭")
+        self._redis = None
+    
+    @property
+    def redis(self) -> Redis | None:
+        """获取Redis客户端。"""
+        return self._redis
+    
+    # ==================== 分布式锁 ====================
+    # TODO: 后续优化考虑：
+    #   - 看门狗（Watchdog）机制：自动续期，防止业务执行超过锁超时导致提前释放
+    #   - 可重入锁（Reentrant Lock）
+    #   - Redlock 算法（多 Redis 实例）
+    
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取 Redis 分布式锁。"""
+        if not self._redis:
+            return False
+        
+        start_time = time.monotonic()
+        
+        while True:
+            # SET NX EX 原子操作
+            acquired = await self._redis.set(key, token, nx=True, ex=timeout)
+            if acquired:
+                return True
+            
+            if not blocking:
+                return False
+            
+            # 检查是否超时
+            if blocking_timeout is not None:
+                elapsed = time.monotonic() - start_time
+                if elapsed >= blocking_timeout:
+                    return False
+            
+            # 短暂等待后重试
+            await asyncio.sleep(0.05)
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放 Redis 锁（Lua 脚本保证原子性）。"""
+        if not self._redis:
+            return False
+        
+        # Lua 脚本：只有 token 匹配才删除
+        script = """
+        if redis.call("get", KEYS[1]) == ARGV[1] then
+            return redis.call("del", KEYS[1])
+        else
+            return 0
+        end
+        """
+        result = await self._redis.eval(script, 1, key, token)
+        return bool(result)
+
+
+__all__ = ["RedisCache"]

aury/boot/infrastructure/mq/backends/redis.py

@@ -159,7 +159,7 @@ class RedisMQ(IMQ):
         """关闭连接。"""
         self._consuming = False
         if self._owns_client and self._client:
-            await self._client.close()
+            await self._client.cleanup()
             self._client = None
         logger.debug("Redis 消息队列已关闭")
 

aury/boot/infrastructure/mq/backends/redis_stream.py

@@ -65,6 +65,10 @@ class RedisStreamMQ(IMQ):
         self._max_len = max_len
         self._consuming = False
         self._owns_client = False
+        self._log_sample_counter = 0  # 日志采样计数器
+    
+    # 日志采样率：每 N 个 send 打印 1 次
+    LOG_SAMPLE_RATE = 100
     
     async def _ensure_client(self) -> None:
         """确保 Redis 客户端已初始化。"""
@@ -122,7 +126,10 @@ class RedisStreamMQ(IMQ):
         else:
             msg_id = await self._client.connection.xadd(stream_key, data)
         
-        logger.debug(f"发送消息到 Stream: {stream_key}, id={msg_id}")
+        # 采样日志：每 N 个消息打印 1 次
+        self._log_sample_counter += 1
+        if self._log_sample_counter % self.LOG_SAMPLE_RATE == 1:
+            logger.debug(f"发送消息到 Stream: {stream_key}, id={msg_id}, count={self._log_sample_counter}")
         return message.id
 
     async def receive(
@@ -420,7 +427,7 @@ class RedisStreamMQ(IMQ):
         """关闭连接。"""
         self._consuming = False
         if self._owns_client and self._client:
-            await self._client.close()
+            await self._client.cleanup()
             self._client = None
         logger.debug("Redis Stream 消息队列已关闭")
 

{aury_boot-0.0.37.dist-info → aury_boot-0.0.39.dist-info}/METADATA

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

{aury_boot-0.0.37.dist-info → aury_boot-0.0.39.dist-info}/RECORD

@@ -1,5 +1,5 @@
 aury/boot/__init__.py,sha256=pCno-EInnpIBa1OtxNYF-JWf9j95Cd2h6vmu0xqa_-4,1791
-aury/boot/_version.py,sha256=BV1Ma7idHU0hCvzfaqU-vGA4N-4x9mQtKafasKpzadA,706
+aury/boot/_version.py,sha256=4ZEdlNp6MHArYK_GfVRp7IC9mBDzzgBih3DH2hlHeCo,706
 aury/boot/application/__init__.py,sha256=I2KqNVdYg2q5nlOXr0TtFGyHmhj4oWdaR6ZB73Mwg7Y,3041
 aury/boot/application/adapter/__init__.py,sha256=e1bcSb1bxUMfofTwiCuHBZJk5-STkMCWPF2EJXHQ7UU,3976
 aury/boot/application/adapter/base.py,sha256=Ar_66fiHPDEmV-1DKnqXKwc53p3pozG31bgTJTEUriY,15763
@@ -32,7 +32,7 @@ aury/boot/application/middleware/__init__.py,sha256=T01fmbcdO0Sm6JE74g23uuDyebBG
 aury/boot/application/middleware/logging.py,sha256=kStfLskA_srNvWIuNMs0ptZ4Wr9-ke6hYl8kESxbhxc,13509
 aury/boot/application/migrations/__init__.py,sha256=Z5Gizx7f3AImRcl3cooiIDAZcNi5W-6GvB7mK5w1TNA,204
 aury/boot/application/migrations/manager.py,sha256=G7mzkNA3MFjyQmM2UwY0ZFNgGGVS4W5GoG2Sbj5AUXk,23685
-aury/boot/application/migrations/setup.py,sha256=cxzBIHGzRXhlIYs4_ZW6P85Z9A7uVnTq_dmQFKp3ha4,6485
+aury/boot/application/migrations/setup.py,sha256=mA7q8JEkVVDW55PdSE6KUhhmDNMMWmbQxqfwOts4vIw,6889
 aury/boot/application/rpc/__init__.py,sha256=0mVyksLbTOLYMN4OtYrdf9naBNVQnAU9pt2kS2w_9ZY,2064
 aury/boot/application/rpc/base.py,sha256=KqdWupF2PTizr--jE0KgJUDCfBap72ZWk9FtU5FM9_8,2618
 aury/boot/application/rpc/client.py,sha256=ApW4h_DrwnnkAh921TVUd4fvdWP-rVIse3VW1_1TLPk,9113
@@ -136,11 +136,13 @@ aury/boot/domain/service/base.py,sha256=6sN0nf8r5yUZsE6AcZOiOXFCqzb61oCxTfrWlqjI
 aury/boot/domain/transaction/__init__.py,sha256=EKnjJ235SYjMCvGIuLVlTdYRzU35RxNMejRGUExYqqE,15488
 aury/boot/infrastructure/__init__.py,sha256=DDEr_BIL5OyMJjNlI05jGIUrSHn6MPdnW9xnCS4eHfg,2949
 aury/boot/infrastructure/cache/__init__.py,sha256=G40uCkpJ1jSs2fc_CBDem73iQQzCcp-4GG1WpDJzwaA,658
-aury/boot/infrastructure/cache/backends.py,sha256=9QMQ8G9DtZgzVXZ_Ng7n1gXRu-_OQZgw4FHPOfr1qco,13585
-aury/boot/infrastructure/cache/base.py,sha256=Yn-h_SGcOoGGZW1unOnz_zgcuHaMKOEmwiUP0P7_pIM,1624
+aury/boot/infrastructure/cache/backends.py,sha256=wh9U2LjlXV22dpV87ID8DL9Rmgztw3yMUrDjJdGgTQw,245
+aury/boot/infrastructure/cache/base.py,sha256=3XA6v_zwsgMSUDN8aG7eu_2-zCnGWF9eeEyVZxxezBU,2621
 aury/boot/infrastructure/cache/exceptions.py,sha256=KZsFIHXW3_kOh_KB93EVZJKbiDvDw8aloAefJ3kasP8,622
 aury/boot/infrastructure/cache/factory.py,sha256=aF74JoiiSKFgctqqh2Z8OtGRS2Am_ou-I40GyygLzC0,2489
-aury/boot/infrastructure/cache/manager.py,sha256=GGoOgYyIdWKMmhej5cRvEfpNeMN1GaSaU9hc0dy8_sA,12106
+aury/boot/infrastructure/cache/manager.py,sha256=2jlshbO4NqpPxH-8DBiMFNAvWuZUI3atUCsw9GGlzc8,16807
+aury/boot/infrastructure/cache/memory.py,sha256=qGhLKKjGsEUHjVRFMV6A33MB_1iPaKCEEkT6VFrLkQY,9832
+aury/boot/infrastructure/cache/redis.py,sha256=MxLwqnBrPWmkS_AGDq4hKfPlBrF358cq_nKbUlP-JYE,8085
 aury/boot/infrastructure/channel/__init__.py,sha256=NmjddenZPz1Dcl0glwIF1Xn9gxBzvGvlOlzhV3eEnEQ,664
 aury/boot/infrastructure/channel/base.py,sha256=TDiP7pXyd2ixiOM3cbxqCSOluGLTkmLCa8pv-KyQ0jo,2941
 aury/boot/infrastructure/channel/manager.py,sha256=GT6eG6PglduKAr23i1PSmjjTQsALvGGoLjYiQ33aZiw,7488
@@ -190,8 +192,8 @@ aury/boot/infrastructure/mq/base.py,sha256=ld4wtzhO_6y8wJRXL1DagqJiwhd0VQ6MJlJGD
 aury/boot/infrastructure/mq/manager.py,sha256=Bu4E1Tgz0CzFvJuCS9_fBMj9eAqmXcZp8aFIYhvNUl4,7692
 aury/boot/infrastructure/mq/backends/__init__.py,sha256=10nggw2V-AzuZ1vvzq_ksoXR4FI3e4BR36EfY49Pek4,200
 aury/boot/infrastructure/mq/backends/rabbitmq.py,sha256=0NWgPKEwtbmI63EVvKINdfXXDNyOvuOOP9LlBzqH91E,5493
-aury/boot/infrastructure/mq/backends/redis.py,sha256=i8KECToIFEZ6CnHyNCk34_xdff5ioK172_knOy6EeUU,5279
-aury/boot/infrastructure/mq/backends/redis_stream.py,sha256=hbSX03d0BLshE10GryjyvqybtjDBOS4pQUsNHhQFB-Q,14420
+aury/boot/infrastructure/mq/backends/redis.py,sha256=B89U7mqIceUsCXE4G3u1u6aFM9hv4mmLLwuCYq1T9tQ,5281
+aury/boot/infrastructure/mq/backends/redis_stream.py,sha256=p2WTj10-zbxQ_2NPU97w-n4DZ8KSHhLjqcnplLPCw4U,14761
 aury/boot/infrastructure/scheduler/__init__.py,sha256=eTRJ5dSPcKvyFvLVtraoQteXTTDDGwIrmw06J2hoNdA,323
 aury/boot/infrastructure/scheduler/exceptions.py,sha256=ROltrhSctVWA-6ulnjuYeHAk3ZF-sykDoesuierYzew,634
 aury/boot/infrastructure/scheduler/manager.py,sha256=OHQOHQlcoN8yFnky4kfuhsEIk39qX6nLZ7xJ51tfg68,23130
@@ -210,7 +212,7 @@ aury/boot/testing/client.py,sha256=KOg1EemuIVsBG68G5y0DjSxZGcIQVdWQ4ASaHE3o1R0,4
 aury/boot/testing/factory.py,sha256=8GvwX9qIDu0L65gzJMlrWB0xbmJ-7zPHuwk3eECULcg,5185
 aury/boot/toolkit/__init__.py,sha256=AcyVb9fDf3CaEmJPNkWC4iGv32qCPyk4BuFKSuNiJRQ,334
 aury/boot/toolkit/http/__init__.py,sha256=zIPmpIZ9Qbqe25VmEr7jixoY2fkRbLm7NkCB9vKpg6I,11039
-aury_boot-0.0.37.dist-info/METADATA,sha256=8Kgz7a5fhou-Ki53QzjfwAfv68cE8iu83UWQ8aR6BOI,8694
-aury_boot-0.0.37.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-aury_boot-0.0.37.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
-aury_boot-0.0.37.dist-info/RECORD,,
+aury_boot-0.0.39.dist-info/METADATA,sha256=qX6IZza7loT9gQzeJlbhPz1QKshBy3fZH__Fic8U1s0,8694
+aury_boot-0.0.39.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aury_boot-0.0.39.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
+aury_boot-0.0.39.dist-info/RECORD,,