2.x 升级指南
本篇将介绍从 midway v2 升级为 midway v3 的方式。
从 Midway v2 升级到 Midway v3,会有一些 Breaking Change。本篇文档会详细列出这些 Breaking 的地方,让用户可以提前知道变化,做出应对。
自动升级工具
在升级前,请切出一个 新的分支,避免升级失败导致无法恢复!!!
拷贝以下脚本,在项目根目录执行:
$ npx --ignore-existing midway-upgrade
提示
由于业务情况各异,请在脚本升级之后,再进行手动升级的核对。
手动升级
midway v3 支持从 node v12 起。
包版本更新
所有的组件包,核心包都将升级为 3.x 版本。
{
"dependencies": {
"@midwayjs/bootstrap": "^3.0.0",
"@midwayjs/core": "^3.0.0",
"@midwayjs/decorator": "^3.0.0",
"@midwayjs/koa": "^3.0.0",
"@midwayjs/task": "^3.0.0",
},
"devDependencies": {
"@midwayjs/cli": "^1.2.90",
"@midwayjs/luckyeye": "^1.0.0",
"@midwayjs/mock": "^3.0.0",
// ...
}
}
@midwayjs/cli
和 @midwyajs/luckeye
, @midwayjs/logger
的版本除外。
Query/Body/Param/Header 装饰器变更
主要是默认无参数下的行为。
旧
async invoke(@Query() name) {
// ctx.query.name
}
新
async invoke(@Query() name) {
// ctx.query
}
async invoke(@Query('name') name) {
// ctx.query.name
}
Validate/Rule 装饰器
旧
import { Validate, Rule, RuleType } from '@midwayjs/decorator';
新
import { Validate, Rule, RuleType } from '@midwayjs/validate';
由于 validate 抽象成了组件,需要在代码中安装依赖并开启。
// src/configuration
import * as validate from '@midwayjs/validate';
@Configuration({
// ...
imports: [
validate
],
})
export class MainConfiguration {
// ...
}
task 组件配置 key 变更
旧
export const taskConfig = {};
新
export const task = {};
配置的绝对路径
不再支持相对路径
旧
// src/configuration
@Configuration({
// ...
importConfigs: [
'./config' // ok
]
})
export class MainConfiguration {
// ...
}
新
// src/configuration
import { join } from 'path';
@Configuration({
// ...
importConfigs: [
- './config' // error
+ join(__dirname, './config') // ok
]
})
export class MainConfiguration {
// ...
}
使用默认框架/多框架
旧,会在 bootstrap.js 中引入
const WebFramework = require('@midwayjs/koa').Framework;
const GRPCFramework = require('@midwayjs/grpc').Framework;
const { Bootstrap } = require('@midwayjs/bootstrap');
Bootstrap
.load(config => {
return new WebFramework().configure(config.cluster);
})
.load(config => {
return new GRPCFramemwork().configure(config.grpcServer);
})
.run();
新版本
bootstrap.js 中不再需要单独实例化
const { Bootstrap } = require('@midwayjs/bootstrap');
Bootstrap.run();
作为替代,以组件的形式引入
// src/configuration
import * as web from '@midwayjs/web';
import * as grpc from '@midwayjs/grpc';
@Configuration({
// ...
imports: [
web,
grpc,
//...
],
})
export class MainConfiguration {
// ...
}
其他影响:
- 1、测试中不再需要使用 createBootstrap 方法从 bootstrap.js 启动
- 2、原有入口 Framework 的配置现在可以放到 config.*.ts 中,以框架名作为 key
删除了一批 IoC 容器 API
移除 container 上的下列方法
- getConfigService(): IConfigService;
- getEnvironmentService(): IEnvironmentService;
- getInformationService(): IInformationService;
- setInformationService(service: IInformationService): void;
- getAspectService(): IAspectService;
- getCurrentEnv(): string;
现在都有相应的框架内置服务来替代。
比如旧写法:
const environmentService = app.getApplicationContext().getEnvironmentService();
const env = environmentService.getCurrentEnvironment();
新写法
const environmentService = app.getApplicationContext().get(MidwayEnvironmentService)
const env = environmentService.getCurrentEnvironment();
@midwayjs/web(egg)部分
启动端口
新版本框架启动会读取一个端口配置,如果未配,可能不会启动端口监听。
// src/config/config.default
export default {
// ...
egg: {
port: 7001,
},
}
添加 egg-mock
由于框架移除了 egg-mock 包,在新版本 package.json
需要手动引用。
{
"devDependencies": {
"egg-mock": "^1.0.0",
// ...
}
}