Skip to main content

Release 3.17.0

· 3 minute read
Harry Chen
Maintainer of Midway

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

本次 3.17 版本,我们增加了一些新的特性,以及修复了一些问题,主要有:

  • 1、使用 替换原有的上传组件
  • 2、busboy 上传的数据中的 filedName,在流式模式下不再提供
  • 3、增加了一个新的服务端响应格式
  • 4、class 中间件现在可以复用了

下面是更为细节的描述。

定制服务端响应格式

在 3.17 版本中,我们增加了一个新的特性,可以定制服务端的响应的通用格式。

在之前的版本中,我们依靠中间件和过滤器来实现这个功能,但是这种方式有一些局限性,代码也会分散在不同的地方。

如果由一个统一的可调整的返回逻辑,可能更为合理,为此,添加了 ServerResponseHttpServerResponse 的实现。

import { ServerResponse, HttpServerResponse } from '@midwayjs/core';

@Controller()
export class HomeController {
@Inject()
ctx: Context;

@Get('/')
async index() {
return new HttpServerResponse(this.ctx).json({
success: true,
data: 'hello world',
});
}
}

HttpServerResponseServerResponse 的一个 Http 实现,提供了一些常用的方法。

最为特殊的是他可以针对不同的数据格式,设置成功和失败的模版。

比如针对 JSON 数据,框架提供了以下的默认结构。

HttpServerResponse.JSON_TPL = (data, isSuccess) => {
if (isSuccess) {
return {
success: 'true',
data,
};
} else {
return {
success: 'false',
message: data || 'fail',
};
}
};

这样,当返回 JSON 格式时,就会按照这个模版进行返回。

// 失败的返回
return new HttpServerResponse(this.ctx).fail().json('hello world');

就会获取到以下的数据。

{
success: 'false',
message: 'hello world',
}

此外,基于这个模式,也同时实现了 SSE 的响应返回,也有其他的一些数据结构的返回,更多的内容,请参考 细节文档

上传组件

由于在小文件场景下上传碰到一些问题,从 v3.17 开始,基于 busboy 实现了一个新的上传组件,替换原有的 @midwayjs/upload

和原有的组件比有一些不同。

  • 1、不再默认加载中间件,因为上传只是少部分接口的特殊逻辑,不需要全局加载
  • 2、配置的 key 为了避免冲突,从 upload 变为 busboy

其余的使用方式和原有的上传组件一致,

更多细节请访问 文档

类中间件复用

在之前,如果需要复用中间件,只能使用函数中间件。

const mw = (ctx, next) => {
// ...
}

@Controller(/**/)
export class HomeController {

@Get('/', { middleware: [mw]})
async home() {}

@Get('/api', { middleware: [mw]})
async api() {}
}

但是如果希望用上继承,或者 matchignore 功能的,则是类的行为更为方便。

这个版本框架提供了 createMiddleware 功能,保留原有的逻辑同时,可以创建出一个新的中间件实例。


@Middleware()
export class ReportMiddleware implements IMiddleware<Context, NextFunction> {
// ...
}

@Controller(/**/)
export class HomeController {

@Get('/', { middleware: [createMiddleware(ReportMiddleware, {}, 'name1')]})
async home() {}

@Get('/api', { middleware: [createMiddleware(ReportMiddleware, {}, 'name2')]})
async api() {}
}

通过向 createMiddleware 传递不同的参数,以及中间件名字,就可以引用到不同的逻辑。

更多的细节,请查看 Web中间件 文档。

更多的变化

  • 修复了一个多语言匹配 key 的问题
  • 一些不合理类型定义的调整

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

mwtsc 增加版本检查

· 2 minute read
Harry Chen
Maintainer of Midway

由于 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 版本,更新组件到最兼容的版本,而不是最新版本。

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

Release 3.16.0

· 2 minute read
Harry Chen
Maintainer of Midway

升级请参考 如何更新 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

Release 3.15.0

· One minute read
Harry Chen
Maintainer of Midway

开工大吉。

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

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

全新的 MQTT 组件

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

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

Swagger 方法级别的 Security 忽略

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

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

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

更多的变化

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

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

Release 3.14.0

· 3 minute read
Harry Chen
Maintainer of Midway

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。

现在,通过 renderSwaggerUIDistrenderJSONrenderSwaggerUIRemote 方法,你可以选择自己喜欢的方式进行渲染。

// 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