# 快速開始

只需要 5 分鐘，讓我們一起體驗 Redis Toolkit 的強大功能！

# 🚀 一分鐘安裝

打開終端機，執行以下命令：

pip install redis-toolkit

就這麼簡單！基礎功能已經可以使用了。

# 🎯 第一個範例

# 1. 導入並初始化

from redis_toolkit import RedisToolkit

# 最簡單的初始化方式
toolkit = RedisToolkit()

1
2
3
4

提示

預設連接到 localhost:6379。如果您的 Redis 在其他位置，請看配置選項。

# 2. 存儲和讀取資料

# 存儲一個字典
user_data = {
    "id": 1001,
    "name": "Alice",
    "email": "alice@example.com",
    "scores": [95, 87, 92]
}
toolkit.setter("user:1001", user_data)

# 讀取資料 - 自動反序列化為原始類型！
retrieved = toolkit.getter("user:1001")
print(retrieved)
# 輸出: {'id': 1001, 'name': 'Alice', 'email': 'alice@example.com', 'scores': [95, 87, 92]}

# 注意：retrieved 是 dict，不是字串！
print(type(retrieved))  # <class 'dict'>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 3. 處理不同資料類型

Redis Toolkit 的強大之處在於自動處理各種 Python 資料類型：

# 列表
toolkit.setter("top_scores", [100, 98, 95, 92, 88])
scores = toolkit.getter("top_scores")  # 返回 list

# 布林值
toolkit.setter("is_active", True)
active = toolkit.getter("is_active")  # 返回 bool，不是字串 "true"

# 數字
toolkit.setter("temperature", 23.5)
temp = toolkit.getter("temperature")  # 返回 float

# 位元組資料
toolkit.setter("binary_data", b"Hello bytes!")
data = toolkit.getter("binary_data")  # 返回 bytes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 📡 快速體驗發布訂閱

# 發送訊息

# 發布者
publisher = RedisToolkit()

# 發送結構化訊息
message = {
    "event": "user_login",
    "user_id": 1001,
    "timestamp": "2024-01-01 10:00:00"
}
publisher.publisher("events", message)

1
2
3
4
5
6
7
8
9
10

# 接收訊息

# 訂閱者
def handle_message(channel, data):
    print(f"收到來自 {channel} 的訊息:")
    print(f"事件: {data['event']}")
    print(f"用戶: {data['user_id']}")

subscriber = RedisToolkit(
    channels=["events"],
    message_handler=handle_message
)

# 訂閱者會自動在背景監聽訊息

1
2
3
4
5
6
7
8
9
10
11
12

# 🎨 媒體處理預覽

如果您安裝了媒體處理套件，可以輕鬆處理圖片：

# 需要先安裝: pip install redis-toolkit[cv2]
from redis_toolkit.converters import encode_image, decode_image
import cv2

# 讀取並儲存圖片
img = cv2.imread('photo.jpg')
encoded = encode_image(img, format='jpg', quality=85)
toolkit.setter('user:1001:avatar', encoded)

# 取回圖片
avatar_bytes = toolkit.getter('user:1001:avatar')
avatar_img = decode_image(avatar_bytes)

1
2
3
4
5
6
7
8
9
10
11
12

# ✅ 完整範例：用戶系統

讓我們用一個實際的例子來整合所學：

from redis_toolkit import RedisToolkit
from datetime import datetime

class UserCache:
    def __init__(self):
        self.toolkit = RedisToolkit()
    
    def save_user(self, user_id, user_info):
        """儲存用戶資訊"""
        # 添加時間戳記
        user_info['last_updated'] = datetime.now().isoformat()
        
        # 儲存到 Redis
        key = f"user:{user_id}"
        self.toolkit.setter(key, user_info)
        
        # 設定過期時間（選用）
        self.toolkit.client.expire(key, 3600)  # 1小時後過期
    
    def get_user(self, user_id):
        """獲取用戶資訊"""
        return self.toolkit.getter(f"user:{user_id}")
    
    def update_score(self, user_id, new_score):
        """更新用戶分數"""
        user = self.get_user(user_id)
        if user:
            if 'scores' not in user:
                user['scores'] = []
            user['scores'].append(new_score)
            self.save_user(user_id, user)
            return True
        return False

# 使用範例
cache = UserCache()

# 儲存用戶
cache.save_user(1001, {
    "name": "Alice",
    "email": "alice@example.com",
    "level": 5,
    "scores": [95, 87]
})

# 更新分數
cache.update_score(1001, 92)

# 獲取用戶
user = cache.get_user(1001)
print(f"{user['name']} 的分數: {user['scores']}")
# 輸出: Alice 的分數: [95, 87, 92]