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

技能文件概览

数据结构（skills/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 中进行最近邻搜索

高级功能（skills/advanced-features/）

复杂操作和优化：

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

模式（skills/patterns/）

常见用例和架构模式：

• caching.md - Cache-aside、write-through、TTL 策略
• rate-limiting.md - 与 @upstash/ratelimit 软件包集成
• session-management.md - 会话存储和用户状态管理
• distributed-locks.md - 锁的实现、防止死锁
• leaderboard.md - 有序集合排行榜、实时排名

性能（skills/performance/）

优化技术和最佳实践：

• batching-operations.md - MGET、MSET、批量操作
• pipeline-optimization.md - 何时使用管道、性能提示
• ttl-expiration.md - 键过期策略、内存管理
• data-serialization.md - 深入了解自动序列化、自定义序列化器、边缘情况
• error-handling.md - 错误类型、重试策略、超时处理、调试提示
• redis-replicas.md - 全局数据库设置、只读副本、读写一致性

搜索（skills/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 进行搜索

迁移（skills/migrations/）

从其他库迁移的指南：

• from-ioredis.md - 从 ioredis 迁移、主要差异、序列化变更
• from-redis-node.md - 从 node-redis 迁移、API 差异

常见错误（尤其是 LLM）

❌ 错误 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）

资源

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

获取帮助

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