Midway Redis 集成指南:基于 @midwayjs/redis 的单机、哨兵与集群实战
Midway Redis 集成指南:基于 @midwayjs/redis 的单机、哨兵与集群实战
本文面向 Midway 开发者,系统讲解如何在项目中接入 @midwayjs/redis 组件,覆盖单客户端、哨兵(Sentinel)、集群(Cluster)与多客户端四种配置形态,以及 RedisService、RedisServiceFactory、@InjectClient 三种服务获取方式,并结合仓库源码与测试用例剖析底层连接管理与生命周期实现。读完本文,你将能够在标准项目、Serverless 场景以及集成测试中快速、规范地使用 Redis。
组件能力一览
@midwayjs/redis 是 Midway 生态中的官方 Redis 组件包,其定位与能力边界如下:
| 描述 | 是否支持 |
|---|---|
| 可用于标准项目 | ✅ |
| 可用于 Serverless | ✅ |
| 可用于集成(integration) | ✅ |
| 包含独立主框架 | ❌ |
| 包含独立日志 | ❌ |
也就是说,它不是一个独立可运行的主框架,而是作为 Midway 应用的一个功能组件被引入,日志统一使用 Midway 核心日志体系。组件内部基于 ioredis 封装,因此 ioredis 的全部客户端能力(字符串、Hash、List、Set、ZSet、Pub/Sub、Lua 脚本等)都可以直接使用。
安装依赖
@midwayjs/redis 是主要功能包,安装命令如下:
$ npm i @midwayjs/redis@3 --save
也可以直接在 package.json 中声明依赖后重新安装:
{
"dependencies": {
"@midwayjs/redis": "^3.0.0",
// ...
}
}
安装完成后,组件会自动携带 ioredis 作为其运行依赖,业务代码无需再手动安装 ioredis,即可直接使用其返回的客户端实例。
引入组件
在项目入口 src/configuration.ts 中通过 imports 引入 redis 组件:
import { Configuration } from '@midwayjs/core';
import * as redis from '@midwayjs/redis';
import { join } from 'path';
@Configuration({
imports: [
// ...
redis // import redis components
],
importConfigs: [
join(__dirname, 'config')
],
})
export class MainConfiguration {
}
引入后,Midway 会在容器启动阶段自动实例化 RedisServiceFactory 并完成客户端连接。从源码看,组件配置类 packages/redis/src/configuration.ts 以 namespace: 'redis' 注册,并在 onReady 阶段通过 container.getAsync(RedisServiceFactory) 主动触发工厂初始化,确保所有依赖 Redis 的业务代码在启动后即可安全注入;同时在 onStop 阶段调用 factory.stop() 优雅关闭所有连接。它还实现了 onHealthCheck,用于探活检查——该逻辑会遍历所有已创建的客户端实例,若发现某个非低优先级(isLowPriority 为 false)的客户端状态不是 ready,则判定健康检查失败,具体实现可参考同文件中的 onHealthCheck 方法。
配置 Redis
Redis 配置统一放在 src/config/config.default.ts 中,通过 redis 配置项声明。组件底层配置类型定义为 ServiceFactoryConfigOption<RedisConfigOptions>(见 packages/redis/src/interface.ts),其中 RedisConfigOptions 兼容 ioredis 的 RedisOptions,也支持 nodes + ClusterOptions 的集群形态,因此除下述示例外,ioredis 文档中的更多连接参数(超时、重试策略、TLS 等)均可直接透传使用。
单客户端配置
// src/config/config.default.ts
export default {
// ...
redis: {
client: {
port: 6379, // Redis port
host: "127.0.0.1", // Redis host
password: "auth ",
db: 0
},
},
}
这是最常见的形态,等价于声明一个名为 default 的客户端实例。需要说明的是,host 与 port 是必填项:从 packages/redis/src/manager.ts 的 createClient 逻辑可以看出,非哨兵、非集群模式下组件会通过 assert 校验 config.host && config.port,缺失任一字段都会在启动时抛出 [midway:redis] client(xxx) 'host: ...', 'port: ...' are required on config 错误。连接成功后日志会打印 [midway:redis] client(xxx) connect success,便于排查。
测试用例 packages/redis/test/fixtures/base-app-single-client/src/config.default.ts 即采用 client 单客户端形态,与之对应的单客户端读写测试位于 packages/redis/test/index.test.ts。
哨兵(Sentinel)模式配置
// src/config/config.default.ts
export default {
// ...
redis: {
client: {
sentinels: [{ // Sentinel instances
port: 26379, // Sentinel port
host: '127.0.0.1', // Sentinel host
}],
name: 'mymaster', // Master name
password: 'auth',
db: 0
},
},
}
当配置中存在 sentinels 数组时,组件会走哨兵分支创建 ioredis 客户端:每个哨兵节点必须包含 host 与 port,否则同样会触发 assert 校验错误;name 指定主节点(master)名称。仓库内置的哨兵 fixture packages/redis/test/fixtures/base-app-sentinel/src/config.default.ts 配置了两个哨兵节点与 mymaster 主名,可作为最小可用参考。
集群(Cluster)模式配置
集群模式需要配置多个节点,并通过 cluster: true 开启:
// src/config/config.default.ts
export default {
// ...
redis: {
// Cluster Redis
client: {
cluster: true
nodes: [{
host: 'host',
port: 'port',
},{
host: 'host',
port: 'port',
}],
redisOptions: {
family: '',
password: 'xxxx',
db: 'xxx'
}
}
},
}
从 packages/redis/src/manager.ts 的源码可以看到集群分支的两条硬性校验:一是 nodes 必须存在且非空,二是每个节点必须同时具备 host 与 port。满足条件后组件会通过 new Redis.Cluster(config.nodes, config) 创建集群客户端,redisOptions 中的连接参数会被透传给底层节点。这里给出的 family(IP 协议族)、password、db 为典型透传项,实际可按 ioredis Cluster 选项进一步补充 maxRedirections、scaleReads 等集群专属参数。
多客户端配置
// src/config/config.default.ts
export default {
// ...
redis: {
// Multi Redis
clients: {
instance1: {
host: 'host',
port: 'port',
password: 'password',
db: 'db',
},
instance2: {
host: 'host',
port: 'port',
password: 'password',
db: 'db',
},
},
},
}
使用 clients 对象可以同时连接多个 Redis 实例,每个 key 即客户端实例名。仓库的多客户端 fixture packages/redis/test/fixtures/base-app-multi-client/src/config.default.ts 声明了 session(db 0)与 cache(db 1)两个实例,对应测试通过 redisServiceFactory.get('cache') 获取指定实例并完成读写。
注意:client 与 clients 是两种互斥的声明方式,前者声明默认实例,后者声明多实例集合。另外 RedisServiceFactory 继承自 Midway 的 ServiceFactory 基类,因此 clients 形态下还支持通过 priority 配置实例优先级(测试中可见 priority: { default: 'Low' } 的用法),低优先级实例不会触发健康检查失败。
ioredis 支持的全部连接参数可参考 ioredis 官方 API 文档(仓库源码中的 RedisConfigOptions 直接继承自 ioredis 类型定义)。
使用 Redis 服务
方式一:直接注入 RedisService
RedisService 是默认实例的便捷封装,可以在任意被 IoC 容器管理的类中注入:
import { Provide, Controller, Inject, Get } from '@midwayjs/core';
import { RedisService } from '@midwayjs/redis';
@Provide()
export class UserService {
@Inject()
redisService: RedisService;
async invoke() {
// Simple setup
await this.redisService.set('foo', 'bar');
// Set the expiration time in seconds.
await this.redisService.set('foo', 'bar', 'EX', 10);
// get data
const result = await this.redisService.get('foo');
// result => bar
}
}
从实现上看,RedisService(见 packages/redis/src/manager.ts)在 @Init() 阶段从工厂中取出默认客户端(getDefaultClientName() 或 'default'),并通过 delegateTargetAllPrototypeMethod(RedisService, Redis) 将 ioredis 实例的全部原型方法代理到自身,因此 set、get、hset、publish 等所有 ioredis 命令均可直接调用;若默认实例不存在,会抛出 redis default instance not found 错误。它同样支持 defineCommand 注册自定义 Lua 命令,注册后新命令会被动态代理到服务上——这一点在测试 packages/redis/test/index.test.ts 中有直接验证:通过 redisService.defineCommand('myecho', {...}) 后即可调用 redisService.myecho(...) 执行 Lua 脚本。
方式二:通过 RedisServiceFactory 获取不同实例
多客户端场景下,可以注入工厂并按实例名获取客户端:
import { RedisServiceFactory } from '@midwayjs/redis';
import { join } from 'path';
@Provide()
export class UserService {
@Inject()
redisServiceFactory: RedisServiceFactory;
async save() {
const redis1 = this.redisServiceFactory.get('instance1');
const redis2 = this.redisServiceFactory.get('instance3');
//...
}
}
RedisServiceFactory 是单例的客户端工厂(@Scope(ScopeEnum.Singleton)),在 @Init() 阶段根据 redis 配置并发初始化全部客户端(initClients(this.redisConfig, { concurrent: true }))。每个客户端创建时会等待其 ready 事件后再返回,任一客户端 error 都会导致启动失败——测试用例 should fail when unable to connect redis(packages/redis/test/index.test.ts)正是通过坏连接 fixture 验证了这一点。
工厂还支持 customClientClass 自定义客户端类:在配置中传入自定义类的引用后,组件会用 new customClientClass(otherConfig) 替换默认的 ioredis 客户端(customClientClass 本身会被从透传配置中剔除),相关验证见 packages/redis/test/customClient.test.ts。
方式三:通过装饰器获取指定实例
使用 @InjectClient 装饰器可以直接注入指定实例名的客户端:
import { RedisServiceFactory, RedisService } from '@midwayjs/redis';
import { InjectClient } from '@midwayjs/core';
@Provide()
export class UserService {
@InjectClient(RedisServiceFactory, 'instance1')
redis1: RedisService;
@InjectClient(RedisServiceFactory, 'instance3')
redis2: RedisService;
async save() {
//...
}
}
@InjectClient 是 Midway 核心提供的工厂注入装饰器,第一个参数指定工厂类,第二个参数指定实例名。这种方式适合业务中需要同时使用多个 Redis 实例(如 session 库与 cache 库分离)的场合,避免了手动 get 的样板代码。
从源码看连接生命周期与扩展能力
除文档中的基础用法外,组件在仓库中还提供了两项值得留意的底层能力:
1. 链路追踪(Tracing)
RedisServiceFactory 在客户端创建成功后调用 bindTraceContext(见 packages/redis/src/manager.ts),会包装客户端的 sendCommand,为每条 Redis 命令创建退出 Span(redis.<commandName>),并附带 midway.protocol: redis、midway.redis.command、midway.redis.client 等属性。可通过配置 redis.tracing.enable 控制开关,redis.tracing.meta 与 redis.tracing.injector 定制追踪元数据与注入逻辑。对应验证见 packages/redis/test/trace.test.ts。
2. 基于 Redis 的服务发现(ServiceDiscovery)
组件还提供了 RedisServiceDiscovery(见 packages/redis/src/extension/serviceDiscovery.ts),可将 Redis 作为注册中心:实例通过 register/deregister/online/offline 管理自身注册信息,key 格式为 <prefix><serviceName>:instance:<instanceId>,默认前缀 services:,TTL 默认 30 秒并自动续期;消费方通过 getInstances(serviceName) 获取实例列表,实例变更通过 Redis Pub/Sub 通道 service:change:<serviceName> 推送,并支持 ttl、prefix、scanCount(SCAN 游标遍历数量,默认 100)、downTTL 等选项(类型定义见 packages/redis/src/interface.ts)。
以上两项能力均建立在文档所述的客户端配置体系之上,业务代码可按需在 redis 配置中追加 tracing 与 serviceDiscovery 选项启用。
小结
通过本文可以完成 Midway 项目中 Redis 的完整接入:安装 @midwayjs/redis@3 并在 configuration.ts 中引入组件,依据单机、哨兵、集群或多实例场景配置 redis 选项,再通过 RedisService、RedisServiceFactory 或 @InjectClient 三种方式注入使用。组件在启动阶段完成连接就绪校验与健康检查,退出阶段自动优雅关闭,并额外提供链路追踪与服务发现能力,无论是标准 Web 项目、Serverless 函数还是集成测试环境,都可以复用同一套配置与注入模型。