# fn_cache: 轻量级函数缓存工具
`fn_cache` 是一个专为现代 Python 应用设计的轻量级缓存库，提供统一的接口、多种缓存策略和存储后端。无论您需要简单的内存缓存还是分布式 Redis 缓存，`fn_cache` 都能轻松应对。
## ✨ 核心特性
- **多种缓存策略**: 支持 TTL (Time-To-Live) 和 LRU (Least Recently Used) 缓存淘汰策略. 支持异步函数的 LRU 缓存（async lru_cache），让异步场景下也能高效利用 LRU 策略
- **灵活的存储后端**: 内置内存和 Redis 两种存储后端，可根据需求轻松切换
- **多种序列化格式**: 支持 JSON、Pickle、MessagePack 和字符串序列化
- **版本控制机制**: 通过全局版本号实现一键失效所有缓存，便于调试和管理
- **用户级别版本控制**: 支持按用户失效缓存，适用于多用户应用场景
- **缓存键枚举**: 支持定义结构化的缓存键模板，提高代码可维护性
- **动态过期时间**: 支持根据缓存值动态计算过期时间
- **强大的装饰器**: 提供 `cached` 装饰器，支持丰富的配置，并与同步/异步函数无缝集成
- **缓存预加载**: 支持在服务启动时预先加载数据到内存缓存，提升应用初始性能
- **缓存统计**: 提供详细的缓存性能监控，包括命中率、响应时间等指标
- **内存监控**: 支持内存占用监控和定期报告
- **健壮的错误处理**: 内置 Redis 超时和连接错误处理，确保缓存问题不影响核心业务逻辑
## 🚀 快速上手
### 1. 基本用法: `cached` 装饰器
使用 `cached` 装饰器，可以轻松为函数添加缓存功能。
```python
from fn_cache import cached, SerializerType
# 使用内存TTL缓存 (默认)
@cached(ttl_seconds=60)
def get_some_data(user_id: int):
print("正在执行复杂的数据查询...")
return f"这是用户 {user_id} 的数据"
# 使用不同序列化器
@cached(
storage_type='memory',
serializer_type=SerializerType.JSON,
ttl_seconds=300
)
def get_user_profile(user_id: int):
return {"user_id": user_id, "name": f"用户_{user_id}"}
# 第一次调用，函数会执行
get_some_data(123) # 输出: "正在执行复杂的数据查询..."
# 第二次调用，直接从缓存返回
get_some_data(123) # 无输出
```
### 2. 异步函数支持
```python
@cached(ttl_seconds=300)
async def fetch_user_data(user_id: int):
print(f"正在从数据库获取用户 {user_id} 的数据...")
await asyncio.sleep(1) # 模拟数据库查询延迟
return {
"user_id": user_id,
"name": f"User_{user_id}",
"email": f"user{user_id}@example.com"
}
```
### 3. 缓存预加载
对于需要快速响应的内存缓存数据，可以使用预加载功能，在服务启动时就将热点数据加载到缓存中。
```python
from fn_cache import cached, preload_all_caches
import asyncio
# 1. 定义一个数据提供者函数
def user_ids_provider():
# 这些ID可以是来自配置、数据库或其他来源
for user_id in [1, 2, 3]:
yield (user_id,), {} # (args, kwargs)
# 2. 在装饰器中指定 preload_provider
@cached(storage_type='memory', preload_provider=user_ids_provider)
def get_user_name(user_id: int):
print(f"从数据库查询用户 {user_id}...")
return f"用户_{user_id}"
# 3. 在应用启动时，调用预加载函数
async def main():
await preload_all_caches()
# 此时，数据已在缓存中，函数不会再次执行
print(get_user_name(1)) # 直接输出 "用户_1"
print(get_user_name(2)) # 直接输出 "用户_2"
if __name__ == "__main__":
asyncio.run(main())
```
### 4. 缓存统计和监控
```python
from fn_cache import get_cache_statistics, start_cache_memory_monitoring
# 启动内存监控
start_cache_memory_monitoring(interval_seconds=300) # 每5分钟监控一次
# 获取缓存统计信息
stats = get_cache_statistics()
for cache_id, cache_stats in stats.items():
print(f"缓存 {cache_id}:")
print(f" 命中率: {cache_stats['hit_rate']:.2%}")
print(f" 平均响应时间: {cache_stats['avg_response_time']:.4f}s")
```
## 📚 API 参考
### `cached` 装饰器类
这是 `fn_cache` 的核心装饰器。
**参数**:
- `cache_type` (`CacheType`): 缓存类型，`CacheType.TTL` (默认) 或 `CacheType.LRU`
- `storage_type` (`StorageType`): 存储类型，`StorageType.MEMORY` (默认) 或 `StorageType.REDIS`
- `serializer_type` (`SerializerType`): 序列化类型，`SerializerType.JSON` (默认)、`SerializerType.PICKLE`、`SerializerType.MESSAGEPACK` 或 `SerializerType.STRING`
- `ttl_seconds` (`int`): TTL 缓存的过期时间（秒），默认为 600
- `max_size` (`int`): LRU 缓存的最大容量，默认为 1000
- `key_func` (`Callable`): 自定义缓存键生成函数。接收与被装饰函数相同的参数
- `key_params` (`list[str]`): 用于自动生成缓存键的参数名列表
- `prefix` (`str`): 缓存键的前缀，默认为 `"fn_cache:"`
- `preload_provider` (`Callable`): 一个函数，返回一个可迭代对象，用于缓存预加载。迭代的每个元素都是一个 `(args, kwargs)` 元组
### `CacheKeyEnum` 基类
缓存键枚举基类，用于定义结构化的缓存键模板。
```python
class CacheKeyEnum(str, Enum):
"""缓存键枚举基类"""
def format(self, **kwargs) -> str:
"""格式化缓存键，替换模板中的参数"""
return self.value.format(**kwargs)
```
### `UniversalCacheManager` 类
提供了所有底层缓存操作的接口。
**核心方法**:
- `get(key, user_id=None)`: (异步) 获取缓存
- `set(key, value, ttl_seconds=None, user_id=None)`: (异步) 设置缓存
- `delete(key)`: (异步) 删除缓存
- `get_sync(key, user_id=None)` / `set_sync(...)` / `delete_sync(key)`: 内存缓存的同步版本
- `increment_global_version()`: (异步) 递增全局版本号，使所有缓存失效
- `increment_user_version(user_id)`: (异步) 递增用户版本号，使该用户的所有缓存失效
- `invalidate_all()`: (异步) 使所有缓存失效
- `invalidate_user_cache(user_id)`: (异步) 使用户的所有缓存失效
**核心属性**:
- `is_global_cache_enabled_sync` (`bool`): (同步) 检查内存缓存是否已启用
### 全局控制函数
- `preload_all_caches()`: (异步) 执行所有已注册的缓存预加载任务
- `invalidate_all_caches()`: (异步) 失效所有使用默认管理器的缓存
- `invalidate_user_cache(user_id)`: (异步) 使用户的所有缓存失效
- `get_cache_statistics(cache_id=None)`: 获取缓存统计信息
- `reset_cache_statistics(cache_id=None)`: 重置缓存统计信息
- `start_cache_memory_monitoring(interval_seconds=300)`: 启动内存监控
- `get_cache_memory_usage()`: 获取内存使用情况
## ⚙️ 高级用法
### 切换到 Redis 存储
只需更改 `storage_type` 参数即可。
```python
@cached(
storage_type=StorageType.REDIS,
serializer_type=SerializerType.MESSAGEPACK,
ttl_seconds=3600
)
async def get_shared_data():
# ... 从数据库或RPC获取数据 ...
return {"data": "some shared data"}
```
### 使用 LRU 缓存策略
```python
@cached(
cache_type=CacheType.LRU,
max_size=100,
storage_type=StorageType.MEMORY
)
def calculate_fibonacci(n: int) -> int:
"""计算斐波那契数列（同步函数示例）"""
if n <= 1:
return n
return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)
```
### 自定义缓存键
对于复杂的参数，可以提供自定义的 `key_func`。
```python
def make_user_key(user: User):
return f"user_cache:{user.org_id}:{user.id}"
@cached(key_func=make_user_key)
def get_user_permissions(user: User):
# ...
return ["perm1", "perm2"]
```
或者，使用 `key_params` 自动生成。
```python
@cached(key_params=['user_id', 'tenant_id'])
def get_document(doc_id: int, user_id: int, tenant_id: str):
# 自动生成的key类似于: "app.module.get_document:user_id=123:tenant_id=abc"
pass
```
### 用户级别缓存管理
```python
from fn_cache import UniversalCacheManager, CacheConfig, StorageType
class UserCacheService:
def __init__(self):
config = CacheConfig(
storage_type=StorageType.REDIS,
serializer_type=SerializerType.JSON,
prefix="user_cache:"
)
self.cache = UniversalCacheManager(config)
async def get_user_data(self, user_id: int):
cache_key = f"user_data:{user_id}"
# 使用用户级别版本控制
cached_data = await self.cache.get(cache_key, user_id=str(user_id))
if cached_data:
return cached_data
# 缓存未命中，获取数据
user_data = await self._fetch_user_data(user_id)
# 存储到缓存，使用用户级别版本控制
await self.cache.set(cache_key, user_data, user_id=str(user_id))
return user_data
async def invalidate_user_cache(self, user_id: int):
"""使用户的所有缓存失效"""
await self.cache.invalidate_user_cache(str(user_id))
```
### 动态过期时间
```python
@cached(
ttl_seconds=300
)
async def get_user_vip_info(user_id: int):
# VIP用户缓存1小时，普通用户缓存30分钟
pass
```
### 多参数缓存键
```python
@cached(
ttl_seconds=300
)
async def get_user_profile(user_id: int, tenant_id: str):
# 支持多租户的用户资料缓存
pass
```
## 🔧 配置选项
### CacheConfig 配置类
```python
from fn_cache import CacheConfig, CacheType, StorageType, SerializerType
config = CacheConfig(
cache_type=CacheType.TTL, # 缓存策略: TTL 或 LRU
storage_type=StorageType.MEMORY, # 存储后端: MEMORY 或 REDIS
serializer_type=SerializerType.JSON, # 序列化类型: JSON, PICKLE, MESSAGEPACK, STRING
ttl_seconds=600, # TTL 过期时间（秒）
max_size=1000, # LRU 最大容量
prefix="cache:", # 缓存键前缀
global_version_key="fn_cache:global:version", # 全局版本号键
user_version_key="fn_cache:user:version:{user_id}", # 用户版本号键
make_expire_sec_func=None, # 动态过期时间函数
serializer_kwargs={}, # 序列化器参数
enable_statistics=True, # 是否启用统计
enable_memory_monitoring=True, # 是否启用内存监控
redis_config={ # Redis连接配置
"host": "localhost",
"port": 6379,
"db": 0,
"decode_responses": True,
"socket_timeout": 1.0,
"socket_connect_timeout": 1.0,
"retry_on_timeout": True,
"health_check_interval": 30,
}
)
```
## 💡 设计理念
- **统一接口**: `UniversalCacheManager` 提供了统一的接口，屏蔽了不同存储后端的实现细节
- **版本控制**: 通过全局版本号机制实现一键失效所有缓存，便于调试和管理
- **用户级别控制**: 支持按用户失效缓存，适用于多用户应用场景
- **结构化缓存键**: 通过枚举定义缓存键模板，提高代码可维护性和一致性
- **装饰器模式**: `cached` 使用装饰器模式，以非侵入的方式为函数添加缓存逻辑
- **错误隔离**: 内置 Redis 超时和连接错误处理，确保缓存问题不影响核心业务逻辑
- **性能优化**: 支持缓存预加载和动态过期时间，提升应用性能
- **监控统计**: 提供详细的缓存性能监控，帮助优化缓存策略
## 📝 使用示例
更多详细的使用示例，请参考 `examples_v2.py` 文件，其中包含了：
- 不同序列化器的使用
- 缓存统计和性能监控
- 内存监控功能
- 批量操作和缓存预热
- 用户级别版本控制
- 直接使用缓存管理器
## 🔄 v2.0 新特性
相比 v1.0，v2.0 版本新增了以下特性：
1. **多种序列化格式支持**: 支持 JSON、Pickle、MessagePack 和字符串序列化
2. **缓存统计功能**: 提供详细的缓存性能监控，包括命中率、响应时间等指标
3. **更灵活的配置**: 支持序列化器参数、Redis 连接配置等
4. **更好的错误处理**: 改进的异常处理和日志记录
5. **性能优化**: 更高效的序列化和反序列化
6. **监控增强**: 更详细的内存使用监控和统计报告
## 📦 安装
```bash
pip install fn_cache
```
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 🪪 许可证
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/leowzz/fn_cache",
"name": "fn-cache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "LeoWang <leolswq@163.com>",
"keywords": "cache, memory, ttl, lru, async, decorator",
"author": "LeoWang",
"author_email": "LeoWang <leolswq@163.com>",
"download_url": "https://files.pythonhosted.org/packages/51/1f/edf8b359234d2352417a28d6b2571220a7ee320b81de2fbf243c541d9a0c/fn_cache-0.1.6.tar.gz",
"platform": null,
"description": "# fn_cache: \u8f7b\u91cf\u7ea7\u51fd\u6570\u7f13\u5b58\u5de5\u5177\n\n`fn_cache` \u662f\u4e00\u4e2a\u4e13\u4e3a\u73b0\u4ee3 Python \u5e94\u7528\u8bbe\u8ba1\u7684\u8f7b\u91cf\u7ea7\u7f13\u5b58\u5e93\uff0c\u63d0\u4f9b\u7edf\u4e00\u7684\u63a5\u53e3\u3001\u591a\u79cd\u7f13\u5b58\u7b56\u7565\u548c\u5b58\u50a8\u540e\u7aef\u3002\u65e0\u8bba\u60a8\u9700\u8981\u7b80\u5355\u7684\u5185\u5b58\u7f13\u5b58\u8fd8\u662f\u5206\u5e03\u5f0f Redis \u7f13\u5b58\uff0c`fn_cache` \u90fd\u80fd\u8f7b\u677e\u5e94\u5bf9\u3002\n\n## \u2728 \u6838\u5fc3\u7279\u6027\n\n- **\u591a\u79cd\u7f13\u5b58\u7b56\u7565**: \u652f\u6301 TTL (Time-To-Live) \u548c LRU (Least Recently Used) \u7f13\u5b58\u6dd8\u6c70\u7b56\u7565. \u652f\u6301\u5f02\u6b65\u51fd\u6570\u7684 LRU \u7f13\u5b58\uff08async lru_cache\uff09\uff0c\u8ba9\u5f02\u6b65\u573a\u666f\u4e0b\u4e5f\u80fd\u9ad8\u6548\u5229\u7528 LRU \u7b56\u7565\n- **\u7075\u6d3b\u7684\u5b58\u50a8\u540e\u7aef**: \u5185\u7f6e\u5185\u5b58\u548c Redis \u4e24\u79cd\u5b58\u50a8\u540e\u7aef\uff0c\u53ef\u6839\u636e\u9700\u6c42\u8f7b\u677e\u5207\u6362\n- **\u591a\u79cd\u5e8f\u5217\u5316\u683c\u5f0f**: \u652f\u6301 JSON\u3001Pickle\u3001MessagePack \u548c\u5b57\u7b26\u4e32\u5e8f\u5217\u5316\n- **\u7248\u672c\u63a7\u5236\u673a\u5236**: \u901a\u8fc7\u5168\u5c40\u7248\u672c\u53f7\u5b9e\u73b0\u4e00\u952e\u5931\u6548\u6240\u6709\u7f13\u5b58\uff0c\u4fbf\u4e8e\u8c03\u8bd5\u548c\u7ba1\u7406\n- **\u7528\u6237\u7ea7\u522b\u7248\u672c\u63a7\u5236**: \u652f\u6301\u6309\u7528\u6237\u5931\u6548\u7f13\u5b58\uff0c\u9002\u7528\u4e8e\u591a\u7528\u6237\u5e94\u7528\u573a\u666f\n- **\u7f13\u5b58\u952e\u679a\u4e3e**: \u652f\u6301\u5b9a\u4e49\u7ed3\u6784\u5316\u7684\u7f13\u5b58\u952e\u6a21\u677f\uff0c\u63d0\u9ad8\u4ee3\u7801\u53ef\u7ef4\u62a4\u6027\n- **\u52a8\u6001\u8fc7\u671f\u65f6\u95f4**: \u652f\u6301\u6839\u636e\u7f13\u5b58\u503c\u52a8\u6001\u8ba1\u7b97\u8fc7\u671f\u65f6\u95f4\n- **\u5f3a\u5927\u7684\u88c5\u9970\u5668**: \u63d0\u4f9b `cached` \u88c5\u9970\u5668\uff0c\u652f\u6301\u4e30\u5bcc\u7684\u914d\u7f6e\uff0c\u5e76\u4e0e\u540c\u6b65/\u5f02\u6b65\u51fd\u6570\u65e0\u7f1d\u96c6\u6210\n- **\u7f13\u5b58\u9884\u52a0\u8f7d**: \u652f\u6301\u5728\u670d\u52a1\u542f\u52a8\u65f6\u9884\u5148\u52a0\u8f7d\u6570\u636e\u5230\u5185\u5b58\u7f13\u5b58\uff0c\u63d0\u5347\u5e94\u7528\u521d\u59cb\u6027\u80fd\n- **\u7f13\u5b58\u7edf\u8ba1**: \u63d0\u4f9b\u8be6\u7ec6\u7684\u7f13\u5b58\u6027\u80fd\u76d1\u63a7\uff0c\u5305\u62ec\u547d\u4e2d\u7387\u3001\u54cd\u5e94\u65f6\u95f4\u7b49\u6307\u6807\n- **\u5185\u5b58\u76d1\u63a7**: \u652f\u6301\u5185\u5b58\u5360\u7528\u76d1\u63a7\u548c\u5b9a\u671f\u62a5\u544a\n- **\u5065\u58ee\u7684\u9519\u8bef\u5904\u7406**: \u5185\u7f6e Redis \u8d85\u65f6\u548c\u8fde\u63a5\u9519\u8bef\u5904\u7406\uff0c\u786e\u4fdd\u7f13\u5b58\u95ee\u9898\u4e0d\u5f71\u54cd\u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\n\n## \ud83d\ude80 \u5feb\u901f\u4e0a\u624b\n\n### 1. \u57fa\u672c\u7528\u6cd5: `cached` \u88c5\u9970\u5668\n\n\u4f7f\u7528 `cached` \u88c5\u9970\u5668\uff0c\u53ef\u4ee5\u8f7b\u677e\u4e3a\u51fd\u6570\u6dfb\u52a0\u7f13\u5b58\u529f\u80fd\u3002\n\n```python\nfrom fn_cache import cached, SerializerType\n\n\n# \u4f7f\u7528\u5185\u5b58TTL\u7f13\u5b58 (\u9ed8\u8ba4)\n@cached(ttl_seconds=60)\ndef get_some_data(user_id: int):\n print(\"\u6b63\u5728\u6267\u884c\u590d\u6742\u7684\u6570\u636e\u67e5\u8be2...\")\n return f\"\u8fd9\u662f\u7528\u6237 {user_id} \u7684\u6570\u636e\"\n\n\n# \u4f7f\u7528\u4e0d\u540c\u5e8f\u5217\u5316\u5668\n@cached(\n storage_type='memory',\n serializer_type=SerializerType.JSON,\n ttl_seconds=300\n)\ndef get_user_profile(user_id: int):\n return {\"user_id\": user_id, \"name\": f\"\u7528\u6237_{user_id}\"}\n\n\n# \u7b2c\u4e00\u6b21\u8c03\u7528\uff0c\u51fd\u6570\u4f1a\u6267\u884c\nget_some_data(123) # \u8f93\u51fa: \"\u6b63\u5728\u6267\u884c\u590d\u6742\u7684\u6570\u636e\u67e5\u8be2...\"\n\n# \u7b2c\u4e8c\u6b21\u8c03\u7528\uff0c\u76f4\u63a5\u4ece\u7f13\u5b58\u8fd4\u56de\nget_some_data(123) # \u65e0\u8f93\u51fa\n```\n\n### 2. \u5f02\u6b65\u51fd\u6570\u652f\u6301\n\n```python\n@cached(ttl_seconds=300)\nasync def fetch_user_data(user_id: int):\n print(f\"\u6b63\u5728\u4ece\u6570\u636e\u5e93\u83b7\u53d6\u7528\u6237 {user_id} \u7684\u6570\u636e...\")\n await asyncio.sleep(1) # \u6a21\u62df\u6570\u636e\u5e93\u67e5\u8be2\u5ef6\u8fdf\n return {\n \"user_id\": user_id,\n \"name\": f\"User_{user_id}\",\n \"email\": f\"user{user_id}@example.com\"\n }\n```\n\n### 3. \u7f13\u5b58\u9884\u52a0\u8f7d\n\n\u5bf9\u4e8e\u9700\u8981\u5feb\u901f\u54cd\u5e94\u7684\u5185\u5b58\u7f13\u5b58\u6570\u636e\uff0c\u53ef\u4ee5\u4f7f\u7528\u9884\u52a0\u8f7d\u529f\u80fd\uff0c\u5728\u670d\u52a1\u542f\u52a8\u65f6\u5c31\u5c06\u70ed\u70b9\u6570\u636e\u52a0\u8f7d\u5230\u7f13\u5b58\u4e2d\u3002\n\n```python\nfrom fn_cache import cached, preload_all_caches\nimport asyncio\n\n\n# 1. \u5b9a\u4e49\u4e00\u4e2a\u6570\u636e\u63d0\u4f9b\u8005\u51fd\u6570\ndef user_ids_provider():\n # \u8fd9\u4e9bID\u53ef\u4ee5\u662f\u6765\u81ea\u914d\u7f6e\u3001\u6570\u636e\u5e93\u6216\u5176\u4ed6\u6765\u6e90\n for user_id in [1, 2, 3]:\n yield (user_id,), {} # (args, kwargs)\n\n\n# 2. \u5728\u88c5\u9970\u5668\u4e2d\u6307\u5b9a preload_provider\n@cached(storage_type='memory', preload_provider=user_ids_provider)\ndef get_user_name(user_id: int):\n print(f\"\u4ece\u6570\u636e\u5e93\u67e5\u8be2\u7528\u6237 {user_id}...\")\n return f\"\u7528\u6237_{user_id}\"\n\n\n# 3. \u5728\u5e94\u7528\u542f\u52a8\u65f6\uff0c\u8c03\u7528\u9884\u52a0\u8f7d\u51fd\u6570\nasync def main():\n await preload_all_caches()\n\n # \u6b64\u65f6\uff0c\u6570\u636e\u5df2\u5728\u7f13\u5b58\u4e2d\uff0c\u51fd\u6570\u4e0d\u4f1a\u518d\u6b21\u6267\u884c\n print(get_user_name(1)) # \u76f4\u63a5\u8f93\u51fa \"\u7528\u6237_1\"\n print(get_user_name(2)) # \u76f4\u63a5\u8f93\u51fa \"\u7528\u6237_2\"\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 4. \u7f13\u5b58\u7edf\u8ba1\u548c\u76d1\u63a7\n\n```python\nfrom fn_cache import get_cache_statistics, start_cache_memory_monitoring\n\n# \u542f\u52a8\u5185\u5b58\u76d1\u63a7\nstart_cache_memory_monitoring(interval_seconds=300) # \u6bcf5\u5206\u949f\u76d1\u63a7\u4e00\u6b21\n\n# \u83b7\u53d6\u7f13\u5b58\u7edf\u8ba1\u4fe1\u606f\nstats = get_cache_statistics()\nfor cache_id, cache_stats in stats.items():\n print(f\"\u7f13\u5b58 {cache_id}:\")\n print(f\" \u547d\u4e2d\u7387: {cache_stats['hit_rate']:.2%}\")\n print(f\" \u5e73\u5747\u54cd\u5e94\u65f6\u95f4: {cache_stats['avg_response_time']:.4f}s\")\n```\n\n## \ud83d\udcda API \u53c2\u8003\n\n### `cached` \u88c5\u9970\u5668\u7c7b\n\n\u8fd9\u662f `fn_cache` \u7684\u6838\u5fc3\u88c5\u9970\u5668\u3002\n\n**\u53c2\u6570**:\n\n- `cache_type` (`CacheType`): \u7f13\u5b58\u7c7b\u578b\uff0c`CacheType.TTL` (\u9ed8\u8ba4) \u6216 `CacheType.LRU`\n- `storage_type` (`StorageType`): \u5b58\u50a8\u7c7b\u578b\uff0c`StorageType.MEMORY` (\u9ed8\u8ba4) \u6216 `StorageType.REDIS`\n- `serializer_type` (`SerializerType`): \u5e8f\u5217\u5316\u7c7b\u578b\uff0c`SerializerType.JSON` (\u9ed8\u8ba4)\u3001`SerializerType.PICKLE`\u3001`SerializerType.MESSAGEPACK` \u6216 `SerializerType.STRING`\n- `ttl_seconds` (`int`): TTL \u7f13\u5b58\u7684\u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff09\uff0c\u9ed8\u8ba4\u4e3a 600\n- `max_size` (`int`): LRU \u7f13\u5b58\u7684\u6700\u5927\u5bb9\u91cf\uff0c\u9ed8\u8ba4\u4e3a 1000\n- `key_func` (`Callable`): \u81ea\u5b9a\u4e49\u7f13\u5b58\u952e\u751f\u6210\u51fd\u6570\u3002\u63a5\u6536\u4e0e\u88ab\u88c5\u9970\u51fd\u6570\u76f8\u540c\u7684\u53c2\u6570\n- `key_params` (`list[str]`): \u7528\u4e8e\u81ea\u52a8\u751f\u6210\u7f13\u5b58\u952e\u7684\u53c2\u6570\u540d\u5217\u8868\n- `prefix` (`str`): \u7f13\u5b58\u952e\u7684\u524d\u7f00\uff0c\u9ed8\u8ba4\u4e3a `\"fn_cache:\"`\n- `preload_provider` (`Callable`): \u4e00\u4e2a\u51fd\u6570\uff0c\u8fd4\u56de\u4e00\u4e2a\u53ef\u8fed\u4ee3\u5bf9\u8c61\uff0c\u7528\u4e8e\u7f13\u5b58\u9884\u52a0\u8f7d\u3002\u8fed\u4ee3\u7684\u6bcf\u4e2a\u5143\u7d20\u90fd\u662f\u4e00\u4e2a `(args, kwargs)` \u5143\u7ec4\n\n### `CacheKeyEnum` \u57fa\u7c7b\n\n\u7f13\u5b58\u952e\u679a\u4e3e\u57fa\u7c7b\uff0c\u7528\u4e8e\u5b9a\u4e49\u7ed3\u6784\u5316\u7684\u7f13\u5b58\u952e\u6a21\u677f\u3002\n\n```python\nclass CacheKeyEnum(str, Enum):\n \"\"\"\u7f13\u5b58\u952e\u679a\u4e3e\u57fa\u7c7b\"\"\"\n \n def format(self, **kwargs) -> str:\n \"\"\"\u683c\u5f0f\u5316\u7f13\u5b58\u952e\uff0c\u66ff\u6362\u6a21\u677f\u4e2d\u7684\u53c2\u6570\"\"\"\n return self.value.format(**kwargs)\n```\n\n### `UniversalCacheManager` \u7c7b\n\n\u63d0\u4f9b\u4e86\u6240\u6709\u5e95\u5c42\u7f13\u5b58\u64cd\u4f5c\u7684\u63a5\u53e3\u3002\n\n**\u6838\u5fc3\u65b9\u6cd5**:\n\n- `get(key, user_id=None)`: (\u5f02\u6b65) \u83b7\u53d6\u7f13\u5b58\n- `set(key, value, ttl_seconds=None, user_id=None)`: (\u5f02\u6b65) \u8bbe\u7f6e\u7f13\u5b58\n- `delete(key)`: (\u5f02\u6b65) \u5220\u9664\u7f13\u5b58\n- `get_sync(key, user_id=None)` / `set_sync(...)` / `delete_sync(key)`: \u5185\u5b58\u7f13\u5b58\u7684\u540c\u6b65\u7248\u672c\n- `increment_global_version()`: (\u5f02\u6b65) \u9012\u589e\u5168\u5c40\u7248\u672c\u53f7\uff0c\u4f7f\u6240\u6709\u7f13\u5b58\u5931\u6548\n- `increment_user_version(user_id)`: (\u5f02\u6b65) \u9012\u589e\u7528\u6237\u7248\u672c\u53f7\uff0c\u4f7f\u8be5\u7528\u6237\u7684\u6240\u6709\u7f13\u5b58\u5931\u6548\n- `invalidate_all()`: (\u5f02\u6b65) \u4f7f\u6240\u6709\u7f13\u5b58\u5931\u6548\n- `invalidate_user_cache(user_id)`: (\u5f02\u6b65) \u4f7f\u7528\u6237\u7684\u6240\u6709\u7f13\u5b58\u5931\u6548\n\n**\u6838\u5fc3\u5c5e\u6027**:\n\n- `is_global_cache_enabled_sync` (`bool`): (\u540c\u6b65) \u68c0\u67e5\u5185\u5b58\u7f13\u5b58\u662f\u5426\u5df2\u542f\u7528\n\n### \u5168\u5c40\u63a7\u5236\u51fd\u6570\n\n- `preload_all_caches()`: (\u5f02\u6b65) \u6267\u884c\u6240\u6709\u5df2\u6ce8\u518c\u7684\u7f13\u5b58\u9884\u52a0\u8f7d\u4efb\u52a1\n- `invalidate_all_caches()`: (\u5f02\u6b65) \u5931\u6548\u6240\u6709\u4f7f\u7528\u9ed8\u8ba4\u7ba1\u7406\u5668\u7684\u7f13\u5b58\n- `invalidate_user_cache(user_id)`: (\u5f02\u6b65) \u4f7f\u7528\u6237\u7684\u6240\u6709\u7f13\u5b58\u5931\u6548\n- `get_cache_statistics(cache_id=None)`: \u83b7\u53d6\u7f13\u5b58\u7edf\u8ba1\u4fe1\u606f\n- `reset_cache_statistics(cache_id=None)`: \u91cd\u7f6e\u7f13\u5b58\u7edf\u8ba1\u4fe1\u606f\n- `start_cache_memory_monitoring(interval_seconds=300)`: \u542f\u52a8\u5185\u5b58\u76d1\u63a7\n- `get_cache_memory_usage()`: \u83b7\u53d6\u5185\u5b58\u4f7f\u7528\u60c5\u51b5\n\n## \u2699\ufe0f \u9ad8\u7ea7\u7528\u6cd5\n\n### \u5207\u6362\u5230 Redis \u5b58\u50a8\n\n\u53ea\u9700\u66f4\u6539 `storage_type` \u53c2\u6570\u5373\u53ef\u3002\n\n```python\n@cached(\n storage_type=StorageType.REDIS, \n serializer_type=SerializerType.MESSAGEPACK,\n ttl_seconds=3600\n)\nasync def get_shared_data():\n # ... \u4ece\u6570\u636e\u5e93\u6216RPC\u83b7\u53d6\u6570\u636e ...\n return {\"data\": \"some shared data\"}\n```\n\n### \u4f7f\u7528 LRU \u7f13\u5b58\u7b56\u7565\n\n```python\n@cached(\n cache_type=CacheType.LRU,\n max_size=100,\n storage_type=StorageType.MEMORY\n)\ndef calculate_fibonacci(n: int) -> int:\n \"\"\"\u8ba1\u7b97\u6590\u6ce2\u90a3\u5951\u6570\u5217\uff08\u540c\u6b65\u51fd\u6570\u793a\u4f8b\uff09\"\"\"\n if n <= 1:\n return n\n return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)\n```\n\n### \u81ea\u5b9a\u4e49\u7f13\u5b58\u952e\n\n\u5bf9\u4e8e\u590d\u6742\u7684\u53c2\u6570\uff0c\u53ef\u4ee5\u63d0\u4f9b\u81ea\u5b9a\u4e49\u7684 `key_func`\u3002\n\n```python\ndef make_user_key(user: User):\n return f\"user_cache:{user.org_id}:{user.id}\"\n\n@cached(key_func=make_user_key)\ndef get_user_permissions(user: User):\n # ...\n return [\"perm1\", \"perm2\"]\n```\n\n\u6216\u8005\uff0c\u4f7f\u7528 `key_params` \u81ea\u52a8\u751f\u6210\u3002\n\n```python\n@cached(key_params=['user_id', 'tenant_id'])\ndef get_document(doc_id: int, user_id: int, tenant_id: str):\n # \u81ea\u52a8\u751f\u6210\u7684key\u7c7b\u4f3c\u4e8e: \"app.module.get_document:user_id=123:tenant_id=abc\"\n pass\n```\n\n### \u7528\u6237\u7ea7\u522b\u7f13\u5b58\u7ba1\u7406\n\n```python\nfrom fn_cache import UniversalCacheManager, CacheConfig, StorageType\n\n\nclass UserCacheService:\n def __init__(self):\n config = CacheConfig(\n storage_type=StorageType.REDIS,\n serializer_type=SerializerType.JSON,\n prefix=\"user_cache:\"\n )\n self.cache = UniversalCacheManager(config)\n\n async def get_user_data(self, user_id: int):\n cache_key = f\"user_data:{user_id}\"\n\n # \u4f7f\u7528\u7528\u6237\u7ea7\u522b\u7248\u672c\u63a7\u5236\n cached_data = await self.cache.get(cache_key, user_id=str(user_id))\n if cached_data:\n return cached_data\n\n # \u7f13\u5b58\u672a\u547d\u4e2d\uff0c\u83b7\u53d6\u6570\u636e\n user_data = await self._fetch_user_data(user_id)\n\n # \u5b58\u50a8\u5230\u7f13\u5b58\uff0c\u4f7f\u7528\u7528\u6237\u7ea7\u522b\u7248\u672c\u63a7\u5236\n await self.cache.set(cache_key, user_data, user_id=str(user_id))\n return user_data\n\n async def invalidate_user_cache(self, user_id: int):\n \"\"\"\u4f7f\u7528\u6237\u7684\u6240\u6709\u7f13\u5b58\u5931\u6548\"\"\"\n await self.cache.invalidate_user_cache(str(user_id))\n```\n\n### \u52a8\u6001\u8fc7\u671f\u65f6\u95f4\n\n```python\n@cached(\n ttl_seconds=300\n)\nasync def get_user_vip_info(user_id: int):\n # VIP\u7528\u6237\u7f13\u5b581\u5c0f\u65f6\uff0c\u666e\u901a\u7528\u6237\u7f13\u5b5830\u5206\u949f\n pass\n```\n\n### \u591a\u53c2\u6570\u7f13\u5b58\u952e\n\n```python\n@cached(\n ttl_seconds=300\n)\nasync def get_user_profile(user_id: int, tenant_id: str):\n # \u652f\u6301\u591a\u79df\u6237\u7684\u7528\u6237\u8d44\u6599\u7f13\u5b58\n pass\n```\n\n## \ud83d\udd27 \u914d\u7f6e\u9009\u9879\n\n### CacheConfig \u914d\u7f6e\u7c7b\n\n```python\nfrom fn_cache import CacheConfig, CacheType, StorageType, SerializerType\n\nconfig = CacheConfig(\n cache_type=CacheType.TTL, # \u7f13\u5b58\u7b56\u7565: TTL \u6216 LRU\n storage_type=StorageType.MEMORY, # \u5b58\u50a8\u540e\u7aef: MEMORY \u6216 REDIS\n serializer_type=SerializerType.JSON, # \u5e8f\u5217\u5316\u7c7b\u578b: JSON, PICKLE, MESSAGEPACK, STRING\n ttl_seconds=600, # TTL \u8fc7\u671f\u65f6\u95f4\uff08\u79d2\uff09\n max_size=1000, # LRU \u6700\u5927\u5bb9\u91cf\n prefix=\"cache:\", # \u7f13\u5b58\u952e\u524d\u7f00\n global_version_key=\"fn_cache:global:version\", # \u5168\u5c40\u7248\u672c\u53f7\u952e\n user_version_key=\"fn_cache:user:version:{user_id}\", # \u7528\u6237\u7248\u672c\u53f7\u952e\n make_expire_sec_func=None, # \u52a8\u6001\u8fc7\u671f\u65f6\u95f4\u51fd\u6570\n serializer_kwargs={}, # \u5e8f\u5217\u5316\u5668\u53c2\u6570\n enable_statistics=True, # \u662f\u5426\u542f\u7528\u7edf\u8ba1\n enable_memory_monitoring=True, # \u662f\u5426\u542f\u7528\u5185\u5b58\u76d1\u63a7\n redis_config={ # Redis\u8fde\u63a5\u914d\u7f6e\n \"host\": \"localhost\",\n \"port\": 6379,\n \"db\": 0,\n \"decode_responses\": True,\n \"socket_timeout\": 1.0,\n \"socket_connect_timeout\": 1.0,\n \"retry_on_timeout\": True,\n \"health_check_interval\": 30,\n }\n)\n```\n\n## \ud83d\udca1 \u8bbe\u8ba1\u7406\u5ff5\n\n- **\u7edf\u4e00\u63a5\u53e3**: `UniversalCacheManager` \u63d0\u4f9b\u4e86\u7edf\u4e00\u7684\u63a5\u53e3\uff0c\u5c4f\u853d\u4e86\u4e0d\u540c\u5b58\u50a8\u540e\u7aef\u7684\u5b9e\u73b0\u7ec6\u8282\n- **\u7248\u672c\u63a7\u5236**: \u901a\u8fc7\u5168\u5c40\u7248\u672c\u53f7\u673a\u5236\u5b9e\u73b0\u4e00\u952e\u5931\u6548\u6240\u6709\u7f13\u5b58\uff0c\u4fbf\u4e8e\u8c03\u8bd5\u548c\u7ba1\u7406\n- **\u7528\u6237\u7ea7\u522b\u63a7\u5236**: \u652f\u6301\u6309\u7528\u6237\u5931\u6548\u7f13\u5b58\uff0c\u9002\u7528\u4e8e\u591a\u7528\u6237\u5e94\u7528\u573a\u666f\n- **\u7ed3\u6784\u5316\u7f13\u5b58\u952e**: \u901a\u8fc7\u679a\u4e3e\u5b9a\u4e49\u7f13\u5b58\u952e\u6a21\u677f\uff0c\u63d0\u9ad8\u4ee3\u7801\u53ef\u7ef4\u62a4\u6027\u548c\u4e00\u81f4\u6027\n- **\u88c5\u9970\u5668\u6a21\u5f0f**: `cached` \u4f7f\u7528\u88c5\u9970\u5668\u6a21\u5f0f\uff0c\u4ee5\u975e\u4fb5\u5165\u7684\u65b9\u5f0f\u4e3a\u51fd\u6570\u6dfb\u52a0\u7f13\u5b58\u903b\u8f91\n- **\u9519\u8bef\u9694\u79bb**: \u5185\u7f6e Redis \u8d85\u65f6\u548c\u8fde\u63a5\u9519\u8bef\u5904\u7406\uff0c\u786e\u4fdd\u7f13\u5b58\u95ee\u9898\u4e0d\u5f71\u54cd\u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\n- **\u6027\u80fd\u4f18\u5316**: \u652f\u6301\u7f13\u5b58\u9884\u52a0\u8f7d\u548c\u52a8\u6001\u8fc7\u671f\u65f6\u95f4\uff0c\u63d0\u5347\u5e94\u7528\u6027\u80fd\n- **\u76d1\u63a7\u7edf\u8ba1**: \u63d0\u4f9b\u8be6\u7ec6\u7684\u7f13\u5b58\u6027\u80fd\u76d1\u63a7\uff0c\u5e2e\u52a9\u4f18\u5316\u7f13\u5b58\u7b56\u7565\n\n## \ud83d\udcdd \u4f7f\u7528\u793a\u4f8b\n\n\u66f4\u591a\u8be6\u7ec6\u7684\u4f7f\u7528\u793a\u4f8b\uff0c\u8bf7\u53c2\u8003 `examples_v2.py` \u6587\u4ef6\uff0c\u5176\u4e2d\u5305\u542b\u4e86\uff1a\n\n- \u4e0d\u540c\u5e8f\u5217\u5316\u5668\u7684\u4f7f\u7528\n- \u7f13\u5b58\u7edf\u8ba1\u548c\u6027\u80fd\u76d1\u63a7\n- \u5185\u5b58\u76d1\u63a7\u529f\u80fd\n- \u6279\u91cf\u64cd\u4f5c\u548c\u7f13\u5b58\u9884\u70ed\n- \u7528\u6237\u7ea7\u522b\u7248\u672c\u63a7\u5236\n- \u76f4\u63a5\u4f7f\u7528\u7f13\u5b58\u7ba1\u7406\u5668\n\n## \ud83d\udd04 v2.0 \u65b0\u7279\u6027\n\n\u76f8\u6bd4 v1.0\uff0cv2.0 \u7248\u672c\u65b0\u589e\u4e86\u4ee5\u4e0b\u7279\u6027\uff1a\n\n1. **\u591a\u79cd\u5e8f\u5217\u5316\u683c\u5f0f\u652f\u6301**: \u652f\u6301 JSON\u3001Pickle\u3001MessagePack \u548c\u5b57\u7b26\u4e32\u5e8f\u5217\u5316\n2. **\u7f13\u5b58\u7edf\u8ba1\u529f\u80fd**: \u63d0\u4f9b\u8be6\u7ec6\u7684\u7f13\u5b58\u6027\u80fd\u76d1\u63a7\uff0c\u5305\u62ec\u547d\u4e2d\u7387\u3001\u54cd\u5e94\u65f6\u95f4\u7b49\u6307\u6807\n3. **\u66f4\u7075\u6d3b\u7684\u914d\u7f6e**: \u652f\u6301\u5e8f\u5217\u5316\u5668\u53c2\u6570\u3001Redis \u8fde\u63a5\u914d\u7f6e\u7b49\n4. **\u66f4\u597d\u7684\u9519\u8bef\u5904\u7406**: \u6539\u8fdb\u7684\u5f02\u5e38\u5904\u7406\u548c\u65e5\u5fd7\u8bb0\u5f55\n5. **\u6027\u80fd\u4f18\u5316**: \u66f4\u9ad8\u6548\u7684\u5e8f\u5217\u5316\u548c\u53cd\u5e8f\u5217\u5316\n6. **\u76d1\u63a7\u589e\u5f3a**: \u66f4\u8be6\u7ec6\u7684\u5185\u5b58\u4f7f\u7528\u76d1\u63a7\u548c\u7edf\u8ba1\u62a5\u544a\n\n## \ud83d\udce6 \u5b89\u88c5\n\n```bash\npip install fn_cache\n```\n\n## \ud83e\udd1d \u8d21\u732e\n\n\u6b22\u8fce\u63d0\u4ea4 Issue \u548c Pull Request\uff01\n\n## \ud83e\udeaa \u8bb8\u53ef\u8bc1\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u8f7b\u91cf\u7ea7\u901a\u7528\u7f13\u5b58\u5e93",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/leowzz/fn_cache/issues",
"Documentation": "https://fn-cache.readthedocs.io/",
"Homepage": "https://github.com/leowzz/fn_cache",
"Repository": "https://github.com/leowzz/fn_cache"
},
"split_keywords": [
"cache",
" memory",
" ttl",
" lru",
" async",
" decorator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "61379f931083f12adc89d11f8964b682b4eff17351b7639a71e3e28dc89835dd",
"md5": "555d007f6dfd46740100ef1d81651d56",
"sha256": "6b1808db71620325f41aa80413018b9ff5c185da06cd086ce5715cb7ec6c46dd"
},
"downloads": -1,
"filename": "fn_cache-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "555d007f6dfd46740100ef1d81651d56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31098,
"upload_time": "2025-07-17T11:26:58",
"upload_time_iso_8601": "2025-07-17T11:26:58.104127Z",
"url": "https://files.pythonhosted.org/packages/61/37/9f931083f12adc89d11f8964b682b4eff17351b7639a71e3e28dc89835dd/fn_cache-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "511fedf8b359234d2352417a28d6b2571220a7ee320b81de2fbf243c541d9a0c",
"md5": "0e70b666f62a4e8f1dc3938e2e757302",
"sha256": "ef9611965bf3e1b90f3e5495478d4faa64bf4e93087fe502222262ec9454cbf3"
},
"downloads": -1,
"filename": "fn_cache-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "0e70b666f62a4e8f1dc3938e2e757302",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 47569,
"upload_time": "2025-07-17T11:26:59",
"upload_time_iso_8601": "2025-07-17T11:26:59.434295Z",
"url": "https://files.pythonhosted.org/packages/51/1f/edf8b359234d2352417a28d6b2571220a7ee320b81de2fbf243c541d9a0c/fn_cache-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 11:26:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "leowzz",
"github_project": "fn_cache",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">",
"2.4"
],
[
"<",
"3.0"
]
]
},
{
"name": "fastapi",
"specs": [
[
"<",
"0.116.0"
],
[
">",
"0.100.0"
]
]
},
{
"name": "loguru",
"specs": [
[
"~=",
"0.7.3"
]
]
}
],
"lcname": "fn-cache"
}
JSON
