Midway Redis 集成指南:基于 @midwayjs/redis 的单机、哨兵与集群实战

原创2026-10-08 22:09:031,617 阅读
文章标签:后端微服务云原生

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 函数还是集成测试环境,都可以复用同一套配置与注入模型。

登录后查看全文
midway