pynomadic 0.1.0__tar.gz

pynomadic-0.1.0/PKG-INFO

@@ -0,0 +1,3440 @@
+Metadata-Version: 2.4
+Name: pynomadic
+Version: 0.1.0
+Summary: 一个python工具包,包括自动配置系统,常用工具包,控制台输出系统,日志系统,命名系统,缓存系统,返回值封装类
+License-Expression: MIT
+Author: nomadicooer
+Author-email: nomadicooer@qq.com
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: redis (>=7.3.0,<8.0.0)
+Description-Content-Type: text/markdown
+
+# pynomad
+
+[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**仓库地址**: https://gitee.com/nomadicooer/pynomad.git
+
+> ⚠️ **重要声明**
+>
+> - 本系统大部分代码由 AI 生成
+> - 本介绍文档完全由 AI 生成，当中存在大量错误介绍
+> - 正确用法请自行发掘
+> - 具体使用方法可参照 [findata 项目](https://gitee.com/nomadicooer/findata.git)
+
+一个功能丰富的 Python 工具包，提供自动配置系统、多级缓存、DataFrame 缓存、日志系统、命名系统和结果封装等核心功能。
+
+## 功能特性
+
+### 🚀 缓存系统
+
+提供多种缓存实现和灵活的缓存策略：
+
+- **Memory Cache** (`@memcached`) - 内存缓存
+  - 支持淘汰策略 (LFU/LRU/FIFO)
+  - 线程安全实现
+  - 适合临时数据缓存
+
+- **Pickle Cache** (`@pickled`) - Pickle 文件缓存
+  - 持久化到本地文件
+  - 支持对象序列化
+
+- **Redis Cache** (`@rediscached`) - Redis 分布式缓存
+  - 支持自定义 Redis 客户端和连接池
+  - 支持加密存储
+  - 提供分布式缓存能力
+
+- **DataFrame 缓存** - 专为 DataFrame 设计的缓存系统
+  - **Memory** (`@df_memcached`) - DataFrame 内存缓存
+  - **Pickle** (`@df_pickled`) - DataFrame 文件缓存
+  - **Redis** (`@df_rediscached`) - DataFrame Redis 缓存
+  - **SQL** (`@sqlcached`) - DataFrame SQL 数据库缓存
+  - 采用三阶段处理模型（GET → PUT → EXTRACT）
+  - 支持自定义 ValueLoader 实现灵活的数据处理逻辑
+
+- **多级缓存** (`@multi_level_cached`)
+  - 支持三级缓存 (L1/L2/L3)
+  - 写穿透策略 (Write-Through)
+  - 读穿透策略 (Read-Through)
+  - 独立的 TTL 和淘汰策略配置
+
+### 🎯 Result 结果封装
+
+统一的结果封装模式，优雅的错误处理：
+
+```python
+Result.success(data)           # 成功
+Result.client_error(exception)  # 客户端错误
+Result.network_error(exception) # 网络错误
+Result.server_error(exception)  # 服务端错误
+Result.third_party_error(ex)    # 第三方错误
+```
+
+**链式操作**：
+```python
+result.map(fn)              # 转换数据
+result.map_err(fn)          # 转换异常
+result.unwrap()             # 获取数据或抛异常
+result.unwrap_or(default)   # 获取数据或返回默认值
+```
+
+### ⚙️ 自动配置系统
+
+类似 Spring Boot `@ConfigurationProperties` 的配置注入：
+
+```python
+@inject(prefix="database")
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 3306
+
+config = DatabaseConfig()  # 自动从配置加载
+```
+
+**支持的配置格式**：
+- TOML (`.toml`) - 推荐使用 `settings.toml`
+- 环境变量（配置文件中支持 `${ENV_VAR}` 格式）
+
+### 📝 日志系统
+
+功能完善的日志系统：
+
+- 自定义 Logger 类
+- 彩色输出 (`ColorFormatter`)
+- 支持 TRACE/DEBUG/INFO/WARNING/ERROR/CRITICAL 级别
+- 动态日志级别配置
+
+```python
+from pynomad.logsystem.manager import get_logger
+
+logger = get_logger()
+logger.trace("追踪信息")
+logger.debug("调试信息")
+logger.info("信息")
+logger.warning("警告")
+logger.error("错误")
+```
+
+### 🏷️ 命名系统
+
+支持 16 种命名风格的转换和检测：
+
+- `camelCase` - 驼峰命名
+- `PascalCase` - 帕斯卡命名
+- `snake_case` - 蛇形命名
+- `kebab-case` - 短横线命名
+- `SCREAMING_SNAKE_CASE` - 大写蛇形
+- 等其他变体
+
+```python
+from pynomad.naming.naming import convert_name, detect_style
+
+style = detect_style("myVariable")  # 返回 NameStyle.CAMEL
+converted = convert_name("myVariable", NameStyle.SNAKE)  # 返回 "my_variable"
+```
+
+### 🔧 通用工具
+
+- **单例装饰器** - 线程安全的单例模式
+- **线程安全装饰器** - 并发控制
+- **重试装饰器** - 自动重试机制
+- **环境检测** - 自动检测项目根目录
+- **网络检测** - 网络连接检查
+- **字典工具** - 字典序列化、展平、转换
+- **序列化工具** - 支持 INI/TOML/JSON
+
+## 安装
+
+```bash
+pip install pynomadic
+```
+
+### 可选依赖
+
+```bash
+# Redis 缓存
+pip install redis>=7.3.0
+
+# SQL 缓存
+pip install sqlalchemy>=2.0.48
+
+# DataFrame 缓存
+pip install pandas>=3.0.1
+```
+
+## 快速开始
+
+### 基本缓存使用
+
+```python
+from pynomad import memcached, rediscached
+
+@memcached(ttl=60)
+def expensive_calc(x: int, y: int) -> int:
+    return x + y
+
+@rediscached(ttl=300, host="localhost")
+def get_user_data(user_id: str) -> dict:
+    return fetch_from_db(user_id)
+```
+
+### DataFrame 缓存
+
+```python
+from pynomad import df_memcached
+from pandas import DataFrame
+
+@df_memcached(ttl=3600)
+def load_data(symbol: str) -> DataFrame:
+    # 从 API 加载数据
+    return DataFrame()
+```
+
+### SQL 缓存
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+from pandas import DataFrame
+
+@sqlcached(db_type="sqlite", db_url="sqlite:///cache.db", ttl=3600)
+def fetch_data(symbol: str) -> Result[DataFrame]:
+    # 从 API 加载数据
+    df = DataFrame({"symbol": [symbol], "price": [100.0]})
+    return Result.success(df)
+```
+
+### 多级缓存
+
+```python
+from pynomad import multi_level_cached
+
+@multi_level_cached(
+    name="my_cache",
+    l1_code="memory",    # L1: 内存
+    l2_code="pickle",     # L2: 文件
+    l3_code="redis",      # L3: Redis
+    l1_ttl=10,           # L1: 10秒
+    l2_ttl=60,           # L2: 60秒
+    l3_ttl=300,          # L3: 300秒
+)
+def get_data(key: str):
+    return expensive_operation(key)
+```
+
+### Result 使用
+
+```python
+from pynomad import Result
+
+result = Result.success({"id": 1, "name": "Alice"})
+if result.is_success():
+    data = result.data
+
+result = Result.client_error(ValueError("Invalid parameter"))
+result.unwrap_or(None)
+
+# 链式操作
+result = result.map(lambda x: x * 2)
+```
+
+## 自动配置系统详解
+
+pynomad 提供类似 Spring Boot `@ConfigurationProperties` 的自动配置系统，支持从 `settings.toml` 配置文件自动注入配置值。
+
+### 1. 基本用法
+
+#### 1.1 使用 prefix 参数
+
+`@inject` 装饰器的 `prefix` 参数用于指定配置文件中的配置前缀：
+
+**settings.toml：**
+
+```toml
+[database]
+host = "localhost"
+port = 3306
+username = "root"
+password = "${DB_PASSWORD}"
+
+[cache.redis]
+host = "localhost"
+port = 6379
+db = 0
+password = "${REDIS_PASSWORD}"
+ttl = 3600
+```
+
+**Python 代码：**
+
+```python
+from pynomad.config.auto.autoconfig import inject
+
+@inject(prefix="database")
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 3306
+    username: str = "root"
+    password: str = ""
+
+# 创建实例时自动注入配置
+config = DatabaseConfig()
+print(config.host)   # 从 settings.toml 的 database.host 读取
+print(config.port)   # 从 settings.toml 的 database.port 读取
+```
+
+#### 1.2 使用 field() 函数
+
+`field()` 函数用于指定默认值、自定义转换器和别名（不是配置路径）：
+
+```python
+from pynomad.config.auto.autoconfig import inject
+from pynomad.config.auto.field_info import field
+
+@inject(prefix="cache.redis")
+class RedisConfig:
+    host: str = field(default="localhost")  # 默认值
+    port: int = field(default=6379)
+    db: int = field(default=0)
+    password: str = field(default="")
+    ttl: int = field(default=3600)
+
+redis_config = RedisConfig()
+print(redis_config.host)  # 从 cache.redis.host 读取
+```
+
+**注意：**
+- `field()` 的第一个参数是 `default`（默认值），不是配置路径
+- 配置路径由 `@inject(prefix="...")` 和字段名自动确定
+- `field()` 主要用于：
+  - 指定默认值（`default`）
+  - 自定义类型转换器（`converter`）
+  - 指定配置文件中的别名（`alias`）
+
+---
+
+### 2. 高级功能
+
+#### 2.1 单例模式
+
+使用 `@inject` 装饰的类采用单例模式，多次创建返回同一实例：
+
+```python
+config1 = DatabaseConfig()
+config2 = DatabaseConfig()
+
+print(config1 is config2)  # True，同一实例
+```
+
+**单例模式的优势：**
+- 全局配置一致性
+- 避免重复加载配置
+- 提高性能
+
+**注意事项：**
+- 配置对象应为只读，不建议运行时修改
+- 如需临时修改，使用 `copy_config()` 创建副本
+
+#### 2.2 配置副本
+
+使用 `copy_config()` 创建配置对象的深拷贝副本：
+
+```python
+from pynomad.config.auto.autoconfig import inject, copy_config
+
+@inject(prefix="database")
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 3306
+
+config = DatabaseConfig()
+config_copy = copy_config(config)
+
+# 修改副本不影响原始配置
+config_copy.host = "modified.host"
+print(config.host)        # 仍然是原始值
+print(config_copy.host)   # 已修改
+```
+
+#### 2.3 重新加载配置
+
+使用 `reload_config()` 重新加载配置文件：
+
+```python
+from pynomad.config.auto.autoconfig import inject, reload_config
+
+@inject(prefix="database")
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 3306
+
+config = DatabaseConfig()
+
+# 修改 settings.toml 文件后
+reload_config(config)
+# config 的属性会更新为最新的配置值
+```
+
+#### 2.4 清除配置缓存
+
+使用 `clear_config_cache()` 清除配置缓存：
+
+```python
+from pynomad.config.auto.autoconfig import clear_config_cache, DatabaseConfig
+
+# 清除缓存
+clear_config_cache()
+
+# 下次创建实例时会重新加载配置
+config = DatabaseConfig()
+```
+
+#### 2.5 获取配置值
+
+使用 `get_config_value()` 便捷函数获取配置值：
+
+```python
+from pynomad.config.auto.autoconfig import get_config_value
+
+# 获取 database.host，默认为 "localhost"
+host = get_config_value("database", "host", "localhost")
+print(host)
+```
+
+---
+
+### 3. 类型支持
+
+#### 3.1 基本类型
+
+自动配置系统支持所有基本 Python 类型：
+
+```python
+@inject(prefix="app")
+class AppConfig:
+    # 字符串
+    name: str = field(default="my_app")
+    # 整数
+    port: int = field(default=8080)
+    # 浮点数
+    timeout: float = field(default=3.5)
+    # 布尔值
+    enabled: bool = field(default=True)
+```
+
+**settings.toml：**
+
+```toml
+[app]
+name = "my_application"
+port = 9090
+timeout = 5.0
+enabled = false
+```
+
+#### 3.2 路径类型
+
+支持 `Path` 类型，并自动展开路径变量：
+
+```python
+from pathlib import Path
+
+@inject(prefix="paths")
+class PathConfig:
+    home_dir: Path = field(default="{home}/app")
+    workspace_dir: Path = field(default="{workspace}/data")
+    cache_dir: Path = field(default="./cache")
+```
+
+**settings.toml：**
+
+```toml
+[paths]
+home_dir = "{home}/my_app"
+workspace_dir = "{workspace}/project"
+cache_dir = "./cache"
+```
+
+**支持的路径变量：**
+- `{home}` - 用户主目录
+- `{workspace}` - 项目根目录
+- `{temp}` - 临时目录
+
+#### 3.3 列表类型
+
+支持 `list` 和 `List[T]` 类型：
+
+```python
+@inject(prefix="servers")
+class ServerConfig:
+    hosts: list[str] = field(default=[])
+    ports: list[int] = field(default=[])
+    enabled: list[bool] = field(default=[])
+```
+
+**settings.toml：**
+
+```toml
+[servers]
+hosts = ["server1.example.com", "server2.example.com"]
+ports = [8080, 9090]
+enabled = [true, false]
+```
+
+#### 3.4 嵌套配置类
+
+支持嵌套配置类：
+
+```python
+from dataclasses import dataclass
+
+@inject(prefix="app")
+class AppConfig:
+    name: str = "my_app"
+    debug: bool = False
+
+@dataclass
+class DatabaseSection:
+    host: str = "localhost"
+    port: int = 3306
+
+@inject(prefix="database")
+class DatabaseConfig:
+    connection: DatabaseSection = DatabaseSection()
+    username: str = "root"
+    password: str = ""
+```
+
+**settings.toml：**
+
+```toml
+[app]
+name = "production_app"
+debug = false
+
+[database.connection]
+host = "db.example.com"
+port = 3306
+
+[database]
+username = "db_user"
+password = "${DB_PASSWORD}"
+```
+
+---
+
+### 4. 自定义转换器
+
+使用 `field()` 的 `converter` 参数自定义类型转换：
+
+```python
+from pynomad.config.auto.autoconfig import inject
+from pynomad.config.auto.field_info import field
+
+def to_seconds(value) -> int:
+    """将时间字符串转换为秒数"""
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        if value.endswith("s"):
+            return int(value[:-1])
+        if value.endswith("m"):
+            return int(value[:-1]) * 60
+        if value.endswith("h"):
+            return int(value[:-1]) * 3600
+    return int(value)
+
+@inject(prefix="cache")
+class CacheConfig:
+    timeout: int = field(default=60, converter=to_seconds)
+    ttl: int = field(default=3600, converter=to_seconds)
+```
+
+**settings.toml：**
+
+```toml
+[cache]
+timeout = "5m"   # 自动转换为 300 秒
+ttl = "1h"      # 自动转换为 3600 秒
+```
+
+---
+
+### 5. 别名支持
+
+使用 `alias` 参数解决 Python 关键字冲突：
+
+```python
+@inject(prefix="app")
+class AppConfig:
+    # Python 中 class 是关键字，使用 class_ 作为属性名
+    class_: str = field(default="default_class", alias="class")
+    # 配置文件中使用 "class"，代码中使用 "class_"
+    type_: str = field(default="default_type", alias="type")
+```
+
+**settings.toml：**
+
+```toml
+[app]
+class = "my_class"
+type = "my_type"
+```
+
+---
+
+### 6. 环境变量替换
+
+配置文件支持环境变量替换：
+
+**settings.toml：**
+
+```toml
+[database]
+host = "localhost"
+port = 3306
+username = "root"
+password = "${DB_PASSWORD}"
+
+[cache.redis]
+host = "localhost"
+port = 6379
+password = "${REDIS_PASSWORD}"
+```
+
+**设置环境变量：**
+
+```bash
+# Linux/Mac
+export DB_PASSWORD="my_db_password"
+export REDIS_PASSWORD="my_redis_password"
+
+# Windows
+set DB_PASSWORD=my_db_password
+set REDIS_PASSWORD=my_redis_password
+```
+
+---
+
+### 7. 配置文件位置
+
+`settings.toml` 文件应放在以下位置之一（按优先级顺序）：
+
+1. **项目根目录**：`./settings.toml`
+2. **配置目录**：`./config/settings.toml`
+3. **用户目录**：`~/.pynomad/settings.toml`
+4. **环境变量指定**：`PYNOMAD_CONFIG_PATH`
+
+```bash
+# 通过环境变量指定配置文件路径
+export PYNOMAD_CONFIG_PATH="/path/to/settings.toml"
+```
+
+---
+
+### 8. 完整示例
+
+**settings.toml：**
+
+```toml
+[app]
+name = "my_application"
+version = "1.0.0"
+debug = false
+timeout = "5m"
+
+[database]
+host = "localhost"
+port = 3306
+username = "root"
+password = "${DB_PASSWORD}"
+pool_size = 10
+
+[cache.memory]
+ttl = 600
+maxsize = 1000
+
+[cache.redis]
+host = "localhost"
+port = 6379
+db = 0
+password = "${REDIS_PASSWORD}"
+ttl = 1800
+
+[paths]
+home_dir = "{home}/my_app"
+workspace_dir = "{workspace}/data"
+cache_dir = "./cache"
+
+[servers]
+hosts = ["server1.example.com", "server2.example.com"]
+ports = [8080, 9090]
+```
+
+**main.py：**
+
+```python
+from pynomad.config.auto.autoconfig import inject, field
+from pynomad.config.auto.field_info import field as config_field
+from pathlib import Path
+
+def to_seconds(value) -> int:
+    """将时间字符串转换为秒数"""
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        if value.endswith("m"):
+            return int(value[:-1]) * 60
+        if value.endswith("h"):
+            return int(value[:-1]) * 3600
+    return int(value)
+
+@inject(prefix="app")
+class AppConfig:
+    name: str = "my_app"
+    version: str = "0.0.1"
+    debug: bool = False
+    timeout: int = field(default=60, converter=to_seconds)
+
+@inject(prefix="database")
+class DatabaseConfig:
+    host: str = "localhost"
+    port: int = 3306
+    username: str = "root"
+    password: str = ""
+    pool_size: int = 10
+
+@inject(prefix="cache.redis")
+class RedisCacheConfig:
+    host: str = "localhost"
+    port: int = 6379
+    db: int = 0
+    password: str = ""
+    ttl: int = 3600
+
+@inject(prefix="paths")
+class PathConfig:
+    home_dir: Path = field(default="{home}/app")
+    workspace_dir: Path = field(default="{workspace}/data")
+    cache_dir: Path = field(default="./cache")
+
+@inject(prefix="servers")
+class ServerConfig:
+    hosts: list[str] = []
+    ports: list[int] = []
+
+# 使用配置
+app_config = AppConfig()
+db_config = DatabaseConfig()
+redis_config = RedisCacheConfig()
+path_config = PathConfig()
+server_config = ServerConfig()
+
+print(f"应用名称: {app_config.name}")
+print(f"应用版本: {app_config.version}")
+print(f"调试模式: {app_config.debug}")
+print(f"超时时间: {app_config.timeout} 秒")
+print(f"数据库主机: {db_config.host}")
+print(f"数据库端口: {db_config.port}")
+print(f"Redis 主机: {redis_config.host}")
+print(f"缓存目录: {path_config.cache_dir}")
+print(f"服务器列表: {server_config.hosts}")
+```
+
+---
+
+### 9. 测试场景
+
+#### 9.1 重置单例
+
+测试时使用 `reset_singleton()` 重置单例：
+
+```python
+from pynomad.config.auto.autoconfig import DatabaseConfig, reset_singleton
+
+def test_database_config():
+    # 测试前重置单例
+    reset_singleton(DatabaseConfig)
+
+    config = DatabaseConfig()
+    assert config.host == "localhost"
+
+    # 清理
+    reset_singleton(DatabaseConfig)
+```
+
+#### 9.2 使用配置副本
+
+测试时使用配置副本避免影响原始配置：
+
+```python
+from pynomad.config.auto.autoconfig import DatabaseConfig, copy_config
+
+def test_with_modified_config():
+    original_config = DatabaseConfig()
+    test_config = copy_config(original_config)
+
+    # 修改副本用于测试
+    test_config.host = "test.host"
+
+    # 原始配置不受影响
+    assert original_config.host != test_config.host
+```
+
+---
+
+## 缓存系统完整指南
+
+### 缓存类型总览
+
+pynomad 提供多种缓存实现，适用于不同的使用场景：
+
+| 缓存类型 | 装饰器 | 适用场景 | 持久化 | 分布式 |
+|---------|--------|---------|--------|--------|
+| Memory Cache | `@memcached` | 临时数据、高频访问 | ❌ | ❌ |
+| Pickle Cache | `@pickled` | 本地持久化、离线场景 | ✅ | ❌ |
+| Redis Cache | `@rediscached` | 分布式缓存、多实例共享 | ✅ | ✅ |
+| DataFrame Memory | `@df_memcached` | DataFrame 临时缓存 | ❌ | ❌ |
+| DataFrame Pickle | `@df_pickled` | DataFrame 持久化 | ✅ | ❌ |
+| DataFrame Redis | `@df_rediscached` | DataFrame 分布式 | ✅ | ✅ |
+| DataFrame SQL | `@sqlcached` | DataFrame SQL 数据库缓存 | ✅ | ✅ |
+| 多级缓存 | `@multi_level_cached` | 性能与可靠性平衡 | 混合 | 混合 |
+
+### 1. Memory Cache (内存缓存)
+
+#### 基本用法
+
+```python
+from pynomad import memcached
+
+# 无参数装饰（使用默认配置）
+@memcached
+def expensive_calc(x: int, y: int) -> int:
+    print("执行计算...")
+    return x + y
+```
+
+#### 带参数配置
+
+```python
+from pynomad import memcached
+
+@memcached(
+    name="my_cache",           # 缓存名称
+    ttl=60,                    # 缓存存活时间（秒），0 表示永不过期
+    maxsize=100,               # 最大缓存数量
+    eviction_policy="lru"      # 淘汰策略: lru/lfu/fifo/none
+)
+def fetch_user(user_id: int) -> dict:
+    print(f"从数据库查询用户 {user_id}...")
+    return {"id": user_id, "name": f"User{user_id}"}
+```
+
+#### 淘汰策略说明
+
+- **LRU (Least Recently Used)**: 淘汰最久未使用的数据
+- **LFU (Least Frequently Used)**: 淘汰使用频率最低的数据
+- **FIFO (First In First Out)**: 淘汰最早缓存的数据
+- **None**: 不淘汰，缓存满时拒绝写入
+
+#### 使用场景
+
+- 高频访问的临时数据
+- API 响应缓存
+- 计算密集型操作结果缓存
+
+---
+
+### 2. Pickle Cache (文件缓存)
+
+#### 基本用法
+
+```python
+from pynomad import pickled
+
+@pickled(ttl=3600)
+def load_config() -> dict:
+    print("加载配置文件...")
+    return {"debug": True, "timeout": 30}
+```
+
+#### 带参数配置
+
+```python
+from pynomad import pickled
+
+@pickled(
+    name="app_cache",
+    ttl=3600,                  # 1小时过期
+    maxsize=500,
+    cache_dir="./cache",      # 缓存文件存储目录
+    enable_encryption=True,    # 启用加密
+    salt="my_app_v1",          # 加密盐值
+    enable_background_cleanup=True,  # 启用后台清理
+    cleanup_interval=300       # 每5分钟清理一次
+)
+def process_data(data_id: str) -> dict:
+    print(f"处理数据 {data_id}...")
+    return {"id": data_id, "processed": True}
+```
+
+#### 使用场景
+
+- 需要持久化的缓存数据
+- 离线场景的数据访问
+- 跨进程共享（通过共享目录）
+- 数据迁移和备份
+- 数据分析和审计
+
+#### 加密说明
+
+- 使用机器派生密钥进行加密
+- `salt` 参数用于生成密钥，建议使用项目版本号
+- 不同机器使用不同的加密密钥，增强安全性
+
+---
+
+### 3. Redis Cache (Redis 分布式缓存)
+
+#### 基本用法
+
+```python
+from pynomad import rediscached
+
+@rediscached(ttl=300)
+def get_product(product_id: str) -> dict:
+    print(f"从数据库查询产品 {product_id}...")
+    return {"id": product_id, "price": 99.99}
+```
+
+#### 带参数配置
+
+```python
+from pynomad import rediscached
+
+@rediscached(
+    name="product_cache",
+    ttl=1800,                  # 30分钟过期
+    host="localhost",          # Redis 主机
+    port=6379,                 # Redis 端口
+    db=0,                      # 数据库编号
+    username="default",        # 用户名
+    password="password",       # 密码
+    enable_encryption=True,    # 启用加密
+    salt="redis_cache_v1"      # 加密盐值
+)
+def get_order(order_id: str) -> dict:
+    print(f"从数据库查询订单 {order_id}...")
+    return {"id": order_id, "status": "completed"}
+```
+
+#### 使用自定义 Redis 客户端
+
+```python
+from redis import Redis, ConnectionPool
+from pynomad import rediscached
+
+# 创建连接池
+pool = ConnectionPool(
+    host="localhost",
+    port=6379,
+    db=0,
+    password="password",
+    max_connections=10
+)
+
+# 创建 Redis 客户端
+redis_client = Redis(connection_pool=pool)
+
+@rediscached(
+    name="custom_redis",
+    redis_client=redis_client,  # 使用自定义客户端
+    ttl=600
+)
+def get_user(user_id: int) -> dict:
+    print(f"查询用户 {user_id}...")
+    return {"id": user_id, "name": f"User{user_id}"}
+```
+
+#### 使用场景
+
+- 分布式系统缓存
+- 多实例共享缓存
+- 高并发场景
+- 实时数据同步
+
+---
+
+### 4. DataFrame 缓存
+
+DataFrame 缓存采用三阶段处理模型：**GET → PUT → EXTRACT**
+
+**重要规范**：所有 DataFrame 缓存装饰器装饰的函数必须显式声明返回类型注解。
+
+#### 4.1 DataFrame 内存缓存 (`@df_memcached`)
+
+```python
+from pynomad import df_memcached
+from pandas import DataFrame
+import pandas as pd
+
+# 无参数装饰（使用配置默认值）
+@df_memcached
+def load_stock_data(symbol: str) -> DataFrame:
+    """必须声明返回类型为 DataFrame"""
+    print(f"加载股票数据: {symbol}")
+    return DataFrame({
+        "symbol": [symbol] * 5,
+        "date": pd.date_range("2024-01-01", periods=5),
+        "price": [100.0, 101.0, 102.0, 101.5, 103.0]
+    })
+
+# 带参数装饰
+@df_memcached(
+    name="stock_cache",
+    ttl=600,                    # 10分钟过期
+    maxsize=100,                # 最多缓存100个symbol
+    eviction_policy="lru"       # LRU淘汰策略
+)
+def load_market_data(symbol: str, period: str = "1d") -> DataFrame:
+    print(f"加载市场数据: {symbol}, 周期: {period}")
+    return DataFrame()
+```
+
+#### 4.2 DataFrame 文件缓存 (`@df_pickled`)
+
+```python
+from pynomad import df_pickled
+from pandas import DataFrame
+
+# 基本用法
+@df_pickled(ttl=3600)
+def load_historical_data(symbol: str) -> DataFrame:
+    print(f"加载历史数据: {symbol}")
+    # 从 API 获取数据
+    return DataFrame()
+
+# 完整配置
+@df_pickled(
+    name="historical_cache",
+    cache_dir="./df_cache",      # 缓存文件存储目录
+    ttl=86400,                   # 24小时过期
+    maxsize=500,
+    enable_encryption=True,      # 启用加密
+    salt="finance_data_v1",      # 加密盐值
+    enable_background_cleanup=True,  # 启用后台清理
+    cleanup_interval=300         # 每5分钟清理一次
+)
+def load_daily_data(date: str) -> DataFrame:
+    print(f"加载日线数据: {date}")
+    return DataFrame()
+```
+
+#### 4.3 DataFrame Redis 缓存 (`@df_rediscached`)
+
+```python
+from pynomad import df_rediscached
+from pandas import DataFrame
+
+# 基本用法
+@df_rediscached(ttl=1800)
+def load_realtime_data(symbol: str) -> DataFrame:
+    print(f"加载实时数据: {symbol}")
+    # 从实时数据源获取
+    return DataFrame()
+
+# 完整配置
+@df_rediscached(
+    name="realtime_cache",
+    host="localhost",
+    port=6379,
+    db=0,
+    username="default",
+    password="password",
+    ttl=300,                     # 5分钟过期
+    maxsize=1000,
+    enable_encryption=True,      # 启用加密
+    salt="realtime_v1"          # 加密盐值
+)
+def load_tick_data(symbol: str) -> DataFrame:
+    print(f"加载Tick数据: {symbol}")
+    return DataFrame()
+```
+
+#### 5.4 使用自定义 Redis 客户端
+
+```python
+from redis import Redis, ConnectionPool
+from pynomad import df_rediscached
+
+# 创建连接池
+pool = ConnectionPool(
+    host="localhost",
+    port=6379,
+    db=0,
+    password="password",
+    max_connections=10
+)
+
+# 创建 Redis 客户端
+redis_client = Redis(connection_pool=pool)
+
+@df_rediscached(
+    name="custom_redis_cache",
+    redis_client=redis_client,  # 使用自定义客户端
+    ttl=600
+)
+def load_custom_data(symbol: str) -> DataFrame:
+    print(f"加载自定义数据: {symbol}")
+    return DataFrame()
+```
+
+#### 4.4 DataFrame SQL 缓存 (`@sqlcached`)
+
+`@sqlcached` 是专门用于 DataFrame 的 SQL 数据库缓存装饰器，支持 SQLite、MySQL、PostgreSQL 等多种数据库。
+
+##### SQLite 缓存
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+from pandas import DataFrame
+
+@sqlcached(
+    db_type="sqlite",
+    db_url="sqlite:///cache.db",  # SQLite 数据库文件
+    ttl=3600
+)
+def fetch_data(symbol: str) -> Result[DataFrame]:
+    """必须声明返回类型为 Result[DataFrame]"""
+    print(f"从 API 获取 {symbol} 数据...")
+    df = DataFrame({
+        "symbol": [symbol],
+        "price": [100.0],
+        "timestamp": ["2024-01-01"]
+    })
+    return Result.success(df)
+```
+
+##### MySQL 缓存
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+from pandas import DataFrame
+
+@sqlcached(
+    db_type="mysql",
+    host="localhost",
+    port=3306,
+    db_name="cache_db",
+    username="root",
+    password="password",
+    pool_size=5,              # 连接池大小
+    max_overflow=10,          # 最大溢出连接数
+    pool_timeout=30,          # 连接超时（秒）
+    pool_recycle=3600,        # 连接回收时间（秒）
+    pool_pre_ping=True,       # 连接前测试
+    max_retry_attempts=3,     # 最大重试次数
+    retry_delay=1.0,          # 重试延迟（秒）
+    ttl=7200
+)
+def fetch_market_data(symbol: str) -> Result[DataFrame]:
+    print(f"获取 {symbol} 市场数据...")
+    df = DataFrame({
+        "symbol": [symbol],
+        "open": [100.0],
+        "high": [105.0],
+        "low": [99.0],
+        "close": [104.0]
+    })
+    return Result.success(df)
+```
+
+##### PostgreSQL 缓存
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+from pandas import DataFrame
+
+@sqlcached(
+    db_type="postgresql",
+    host="localhost",
+    port=5432,
+    db_name="cache_db",
+    username="postgres",
+    password="password",
+    ttl=3600
+)
+def fetch_analytics_data(date: str) -> Result[DataFrame]:
+    print(f"获取 {date} 分析数据...")
+    df = DataFrame({
+        "date": [date],
+        "views": [1000],
+        "clicks": [100]
+    })
+    return Result.success(df)
+```
+
+##### 完整配置参数
+
+```python
+from pynomad import sqlcached
+
+@sqlcached(
+    name="sql_cache",           # 缓存名称
+    second_name="data",         # 二级名称
+    maxsize=128,                # 最大缓存数量
+    eviction_policy="lru",      # 淘汰策略: lru/lfu/fifo/none
+    ttl=3600,                   # 缓存存活时间（秒）
+    value_loader=custom_loader, # 自定义 ValueLoader
+    
+    # 数据库配置
+    db_type="sqlite",           # 数据库类型: sqlite/mysql/postgresql
+    db_url="sqlite:///cache.db", # 数据库连接 URL（与 host/port/db_name 互斥）
+    
+    # 连接参数（与 db_url 互斥）
+    host="localhost",           # 数据库主机
+    port=3306,                  # 数据库端口
+    db_name="cache_db",         # 数据库名称
+    username="root",            # 用户名
+    password="password",        # 密码
+    
+    # 连接池配置
+    pool_size=5,                # 连接池大小
+    max_overflow=10,            # 最大溢出连接数
+    pool_timeout=30,            # 连接超时（秒）
+    pool_recycle=3600,          # 连接回收时间（秒）
+    pool_pre_ping=True,         # 连接前测试
+    
+    # 重试配置
+    max_retry_attempts=3,       # 最大重试次数
+    retry_delay=1.0,            # 重试延迟（秒）
+)
+def load_data(key: str) -> Result[DataFrame]:
+    return Result.success(DataFrame())
+```
+
+##### 使用场景
+
+- **结构化数据持久化**: 适合需要结构化存储的 DataFrame 数据
+- **需要复杂查询的场景**: 可以通过 SQL 查询筛选缓存数据
+- **数据分析和报表**: 支持大量数据的存储和查询
+- **大数据量缓存**: 相比文件缓存，SQL 数据库更擅长处理大数据量
+
+##### 重要提示
+
+**必须声明返回类型为 Result[DataFrame]**:
+
+```python
+# ✅ 正确
+@sqlcached(db_type="sqlite", db_url="sqlite:///cache.db", ttl=3600)
+def fetch_data(symbol: str) -> Result[DataFrame]:
+    df = DataFrame({"symbol": [symbol]})
+    return Result.success(df)
+
+# ❌ 错误（缺少类型注解）
+@sqlcached(db_type="sqlite", db_url="sqlite:///cache.db", ttl=3600)
+def fetch_data(symbol: str):
+    df = DataFrame({"symbol": [symbol]})
+    return Result.success(df)
+
+# ❌ 错误（返回类型不对）
+@sqlcached(db_type="sqlite", db_url="sqlite:///cache.db", ttl=3600)
+def fetch_data(symbol: str) -> DataFrame:
+    df = DataFrame({"symbol": [symbol]})
+    return df
+```
+
+---
+
+#### 4.5 三阶段处理模型详解
+
+DataFrame 缓存采用独特的三阶段处理模型，实现灵活的数据处理逻辑：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     DataFrame 缓存流程                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. GET 阶段（缓存提取）                                     │
+│     ├─ 从缓存读取 DataFrame                                  │
+│     ├─ 比较当前参数与缓存参数                                │
+│     ├─ 判断缓存是否可用                                      │
+│     └─ 返回缓存数据 或 刷新参数                              │
+│                                                             │
+│  2. PUT 阶段（数据合并）                                     │
+│     ├─ 获取新数据（函数执行）                                │
+│     ├─ 合并缓存数据和新数据                                  │
+│     └─ 缓存合并后的数据                                     │
+│                                                             │
+│  3. EXTRACT 阶段（数据提取）                                 │
+│     ├─ 从合并后的数据中提取返回数据                          │
+│     └─ 支持过滤、转换、切片等操作                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 4.6 自定义 ValueLoader
+
+`ValueLoader` 是实现三阶段处理逻辑的核心接口。
+
+##### 基本用法（使用默认加载器）
+
+```python
+from pynomad import df_memcached
+from pandas import DataFrame
+
+# 使用默认的 DefaultDataFrameValueLoader
+# 默认行为：参数相同返回缓存，参数不同刷新数据
+@df_memcached(ttl=600)
+def load_data(symbol: str, start_date: str) -> DataFrame:
+    print(f"加载数据: {symbol}, {start_date}")
+    return DataFrame()
+```
+
+##### 自定义 ValueLoader - 增量更新场景
+
+```python
+from pynomad.cache.dataframe.types import DataFrameValueLoader
+from pynomad import Result
+from pandas import DataFrame
+from datetime import datetime
+
+class IncrementalValueLoader(DataFrameValueLoader):
+    """增量更新 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict[str, Any]]:
+        """GET 阶段：检查缓存是否需要更新"""
+        # 获取缓存的参数
+        last_args = tuple(extra_params.get("args", ()))
+        last_kwargs = extra_params.get("kwargs", {})
+
+        # 参数相同，使用缓存
+        if last_args == args and last_kwargs == kwargs:
+            return Result.success(data=cached_df)
+
+        # 参数不同，返回刷新参数
+        return Result.client_error(
+            exception=Exception("参数变化，需要刷新"),
+            data={"args": args, "kwargs": kwargs}
+        )
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：合并新旧数据（增量更新）"""
+        # 如果缓存为空，直接返回新数据
+        if cached_df.empty:
+            return Result.success(data=new_df)
+
+        # 合并数据（去重）
+        merged_df = pd.concat([cached_df, new_df]).drop_duplicates()
+        return Result.success(data=merged_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：提取返回数据"""
+        # 直接返回合并后的数据
+        return Result.success(data=merged_df)
+
+# 使用自定义 ValueLoader
+@df_memcached(value_loader=IncrementalValueLoader(), ttl=600)
+def load_incremental_data(symbol: str) -> DataFrame:
+    print(f"加载增量数据: {symbol}")
+    return DataFrame()
+```
+
+##### 自定义 ValueLoader - 数据过滤场景
+
+```python
+class FilteredValueLoader(DataFrameValueLoader):
+    """支持参数过滤的 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict[str, Any]]:
+        """GET 阶段：直接返回缓存，过滤在 EXTRACT 阶段进行"""
+        if not cached_df.empty:
+            return Result.success(data=cached_df)
+
+        # 缓存为空，需要刷新
+        return Result.client_error(
+            exception=Exception("缓存为空"),
+            data={"args": args, "kwargs": kwargs}
+        )
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：直接缓存新数据（不合并）"""
+        return Result.success(data=new_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：根据参数过滤数据"""
+        # 从 kwargs 中获取过滤条件
+        symbol = kwargs.get("symbol")
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        # 应用过滤条件
+        filtered_df = merged_df
+        if symbol:
+            filtered_df = filtered_df[filtered_df["symbol"] == symbol]
+        if start_date:
+            filtered_df = filtered_df[filtered_df["date"] >= start_date]
+        if end_date:
+            filtered_df = filtered_df[filtered_df["date"] <= end_date]
+
+        return Result.success(data=filtered_df)
+
+# 使用过滤 ValueLoader
+@df_memcached(value_loader=FilteredValueLoader(), ttl=3600)
+def load_and_filter_data(
+    symbol: str,
+    start_date: str,
+    end_date: str
+) -> DataFrame:
+    print(f"加载数据: {symbol}, {start_date} ~ {end_date}")
+    # 从数据库加载全量数据
+    return DataFrame()
+```
+
+##### 自定义 ValueLoader - 时间窗口缓存
+
+```python
+class TimeWindowValueLoader(DataFrameValueLoader):
+    """时间窗口缓存 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict[str, Any]]:
+        """GET 阶段：检查缓存是否覆盖请求的时间范围"""
+        if cached_df.empty:
+            return Result.client_error(
+                exception=Exception("缓存为空"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        # 获取请求的时间范围
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        # 检查缓存是否覆盖请求范围
+        cache_start = cached_df["date"].min()
+        cache_end = cached_df["date"].max()
+
+        if start_date and cache_start > pd.Timestamp(start_date):
+            return Result.client_error(
+                exception=Exception(f"缓存起始时间 {cache_start} 晚于请求时间 {start_date}"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        if end_date and cache_end < pd.Timestamp(end_date):
+            return Result.client_error(
+                exception=Exception(f"缓存结束时间 {cache_end} 早于请求时间 {end_date}"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        # 缓存覆盖请求范围
+        return Result.success(data=cached_df)
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：扩展缓存的时间范围"""
+        # 合并数据并去重
+        merged_df = pd.concat([cached_df, new_df]).drop_duplicates()
+        return Result.success(data=merged_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：返回请求时间范围内的数据"""
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        filtered_df = merged_df
+        if start_date:
+            filtered_df = filtered_df[filtered_df["date"] >= pd.Timestamp(start_date)]
+        if end_date:
+            filtered_df = filtered_df[filtered_df["date"] <= pd.Timestamp(end_date)]
+
+        return Result.success(data=filtered_df)
+
+# 使用时间窗口 ValueLoader
+@df_memcached(value_loader=TimeWindowValueLoader(), ttl=7200)
+def load_time_series_data(
+    symbol: str,
+    start_date: str,
+    end_date: str
+) -> DataFrame:
+    print(f"加载时间序列: {symbol}, {start_date} ~ {end_date}")
+    return DataFrame()
+```
+
+#### 4.7 DataFrame 缓存常见场景
+
+##### 场景1：股票数据缓存
+
+```python
+from pynomad import df_pickled
+from pandas import DataFrame
+from datetime import datetime, timedelta
+
+@df_pickled(
+    name="stock_cache",
+    cache_dir="./stock_cache",
+    ttl=86400  # 24小时
+)
+def get_stock_daily(
+    symbol: str,
+    start_date: str,
+    end_date: str
+) -> DataFrame:
+    """获取股票日线数据"""
+    print(f"从 API 获取 {symbol} 数据: {start_date} ~ {end_date}")
+    # 模拟数据
+    dates = pd.date_range(start_date, end_date)
+    return DataFrame({
+        "symbol": [symbol] * len(dates),
+        "date": dates,
+        "open": [100.0] * len(dates),
+        "high": [105.0] * len(dates),
+        "low": [98.0] * len(dates),
+        "close": [103.0] * len(dates),
+        "volume": [1000000] * len(dates)
+    })
+
+# 第一次调用（从 API 加载）
+df1 = get_stock_daily("AAPL", "2024-01-01", "2024-01-10")
+# 第二次调用（从缓存读取）
+df2 = get_stock_daily("AAPL", "2024-01-01", "2024-01-10")
+```
+
+##### 场景2：实时行情缓存
+
+```python
+from pynomad import df_rediscached
+
+@df_rediscached(
+    name="realtime_cache",
+    host="localhost",
+    port=6379,
+    ttl=5  # 5秒过期
+)
+def get_realtime_quotes(symbols: list[str]) -> DataFrame:
+    """获取实时行情"""
+    print(f"获取实时行情: {symbols}")
+    # 模拟数据
+    return DataFrame({
+        "symbol": symbols,
+        "price": [100.0 + i for i in range(len(symbols))],
+        "change": [1.0] * len(symbols),
+        "change_pct": [1.0] * len(symbols),
+        "timestamp": [datetime.now()] * len(symbols)
+    })
+
+# 首次调用（从数据源获取）
+quotes1 = get_realtime_quotes(["AAPL", "GOOGL", "MSFT"])
+
+# 5秒内调用（从缓存读取）
+quotes2 = get_realtime_quotes(["AAPL", "GOOGL", "MSFT"])
+
+# 5秒后调用（重新获取）
+# time.sleep(6)
+# quotes3 = get_realtime_quotes(["AAPL", "GOOGL", "MSFT"])
+```
+
+##### 场景3：技术指标缓存
+
+```python
+from pynomad import df_memcached
+
+@df_memcached(
+    name="indicator_cache",
+    ttl=3600  # 1小时
+)
+def calculate_sma(
+    df: DataFrame,
+    period: int = 20
+) -> DataFrame:
+    """计算简单移动平均线"""
+    print(f"计算 SMA({period})")
+    df = df.copy()
+    df[f"sma_{period}"] = df["close"].rolling(window=period).mean()
+    return df
+
+# 使用示例
+import pandas as pd
+prices = pd.DataFrame({
+    "date": pd.date_range("2024-01-01", periods=100),
+    "close": [100 + i * 0.5 for i in range(100)]
+})
+
+# 首次计算
+result1 = calculate_sma(prices, period=20)
+
+# 再次使用相同参数（从缓存）
+result2 = calculate_sma(prices, period=20)
+```
+
+#### 4.8 DataFrame 缓存最佳实践
+
+1. **选择合适的缓存类型**:
+   - 临时数据 → `@df_memcached`
+   - 需要持久化 → `@df_pickled`
+   - 分布式场景 → `@df_rediscached`
+   - 结构化数据/大数据量 → `@sqlcached`
+
+2. **合理设置 TTL**:
+   - 实时数据 → 短 TTL（秒级）
+   - 日线数据 → 中 TTL（小时级）
+   - 历史数据 → 长 TTL（天级）
+
+3. **使用自定义 ValueLoader**:
+   - 增量更新场景
+   - 数据过滤场景
+   - 时间窗口缓存
+
+4. **注意内存管理**:
+   - 设置合理的 `maxsize`
+   - 使用合适的淘汰策略
+   - 定期清理过期缓存
+
+5. **根据数据量选择存储**:
+   - 小数据量 → 内存或文件缓存
+   - 中等数据量 → Redis 缓存
+   - 大数据量 → SQL 缓存
+
+#### 4.9 DataFrame 缓存常见问题
+
+**Q: 为什么函数必须声明返回类型？**
+
+A: DataFrame 缓存装饰器需要区分返回 `DataFrame` 和 `Result[DataFrame]`，以便正确处理装箱和缓存一致性。这是 Python 动态类型系统的局限性。
+
+```python
+# ✅ 正确 - @df_memcached, @df_pickled, @df_rediscached 返回 DataFrame
+@df_memcached(ttl=60)
+def load_data() -> DataFrame:
+    return DataFrame()
+
+# ✅ 正确 - @sqlcached 返回 Result[DataFrame]
+@sqlcached(db_type="sqlite", db_url="sqlite:///cache.db", ttl=60)
+def fetch_data() -> Result[DataFrame]:
+    return Result.success(DataFrame())
+
+# ❌ 错误（缺少类型注解）
+@df_memcached(ttl=60)
+def load_data():
+    return DataFrame()
+```
+
+**Q: 如何处理大数据量的 DataFrame？**
+
+A: 建议使用 `@df_pickled`、`@df_rediscached` 或 `@sqlcached`，避免内存溢出。同时可以：
+- 设置合理的 `maxsize`
+- 使用数据分片
+- 在 `extract` 阶段过滤返回的数据
+- 对于大数据量，优先使用 `@sqlcached`
+
+**Q: 如何实现缓存预热？**
+
+A: 在应用启动时，主动调用一次带所有必要参数的函数：
+
+```python
+# 预热缓存
+get_stock_daily("AAPL", "2024-01-01", "2024-12-31")
+get_stock_daily("GOOGL", "2024-01-01", "2024-12-31")
+get_stock_daily("MSFT", "2024-01-01", "2024-12-31")
+```
+
+---
+
+### 5. 多级缓存
+
+#### 双级缓存（L1 + L2）
+
+```python
+from pynomad import multi_level_cached
+
+@multi_level_cached(
+    name="my_cache",
+    l1_code="memory",       # L1: 内存缓存
+    l2_code="pickle",        # L2: 文件缓存
+    l1_ttl=60,              # L1: 1分钟
+    l2_ttl=3600             # L2: 1小时
+)
+def get_config(key: str) -> str:
+    print(f"加载配置: {key}")
+    return "config_value"
+```
+
+#### 三级缓存（L1 + L2 + L3）
+
+```python
+from pynomad import multi_level_cached
+
+@multi_level_cached(
+    name="my_cache",
+    l1_code="memory",       # L1: 内存
+    l2_code="pickle",        # L2: 文件
+    l3_code="redis",         # L3: Redis
+    l1_ttl=10,               # L1: 10秒
+    l2_ttl=60,               # L2: 1分钟
+    l3_ttl=300               # L3: 5分钟
+)
+def get_data(key: str) -> dict:
+    print(f"获取数据: {key}")
+    return {"key": key, "value": "data"}
+```
+
+#### 读穿透策略
+
+```
+请求 → L1 缓存
+       ├─ 命中 → 返回数据
+       └─ 未命中 → L2 缓存
+                  ├─ 命中 → 缓存到 L1 → 返回数据
+                  └─ 未命中 → L3 缓存
+                             ├─ 命中 → 缓存到 L2, L1 → 返回数据
+                             └─ 未命中 → 执行函数 → 缓存到 L3, L2, L1 → 返回数据
+```
+
+#### 写穿透策略
+
+```
+函数执行 → 写入 L1
+         → 写入 L2
+         → 写入 L3
+```
+
+#### 管理缓存
+
+```python
+from pynomad import multi_level_cached
+
+# 获取统计信息
+@multi_level_cached(name="my_cache", l1_code="memory", l2_code="pickle")
+def get_data(key: str):
+    return fetch_from_db(key)
+
+# 访问装饰器实例
+decorator = get_data.__wrapped__.__closure__[0].cell_contents
+
+# 清空所有缓存
+decorator.clear()
+
+# 获取缓存统计
+stats = decorator.get_stats()
+print(stats)
+# 输出: {'l1': {'size': 10}, 'l2': {'size': 5}}
+```
+
+#### 使用场景
+
+- 需要高性能和高可靠性
+- 热点数据频繁访问
+- 降低后端压力
+- 容灾备份
+
+---
+
+### 6. 缓存键生成器
+
+#### 默认键生成器
+
+```python
+from pynomad import memcached
+
+@memcached
+def get_user(user_id: int) -> dict:
+    # 键格式: module.function:args_kwargs
+    pass
+
+# 键示例: mymodule.get_user:(1,):{}
+```
+
+#### 模块函数键生成器
+
+```python
+from pynomad.cache.decorator.keygenerator import module_function_key_generator
+
+@memcached(keygenerator=module_function_key_generator)
+def get_product(product_id: str) -> dict:
+    # 键格式: module.function:args_kwargs
+    pass
+```
+
+#### 自定义键生成器
+
+```python
+from pynomad import memcached
+from pynomad.cache.core.types import KeyGenerator
+
+def custom_key_generator(func, instance, args, kwargs) -> str:
+    """自定义键生成逻辑"""
+    # 简化键，只使用特定参数
+    return f"{func.__name__}:{args[0]}"
+
+@memcached(keygenerator=custom_key_generator)
+def get_data(user_id: int, timestamp: int) -> dict:
+    # 键格式: get_data:1 (忽略 timestamp)
+    pass
+```
+
+---
+
+### 7. 缓存配置详解
+
+#### 7.1 通用配置参数
+
+所有缓存类型都支持的通用参数：
+
+| 参数 | 类型 | 默认值 | 说明 | 适用缓存类型 |
+|------|------|--------|------|-------------|
+| `name` | `str` | `"default"` | 缓存名称，用于区分不同的缓存实例 | 所有 |
+| `ttl` | `int` | `3600` | 缓存存活时间（秒），`0` 表示永不过期 | 所有 |
+| `maxsize` | `int` | `100` | 最大缓存数量，`0` 表示无限制 | 所有 |
+| `eviction_policy` | `str` | `"lru"` | 淘汰策略：`lru`/`lfu`/`fifo`/`none` | 内存类缓存 |
+| `enable_encryption` | `bool` | `False` | 是否启用数据加密 | 持久化缓存 |
+| `salt` | `str` | `None` | 加密盐值，用于生成加密密钥 | 持久化缓存 |
+
+**通用配置示例：**
+
+```python
+from pynomad import memcached, pickled, rediscached
+
+# 内存缓存配置
+@memcached(
+    name="user_cache",
+    ttl=600,                    # 10分钟过期
+    maxsize=1000,               # 最多缓存1000个用户
+    eviction_policy="lru"       # LRU淘汰策略
+)
+def get_user(user_id: int) -> dict:
+    return fetch_user_from_db(user_id)
+
+# 文件缓存配置
+@pickled(
+    name="config_cache",
+    ttl=86400,                  # 24小时过期
+    maxsize=500,
+    cache_dir="./cache",        # 缓存目录
+    enable_encryption=True,     # 启用加密
+    salt="app_v1.0"            # 加密盐值
+)
+def load_app_config() -> dict:
+    return load_config_file()
+
+# Redis 缓存配置
+@rediscached(
+    name="product_cache",
+    ttl=1800,                   # 30分钟过期
+    maxsize=2000,
+    host="localhost",
+    port=6379,
+    db=0,
+    enable_encryption=True,
+    salt="redis_cache_v1"
+)
+def get_product(product_id: str) -> dict:
+    return fetch_product_from_db(product_id)
+```
+
+---
+
+#### 7.2 Memory Cache 专属配置
+
+Memory Cache（内存缓存）的专属配置：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| 无专属参数 | - | - | 使用通用配置 |
+
+**淘汰策略详解：**
+
+```python
+from pynomad import memcached
+
+# LRU (Least Recently Used) - 最久未使用淘汰
+@memcached(
+    ttl=60,
+    maxsize=100,
+    eviction_policy="lru"  # ✅ 最常用，淘汰最久未访问的数据
+)
+def get_lru_cache(key: str):
+    pass
+
+# LFU (Least Frequently Used) - 最少使用频率淘汰
+@memcached(
+    ttl=60,
+    maxsize=100,
+    eviction_policy="lfu"  # 适用于访问模式稳定的数据
+)
+def get_lfu_cache(key: str):
+    pass
+
+# FIFO (First In First Out) - 先进先出淘汰
+@memcached(
+    ttl=60,
+    maxsize=100,
+    eviction_policy="fifo"  # 适用于时间序列数据
+)
+def get_fifo_cache(key: str):
+    pass
+
+# None - 不淘汰，缓存满时拒绝写入
+@memcached(
+    ttl=60,
+    maxsize=100,
+    eviction_policy="none"  # 适用于大小可控的缓存
+)
+def get_none_cache(key: str):
+    pass
+```
+
+---
+
+#### 7.3 Pickle Cache 专属配置
+
+Pickle Cache（文件缓存）的专属配置：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_dir` | `str` | `"./.pynomad_cache"` | 缓存文件存储目录 |
+| `enable_background_cleanup` | `bool` | `False` | 是否启用后台清理任务 |
+| `cleanup_interval` | `int` | `300` | 后台清理间隔（秒） |
+
+**完整配置示例：**
+
+```python
+from pynomad import pickled
+
+@pickled(
+    name="historical_data",
+    ttl=86400,                       # 24小时过期
+    maxsize=500,
+    cache_dir="./cache/data",        # 自定义缓存目录
+    enable_encryption=True,          # 启用加密
+    salt="finance_v2.0",             # 加密盐值
+    enable_background_cleanup=True,   # 启用后台清理
+    cleanup_interval=600              # 每10分钟清理一次
+)
+def load_historical_data(symbol: str) -> dict:
+    return fetch_historical_data(symbol)
+```
+
+**目录结构示例：**
+
+```
+cache/
+└── data/
+    ├── historical_data/
+    │   ├── key1.pkl
+    │   ├── key2.pkl
+    │   └── .metadata.json
+    └── historical_data_cleanup.log
+```
+
+---
+
+#### 7.4 Redis Cache 专属配置
+
+Redis Cache 的专属配置：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `host` | `str` | `"localhost"` | Redis 主机地址 |
+| `port` | `int` | `6379` | Redis 端口 |
+| `db` | `int` | `0` | Redis 数据库编号（0-15） |
+| `username` | `str` | `None` | Redis 用户名（Redis 6.0+） |
+| `password` | `str` | `None` | Redis 密码 |
+| `redis_client` | `Redis` | `None` | 自定义 Redis 客户端实例 |
+
+**方式一：使用连接参数配置**
+
+```python
+from pynomad import rediscached
+
+@rediscached(
+    name="order_cache",
+    ttl=1800,                   # 30分钟过期
+    maxsize=1000,
+    host="localhost",           # Redis 主机
+    port=6379,                  # Redis 端口
+    db=0,                       # 数据库编号
+    username="default",          # 用户名（可选）
+    password="your_password",    # 密码（可选）
+    enable_encryption=True,
+    salt="redis_v1"
+)
+def get_order(order_id: str) -> dict:
+    return fetch_order_from_db(order_id)
+```
+
+**方式二：使用自定义 Redis 客户端**
+
+```python
+from redis import Redis, ConnectionPool
+from pynomad import rediscached
+
+# 创建连接池
+pool = ConnectionPool(
+    host="localhost",
+    port=6379,
+    db=0,
+    username="default",
+    password="your_password",
+    max_connections=20,          # 最大连接数
+    socket_timeout=5,            # Socket 超时（秒）
+    socket_connect_timeout=5,    # 连接超时（秒）
+    retry_on_timeout=True        # 超时重试
+)
+
+# 创建 Redis 客户端
+redis_client = Redis(connection_pool=pool)
+
+@rediscached(
+    name="product_cache",
+    redis_client=redis_client,  # 使用自定义客户端
+    ttl=3600
+)
+def get_product(product_id: str) -> dict:
+    return fetch_product_from_db(product_id)
+```
+
+**连接池配置建议：**
+
+```python
+# 高并发场景
+pool = ConnectionPool(
+    host="redis.example.com",
+    port=6379,
+    password="password",
+    max_connections=50,         # 更多连接
+    socket_timeout=3,
+    socket_connect_timeout=3,
+    decode_responses=False      # 保持字节返回（适合二进制数据）
+)
+
+# 低延迟场景
+pool = ConnectionPool(
+    host="127.0.0.1",           # 使用本地回环地址
+    port=6379,
+    max_connections=10,
+    socket_timeout=1,           # 短超时
+    socket_connect_timeout=1
+)
+```
+
+---
+
+#### 7.5 SQL Cache 专属配置
+
+SQL Cache 的专属配置：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `db_type` | `str` | `"sqlite"` | 数据库类型：`sqlite`/`mysql`/`postgresql` |
+| `db_url` | `str` | `None` | 完整数据库连接 URL（优先级高于其他参数） |
+| `host` | `str` | `"localhost"` | 数据库主机地址 |
+| `port` | `int` | `None` | 数据库端口 |
+| `db_name` | `str` | `None` | 数据库名称 |
+| `username` | `str` | `None` | 数据库用户名 |
+| `password` | `str` | `None` | 数据库密码 |
+| `schema` | `str` | `"public"` | 数据库 schema（PostgreSQL） |
+| `pool_size` | `int` | `5` | 连接池大小 |
+| `max_overflow` | `int` | `10` | 最大溢出连接数 |
+| `pool_timeout` | `int` | `30` | 连接超时（秒） |
+| `pool_recycle` | `int` | `3600` | 连接回收时间（秒） |
+| `pool_pre_ping` | `bool` | `True` | 连接前测试可用性 |
+| `max_retry_attempts` | `int` | `3` | 最大重试次数 |
+| `retry_delay` | `float` | `1.0` | 重试延迟（秒） |
+
+**方式一：使用 db_url（推荐）**
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+from pandas import DataFrame
+
+# SQLite
+@sqlcached(
+    db_type="sqlite",
+    db_url="sqlite:///./cache.db",  # 相对路径
+    ttl=3600
+)
+def fetch_data(symbol: str) -> Result[DataFrame]:
+    df = fetch_from_api(symbol)
+    return Result.success(df)
+
+# MySQL
+@sqlcached(
+    db_type="mysql",
+    db_url="mysql+pymysql://user:password@localhost:3306/cache_db",
+    ttl=3600
+)
+def fetch_market_data(symbol: str) -> Result[DataFrame]:
+    df = fetch_from_api(symbol)
+    return Result.success(df)
+
+# PostgreSQL
+@sqlcached(
+    db_type="postgresql",
+    db_url="postgresql://user:password@localhost:5432/cache_db",
+    ttl=3600
+)
+def fetch_stock_data(symbol: str) -> Result[DataFrame]:
+    df = fetch_from_api(symbol)
+    return Result.success(df)
+```
+
+**方式二：使用连接参数**
+
+```python
+from pynomad import sqlcached
+
+@sqlcached(
+    db_type="mysql",
+    host="localhost",
+    port=3306,
+    db_name="cache_db",
+    username="root",
+    password="password",
+    schema="cache_schema",              # 自定义 schema
+    pool_size=5,                        # 连接池大小
+    max_overflow=10,                    # 最大溢出连接数
+    pool_timeout=30,                    # 连接超时
+    pool_recycle=3600,                  # 连接回收时间（1小时）
+    pool_pre_ping=True,                 # 连接前测试
+    max_retry_attempts=3,               # 最大重试次数
+    retry_delay=1.0,                    # 重试延迟
+    ttl=7200
+)
+def fetch_historical_data(symbol: str) -> Result[DataFrame]:
+    df = fetch_from_api(symbol)
+    return Result.success(df)
+```
+
+**连接池配置建议：**
+
+```python
+# 小型应用
+pool_size=5,
+max_overflow=10,
+pool_timeout=30
+
+# 中型应用
+pool_size=10,
+max_overflow=20,
+pool_timeout=20
+
+# 大型应用/高并发
+pool_size=20,
+max_overflow=30,
+pool_timeout=10,
+pool_recycle=1800  # 30分钟回收，防止连接僵死
+```
+
+---
+
+#### 7.6 DataFrame 缓存专属配置
+
+DataFrame 缓存除了继承各自存储类型的配置外，还支持以下参数：
+
+| 参数 | 类型 | 默认值 | 说明 | 适用装饰器 |
+|------|------|--------|------|-----------|
+| `value_loader` | `DataFrameValueLoader` | `None` | 自定义数据加载器 | 所有 DataFrame 缓存 |
+| `keygenerator` | `KeyGenerator` | `None` | 自定义键生成器 | 所有 DataFrame 缓存 |
+
+**自定义 ValueLoader 配置：**
+
+```python
+from pynomad import df_memcached
+from pynomad.cache.dataframe.types import DataFrameValueLoader
+from pandas import DataFrame
+
+class StockDataValueLoader(DataFrameValueLoader):
+    def get(self, cached_df, extra_params, args, kwargs):
+        # GET 阶段逻辑
+        pass
+
+    def put(self, cached_df, new_df, extra_params, args, kwargs):
+        # PUT 阶段逻辑
+        pass
+
+    def extract(self, merged_df, extra_params, args, kwargs):
+        # EXTRACT 阶段逻辑
+        pass
+
+@df_memcached(
+    name="stock_cache",
+    ttl=600,
+    value_loader=StockDataValueLoader()  # 自定义加载器
+)
+def get_stock_data(code: str, start_date: str, end_date: str) -> DataFrame:
+    return fetch_stock_from_api(code, start_date, end_date)
+```
+
+**自定义 KeyGenerator 配置：**
+
+```python
+from pynomad import df_memcached
+from pynomad.cache.core.keygenerator import KeyGenerator
+
+def stock_key_generator(func, args, kwargs):
+    # 只使用 code 和 fq 生成键，忽略时间范围
+    code = args[0]
+    fq = kwargs.get("fq", "qfq")
+    return f"{func.__name__}:{code}:{fq}"
+
+@df_memcached(
+    name="stock_cache",
+    ttl=600,
+    keygenerator=stock_key_generator  # 自定义键生成器
+)
+def get_stock_data(code: str, start_date: str, end_date: str, fq: str = "qfq") -> DataFrame:
+    return fetch_stock_from_api(code, start_date, end_date, fq)
+```
+
+---
+
+#### 7.7 配置文件集成
+
+使用 `@inject` 装饰器从 `settings.toml` 配置文件加载缓存配置：
+
+**配置文件 `settings.toml`：**
+
+```toml
+# settings.toml - pynomad 配置文件
+[cache.redis]
+host = "redis.example.com"
+port = 6379
+db = 0
+password = "${REDIS_PASSWORD}"
+ttl = 3600
+
+[cache.mysql]
+host = "mysql.example.com"
+port = 3306
+db_name = "cache_db"
+username = "cache_user"
+password = "${DB_PASSWORD}"
+pool_size = 10
+max_overflow = 20
+
+[cache.postgresql]
+host = "postgres.example.com"
+port = 5432
+db_name = "cache_db"
+username = "cache_user"
+password = "${DB_PASSWORD}"
+pool_size = 5
+
+[cache.memory]
+ttl = 600
+maxsize = 1000
+
+[cache.pickle]
+cache_dir = "./cache"
+enable_encryption = true
+salt = "app_v1.0"
+```
+
+**使用配置类加载 Redis 配置：**
+
+```python
+from pynomad.config.auto import inject
+from pynomad.config.auto.field_info import field
+from pynomad import rediscached
+
+@inject(prefix="cache.redis")
+class RedisCacheConfig:
+    """Redis 缓存配置"""
+    host: str = field(default="localhost")
+    port: int = field(default=6379)
+    db: int = field(default=0)
+    password: str = field(default="")
+    ttl: int = field(default=3600)
+
+redis_config = RedisCacheConfig()
+
+@rediscached(
+    name="user_cache",
+    host=redis_config.host,
+    port=redis_config.port,
+    db=redis_config.db,
+    password=redis_config.password,
+    ttl=redis_config.ttl
+)
+def get_user(user_id: int) -> dict:
+    return fetch_user_from_db(user_id)
+```
+
+**使用配置类加载 MySQL 缓存配置：**
+
+```python
+from pynomad import sqlcached
+from pynomad.result import Result
+
+@inject(prefix="cache.mysql")
+class MySQLCacheConfig:
+    """MySQL 缓存配置"""
+    host: str = field(default="localhost")
+    port: int = field(default=3306)
+    db_name: str = field(default="cache_db")
+    username: str = field(default="root")
+    password: str = field(default="")
+    pool_size: int = field(default=5)
+    max_overflow: int = field(default=10)
+
+mysql_config = MySQLCacheConfig()
+
+@sqlcached(
+    db_type="mysql",
+    host=mysql_config.host,
+    port=mysql_config.port,
+    db_name=mysql_config.db_name,
+    username=mysql_config.username,
+    password=mysql_config.password,
+    pool_size=mysql_config.pool_size,
+    max_overflow=mysql_config.max_overflow,
+    ttl=3600
+)
+def fetch_market_data(symbol: str) -> Result[DataFrame]:
+    df = fetch_from_api(symbol)
+    return Result.success(df)
+```
+
+**使用配置类加载 Memory 缓存配置：**
+
+```python
+from pynomad import memcached
+
+@inject(prefix="cache.memory")
+class MemoryCacheConfig:
+    """内存缓存配置"""
+    ttl: int = field(default=600)
+    maxsize: int = field(default=1000)
+
+memory_config = MemoryCacheConfig()
+
+@memcached(
+    name="session_cache",
+    ttl=memory_config.ttl,
+    maxsize=memory_config.maxsize
+)
+def get_session_data(session_id: str) -> dict:
+    return fetch_session_from_redis(session_id)
+```
+
+**配置文件路径说明：**
+
+`settings.toml` 文件应放在以下位置之一（按优先级顺序）：
+
+1. 项目根目录：`./settings.toml`
+2. 配置目录：`./config/settings.toml`
+3. 用户目录：`~/.pynomad/settings.toml`
+4. 环境变量指定的路径：`PYNOMAD_CONFIG_PATH`
+
+**环境变量替换：**
+
+配置文件支持环境变量替换：
+
+```toml
+# settings.toml
+[cache.redis]
+password = "${REDIS_PASSWORD}"  # 从环境变量读取
+
+[cache.mysql]
+password = "${DB_PASSWORD}"
+```
+
+**完整示例：项目结构**
+
+```
+my_project/
+├── settings.toml              # 配置文件
+├── main.py                     # 主程序
+└── cache/                      # 缓存目录
+```
+
+**settings.toml：**
+
+```toml
+[cache.redis]
+host = "localhost"
+port = 6379
+db = 0
+password = "${REDIS_PASSWORD}"
+ttl = 1800
+
+[cache.mysql]
+host = "localhost"
+port = 3306
+db_name = "cache_db"
+username = "cache_user"
+password = "${DB_PASSWORD}"
+pool_size = 10
+max_overflow = 20
+
+[cache.memory]
+ttl = 600
+maxsize = 1000
+
+[cache.pickle]
+cache_dir = "./cache"
+enable_encryption = true
+salt = "my_app_v1"
+```
+
+---
+
+#### 7.8 配置优先级
+
+参数优先级（从高到低）：
+
+1. **装饰器参数**：直接在装饰器中传入的参数（优先级最高）
+2. **配置文件**：通过 `@inject` 从配置文件加载的值
+3. **硬编码默认值**：代码中定义的默认值（优先级最低）
+
+```python
+from pynomad import rediscached
+
+# 优先级1: 装饰器参数（优先级最高）
+@rediscached(
+    host="custom.host",        # ✅ 使用此值
+    ttl=60                     # ✅ 使用此值
+)
+def my_function():
+    pass
+
+# 如果配置文件中设置了：
+# cache.redis.host = "config.host"
+# cache.redis.ttl = 300
+#
+# 实际使用 host="custom.host", ttl=60
+```
+
+---
+
+### 8. 缓存最佳实践
+
+#### 选择合适的缓存类型
+
+```python
+# 临时数据 → Memory Cache
+@memcached(ttl=60)
+def get_session_data():
+    pass
+
+# 需要持久化 → Pickle Cache
+@pickled(ttl=3600)
+def get_cached_config():
+    pass
+
+# 分布式系统 → Redis Cache
+@rediscached(ttl=300)
+def get_shared_data():
+    pass
+
+# DataFrame 结构化数据/大数据量 → SQL Cache
+@sqlcached(db_type="sqlite")
+def get_structured_data() -> Result[DataFrame]:
+    return Result.success(DataFrame())
+```
+
+#### 合理设置 TTL
+
+```python
+# 高频变化的数据 → 短 TTL
+@memcached(ttl=10)
+def get_realtime_price():
+    pass
+
+# 相对稳定的数据 → 长 TTL
+@pickled(ttl=86400)  # 24小时
+def get_static_config():
+    pass
+```
+
+#### 处理缓存失效
+
+```python
+from pynomad import memcached, rediscached
+from pynomad.common.exceptions import NeedsRefreshException
+
+@memcached(ttl=60)
+def get_data_with_refresh(key: str) -> dict:
+    # 如果需要强制刷新，抛出 NeedsRefreshException
+    if needs_refresh:
+        raise NeedsRefreshException({"refresh_key": key})
+    return fetch_from_db(key)
+```
+
+#### 监控缓存效果
+
+```python
+import time
+from pynomad import memcached
+
+@memcached(ttl=60)
+def timed_function():
+    start = time.time()
+    result = expensive_operation()
+    print(f"执行时间: {time.time() - start:.2f}秒")
+    return result
+
+# 第一次调用（缓存未命中）
+timed_function()  # 执行时间: 2.50秒
+
+# 第二次调用（缓存命中）
+timed_function()  # 执行时间: 0.00秒
+```
+
+---
+
+### 9. 清除缓存
+
+#### 9.1 等待 TTL 过期（推荐）
+
+缓存会在设定的 TTL 时间后自动过期，这是最简单和可靠的方式：
+
+```python
+from pynomad import memcached
+
+@memcached(ttl=60)  # 60秒后自动过期
+def get_data():
+    return expensive_operation()
+```
+
+#### 9.2 通过 CacheRegistry 清除指定缓存
+
+使用缓存名称清除所有关联的缓存：
+
+```python
+from pynomad import memcached
+from pynomad.cache.core.cache_registry import CacheRegistry
+
+@memcached(name="user_cache", ttl=3600)
+def get_user(user_id: int) -> dict:
+    return fetch_user_from_db(user_id)
+
+# 清除所有名为 "user_cache" 的缓存
+cache = CacheRegistry.get("user_cache")
+cache.clear()
+```
+
+#### 9.3 重启应用
+
+重启应用可以清除所有内存缓存：
+
+- **内存缓存**：应用重启时自动清空
+- **文件/Redis/SQL 缓存**：在缓存过期后失效
+
+#### 9.4 清除特定键的缓存
+
+某些缓存类型支持清除特定键：
+
+```python
+# Redis 缓存示例
+from pynomad import rediscached
+
+@rediscached(name="product_cache", ttl=1800)
+def get_product(product_id: str) -> dict:
+    return fetch_product_from_db(product_id)
+
+# 获取缓存实例
+cache = CacheRegistry.get("product_cache")
+
+# 删除特定键
+cache.delete("get_product:12345")
+```
+
+---
+
+### 10. 常见问题
+
+#### Q: 缓存未生效？
+
+A: 检查以下几点：
+1. 函数参数是否可哈希（避免使用列表、字典等）
+2. TTL 是否设置为 0（永不过期）
+3. 缓存装饰器是否正确应用
+
+#### Q: 如何调试缓存？
+
+```python
+from pynomad.logsystem.manager import get_logger
+
+logger = get_logger()
+logger.set_level("TRACE")  # 开启详细日志
+
+@memcached(ttl=60)
+def my_function():
+    pass
+```
+
+#### Q: DataFrame 缓存报错？
+
+A: 确保函数声明了正确的返回类型注解：
+
+```python
+# ✅ 正确
+@df_memcached(ttl=60)
+def load_data() -> DataFrame:
+    return DataFrame()
+
+# ❌ 错误（缺少类型注解）
+@df_memcached(ttl=60)
+def load_data():
+    return DataFrame()
+```
+
+---
+
+### 11. 自定义缓存实践
+
+#### 10.1 自定义键生成器
+
+键生成器决定了缓存的存储键，可以根据业务需求自定义键的生成逻辑。
+
+##### 基本用法
+
+```python
+from pynomad import memcached
+from pynomad.cache.core.types import KeyGenerator
+
+def custom_key_generator(func, instance, args, kwargs) -> str:
+    """自定义键生成逻辑"""
+    # 只使用函数名和第一个参数作为键
+    return f"{func.__name__}:{args[0]}"
+
+@memcached(keygenerator=custom_key_generator)
+def get_data(user_id: int, timestamp: int) -> dict:
+    # 键格式: get_data:1 (忽略 timestamp)
+    return fetch_from_db(user_id)
+```
+
+##### 场景1: 简化键（忽略某些参数）
+
+```python
+from pynomad import memcached
+
+def ignore_timestamp_key_generator(func, instance, args, kwargs) -> str:
+    """忽略时间戳参数"""
+    # 只使用 user_id 作为键，忽略 timestamp
+    user_id = kwargs.get("user_id") or args[0]
+    return f"{func.__name__}:user_{user_id}"
+
+@memcached(keygenerator=ignore_timestamp_key_generator)
+def get_user_data(user_id: int, timestamp: int) -> dict:
+    # 即使 timestamp 变化，也使用相同的缓存
+    return fetch_user_data(user_id)
+```
+
+##### 场景2: 组合多个参数
+
+```python
+def combined_key_generator(func, instance, args, kwargs) -> str:
+    """组合多个参数作为键"""
+    user_id = kwargs.get("user_id") or args[0]
+    region = kwargs.get("region") or args[1]
+    # 使用 region 和 user_id 的组合
+    return f"{func.__name__}:{region}:{user_id}"
+
+@memcached(keygenerator=combined_key_generator)
+def get_user_data_by_region(user_id: int, region: str) -> dict:
+    return fetch_user_data(user_id, region)
+```
+
+#### 10.2 自定义 ValueLoader（DataFrame 缓存）
+
+ValueLoader 是 DataFrame 缓存三阶段处理的核心，可以实现灵活的数据处理逻辑。
+
+##### 场景1: 增量更新
+
+```python
+from pynomad.cache.dataframe.types import DataFrameValueLoader
+from pynomad import Result, df_memcached
+from pandas import DataFrame
+
+class IncrementalValueLoader(DataFrameValueLoader):
+    """增量更新 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict]:
+        """GET 阶段：参数变化时需要刷新"""
+        last_args = tuple(extra_params.get("args", ()))
+        if last_args == args:
+            return Result.success(data=cached_df)
+        return Result.client_error(
+            exception=Exception("参数变化"),
+            data={"args": args, "kwargs": kwargs}
+        )
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：合并新旧数据（去重）"""
+        if cached_df.empty:
+            return Result.success(data=new_df)
+        merged_df = pd.concat([cached_df, new_df]).drop_duplicates()
+        return Result.success(data=merged_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：返回合并数据"""
+        return Result.success(data=merged_df)
+
+@df_memcached(value_loader=IncrementalValueLoader(), ttl=600)
+def load_incremental_data(symbol: str) -> DataFrame:
+    """增量加载数据"""
+    return fetch_data(symbol)
+```
+
+##### 场景2: 数据过滤
+
+```python
+from pynomad.cache.dataframe.types import DataFrameValueLoader
+
+class FilteredValueLoader(DataFrameValueLoader):
+    """支持参数过滤的 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict]:
+        """GET 阶段：直接返回缓存"""
+        if not cached_df.empty:
+            return Result.success(data=cached_df)
+        return Result.client_error(
+            exception=Exception("缓存为空"),
+            data={"args": args, "kwargs": kwargs}
+        )
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：缓存新数据"""
+        return Result.success(data=new_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：根据参数过滤数据"""
+        symbol = kwargs.get("symbol")
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        filtered_df = merged_df
+        if symbol:
+            filtered_df = filtered_df[filtered_df["symbol"] == symbol]
+        if start_date:
+            filtered_df = filtered_df[filtered_df["date"] >= start_date]
+        if end_date:
+            filtered_df = filtered_df[filtered_df["date"] <= end_date]
+
+        return Result.success(data=filtered_df)
+
+@df_memcached(value_loader=FilteredValueLoader(), ttl=3600)
+def load_and_filter_data(symbol: str, start_date: str, end_date: str) -> DataFrame:
+    """加载并过滤数据"""
+    return fetch_full_data()
+```
+
+##### 场景3: 时间窗口缓存
+
+```python
+class TimeWindowValueLoader(DataFrameValueLoader):
+    """时间窗口缓存 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict]:
+        """GET 阶段：检查缓存是否覆盖请求范围"""
+        if cached_df.empty:
+            return Result.client_error(
+                exception=Exception("缓存为空"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        # 检查缓存是否覆盖请求范围
+        cache_start = cached_df["date"].min()
+        cache_end = cached_df["date"].max()
+
+        if start_date and cache_start > pd.Timestamp(start_date):
+            return Result.client_error(
+                exception=Exception(f"缓存起始时间 {cache_start} 晚于请求时间 {start_date}"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        if end_date and cache_end < pd.Timestamp(end_date):
+            return Result.client_error(
+                exception=Exception(f"缓存结束时间 {cache_end} 早于请求时间 {end_date}"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        return Result.success(data=cached_df)
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """PUT 阶段：扩展缓存的时间范围"""
+        merged_df = pd.concat([cached_df, new_df]).drop_duplicates()
+        return Result.success(data=merged_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """EXTRACT 阶段：返回请求时间范围内的数据"""
+        start_date = kwargs.get("start_date")
+        end_date = kwargs.get("end_date")
+
+        filtered_df = merged_df
+        if start_date:
+            filtered_df = filtered_df[filtered_df["date"] >= pd.Timestamp(start_date)]
+        if end_date:
+            filtered_df = filtered_df[filtered_df["date"] <= pd.Timestamp(end_date)]
+
+        return Result.success(data=filtered_df)
+
+@df_memcached(value_loader=TimeWindowValueLoader(), ttl=7200)
+def load_time_series_data(symbol: str, start_date: str, end_date: str) -> DataFrame:
+    """加载时间序列数据"""
+    return fetch_time_series(symbol, start_date, end_date)
+```
+
+#### 10.3 自定义缓存最佳实践
+
+##### 10.3.1 键生成器设计原则
+
+键是缓存命中的关键，设计合理的键生成器可以大幅提升缓存效率。
+
+**基本原则：**
+- 键应该唯一且确定
+- 避免包含易变的参数（如时间戳）
+- 保持键的简洁性
+
+**实战示例：股票数据缓存的键生成**
+
+```python
+from pynomad import df_memcached
+
+def stock_key_generator(func, instance, args, kwargs):
+    """股票数据缓存键生成器"""
+    # 获取参数
+    code = kwargs.get("code") or args[0]
+    start_date = kwargs.get("start_date") or args[1]
+    end_date = kwargs.get("end_date") or args[2]
+    fq = kwargs.get("fq", "qfq")  # 复权类型，默认前复权
+
+    # ✅ 应该参与键生成的参数
+    # - code: 不同股票的数据应该分别缓存
+    # - fq: 复权类型不同，数据也不同
+    #
+    # ❌ 不应该参与键生成的参数
+    # - start_date + end_date: 时间范围在 EXTRACT 阶段过滤
+    #   这样不同时间范围的请求可以复用同一份缓存
+    #   比如先缓存了 2024-01-01 到 2024-12-31 的数据
+    #   之后请求 2024-01-01 到 2024-03-31 就能直接命中缓存
+    return f"{func.__name__}:{code}:{fq}"
+
+@df_memcached(keygenerator=stock_key_generator, ttl=3600)
+def get_stock_data(code: str, start_date: str, end_date: str, fq: str = "qfq") -> DataFrame:
+    """获取股票数据"""
+    return fetch_stock_from_api(code, start_date, end_date, fq)
+```
+
+**参数是否参与键生成的判断标准：**
+
+| 参数类型 | 应该参与键生成？ | 示例 | 原因 |
+|---------|----------------|------|------|
+| 数据标识 | ✅ 是 | `code`, `symbol`, `user_id` | 不同标识的数据应该分开缓存 |
+| 时间范围 | ❌ 否 | `start_date`, `end_date` | 在 EXTRACT 阶段过滤，可复用缓存 |
+| 业务参数 | ✅ 是 | `fq`, `period`, `interval` | 影响数据内容的参数 |
+| 查询参数 | ❌ 否 | `fields`, `columns` | 可以在 EXTRACT 阶段过滤 |
+| 分页参数 | ❌ 否 | `page`, `page_size` | 可以在 EXTRACT 阶段切片 |
+| 纯控制参数 | ❌ 否 | `format`, `verbose` | 不影响数据内容 |
+| 时间戳 | ❌ 否 | `timestamp`, `ts` | 每次都变，会导致缓存失效 |
+
+**反例分析：**
+
+```python
+# ❌ 错误示例：时间戳参与键生成
+@memcached(ttl=60)
+def get_realtime_price(code: str, timestamp: int) -> dict:
+    # timestamp 每次都不同，导致缓存永远不命中
+    return fetch_price(code, time.time())
+
+# ✅ 正确示例：移除时间戳
+@memcached(ttl=60)
+def get_realtime_price(code: str) -> dict:
+    # 使用 TTL 控制缓存时效，而不是参数
+    return fetch_price(code)
+
+# ❌ 错误示例：时间范围参与键生成
+@df_memcached(ttl=3600)
+def get_stock_data(code: str, start_date: str, end_date: str, fq: str = "qfq") -> DataFrame:
+    # start_date 和 end_date 参与键生成，每次时间参数变化都会从 API 拉取
+    # 三阶段缓存的意义丧失了
+    return fetch_stock_from_api(code, start_date, end_date, fq)
+
+# ✅ 正确示例：时间范围不参与键生成，在 EXTRACT 阶段过滤
+@df_memcached(value_loader=StockDataValueLoader(), ttl=3600)
+def get_stock_data(code: str, start_date: str, end_date: str, fq: str = "qfq") -> DataFrame:
+    # 键只包含 code 和 fq，时间范围在 EXTRACT 阶段过滤
+    # 这样不同时间范围的请求可以复用同一份缓存
+    return fetch_stock_from_api(code, start_date, end_date, fq)
+
+# ❌ 错误示例：fields 参数参与键生成
+@df_memcached(ttl=3600)
+def get_stock_data(code: str, fields: list[str]) -> DataFrame:
+    # fields=["open,close"] 和 fields=["open,close,volume"] 会被视为不同缓存
+    return fetch_all_fields(code)
+
+# ✅ 正确示例：在 EXTRACT 阶段过滤
+@df_memcached(ttl=3600)
+def get_stock_data(code: str, fields: list[str] = None) -> DataFrame:
+    # 始终缓存完整数据，在返回前过滤字段
+    df = fetch_all_fields(code)
+    if fields:
+        return df[fields]
+    return df
+```
+
+##### 10.3.2 ValueLoader 各阶段返回值详解
+
+ValueLoader 的三阶段处理是 DataFrame 缓存的核心，每个阶段的返回值决定了后续的执行流程。
+
+**阶段返回值总览：**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  ValueLoader 执行流程                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  GET 阶段                                                   │
+│  ├─ Result.success(cached_df)     → 跳过 PUT 和 EXTRACT      │
+│  │                               → 直接返回 cached_df         │
+│  ├─ Result.client_error(...)      → 执行函数（获取新数据）   │
+│  │   └─ error.data 包含刷新参数   → 进入 PUT 阶段           │
+│  └─ Result.server_error(...)     → 直接抛出异常             │
+│                                                             │
+│  PUT 阶段（仅在 GET 返回 error 时执行）                      │
+│  ├─ Result.success(merged_df)     → 进入 EXTRACT 阶段       │
+│  └─ Result.error(...)            → 直接抛出异常             │
+│                                                             │
+│  EXTRACT 阶段（仅在 PUT 返回 success 时执行）                 │
+│  ├─ Result.success(extracted_df) → 最终返回数据             │
+│  └─ Result.error(...)            → 直接抛出异常             │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**GET 阶段详解：**
+
+```python
+def get(
+    self,
+    cached_df: DataFrame,
+    extra_params: dict,
+    args: tuple,
+    kwargs: dict
+) -> Result[DataFrame | dict]:
+    """
+    GET 阶段：判断缓存是否可用
+
+    参数说明：
+    - cached_df: 缓存中的 DataFrame（可能为空）
+    - extra_params: 缓存时保存的额外信息（如参数、时间戳）
+    - args: 当前调用的位置参数
+    - kwargs: 当前调用的关键字参数
+
+    返回值：
+    1. Result.success(cached_df)
+       - 表示缓存可用，直接使用缓存数据
+       - 跳过 PUT 和 EXTRACT 阶段
+       - 返回 cached_df
+
+    2. Result.client_error(exception, data={"args": args, "kwargs": kwargs})
+       - 表示缓存不可用，需要刷新
+       - error.data 中的参数会传递给 PUT 阶段
+       - 触发函数执行获取新数据
+
+    3. Result.error(exception)
+       - 表示发生错误，直接抛出异常
+    """
+```
+
+**GET 阶段返回值示例：**
+
+```python
+# 场景1: 参数相同，直接使用缓存
+def get(self, cached_df, extra_params, args, kwargs):
+    last_args = tuple(extra_params.get("args", ()))
+    if last_args == args:
+        return Result.success(data=cached_df)  # ✅ 命中缓存
+
+# 场景2: 参数不同，需要刷新
+def get(self, cached_df, extra_params, args, kwargs):
+    if args != self.last_args:
+        return Result.client_error(
+            exception=Exception("参数变化"),
+            data={"args": args, "kwargs": kwargs}  # ✅ 触发刷新
+        )
+
+# 场景3: 缓存为空，需要刷新
+def get(self, cached_df, extra_params, args, kwargs):
+    if cached_df.empty:
+        return Result.client_error(
+            exception=Exception("缓存为空"),
+            data={"args": args, "kwargs": kwargs}  # ✅ 触发刷新
+        )
+
+# 场景4: 缓存过期，需要刷新
+def get(self, cached_df, extra_params, args, kwargs):
+    cache_time = extra_params.get("timestamp", 0)
+    if time.time() - cache_time > self.cache_interval:
+        return Result.client_error(
+            exception=Exception("缓存过期"),
+            data={"args": args, "kwargs": kwargs}  # ✅ 触发刷新
+        )
+
+# 场景5: 缓存不满足条件，需要刷新
+def get(self, cached_df, extra_params, args, kwargs):
+    required_symbol = args[0]
+    if cached_df.empty or cached_df["symbol"].iloc[0] != required_symbol:
+        return Result.client_error(
+            exception=Exception("缓存不匹配"),
+            data={"args": args, "kwargs": kwargs}  # ✅ 触发刷新
+        )
+```
+
+**PUT 阶段详解：**
+
+```python
+def put(
+    self,
+    cached_df: DataFrame,
+    new_df: DataFrame,
+    extra_params: dict,
+    args: tuple,
+    kwargs: dict
+) -> Result[DataFrame]:
+    """
+    PUT 阶段：合并新旧数据
+
+    参数说明：
+    - cached_df: 缓存中的旧 DataFrame（可能为空）
+    - new_df: 函数执行返回的新 DataFrame
+    - extra_params: GET 阶段传递的参数
+    - args: 当前调用的位置参数
+    - kwargs: 当前调用的关键字参数
+
+    返回值：
+    1. Result.success(merged_df)
+       - 合并后的 DataFrame
+       - 传递给 EXTRACT 阶段
+       - merged_df 会被缓存
+
+    2. Result.error(exception)
+       - 发生错误，直接抛出异常
+    """
+```
+
+**PUT 阶段返回值示例：**
+
+```python
+# 场景1: 缓存为空，直接返回新数据
+def put(self, cached_df, new_df, extra_params, args, kwargs):
+    if cached_df.empty:
+        return Result.success(data=new_df)  # ✅ 使用新数据
+
+# 场景2: 增量更新（追加新数据）
+def put(self, cached_df, new_df, extra_params, args, kwargs):
+    merged_df = pd.concat([cached_df, new_df]).drop_duplicates()
+    return Result.success(data=merged_df)  # ✅ 合并数据
+
+# 场景3: 替换旧数据
+def put(self, cached_df, new_df, extra_params, args, kwargs):
+    # 直接使用新数据，不合并
+    return Result.success(data=new_df)  # ✅ 替换数据
+
+# 场景4: 智能合并（按索引合并）
+def put(self, cached_df, new_df, extra_params, args, kwargs):
+    # 假设按 'date' 列去重
+    merged_df = pd.concat([cached_df, new_df])
+    merged_df = merged_df.drop_duplicates(subset=["date"], keep="last")
+    return Result.success(data=merged_df)  # ✅ 智能合并
+
+# 场景5: 数据聚合（统计场景）
+def put(self, cached_df, new_df, extra_params, args, kwargs):
+    # 聚合相同键的数据
+    merged_df = cached_df.merge(
+        new_df,
+        on=["date"],
+        how="outer",
+        suffixes=("_old", "_new")
+    )
+    return Result.success(data=merged_df)  # ✅ 聚合数据
+```
+
+**EXTRACT 阶段详解：**
+
+```python
+def extract(
+    self,
+    merged_df: DataFrame,
+    extra_params: dict,
+    args: tuple,
+    kwargs: dict
+) -> Result[DataFrame]:
+    """
+    EXTRACT 阶段：提取返回数据
+
+    参数说明：
+    - merged_df: PUT 阶段合并后的 DataFrame
+    - extra_params: GET 阶段传递的参数
+    - args: 当前调用的位置参数
+    - kwargs: 当前调用的关键字参数
+
+    返回值：
+    1. Result.success(extracted_df)
+       - 最终返回给用户的 DataFrame
+       - 这个结果不会被缓存
+
+    2. Result.error(exception)
+       - 发生错误，直接抛出异常
+    """
+```
+
+**EXTRACT 阶段返回值示例：**
+
+```python
+# 场景1: 直接返回全部数据
+def extract(self, merged_df, extra_params, args, kwargs):
+    return Result.success(data=merged_df)  # ✅ 返回全部
+
+# 场景2: 按字段过滤
+def extract(self, merged_df, extra_params, args, kwargs):
+    fields = kwargs.get("fields")
+    if fields:
+        return Result.success(data=merged_df[fields])  # ✅ 字段过滤
+    return Result.success(data=merged_df)
+
+# 场景3: 按时间范围过滤
+def extract(self, merged_df, extra_params, args, kwargs):
+    start_date = kwargs.get("start_date")
+    end_date = kwargs.get("end_date")
+
+    filtered_df = merged_df
+    if start_date:
+        filtered_df = filtered_df[filtered_df["date"] >= start_date]
+    if end_date:
+        filtered_df = filtered_df[filtered_df["date"] <= end_date]
+
+    return Result.success(data=filtered_df)  # ✅ 时间过滤
+
+# 场景4: 数据切片（分页）
+def extract(self, merged_df, extra_params, args, kwargs):
+    page = kwargs.get("page", 1)
+    page_size = kwargs.get("page_size", 100)
+
+    start = (page - 1) * page_size
+    end = start + page_size
+
+    return Result.success(data=merged_df.iloc[start:end])  # ✅ 分页切片
+
+# 场景5: 数据转换
+def extract(self, merged_df, extra_params, args, kwargs):
+    # 计算衍生字段
+    df = merged_df.copy()
+    df["pct_change"] = df["close"].pct_change()
+    return Result.success(data=df)  # ✅ 数据转换
+
+# 场景6: 数据聚合
+def extract(self, merged_df, extra_params, args, kwargs):
+    # 按字段聚合
+    group_by = kwargs.get("group_by")
+    if group_by:
+        aggregated_df = merged_df.groupby(group_by).sum()
+        return Result.success(data=aggregated_df)  # ✅ 数据聚合
+    return Result.success(data=merged_df)
+```
+
+##### 10.3.3 完整示例：股票数据缓存
+
+```python
+from pynomad.cache.dataframe.types import DataFrameValueLoader
+from pynomad import Result, df_memcached
+from pandas import DataFrame
+import pandas as pd
+
+class StockDataValueLoader(DataFrameValueLoader):
+    """股票数据 ValueLoader"""
+
+    def get(
+        self,
+        cached_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame | dict]:
+        """
+        GET 阶段：
+        - 检查缓存是否覆盖请求的时间范围
+        - 如果覆盖，返回缓存
+        - 如果不覆盖，返回需要刷新的参数
+        """
+        # 缓存为空，需要刷新
+        if cached_df.empty:
+            return Result.client_error(
+                exception=Exception("缓存为空"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        # 获取请求的时间范围
+        start_date = pd.Timestamp(kwargs.get("start_date") or args[1])
+        end_date = pd.Timestamp(kwargs.get("end_date") or args[2])
+
+        # 检查缓存是否覆盖请求范围
+        cache_start = cached_df["date"].min()
+        cache_end = cached_df["date"].max()
+
+        # 缓存起始时间晚于请求时间，需要刷新
+        if cache_start > start_date:
+            return Result.client_error(
+                exception=Exception(f"缓存从 {cache_start} 开始，但需要从 {start_date} 开始"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        # 缓存结束时间早于请求时间，需要刷新
+        if cache_end < end_date:
+            return Result.client_error(
+                exception=Exception(f"缓存到 {cache_end} 结束，但需要到 {end_date} 结束"),
+                data={"args": args, "kwargs": kwargs}
+            )
+
+        # 缓存覆盖请求范围，直接返回
+        return Result.success(data=cached_df)
+
+    def put(
+        self,
+        cached_df: DataFrame,
+        new_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """
+        PUT 阶段：
+        - 合并旧数据和新数据
+        - 按日期去重，保留最新的数据
+        """
+        # 缓存为空，直接返回新数据
+        if cached_df.empty:
+            return Result.success(data=new_df)
+
+        # 合并数据并按日期去重
+        merged_df = pd.concat([cached_df, new_df])
+        merged_df = merged_df.drop_duplicates(subset=["date"], keep="last")
+
+        # 按日期排序
+        merged_df = merged_df.sort_values("date").reset_index(drop=True)
+
+        return Result.success(data=merged_df)
+
+    def extract(
+        self,
+        merged_df: DataFrame,
+        extra_params: dict,
+        args: tuple,
+        kwargs: dict
+    ) -> Result[DataFrame]:
+        """
+        EXTRACT 阶段：
+        - 根据请求的时间范围过滤数据
+        - 返回指定范围的数据
+        """
+        start_date = pd.Timestamp(kwargs.get("start_date") or args[1])
+        end_date = pd.Timestamp(kwargs.get("end_date") or args[2])
+
+        # 过滤时间范围
+        filtered_df = merged_df[
+            (merged_df["date"] >= start_date) &
+            (merged_df["date"] <= end_date)
+        ].copy()
+
+        return Result.success(data=filtered_df)
+
+# 使用自定义 ValueLoader
+@df_memcached(value_loader=StockDataValueLoader(), ttl=86400)
+def get_stock_data(code: str, start_date: str, end_date: str, fq: str = "qfq") -> DataFrame:
+    """获取股票数据"""
+    return fetch_stock_from_api(code, start_date, end_date, fq)
+
+# 使用示例
+# 第一次请求 2024-01-01 到 2024-01-10，从 API 获取
+df1 = get_stock_data("AAPL", "2024-01-01", "2024-01-10")
+
+# 第二次请求相同范围，从缓存返回（不调用 API）
+df2 = get_stock_data("AAPL", "2024-01-01", "2024-01-10")
+
+# 第三次请求更大范围 2024-01-01 到 2024-01-20，
+# GET 判断缓存不完整，PUT 合并新旧数据，EXTRACT 返回完整范围
+df3 = get_stock_data("AAPL", "2024-01-01", "2024-01-20")
+```
+
+##### 10.3.4 自定义缓存注意事项
+
+1. **确保线程安全**
+   - ValueLoader 的方法会被多线程调用
+   - 避免在 ValueLoader 中使用共享的可变状态
+
+2. **正确处理 TTL 和淘汰策略**
+   - ValueLoader 主要控制数据处理逻辑
+   - TTL 和淘汰策略由缓存系统自动管理
+
+3. **考虑缓存穿透和雪崩问题**
+   - GET 阶段检查缓存有效性
+   - 合理设置缓存失效条件
+
+4. **性能优化**
+   - 避免在 ValueLoader 中进行耗时操作
+   - 使用向量化操作（如 pandas 的向量化方法）
+
+---
+
+### 11.4 性能优化建议
+
+1. **合理设置缓存大小**：根据内存和磁盘空间调整 `maxsize`
+2. **使用连接池**：Redis 和 SQL 缓存配置连接池参数
+3. **异步操作**：对于高并发场景，考虑使用异步装饰器
+4. **批量操作**：减少缓存读写次数，尽量批量处理
+5. **监控缓存命中率**：定期检查缓存效果，调整 TTL 和大小
+
+---
+
+## 项目结构
+
+```
+pynomad/
+├── cache/              # 缓存系统
+│   ├── core/           # 核心接口
+│   ├── decorator/      # 缓存装饰器
+│   ├── dataframe/      # DataFrame 缓存
+│   └── impl/           # 缓存实现
+├── config/             # 配置系统
+│   └── auto/           # 自动配置
+├── logsystem/          # 日志系统
+├── naming/             # 命名系统
+├── result/             # 结果封装
+└── common/             # 通用工具
+```
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎 Pull Request！
+
+> ⚠️ **不欢迎 Issue**
+>
+> 如有 bug 请自行下载源码进行更改，因为作者正在工厂打螺丝进行着 777 工作制，没有时间更改代码
+