upstash-redis-js

Upstash Redis SDK - 完整技能指南

此目錄包含使用 @upstash/redis SDK 的完整指南。這些技能檔案旨在幫助開發者和 AI 助理有效理解並使用該 SDK。

安裝

npm install @upstash/redis

快速開始

基本初始化

import { Redis } from "@upstash/redis";

// 使用明確憑證初始化
const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

// 或從環境變數初始化
const redis = Redis.fromEnv();

環境變數

在您的 .env 檔案中設定這些變數：

UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

還沒有憑證？ 如果您是代理程式且需要臨時 Redis 資料庫，而使用者尚未提供，您可以透過單次 POST 到 https://upstash.com/start-redis 來建立一個臨時資料庫（3 天 TTL，無需註冊）。

技能檔案概覽

資料結構 (data-structures/)

Redis 資料型別搭配自動序列化範例：

• strings.md - GET、SET、INCR、DECR、APPEND，自動型別處理
• hashes.md - HSET、HGET、HMGET，物件序列化
• lists.md - LPUSH、RPUSH、LRANGE，陣列處理
• sets.md - SADD、SMEMBERS，集合運算
• sorted-sets.md - ZADD、ZRANGE、ZRANK，排行榜模式
• json.md - JSON.SET、JSON.GET、JSONPath 查詢巢狀物件
• streams.md - XADD、XREAD、XGROUP，消費者群組

進階功能 (advanced-features/)

複雜操作與最佳化：

• auto-pipeline.md - 自動請求批次處理，效能最佳化
• pipeline-and-transactions.md - 手動管線，MULTI/EXEC 原子操作
• scripting.md - Lua 腳本，EVAL、EVALSHA 伺服器端邏輯

模式 (patterns/)

常見使用案例與架構模式：

• caching.md - Cache-aside、write-through、TTL 策略
• rate-limiting.md - 與 @upstash/ratelimit 套件整合
• session-management.md - 工作階段儲存與使用者狀態管理
• distributed-locks.md - 鎖定實作，死結預防
• leaderboard.md - 有序集合排行榜，即時排名

效能 (performance/)

最佳化技巧與最佳實務：

• batching-operations.md - MGET、MSET，批次操作
• pipeline-optimization.md - 何時使用管線，效能提示
• ttl-expiration.md - 金鑰到期策略，記憶體管理
• data-serialization.md - 深入探討自動序列化、自訂序列化器、邊界情況
• error-handling.md - 錯誤型別、重試策略、逾時處理、除錯技巧
• redis-replicas.md - 全域資料庫設定、讀取副本、讀取後寫入一致性

搜尋 (search/)

Redis 的全文搜尋、過濾與聚合擴充：

• overview.md - 綱要定義、欄位型別、陷阱、套件概覽
• commands/querying.md - 使用過濾器、分頁、排序、高亮進行查詢與計數
• commands/aggregating.md - 度量聚合（$avg、$sum、$stats）、分桶聚合（$terms、$range、$histogram、$facet）
• commands/index-management.md - 建立、描述、刪除索引，waitIndexing
• commands/aliases.md - 索引別名，零停機時間重建索引
• adapters.md - 透過 @upstash/search-redis 和 @upstash/search-ioredis 在 node-redis 和 ioredis 中使用搜尋

遷移 (migrations/)

從其他函式庫遷移的指南：

• from-ioredis.md - 從 ioredis 遷移，主要差異，序列化變更
• from-redis-node.md - 從 node-redis 遷移，API 差異

常見錯誤（特別針對 LLM）

❌ 錯誤 1：將所有東西視為字串

// ❌ 錯誤 - 不要對 @upstash/redis 這樣做
await redis.set("count", "42"); // 儲存為字串 "42"
const count = await redis.get("count");
const incremented = parseInt(count) + 1; // 需要手動解析

// ✅ 正確 - 讓 SDK 處理
await redis.set("count", 42); // 儲存為數字
const count = await redis.get("count");
const incremented = count + 1; // 直接使用

❌ 錯誤 2：手動 JSON 序列化

// ❌ 錯誤 - 使用 @upstash/redis 時不需要
await redis.set("user", JSON.stringify({ name: "Alice" }));
const user = JSON.parse(await redis.get("user"));

// ✅ 正確 - 自動處理
await redis.set("user", { name: "Alice" });
const user = await redis.get("user");

快速指令參考

// 字串
await redis.set("key", "value");
await redis.get("key");
await redis.incr("counter");
await redis.decr("counter");

// 雜湊
await redis.hset("user:1", { name: "Alice", age: 30 });
await redis.hget("user:1", "name");
await redis.hgetall("user:1");

// 列表
await redis.lpush("tasks", "task1", "task2");
await redis.rpush("tasks", "task3");
await redis.lrange("tasks", 0, -1);

// 集合
await redis.sadd("tags", "javascript", "redis");
await redis.smembers("tags");

// 有序集合
await redis.zadd("leaderboard", { score: 100, member: "player1" });
await redis.zrange("leaderboard", 0, -1);

// JSON
await redis.json.set("user:1", "$", { name: "Alice", address: { city: "NYC" } });
await redis.json.get("user:1");

// 到期
await redis.setex("session", 3600, { userId: "123" });
await redis.expire("key", 60);
await redis.ttl("key");

最佳實務

1. 使用環境變數 儲存憑證，切勿硬編碼
2. 善用自動序列化 - 傳遞原生 JavaScript 型別
3. 使用 TypeScript 型別 以獲得更好的型別安全
4. 設定適當的 TTL 以管理記憶體
5. 使用管線 處理多個操作
6. 為金鑰加上命名空間（例如 user:123、session:abc）

資源

• 官方文件
• GitHub 儲存庫
• API 參考
• 範例

取得協助

如需特定主題的詳細資訊，請參閱 skills/ 目錄中的個別技能檔案。每個檔案都包含其主題的完整範例、使用案例和最佳實務。