由于 Midway 版本发布规则，@midwayjs/core 和组件有着版本对应关系，即低版本的 @midwayjs/core 无法使用高版本的组件。

比如 @midwayjs/axios@3.17.0 可能使用了高版本的 API，是无法在 @midwayjs/core@3.16.0 版本上执行的。

由于 npm 等包管理的特性，包安装时不存在联系，npm i @midwayjs/axios 时往往只会安装组件最新的版本，非常容易造成兼容性问题。

为此我们提供了 npx midway-version 命令，可以快速检查版本之间的兼容性错误。

在推行一阵子之后，我们发现很少有用户主动去执行这样的指令，只会在出错时被动执行，再加上锁包和不锁包的复杂场景，会出现一些很难复现和排查的现象。

为了降低复杂性，在 mwtsc 新版本的启动阶段，我们也加入了检查代码。

如果出现不兼容的版本，工具会进行提示。

此外，新增的 npx midway-version -m 指令可以让固化版本的用户也享受到更新工具。

和之前的 -u 指令不同，-m 会使用当前的 @midwayjs/core 版本，更新组件到最兼容的版本，而不是最新版本。

结合 mwtsc 和 midway-version 工具，可以更简单的管理版本，如有问题可以反馈给我们改进。

升级请参考 如何更新 Midway 中描述，请不要单独升级某个组件包。

本次 3.16 版本，重构了 Swagger 组件，新增了一个租户组件。

Tenant​

新增组件，提供 TenantManager 跨作用域管理租户信息。

比如：

import { TenantManager } from '@midwayjs/tenant';
import { Middleware, Inject, Singleton } from '@midwayjs/core';

// 请求链路中设置，中间件或者 Controller
@Middleware()
class TenantMiddleware {
  @Inject()
  tenantManager: tenant.TenantManager;

  resolve() {
    return async(ctx, next) => {
      this.tenantManager.setCurrentTenant({
        id: '123',
        name: '我的租户'
      });
    }
  }
}

// 服务中
@Singleton()
class TenantService {
  @Inject()
  tenantManager: tenant.TenantManager;

  async getTenantInfo() {
    const tenantInfo = await this.tenantManager.getCurrentTenant();
    console.log(tenantInfo.name);
    // 我的租户
  }
}

MQTT​

增加一个动态添加 mqtt 的方法。

import { Configuration, Inject } from '@midwayjs/core';
import * as mqtt from '@midwayjs/mqtt';

@Configuration({
  // ...
})
class MainConfiguration {
  
  @Inject()
  mqttFramework: mqtt.Framework;
  
  async onReady() {
    await this.mqttFramework.createSubscriber({
      host: 'test.mosquitto.org',
      port: 1883,
    }, {
      topicObject: 'test_midway_dynamic',
    }, TestSubscriber, 'test');
  }
}

Swagger​

代码重构，支持了 oneof 等特殊用法，增加几十个用例确保输出和 openapi 3.0 一致。

比如：

import { ApiProperty } from '@midwayjs/swagger';  

class Album {
  @ApiProperty()
  id: number;

  @ApiProperty()
  name: string;
}

class Photo {
  @ApiProperty({
    oneOf: [
      { type: 'string' },
      {
        type: 'array',
        items: {
          type: 'string',
        },
      },
    ],
  })
  name: string | string[];

  @ApiProperty({
    oneOf: [
      { type: Album },
      {
        type: 'array',
        items: {
          type: () => Album,
        },
      },
    ],
  })
  album: Album | Album[];
}

koa​

提供了 query 的 parse 相关配置。

mwtsc 工具​

切换回 tsc 自带的监听，稳定性更好。

更多的变化​

• 修复了一个健康检查服务丢失 this 的问题
• 参数装饰器增加了一个当前实例的参数

以及一大批依赖进行了更新，可以参考我们的 ChangeLog。

开工大吉。

升级请参考 如何更新 Midway 中描述，请不要单独升级某个组件包。

本次 3.15 版本，主要新增了 MQTT 组件。

全新的 MQTT 组件​

可以通过配置 sub 和 pub 创建多个不同的实例，方便满足用户需求。

更多细节可以接着查看 文档。

Swagger 方法级别的 Security 忽略​

现在可以通过 @ApiExcludeSecurity 来忽略特定的接口。

mwtsc 工具支持了 Alias Path 的识别和替换​

现在新工具已经可以认识 Alias 路径了。

更多的变化​

• @koa/router 升级到了 v12 版本
• 自定义参数装饰器支持抛出异常

此外，还有一大批依赖进行了更新，更多可以参考我们的 ChangeLog。

2024 新年快乐。

升级请参考 如何更新 Midway 中描述，请不要单独升级某个组件包。

本次 3.14 版本，重写了 Cache 组件，同时也带来了一些新的特性，我们将一一介绍。

全新的 CacheManager 组件​

这一版本，Midway 将底层依赖的 cache-manager 模块升级到了 v5 版本，由于存在 Breaking Change，启用了一个新的 @midwayjs/cache-manager 组件，原有 @midwayjs/cache 组件不再更新。

在新组件中，提供了装饰器 @Caching 用于快速缓存函数结果。

比如：

@Caching('default', 100)
async invokeData(name: string) {
  return name;
}

那么，在多次调用时就会缓存返回值，如果超时，则会返回新的值。

await invokeData('harry'); // => harry
await invokeData('harry1'); // => harry
await invokeData('harry2'); // => harry
await sleep(100);
await invokeData('harry3'); // => harry3

这在一些性能敏感的场景会非常有用。

此外，@Caching 装饰器还支持多级缓存，如果一个缓存实例配置了多个 Store，那么它将自动根据缓存的顺序进行处理。

最重要的一点，组件通过新设计器的 createRedisStore 方法支持复用 Redis 组件的配置了。

import { createRedisStore } from '@midwayjs/cache-manager';

// src/config/config.default.ts
export default {
  cacheManager: {
    clients: {
      default: {
        store: createRedisStore('default'),
        // ...
      },
    },
  },
  redis: {
    clients: {
      default: {
        port: 6379,
        host: '127.0.0.1',
      }
    }
  }
}

这下不再需要配置 Redis 多遍了。

更多功能可以接着查看 文档。

Swagger 组件的全新渲染方式​

由于之前的版本无法传递 swagger-ui 参数，这个版本设计了一组新的 UI 渲染方式，尽可能的帮助开发者自定义 UI。

现在，通过 renderSwaggerUIDist ，renderJSON 和 renderSwaggerUIRemote 方法，你可以选择自己喜欢的方式进行渲染。

// src/config/config.default.ts
import { renderSwaggerUIRemote } from '@midwayjs/swagger';

export default {
  // ...
  swagger: {
    swaggerUIRender: renderSwaggerUIRemote,
    swaggerUIRenderOptions: {
      // ...
    }
  },
}

只要网络环境允许，即使不再引用 swagger-ui-dist 包，也可以通过 CDN 资源加载 UI，进一步减轻服务端压力。

也可以仅输出 Swagger JSON 内容，不提供 UI，这都可以根据业务随心配置。

服务工厂实例支持优先级​

这一版本可以针对创建出的实例设置不同的实例优先级。

比如：

// config.default.ts
import { DEFAULT_PRIORITY } from '@midwayjs/core';

export default {
  redis: {
    clients: {
      instance1: {
        // ...
      },
      instance2: {
        // ...
      }
    },
    clientPriority: {
      instance1: DEFAULT_PRIORITY.L1,
      instance2: DEFAULT_PRIORITY.L3,
    }
  }
}

实例优先级不影响实例本身的功能，仅对实现了优先级判断的外部逻辑生效。

比如在健康检查时可以根据优先级进行忽略，低优先级的实例等价于弱依赖，会跳过健康检查。

这一功能目前仅有 HealthService 在使用，理论上别的逻辑也可能会用到，我们期待更多的可能性。

更多的变化​

• mikro-orm 于 2024.01.08 日发布了 v6 版本，现在 @midwayjs/mikro 组件也可以配合 v6 版本使用了
• @midwayjs/redis 增加了基于实例优先级的健康检查逻辑
• 服务工厂增加了 getClients() 和 getClientKeys() 方法，用于快速迭代实例
• 修复了 swagger 组件 ApiOperation 相关的一些问题
• mwtsc 工具修复了 windows 下开发的问题
• 文档的进一步精简，“其他” 菜单合并到了 “使用文档” 菜单中

此外，还有一大批依赖进行了更新，更多可以参考我们的 ChangeLog。

升级请参考 如何更新 Midway 中描述，请不要单独升级某个组件包。

在双十一大促之后，Midway 迎来了 3.13 版本。

这个版本主要调整了内置的 logger 模块，使其可以支持 v3 版本的 logger 库。

Breaking​

• 1、未声明 @midwayjs/logger 依赖的用户的日志会出现意外错误
• 2、日志的配置定义可能丢失

这两个问题的解法在最后描述。

Feature​

1、日志库升级到 v3​

经过一些时间的重写，Midway 搭配的 logger 库也升级到了 v3 版本，在 v3 版本中，我们移除了 winston 依赖，重写了整个 logger 模块，性能几乎翻了一倍。

从 bundlephobia 中也能看到很明显的变化，代码的精简，使得运行更高效，代码更受控。

从这个版本开始，Midway 的日志库可以选择使用 v2 或者 v3 的日志库，注意两者的配置是不同的。

如果你想查看两个版本的变化，可以点击 这里。

如果你希望升级到 v3 版本的日志库，我们的 文档 也已经准备好了。

2、内置服务新增 HealthService​

Midway 一直没有提供内置的健康检查方案，在这一版本，终于 设计 了 HealthService 这一内置的检查服务。

HealthService 用于提供检查 API，在不同的情况下可以自行接入检查自定义组件的状态，文档在此。

同时，我们的 Configuration 生命周期也增加了一个 onHealthCheck 的阶段，用于在每次检查时执行，文档在此。

这一功能目前还没有组件接入，我们将在后续的版本中逐步完善它。

其他的一些变化​

• 1、jwt 组件的配置提供更多的选项，比如 sign，verify，decode 等选项
• 2、jwt 组件导出了默认的 jwt 实例，你可以从上面获取到一些内置的错误实例，方便过滤器拦截
• 3、http-proxy 组件现在可以通过 enable 配置来关闭了，这样你可以自行引入中间件做更多的自定义处理
• 4、在 web 框架中，context.state 的类型现在也可以自定义了，这在文档中也进行了更新
• 5、修复了 static-file 组件的 namespace 不正确的问题
• 6、修复了 framework 加载时主框架顺序不固定的问题

解决方案​

1、日志库丢失的方案​

由于大部分脚手架我们都已经引入了日志库依赖，一般来说不需要处理。

如果未引入日志库，框架会在启动时报错，只需要在 package.json 的依赖中写入即可。

"dependencies": {
+  "@midwayjs/logger": "^2.19.2",
},

注意，只有上述最新版本的日志库才兼容 v3.13.0 以上的 @midwayjs/core。

2、日志的配置定义丢失​

由于 ts 类型合并需要在项目中显式声明一次，你需要在 interface.ts 中加入下面的代码。

+ import type {} from '@midwayjs/logger';

/**
 * @description User-Service parameters
 */
export interface IUserOptions {
  uid: number;
}

这样在 src/config/config.default.ts 中配置 midwayLogger 字段时，日志库的定义会恢复。