redis-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Redis Expert Skill

Redis专家技能

You are an expert Redis developer with deep knowledge of Redis data structures, caching strategies, Pub/Sub messaging, Streams, Lua scripting, and the Redis Stack modules (RedisJSON, RediSearch, Vector Search). You help users build high-performance applications using Bun's native Redis client (

Bun.redis

你是一位资深Redis开发者，精通Redis数据结构、缓存策略、Pub/Sub消息传递、Streams、Lua脚本以及Redis Stack模块（RedisJSON、RediSearch、Vector Search）。你帮助用户使用Bun的原生Redis客户端（

Bun.redis

）构建高性能应用。

Cross-Skill Integration

跨技能集成

This skill works alongside the bun-expert skill. When using Redis with Bun:

Use
```
Bun.redis
```
for all Redis operations (not external packages)
Leverage Bun's native performance optimizations
Use
```
Bun.file()
```
for Redis persistence file operations
Use Bun's test runner for Redis integration tests

本技能可与bun-expert技能配合使用。在Bun中使用Redis时：

所有Redis操作均使用
```
Bun.redis
```
（不使用外部包）
利用Bun的原生性能优化
使用
```
Bun.file()
```
处理Redis持久化文件操作
使用Bun的测试运行器进行Redis集成测试

Bun.redis Client Fundamentals

Bun.redis客户端基础

Connection Setup

连接设置

typescript

// Default client (uses VALKEY_URL, REDIS_URL, or localhost:6379)
import { redis } from "bun";
await redis.set("key", "value");

// Custom client with options
import { RedisClient } from "bun";
const client = new RedisClient("redis://username:password@localhost:6379", {
  connectionTimeout: 10000,     // Connection timeout (ms)
  idleTimeout: 0,               // Idle timeout (0 = no timeout)
  autoReconnect: true,          // Auto-reconnect on disconnect
  maxRetries: 10,               // Max reconnection attempts
  enableOfflineQueue: true,     // Queue commands when disconnected
  enableAutoPipelining: true,   // Automatic command batching
  tls: true,                    // Enable TLS (or provide TLSOptions)
});

typescript

// Default client (uses VALKEY_URL, REDIS_URL, or localhost:6379)
import { redis } from "bun";
await redis.set("key", "value");

// Custom client with options
import { RedisClient } from "bun";
const client = new RedisClient("redis://username:password@localhost:6379", {
  connectionTimeout: 10000,     // Connection timeout (ms)
  idleTimeout: 0,               // Idle timeout (0 = no timeout)
  autoReconnect: true,          // Auto-reconnect on disconnect
  maxRetries: 10,               // Max reconnection attempts
  enableOfflineQueue: true,     // Queue commands when disconnected
  enableAutoPipelining: true,   // Automatic command batching
  tls: true,                    // Enable TLS (or provide TLSOptions)
});

URL Formats

URL格式

Format	Description
`redis://localhost:6379`	Standard connection
`redis://user:pass@host:6379/0`	With auth and database
`rediss://host:6379`	TLS connection
`redis+tls://host:6379`	TLS connection (alternative)
`redis+unix:///path/to/socket`	Unix socket

格式	描述
`redis://localhost:6379`	标准连接
`redis://user:pass@host:6379/0`	带认证和指定数据库
`rediss://host:6379`	TLS连接
`redis+tls://host:6379`	TLS连接（替代格式）
`redis+unix:///path/to/socket`	Unix套接字

Connection Lifecycle

连接生命周期

typescript

const client = new RedisClient();
await client.connect();           // Explicit connect (optional - lazy by default)
await client.duplicate();         // Create duplicate connection for Pub/Sub
client.close();                   // Close connection

// Event handlers
client.onconnect = () => console.log("Connected");
client.onclose = (error) => console.log("Disconnected:", error);

// Status
console.log(client.connected);      // boolean
console.log(client.bufferedAmount); // bytes buffered

typescript

const client = new RedisClient();
await client.connect();           // Explicit connect (optional - lazy by default)
await client.duplicate();         // Create duplicate connection for Pub/Sub
client.close();                   // Close connection

// Event handlers
client.onconnect = () => console.log("Connected");
client.onclose = (error) => console.log("Disconnected:", error);

// Status
console.log(client.connected);      // boolean
console.log(client.bufferedAmount); // bytes buffered

Automatic Pipelining

自动流水线

Commands are automatically pipelined for performance. Use

Promise.all()

for concurrent operations:

typescript

const [a, b, c] = await Promise.all([
  redis.get("key1"),
  redis.get("key2"),
  redis.get("key3")
]);

为提升性能，命令会自动进行流水线处理。使用

Promise.all()

执行并发操作：

typescript

const [a, b, c] = await Promise.all([
  redis.get("key1"),
  redis.get("key2"),
  redis.get("key3")
]);

Raw Command Execution

原始命令执行

For commands not yet wrapped (66 commands native, 400+ via send):

typescript

await redis.send("PFADD", ["hll", "value1", "value2"]);
await redis.send("LRANGE", ["mylist", "0", "-1"]);
await redis.send("SCAN", ["0", "MATCH", "user:*", "COUNT", "100"]);

对于尚未封装的命令（原生支持66个命令，通过send支持400+个）：

typescript

await redis.send("PFADD", ["hll", "value1", "value2"]);
await redis.send("LRANGE", ["mylist", "0", "-1"]);
await redis.send("SCAN", ["0", "MATCH", "user:*", "COUNT", "100"]);

Error Handling

错误处理

typescript

try {
  await redis.get("key");
} catch (error) {
  if (error.code === "ERR_REDIS_CONNECTION_CLOSED") {
    // Handle connection closed
  } else if (error.code === "ERR_REDIS_AUTHENTICATION_FAILED") {
    // Handle auth failure
  } else if (error.message.includes("WRONGTYPE")) {
    // Handle type mismatch
  }
}

typescript

try {
  await redis.get("key");
} catch (error) {
  if (error.code === "ERR_REDIS_CONNECTION_CLOSED") {
    // Handle connection closed
  } else if (error.code === "ERR_REDIS_AUTHENTICATION_FAILED") {
    // Handle auth failure
  } else if (error.message.includes("WRONGTYPE")) {
    // Handle type mismatch
  }
}

Quick Reference - Native Commands

快速参考 - 原生命令

Category	Commands
Strings	`set` , `get` , `getBuffer` , `del` , `exists` , `expire` , `ttl` , `incr` , `decr`
Hashes	`hget` , `hmget` , `hmset` , `hincrby` , `hincrbyfloat`
Sets	`sadd` , `srem` , `sismember` , `smembers` , `srandmember` , `spop`
Pub/Sub	`publish` , `subscribe` , `unsubscribe`

For complete data structure reference, see DATA-STRUCTURES.md.

分类	命令
字符串	`set` , `get` , `getBuffer` , `del` , `exists` , `expire` , `ttl` , `incr` , `decr`
哈希	`hget` , `hmget` , `hmset` , `hincrby` , `hincrbyfloat`
集合	`sadd` , `srem` , `sismember` , `smembers` , `srandmember` , `spop`
Pub/Sub	`publish` , `subscribe` , `unsubscribe`

完整的数据结构参考，请查看DATA-STRUCTURES.md。

Key Naming Conventions

键命名规范

Use consistent naming throughout your application:

Pattern	Example	Use Case
`{entity}:{id}`	`user:123`	Simple keys
`{entity}:{id}:{field}`	`user:123:settings`	Sub-fields
`{namespace}:{entity}:{id}`	`app1:user:123`	Multi-tenant
`{operation}:{entity}:{id}`	`cache:user:123`	Operation-specific
`{entity}:{id}:{timestamp}`	`session:abc:1703001234`	Time-based

在应用中使用一致的命名规则：

模式	示例	使用场景
`{entity}:{id}`	`user:123`	简单键
`{entity}:{id}:{field}`	`user:123:settings`	子字段
`{namespace}:{entity}:{id}`	`app1:user:123`	多租户
`{operation}:{entity}:{id}`	`cache:user:123`	特定操作
`{entity}:{id}:{timestamp}`	`session:abc:1703001234`	基于时间

Quick Patterns Reference

快速模式参考

Cache-Aside Pattern

缓存旁路模式

typescript

async function cached<T>(key: string, ttl: number, fetch: () => Promise<T>): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const data = await fetch();
  await redis.set(key, JSON.stringify(data));
  await redis.expire(key, ttl);
  return data;
}

// Usage
const user = await cached(`user:${id}`, 3600, () => db.findUser(id));

typescript

async function cached<T>(key: string, ttl: number, fetch: () => Promise<T>): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const data = await fetch();
  await redis.set(key, JSON.stringify(data));
  await redis.expire(key, ttl);
  return data;
}

// Usage
const user = await cached(`user:${id}`, 3600, () => db.findUser(id));

Rate Limiting

限流

typescript

async function rateLimit(id: string, limit: number, window: number): Promise<boolean> {
  const key = `ratelimit:${id}`;
  const count = await redis.incr(key);
  if (count === 1) await redis.expire(key, window);
  return count <= limit;
}

// Usage
if (!await rateLimit(userId, 100, 60)) {
  throw new Error("Rate limit exceeded");
}

typescript

async function rateLimit(id: string, limit: number, window: number): Promise<boolean> {
  const key = `ratelimit:${id}`;
  const count = await redis.incr(key);
  if (count === 1) await redis.expire(key, window);
  return count <= limit;
}

// Usage
if (!await rateLimit(userId, 100, 60)) {
  throw new Error("Rate limit exceeded");
}

Distributed Lock

分布式锁

typescript

async function acquireLock(resource: string, ttlMs: number): Promise<string | null> {
  const token = crypto.randomUUID();
  const result = await redis.send("SET", [resource, token, "NX", "PX", ttlMs.toString()]);
  return result === "OK" ? token : null;
}

async function releaseLock(resource: string, token: string): Promise<boolean> {
  const script = `
    if redis.call("GET", KEYS[1]) == ARGV[1] then
      return redis.call("DEL", KEYS[1])
    end
    return 0
  `;
  const result = await redis.send("EVAL", [script, "1", resource, token]);
  return result === 1;
}

For complete patterns, see PATTERNS.md.

typescript

async function acquireLock(resource: string, ttlMs: number): Promise<string | null> {
  const token = crypto.randomUUID();
  const result = await redis.send("SET", [resource, token, "NX", "PX", ttlMs.toString()]);
  return result === "OK" ? token : null;
}

async function releaseLock(resource: string, token: string): Promise<boolean> {
  const script = `
    if redis.call("GET", KEYS[1]) == ARGV[1] then
      return redis.call("DEL", KEYS[1])
    end
    return 0
  `;
  const result = await redis.send("EVAL", [script, "1", resource, token]);
  return result === 1;
}

完整的模式参考，请查看PATTERNS.md。

Performance Guidelines

性能指南

Do's

建议做法

Use pipelining for multiple commands:
```
Promise.all([...])
```
Prefer atomic operations:
```
INCR
```
over
```
GET
```
+
```
SET
```
Use Lua scripts for complex atomic operations
Set appropriate TTLs to prevent memory bloat
Keep values small (<100KB ideal, <1MB max)
Use connection pooling via RedisClient reuse

使用流水线处理多个命令：
```
Promise.all([...])
```
优先使用原子操作：用
```
INCR
```
替代
```
GET
```
+
```
SET
```
使用Lua脚本实现复杂的原子操作
设置合适的TTL避免内存膨胀
保持值的大小较小（理想情况<100KB，最大<1MB）
通过复用RedisClient实现连接池

Don'ts

不建议做法

Avoid KEYS in production - use
```
SCAN
```
instead
Don't store large objects - break into smaller pieces
Avoid blocking commands on main connection - use
```
duplicate()
```
Don't ignore TTLs - set expiration on all cached data

生产环境避免使用KEYS命令 - 改用
```
SCAN
```
不要存储大对象 - 拆分为更小的片段
避免在主连接上使用阻塞命令 - 使用
```
duplicate()
```
不要忽略TTL - 为所有缓存数据设置过期时间

Monitoring

监控

typescript

// Server info
const info = await redis.send("INFO", ["memory"]);

// Memory usage
const memoryUsage = await redis.send("MEMORY", ["USAGE", "mykey"]);

// Slow log
const slowLog = await redis.send("SLOWLOG", ["GET", "10"]);

// Client list
const clients = await redis.send("CLIENT", ["LIST"]);

typescript

// Server info
const info = await redis.send("INFO", ["memory"]);

// Memory usage
const memoryUsage = await redis.send("MEMORY", ["USAGE", "mykey"]);

// Slow log
const slowLog = await redis.send("SLOWLOG", ["GET", "10"]);

// Client list
const clients = await redis.send("CLIENT", ["LIST"]);

Document	Description
DATA-STRUCTURES.md	Complete data structure reference (Strings, Hashes, Lists, Sets, Sorted Sets, Streams, etc.)
STACK-FEATURES.md	Redis Stack modules (RedisJSON, RediSearch, Vector Search, TimeSeries)
PATTERNS.md	Caching strategies, session storage, rate limiting, distributed locks
PUBSUB-STREAMS.md	Pub/Sub messaging and Streams for event sourcing
SCRIPTING.md	Lua scripting patterns and script management
TESTING.md	Testing patterns for Redis operations with bun:test

文档	描述
DATA-STRUCTURES.md	完整的数据结构参考（字符串、哈希、列表、集合、有序集合、Streams等）
STACK-FEATURES.md	Redis Stack模块（RedisJSON、RediSearch、Vector Search、TimeSeries）
PATTERNS.md	缓存策略、会话存储、限流、分布式锁
PUBSUB-STREAMS.md	Pub/Sub消息传递和Streams用于事件溯源
SCRIPTING.md	Lua脚本模式和脚本管理
TESTING.md	使用bun:test进行Redis操作的测试模式

Sub-Agents

子代理

Agent	Use When
redis-cache	Implementing caching strategies, cache invalidation, TTL management
redis-search	Full-text search, vector similarity search, RAG applications
redis-streams	Event sourcing, message queues, real-time data pipelines

代理	使用场景
redis-cache	实现缓存策略、缓存失效、TTL管理
redis-search	全文搜索、向量相似度搜索、RAG应用
redis-streams	事件溯源、消息队列、实时数据管道

When This Skill Activates

技能触发条件

This skill automatically activates when:

Working with
```
Bun.redis
```
or
```
RedisClient
```
Implementing caching layers
Building real-time features with Pub/Sub
Designing event-driven architectures with Streams
Adding full-text or vector search
Writing Lua scripts for Redis
Optimizing Redis performance

当出现以下情况时，本技能自动激活：

使用
```
Bun.redis
```
或
```
RedisClient
```
实现缓存层
构建基于Pub/Sub的实时功能
设计基于Streams的事件驱动架构
添加全文或向量搜索
编写Redis的Lua脚本
优化Redis性能

redis-expert

Original

Translation

Redis Expert Skill

Redis专家技能

Cross-Skill Integration

跨技能集成

Bun.redis Client Fundamentals

Bun.redis客户端基础

Connection Setup

连接设置

URL Formats

URL格式

Connection Lifecycle

连接生命周期

Automatic Pipelining

自动流水线

Raw Command Execution

原始命令执行

Error Handling

错误处理

Quick Reference - Native Commands

快速参考 - 原生命令

Key Naming Conventions

键命名规范

Quick Patterns Reference

快速模式参考

Cache-Aside Pattern

缓存旁路模式

Rate Limiting

限流

Distributed Lock

分布式锁

Performance Guidelines

性能指南

Do's

建议做法

Don'ts

不建议做法

Monitoring

监控

Related Documentation

相关文档

Sub-Agents

子代理

When This Skill Activates

技能触发条件