MoviePilot/MIGRATION_GUIDE.md

CacheBackend Dict操作特性迁移指南

概述

现在CacheBackend已经支持dict相关的操作特性，可以直接使用dict-like的接口操作缓存，无需TTLCache包装器。

新增的Dict操作特性

同步操作

• __getitem__: cache[key] - 获取缓存项
• __setitem__: cache[key] = value - 设置缓存项
• __delitem__: del cache[key] - 删除缓存项
• __contains__: key in cache - 检查键是否存在
• __iter__: for key in cache - 迭代缓存键
• __len__: len(cache) - 获取缓存项数量
• keys(): 获取所有缓存键
• values(): 获取所有缓存值
• items(): 获取所有键值对
• update(): 批量更新缓存
• pop(): 弹出缓存项
• popitem(): 弹出最后一个缓存项
• setdefault(): 设置默认值

异步操作

• __getitem__: await cache[key] - 获取缓存项
• __setitem__: await cache[key] = value - 设置缓存项
• __delitem__: await del cache[key] - 删除缓存项
• __contains__: await key in cache - 检查键是否存在
• __aiter__: async for key in cache - 异步迭代缓存键
• __len__: await len(cache) - 获取缓存项数量
• keys(): 异步获取所有缓存键
• values(): 异步获取所有缓存值
• items(): 异步获取所有键值对
• update(): 异步批量更新缓存
• pop(): 异步弹出缓存项
• popitem(): 异步弹出最后一个缓存项
• setdefault(): 异步设置默认值

迁移示例

从TTLCache迁移

旧代码（使用TTLCache）

from app.core.cache import TTLCache

# 创建TTLCache实例
cache = TTLCache(region="my_region", maxsize=1024, ttl=600)

# 设置缓存
cache.set("key1", "value1")
cache.set("key2", "value2")

# 获取缓存
value1 = cache.get("key1")
value2 = cache.get("key2", "default")

# 删除缓存
cache.delete("key1")

# 清空缓存
cache.clear()

新代码（直接使用CacheBackend）

from app.core.cache import Cache

# 创建Cache实例（等同于TTLCache）
cache = Cache(maxsize=1024, ttl=600)

# 设置缓存（支持region参数）
cache["key1"] = "value1"  # 使用默认region
cache.set("key2", "value2", region="my_region")  # 指定region

# 获取缓存
value1 = cache["key1"]
value2 = cache.get("key2", "default", region="my_region")

# 检查键是否存在
if "key1" in cache:
    print("key1 exists")

# 删除缓存
del cache["key1"]
cache.delete("key2", region="my_region")

# 迭代缓存
for key in cache:
    print(key)

# 获取所有键值对
for key, value in cache.items():
    print(f"{key}: {value}")

# 新增的dict操作
# 批量更新
cache.update({"batch1": "value1", "batch2": "value2"})

# 弹出值
value = cache.pop("batch1")

# 设置默认值
value = cache.setdefault("new_key", "default_value")

# 弹出最后一个项
key, value = cache.popitem()

# 获取所有键和值
keys = list(cache.keys())
values = list(cache.values())

# 获取缓存项数量
count = len(cache)

# 清空缓存
cache.clear()  # 清空默认region
cache.clear(region="my_region")  # 清空指定region

异步操作示例

旧代码（使用AsyncTTLCache）

from app.core.cache import AsyncTTLCache

# 创建异步TTLCache实例
cache = AsyncTTLCache(region="my_region", maxsize=1024, ttl=600)

# 异步设置缓存
await cache["key1"] = "value1"
await cache.set("key2", "value2")

# 异步获取缓存
value1 = await cache["key1"]
value2 = await cache.get("key2", "default")

# 异步检查键是否存在
if await "key1" in cache:
    print("key1 exists")

# 异步删除缓存
await del cache["key1"]
await cache.delete("key2")

# 异步迭代缓存
async for key in cache:
    print(key)

# 异步获取所有键值对
async for key, value in cache.items():
    print(f"{key}: {value}")

# 异步清空缓存
await cache.clear()

新代码（直接使用AsyncCacheBackend）

from app.core.cache import AsyncCache

# 创建异步Cache实例
cache = AsyncCache(maxsize=1024, ttl=600)

# 异步设置缓存
await cache["key1"] = "value1"
await cache.set("key2", "value2", region="my_region")

# 异步获取缓存
value1 = await cache["key1"]
value2 = await cache.get("key2", "default", region="my_region")

# 异步检查键是否存在
if await "key1" in cache:
    print("key1 exists")

# 异步删除缓存
await del cache["key1"]
await cache.delete("key2", region="my_region")

# 异步迭代缓存
async for key in cache:
    print(key)

# 异步获取所有键值对
async for key, value in cache.items():
    print(f"{key}: {value}")

# 新增的异步dict操作
# 异步批量更新
await cache.update({"batch1": "value1", "batch2": "value2"})

# 异步弹出值
value = await cache.pop("batch1")

# 异步设置默认值
value = await cache.setdefault("new_key", "default_value")

# 异步弹出最后一个项
key, value = await cache.popitem()

# 异步获取所有键和值
keys = []
async for key in cache.keys():
    keys.append(key)

values = []
async for value in cache.values():
    values.append(value)

# 异步获取缓存项数量
count = await len(cache)

# 异步清空缓存
await cache.clear()
await cache.clear(region="my_region")

主要优势

1. 统一接口: 所有缓存后端都支持相同的dict操作接口
2. 减少包装器: 无需TTLCache包装器，直接使用CacheBackend
3. 更好的性能: 减少了一层包装，性能更好
4. 更灵活: 支持region参数，可以更好地组织缓存
5. 向后兼容: 原有的set/get/delete等方法仍然可用

注意事项

1. Region参数: dict-like操作默认使用DEFAULT_CACHE_REGION，如需指定region请使用set/get/delete等方法
2. 错误处理: 访问不存在的键会抛出KeyError，使用get()方法可以避免
3. 异步操作: 异步版本的所有操作都需要使用await关键字
4. 性能考虑: 某些操作（如len()、items()）可能需要遍历整个缓存，在大缓存中可能较慢

迁移步骤

1. 将 TTLCache 替换为 Cache
2. 将 AsyncTTLCache 替换为 AsyncCache
3. 更新导入语句
4. 根据需要调整region参数的使用
5. 测试所有缓存操作是否正常工作

测试

运行测试文件验证dict操作特性：

python test_cache_dict_operations.py