Redis
使用 Bun 原生 Redis 客户端，基于 Promise 的 API
Bun 原生 Redis 客户端提供基于 Promise 的 API，内置连接管理、完全类型化的响应以及 TLS 支持。
redis.tsimport { redis } from "bun";
// 设置键值
await redis.set("greeting", "Hello from Bun!");
// 获取键值
const greeting = await redis.get("greeting");
console.log(greeting); // "Hello from Bun!"
// 递增计数器
await redis.set("counter", 0);
await redis.incr("counter");
// 检查键是否存在
const exists = await redis.exists("greeting");
// 删除键
await redis.del("greeting");
入门
使用 Redis 客户端，首先需要创建一个连接：
redis.tsimport { redis, RedisClient } from "bun";
// 使用默认客户端（连接信息从环境变量读取）
// 默认使用 process.env.REDIS_URL
await redis.set("hello", "world");
const result = await redis.get("hello");
// 创建自定义客户端
const client = new RedisClient("redis://username:password@localhost:6379");
await client.set("counter", "0");
await client.incr("counter");
默认情况下，客户端按优先级从以下环境变量读取连接信息：
REDIS_URLVALKEY_URL- 若未设置，默认使用
"redis://localhost:6379"
连接生命周期
Redis 客户端会自动在后台管理连接：
redis.ts// 未执行命令前不会连接
const client = new RedisClient();
// 第一次命令触发连接建立
await client.set("key", "value");
// 连接保持开启，供后续命令使用
await client.get("key");
// 使用结束后显式关闭连接
client.close();
你也可以手动控制连接生命周期：
redis.tsconst client = new RedisClient();
// 显式连接
await client.connect();
// 执行命令
await client.set("key", "value");
// 完成后断开连接
client.close();
基本操作
字符串操作
redis.ts// 设置键值
await redis.set("user:1:name", "Alice");
// 获取键值
const name = await redis.get("user:1:name");
// 以 Uint8Array 形式获取键值
const buffer = await redis.getBuffer("user:1:name");
// 删除键
await redis.del("user:1:name");
// 检查键是否存在
const exists = await redis.exists("user:1:name");
// 设置过期时间（秒）
await redis.set("session:123", "active");
await redis.expire("session:123", 3600); // 一小时后过期
// 获取剩余生存时间（秒）
const ttl = await redis.ttl("session:123");
数值操作
redis.ts// 设置初始值
await redis.set("counter", "0");
// 自增 1
await redis.incr("counter");
// 自减 1
await redis.decr("counter");
哈希操作
redis.ts// 设置哈希多个字段
await redis.hmset("user:123", ["name", "Alice", "email", "alice@example.com", "active", "true"]);
// 获取哈希多个字段
const userFields = await redis.hmget("user:123", ["name", "email"]);
console.log(userFields); // ["Alice", "alice@example.com"]
// 获取单个哈希字段（不存在返回 null）
const userName = await redis.hget("user:123", "name");
console.log(userName); // "Alice"
// 哈希字段数值递增
await redis.hincrby("user:123", "visits", 1);
// 哈希字段浮点数递增
await redis.hincrbyfloat("user:123", "score", 1.5);
集合操作
redis.ts// 添加成员到集合
await redis.sadd("tags", "javascript");
// 从集合移除成员
await redis.srem("tags", "javascript");
// 检查成员是否在集合中
const isMember = await redis.sismember("tags", "javascript");
// 获取集合所有成员
const allTags = await redis.smembers("tags");
// 获取随机成员
const randomTag = await redis.srandmember("tags");
// 弹出（移除并返回）随机成员
const poppedTag = await redis.spop("tags");
发布/订阅（Pub/Sub）
Bun 为 Redis Pub/Sub 协议提供了原生绑定，该功能在 Bun 1.2.23 中加入。
基本用法
在 publisher.ts 中创建发布者：
publisher.tsimport { RedisClient } from "bun";
const writer = new RedisClient("redis://localhost:6379");
await writer.connect();
await writer.publish("general", "Hello everyone!");
writer.close();
在另一个文件 subscriber.ts 中创建订阅者：
subscriber.tsimport { RedisClient } from "bun";
const listener = new RedisClient("redis://localhost:6379");
await listener.connect();
await listener.subscribe("general", (message, channel) => {
console.log(`Received: ${message}`);
});
在一个终端运行订阅者：
terminal
bun run subscriber.ts
另一个终端运行发布者：
terminal
bun run publisher.ts
发布消息
使用 publish() 方法发布消息：
redis.tsawait client.publish(channelName, message);
订阅频道
使用 .subscribe() 方法订阅频道：
redis.tsawait client.subscribe(channel, (message, channel) => {});
使用 .unsubscribe() 取消订阅：
redis.tsawait client.unsubscribe(); // 取消所有频道订阅
await client.unsubscribe(channel); // 取消指定频道订阅
await client.unsubscribe(channel, listener); // 取消指定监听器订阅
高级用法
命令执行与流水线
客户端默认自动进行流水线处理，通过批量发送多个命令并在响应到达时依序处理，提升性能：
redis.ts// 命令默认自动流水线处理
const [infoResult, listResult] = await Promise.all([redis.get("user:1:name"), redis.get("user:2:email")]);
要禁用自动流水线处理，请将 enableAutoPipelining 选项设置为 false：
redis.tsconst client = new RedisClient("redis://localhost:6379", {
enableAutoPipelining: false, // [!code ++]
});
原生命令执行
使用 send 方法运行任意 Redis 命令，包括没有专用方法的命令。第一个参数是命令名称，第二个参数是字符串参数数组。
redis.ts// 执行任意 Redis 命令
const info = await redis.send("INFO", []);
// 向列表 LPUSH
await redis.send("LPUSH", ["mylist", "value1", "value2"]);
// 获取列表范围
const list = await redis.send("LRANGE", ["mylist", "0", "-1"]);
连接事件
可以注册连接事件处理函数：
redis.tsconst client = new RedisClient();
// 成功连接 Redis 服务器时调用
client.onconnect = () => {
console.log("Connected to Redis server");
};
// 与 Redis 服务器断开连接时调用
client.onclose = error => {
console.error("Disconnected from Redis server:", error);
};
// 手动连接与断开
await client.connect();
client.close();
连接状态及监控
redis.ts// 检查连接状态
console.log(client.connected); // 布尔值，表示连接是否建立
// 查看缓冲区数据大小（字节）
console.log(client.bufferedAmount);
类型转换
客户端会自动将 Redis 响应转换为 JavaScript 值：
- Integer 响应会作为 JavaScript 数字返回
- Bulk 字符串会作为 JavaScript 字符串返回
- Simple 字符串会作为 JavaScript 字符串返回
- Null Bulk 字符串和 Null 数组会作为
null返回 - 数组响应会作为 JavaScript 数组返回
- Big number 响应（RESP3）会作为
BigInt返回。非整数文本的负载会作为字符串返回。getBuffer会将负载作为Buffer返回 - 错误响应会抛出带有相应错误代码的 JavaScript 错误
- 布尔响应（RESP3）会作为 JavaScript 布尔值返回
- Map 响应（RESP3）会作为 JavaScript 对象返回
- Set 响应（RESP3）会作为 JavaScript 数组返回
特殊命令特别处理：
EXISTS返回布尔值（1 转 true，0 转 false）SISMEMBER返回布尔值（1 转 true，0 转 false）
以下命令会禁用自动流水线：
AUTHINFOQUITEXECMULTIWATCHSCRIPTSELECTCLUSTERDISCARDUNWATCHPIPELINESUBSCRIBEPSUBSCRIBEUNSUBSCRIBEUNPSUBSCRIBE
连接选项
创建客户端时，可以传入选项来配置连接：
redis.tsconst client = new RedisClient("redis://localhost:6379", {
// 连接超时（毫秒），默认 10000
connectionTimeout: 5000,
// Idle timeout in milliseconds (default: 0 = no timeout). Bun counts it
// from the last data the server sent. Sending does not reset it. When it
// fires, Bun closes the connection and runs onclose. Bun does not reconnect
// on its own, even with autoReconnect: true. Call connect() to reconnect.
idleTimeout: 30000,
// 断线后是否自动重连，默认 true
autoReconnect: true,
// 最大重连尝试次数（默认：20）
maxRetries: 10,
// 断线时是否队列命令，默认 true
enableOfflineQueue: true,
// 是否自动流水线命令，默认 true
enableAutoPipelining: true,
// TLS 配置（默认 false）
tls: true,
// 或者提供自定义 TLS 配置：
// tls: {
// rejectUnauthorized: true,
// ca: "path/to/ca.pem",
// cert: "path/to/cert.pem",
// key: "path/to/key.pem",
// }
});
重连行为
连接断开时，客户端会自动尝试使用指数退避算法重连：
- 客户端从较短的延迟（50ms）开始，每次尝试都会将延迟加倍
- 客户端将重连延迟上限设为 2000ms（2 秒）
- 客户端最多尝试重连
maxRetries次（默认值：20） - 断开连接期间，客户端会：
- 如果
enableOfflineQueue为 true（默认值），则将命令加入队列 - 如果
enableOfflineQueue为 false，则立即拒绝命令
- 如果
支持的 URL 格式
Redis 客户端支持多种连接 URL 格式：
redis.ts// 标准 Redis URL
new RedisClient("redis://localhost:6379");
new RedisClient("redis://localhost:6379");
// 带认证信息
new RedisClient("redis://username:password@localhost:6379");
// 带数据库编号
new RedisClient("redis://localhost:6379/0");
// TLS 连接
new RedisClient("rediss://localhost:6379");
new RedisClient("rediss://localhost:6379");
new RedisClient("redis+tls://localhost:6379");
new RedisClient("redis+tls://localhost:6379");
// Unix 套接字连接
new RedisClient("redis+unix:///path/to/socket");
new RedisClient("redis+unix:///path/to/socket");
// Unix 套接字上的 TLS
new RedisClient("redis+tls+unix:///path/to/socket");
new RedisClient("redis+tls+unix:///path/to/socket");
错误处理
Redis 客户端会抛出带类型的错误，用于不同场景的异常：
redis.tstry {
await redis.get("non-existent-key");
} catch (error) {
if (error.code === "ERR_REDIS_CONNECTION_CLOSED") {
console.error("与 Redis 服务器的连接已关闭");
} else if (error.code === "ERR_REDIS_AUTHENTICATION_FAILED") {
console.error("认证失败");
} else {
console.error("意外错误:", error);
}
}
常见错误码：
ERR_REDIS_CONNECTION_CLOSED- 与服务器的连接已关闭ERR_REDIS_AUTHENTICATION_FAILED- 无法通过服务器的身份验证ERR_REDIS_INVALID_RESPONSE- 收到来自服务器的无效响应ERR_REDIS_SERVER_ERROR- 服务器发送了错误回复，可能是拒绝某条命令，或者在订阅者模式下关闭连接
示例用例
缓存
redis.tsasync function getUserWithCache(userId) {
const cacheKey = `user:${userId}`;
// 尝试先从缓存获取
const cachedUser = await redis.get(cacheKey);
if (cachedUser) {
return JSON.parse(cachedUser);
}
// 缓存未命中，从数据库获取
const user = await database.getUser(userId);
// 缓存 1 小时
await redis.set(cacheKey, JSON.stringify(user));
await redis.expire(cacheKey, 3600);
return user;
}
限流
redis.tsasync function rateLimit(ip, limit = 100, windowSecs = 3600) {
const key = `ratelimit:${ip}`;
// 计数自增
const count = await redis.incr(key);
// 第一次请求设置过期时间
if (count === 1) {
await redis.expire(key, windowSecs);
}
// 检测是否超出限制
return {
limited: count > limit,
remaining: Math.max(0, limit - count),
};
}
会话存储
redis.tsasync function createSession(userId, data) {
const sessionId = crypto.randomUUID();
const key = `session:${sessionId}`;
// 存储会话，设置过期时间
await redis.hmset(key, ["userId", userId.toString(), "created", Date.now().toString(), "data", JSON.stringify(data)]);
await redis.expire(key, 86400); // 24小时
return sessionId;
}
async function getSession(sessionId) {
const key = `session:${sessionId}`;
// 获取会话数据
const exists = await redis.exists(key);
if (!exists) return null;
const [userId, created, data] = await redis.hmget(key, ["userId", "created", "data"]);
return {
userId: Number(userId),
created: Number(created),
data: JSON.parse(data),
};
}
实现说明
Bun 的 Redis 客户端使用 Rust 实现，并使用 Redis 序列化协议（RESP3）。它会使用指数退避算法自动重连。它还会对命令进行流水线处理，因此可以在不等待先前命令响应的情况下发送多个命令。
限制及未来规划
我们计划在未来版本中解决的限制：
- 事务（MULTI/EXEC）需要使用原始命令
不支持的功能：
- Redis Sentinel
- Redis Cluster