Upstash Redis SDK 完整指南 - Redis-JS 安装、使用与性能优化教程

redis-js by upstash/redis-js

206 周安装量

931 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/upstash/redis-js --skill redis-js

Node.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

技能文件概览

数据结构 (skills/data-structures/)

包含自动序列化示例的 Redis 数据类型：

strings.md - GET、SET、INCR、DECR、APPEND 及自动类型处理

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

高级功能 (skills/advanced-features/)

复杂操作和优化：

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

模式 (skills/patterns/)

常见用例和架构模式：

caching.md - 旁路缓存、直写、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 差异

常见错误（尤其对于 LLMs）

❌ 错误 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");

使用环境变量 存储凭据，切勿硬编码
利用自动序列化 - 传递原生 JavaScript 类型
使用 TypeScript 类型 以获得更好的类型安全性
设置适当的 TTL 以管理内存
使用管道 处理多个操作
为您的键命名空间（例如 user:123、session:abc）

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

🇺🇸English

Upstash Redis SDK - Complete Skills Guide

This directory contains comprehensive guides for using the @upstash/redis SDK. These skill files are designed to help developers and AI assistants understand and use the SDK effectively.

Installation

npm install @upstash/redis

Quick Start

Basic Initialization

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();

Environment Variables

Set these in your .env file:

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

Skill Files Overview

Data Structures (skills/data-structures/)

Redis data types with auto-serialization examples:

strings.md - GET, SET, INCR, DECR, APPEND with automatic type handling
hashes.md - HSET, HGET, HMGET with object serialization
lists.md - LPUSH, RPUSH, LRANGE with array handling
sets.md - SADD, SMEMBERS, set operations
sorted-sets.md - ZADD, ZRANGE, ZRANK, leaderboard patterns
json.md - JSON.SET, JSON.GET, JSONPath queries for nested objects
streams.md - XADD, XREAD, XGROUP, consumer groups

Advanced Features (skills/advanced-features/)

Complex operations and optimizations:

auto-pipeline.md - Automatic request batching, performance optimization
pipeline-and-transactions.md - Manual pipelines, MULTI/EXEC, WATCH for atomic operations
scripting.md - Lua scripts, EVAL, EVALSHA for server-side logic

Patterns (skills/patterns/)

Common use cases and architectural patterns:

caching.md - Cache-aside, write-through, TTL strategies
rate-limiting.md - Integration with @upstash/ratelimit package
session-management.md - Session storage and user state management
distributed-locks.md - Lock implementations, deadlock prevention
leaderboard.md - Sorted set leaderboards, real-time rankings

Performance (skills/performance/)

Optimization techniques and best practices:

batching-operations.md - MGET, MSET, batch operations
pipeline-optimization.md - When to use pipelines, performance tips
ttl-expiration.md - Key expiration strategies, memory management
data-serialization.md - Deep dive into auto serialization, custom serializers, edge cases
error-handling.md - Error types, retry strategies, timeout handling, debugging tips
redis-replicas.md - Global database setup, read replicas, read-your-writes consistency

Search (skills/search/)

Full-text search, filtering, and aggregation extension for Redis:

overview.md - Schema definition, field types, pitfalls, package overview
commands/querying.md - Query and count with filters, pagination, sorting, highlighting
commands/aggregating.md - Metric aggregations ($avg, $sum, $stats), bucket aggregations ($terms, $range, $histogram, $facet)
commands/index-management.md - Create, describe, drop indexes, waitIndexing
commands/aliases.md - Index aliases for zero-downtime reindexing
adapters.md - Using search with node-redis and ioredis via @upstash/search-redis and @upstash/search-ioredis

Migrations (skills/migrations/)

Migration guides from other libraries:

from-ioredis.md - Migration from ioredis, key differences, serialization changes
from-redis-node.md - Migration from node-redis, API differences

Common Mistakes (Especially for LLMs)

❌ Mistake 1: Treating Everything as Strings

// ❌ 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

❌ Mistake 2: Manual JSON Serialization

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

Quick Command Reference

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

Best Practices

Use environment variables for credentials, never hardcode
Leverage auto-serialization - pass native JavaScript types
Use TypeScript types for better type safety
Set appropriate TTLs to manage memory
Use pipelines for multiple operations
Namespace your keys (e.g., user:123, session:abc)

Resources

Getting Help

For detailed information on specific topics, refer to the individual skill files in the skills/ directory. Each file contains comprehensive examples, use cases, and best practices for its topic.

Weekly Installs

206

Repository

upstash/redis-js

GitHub Stars

931

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode155

cursor153

codex153

gemini-cli148

github-copilot146

claude-code136

GSAP React 动画库使用指南：useGSAP Hook 与最佳实践

2,400 周安装