Redis Toolkit

# API 參考

歡迎查閱 Redis Toolkit 的 API 參考文檔。這裡提供所有公開類別、方法和函數的詳細說明。

# 📚 API 文檔組織

🔧 核心 API

RedisToolkit 主類別的所有方法

  • 初始化與配置
  • 基本操作方法
  • 批次操作
  • 發布訂閱
查看文檔 →

🎨 轉換器 API

媒體處理相關的轉換器

  • 圖片轉換器
  • 音頻轉換器
  • 視頻轉換器
  • 通用介面
查看文檔 →

⚙️ 配置 API

配置類別和選項

  • RedisConnectionConfig
  • RedisOptions
  • 預設配置
  • 驗證方法
查看文檔 →

🛠️ 工具函數

實用工具和輔助函數

  • 序列化函數
  • 重試裝飾器
  • 驗證工具
  • 異常類別
查看文檔 →

# 🎯 快速導航

# 最常用的 API

# 核心類別
from redis_toolkit import RedisToolkit

# 配置類別
from redis_toolkit import RedisConnectionConfig, RedisOptions

# 轉換器函數
from redis_toolkit.converters import (
    encode_image, decode_image,
    encode_audio, decode_audio,
    get_converter
)

# 工具函數
from redis_toolkit.utils import serialize_value, deserialize_value
from redis_toolkit.utils import with_retry

# 異常類別
from redis_toolkit.exceptions import (
    RedisToolkitError,
    SerializationError,
    ValidationError
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 📖 API 使用範例

# 基本初始化

# 方式 1：使用預設配置
toolkit = RedisToolkit()

# 方式 2：自定義配置
config = RedisConnectionConfig(host='localhost', port=6379)
options = RedisOptions(is_logger_info=True)
toolkit = RedisToolkit(config=config, options=options)

# 方式 3：使用現有 Redis 客戶端
import redis
client = redis.Redis()
toolkit = RedisToolkit(redis=client)
1
2
3
4
5
6
7
8
9
10
11
12

# 常用操作

# 存取資料
toolkit.setter("key", {"data": "value"})
data = toolkit.getter("key")

# 批次操作
batch_data = {"key1": "value1", "key2": "value2"}
toolkit.batch_set(batch_data)
results = toolkit.batch_get(["key1", "key2"])

# 發布訂閱
toolkit.publisher("channel", {"message": "Hello"})
1
2
3
4
5
6
7
8
9
10
11

# 媒體處理

# 圖片處理
img_bytes = encode_image(image_array, format='jpg')
decoded_img = decode_image(img_bytes)

# 使用轉換器
converter = get_converter('image')
resized = converter.resize(image_array, width=800)
1
2
3
4
5
6
7

# 🔍 API 設計原則

# 1. 簡單直觀

我們的 API 設計遵循「簡單優先」原則：

# ✅ 簡單明瞭
toolkit.setter("key", value)
toolkit.getter("key")

# ❌ 過度複雜
toolkit.storage.persistence.set_with_options("key", value, options={...})
1
2
3
4
5
6

# 2. 一致性

所有 API 保持一致的命名和行為模式：

  • setter / getter - 基本存取
  • batch_set / batch_get - 批次操作
  • encode_* / decode_* - 編碼解碼

# 3. 錯誤處理

統一的異常體系，便於錯誤處理：

try:
    toolkit.setter("key", problematic_value)
except SerializationError:
    # 處理序列化錯誤
except ValidationError:
    # 處理驗證錯誤
except RedisToolkitError:
    # 處理其他錯誤
1
2
3
4
5
6
7
8

# 📊 API 版本和相容性

# 版本策略

我們遵循語意化版本控制（Semantic Versioning）：

  • 主版本：不相容的 API 變更
  • 次版本：向下相容的功能新增
  • 修訂版本：向下相容的錯誤修正

# 棄用政策

當 API 需要棄用時：

  1. 在文檔中標記為 @deprecated
  2. 發出棄用警告
  3. 至少保留兩個次版本
  4. 提供遷移指南
# 棄用範例
@deprecated("使用 toolkit.setter 替代")
def set_value(key, value):
    warnings.warn("set_value 已棄用，請使用 setter", DeprecationWarning)
    return toolkit.setter(key, value)
1
2
3
4
5

# 🎯 API 最佳實踐

# 1. 使用類型提示

from typing import Dict, Any, Optional

def process_data(
    key: str,
    data: Dict[str, Any],
    ttl: Optional[int] = None
) -> bool:
    """處理並儲存資料"""
    return toolkit.setter(key, data, ex=ttl)
1
2
3
4
5
6
7
8
9

# 2. 參數驗證

# 使用配置類別的驗證功能
config = RedisConnectionConfig(port=6379)
config.validate()  # 確保配置有效

# 自定義驗證
if not isinstance(data, (dict, list)):
    raise ValidationError("資料必須是 dict 或 list")
1
2
3
4
5
6
7

# 3. 資源管理

# 使用 context manager
with RedisToolkit() as toolkit:
    toolkit.setter("key", "value")
    # 自動清理資源

# 手動清理
toolkit = RedisToolkit()
try:
    # 使用 toolkit
finally:
    toolkit.cleanup()
1
2
3
4
5
6
7
8
9
10
11

# 📚 深入學習

根據您的需求，選擇相應的 API 文檔深入學習：

🔧 核心 API 🎨 轉換器 API ⚙️ 配置 API 🛠️ 工具函數

提示

  • 使用 IDE 的自動完成功能探索 API
  • 查看原始碼了解實現細節
  • 參考範例程式碼學習最佳實踐

核心 API - RedisToolkit →