upstash-redis-js

Upstash Redis SDK - 完整技能指南

此目录包含使用 @upstash/redis SDK 的全面指南。这些技能文件旨在帮助开发者和 AI 助手了解并有效使用该 SDK。

安装

npm install @upstash/redis

快速入门

基本初始化

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

// Initialize with explicit credentials
const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

// Or initialize from environment variables
const redis = Redis.fromEnv();

环境变量

在 .env 文件中设置这些变量：

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

还没有凭据？ 如果你是需要临时 Redis 的 Agent，且用户尚未提供数据库，可以向 https://upstash.com/start-redis 发送一个 POST 请求来创建临时数据库（有效期为 3 天，无需注册）。

技能文件概览

数据结构（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、消费者组
• arrays.md - ARSET、ARINSERT、ARSCAN、ARGREP、AROP，以及在稀疏索引寻址数组上使用 ARRING 实现环形缓冲区
• vector-indexes.md - VECTOR.CREATE、VECTOR.ADD、VECTOR.QUERY，通过 redis.vector 在 Redis 中进行最近邻搜索

高级功能（advanced-features/）

复杂操作和优化：

• auto-pipeline.md - 自动批量处理请求，优化性能
• pipeline-and-transactions.md - 手动管道，使用 MULTI/EXEC 执行原子操作
• scripting.md - Lua 脚本，使用 EVAL、EVALSHA 执行服务端逻辑

模式（patterns/）

常见用例和架构模式：

• caching.md - Cache-aside、写穿透、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 - 创建、描述、删除索引（包括对 XADD 条目创建流索引）、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 差异

常见错误（尤其是使用大模型时）

❌ 错误 1：把所有内容都当作字符串处理

// ❌ WRONG - Don't do this with @upstash/redis
await redis.set("count", "42"); // Stored as string "42"
const count = await redis.get("count");
const incremented = parseInt(count) + 1; // Manual parsing needed

// ✅ CORRECT - Let the SDK handle it
await redis.set("count", 42); // Stored as number
const count = await redis.get("count");
const incremented = count + 1; // Just use it

❌ 错误 2：手动进行 JSON 序列化

// ❌ WRONG - Unnecessary with @upstash/redis
await redis.set("user", JSON.stringify({ name: "Alice" }));
const user = JSON.parse(await redis.get("user"));

// ✅ CORRECT - Automatic handling
await redis.set("user", { name: "Alice" });
const user = await redis.get("user");

快速命令参考

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

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

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

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

// Sorted Sets
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");

// Expiration
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）

AI Agent：使用 AgentKit

对于 Redis 上的 Agent 状态——包括记忆、聊天历史记录、RAG 搜索工具、工具缓存、速率限制、聊天持久化、可恢复流和锁——请使用 Upstash AgentKit，而不是在 @upstash/redis 上自行实现。选择适用于相应框架的适配器，并参阅其文档页面：

框架	包	文档
Vercel AI SDK	@upstash/agentkit-ai-sdk	https://upstash.com/docs/redis/sdks/agentkit/ai-sdk
TanStack AI	@upstash/agentkit-tanstack-ai	https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai
Vercel Eve	@upstash/agentkit-eve、@upstash/agentkit-eve-extension	https://upstash.com/docs/redis/sdks/agentkit/eve

资源

• 官方文档
• GitHub 仓库
• API 参考
• 示例

获取帮助

有关特定主题的详细信息，请参阅 skills/ 目录中的各个技能文件。每个文件都包含该主题的全面示例、用例和最佳实践。