MidWay

Midway 是阿里巴巴 - 淘宝前端架构团队，基于渐进式理念研发的 Node.js 框架，通过自研的依赖注入容器，搭配各种上层模块，组合出适用于不同场景的解决方案。

Midway 是基于 TS 开发,结合了两种编程范式面向对象(OOP+Class+IoC)与函数式编程(FP+Function+Hooks)`，并提供了丰富的上层封装，让开发者以最少的配置，完成业务代码的编写。

Midway 的优势

• Midway 框架是在内部已经使用 5 年以上的 Node.js 框架，有着长期投入和持续维护的团队做后盾

• 已经在每年的大促场景经过考验，稳定性无须担心

• 丰富的组件和扩展能力，例如数据库，缓存，定时任务，进程模型，部署以及 Web，Socket 甚至 Serverless 等新场景的支持

• 一体化调用方案可以方便快捷和前端页面协同开发

• 良好的 TypeScript 定义支持

• 国产化文档和沟通容易简单

多编程范式

Midway 支持面向对象与函数式两种编程范式,你可以根据实际研发的需求,选择不同的范式来开发应用

面向对象(OOP + Class + IoC)

Midway 支持面向对象的编程范式,为应用提供更优雅的架构

下面是基于面向对象,开发路由的示例

// src/controller/home.ts
import {Controller,Get} from "@midwayjs/core"
import {Context} from "@midwayjs/koa"

@Controller("/")
export class HomeController {

 @Inject()
  ctx:Context

 @Get("/")
  async home(){
    return {
      message:"Hello midway"
      query:this.ctx.ip
    }
  }
}

函数式(FP + Function + Hooks)

Midway 也支持函数式的编程范式,为应用提供更高的研发效率

下面式基于函数式,开发路由接口的示例

// src/api/index.ts

import { useContext } from "@midwayjs/hooks";

import { Context } from "@midwayjs/koa";

export async function home() {
  const ctx = useContext<Context>();
  return {
    message: "Hello midway",
    query: ctx.ip,
  };
}

环境准备工作

Midway 运行请先预装 Node.js 和 npm, 在国内可以使用 cnpm

• 操作系统:支持 macOS,Linux,Windows

• 运行环境:建议选择长期版本 最低要求 12.11.0

经过不断的迭代,Midway 的版本要求如下

Midway 版本	开发环境 Node.js 版本要求	部署环境 Node.js 版本要求
>=v3.9.0	>= v14，推荐 LTS 版本	>= v12.11.0
3.0.0 ~ 3.9.0	>= v12，推荐 LTS 版本	>= v12.0.0
2.x	>= v12，推荐 LTS 版本	>= v10.0.0

更新 Midway

什么时候要更新 Midway

一般来说,在下面的情况下,你可能需要更新

• 1. Midway 发布了新版本,你希望用到新功能的时候
• 2. 你安装了一个新的组件且带有 lock 文件的时候
• 3. 出现方法找不到错误的时候

比如出现下面错误的时候

• 一般是装了组件的新包，但是老的 @midwayjs/core 未包含该方法从而报错。

• 一般原因为 mock 依赖的 @midwayjs/core 版本没这个方法，说明版本不对，可能是错误引用了版本，也可能是版本太低

• 新装组件的时候，我们发现某个包的版本实例不止一个

注意事项

midway 项目的依赖使用 lerna 发布，请不要：

• 1. 单独升级某个 @midwayjs/* 的包
• 2. 将 package.json 中的版本号移除 ^ 符号

使用

检查包版本异常

你可以使用下面德命令在项目根目录执行进行检查

# 社区用户
$ npx midway-version (√)
# 内部用户
$ tnpx @ali/midway-version

如果项目是 pnpm 安装的依赖,请使用下面的命令

# 社区用户
$ pnpx midway-version (√)
# 内部用户
$ pnpx @ali/midway-version

使用工具更新版本

你可以使用下面的命令在项目根目录执行 进行更新提示

# 社区用户
$ npx midway-version -u (√)
# 内部用户
$ tnpx @ali/midway-version -u

如果项目为 pnpm 安装的依赖，请使用下面的命令。

# 社区用户
$ pnpx midway-version -u (√)
# 内部用户
$ pnpx @ali/midway-version -u

如果你希望将更新写入到 package.json 中，请使用下面的命令。

# 社区用户
$ pnpx midway-version -u -w (√)
$ npx midway-version -u -w  (√)
# 内部用户
$ pnpx @ali/midway-version -u -w

手动更新

普通使用 npm/yarn 的项目,升级按照如下流程

• 1. 删除 package-lock.json 或者 yarn.lock
• 2. 彻底删除 node_modules 比如 rm -rf node_modules
• 3. 重新安装依赖（ npm install 或者 yarn）

我们不保证使用其他工具,cli单独升级包的效果

lerna 项目更新

使用 lerna 开发项目，由于有 hoist 模式的存在，升级请按照下面的流程（以 lerna3 为例）

• 清理子包的 node_modules，比如（lerna clean --yes）

• 删除主包的 node_modules（比如 rm -rf node_modules)

• 删除 package-lock.json 或者 yarn.lock

• 重新安装依赖（ npm install && lerna bootstrap）

我们不保证使用其他工具,cli单独升级包的效果

大版本更新

请手动修改版本号，比如从 ^1.0.0 修改为 ^2.0.0 。

查看当前包版本

Midway 包采用标准的 Semver 版本进行管理和发布，在 package.json 指定的版本一般为 ^ 开头，表示在大版本范围内都兼容。

比如，package.json 中 @midwayjs/core 为 ^2.3.0 ，那么按照 npm 安装规则，会安装 2.x 这个版本下最新的 latest 版本。

所以实际安装的版本高于 package.json 中指定的版本都是正常的。

你可以使用 npm ls 包名 来查看具体的版本，比如 npm ls @midwayjs/core 来查看 @midwayjs/core 的版本。

版本匹配查询

由于 lerna 发包有一定的依赖性，比如修改到的包才会更新，就会出现 midway 下的包版本不一定完全一致的情况。

比如，@midwayjs/web 的版本高于 @midwayjs/core，这都是很正常的。

midway 每次发布会提交一个 @midwayjs/version 的包，其中包含了我们每个版本

目录中的文件名按照 @midwayjs/decorator 版本 - @midwayjs/core 版本.json 规则创建，每个版本对应一个 JSON 文件。

文件内容以包名作为 key，以可兼容匹配的版本名作为值。

比如，当前文件 decorator(v2.10.18)和 core(v2.10.18) 所能兼容的 egg-layer 包版本为 v2.10.18 和 v2.10.19。

如果 decorator 和 core 组合的文件名未找到，或者文件里的版本不匹配，都说明 版本可能产生了问题。

内容示例如下:

{
  "@midwayjs/egg-layer": ["2.10.18", "2.10.19"],
  "@midwayjs/express-layer": "2.10.18",
  "@midwayjs/faas-typings": "2.10.7",
  "@midwayjs/koa-layer": "2.10.18",
  "@midwayjs/runtime-engine": "2.10.14",
  "@midwayjs/runtime-mock": "2.10.14",
  "@midwayjs/serverless-app": "2.10.18",
  "@midwayjs/serverless-aws-starter": "2.10.14",
  "@midwayjs/serverless-fc-starter": "2.10.18",
  "@midwayjs/serverless-fc-trigger": "2.10.18",
  "@midwayjs/serverless-http-parser": "2.10.7",
  "@midwayjs/serverless-scf-starter": "2.10.14",
  "@midwayjs/serverless-scf-trigger": "2.10.18",
  "@midwayjs/static-layer": "2.10.18",
  "@midwayjs/bootstrap": "2.10.18",
  "@midwayjs/cache": "2.10.18",
  "@midwayjs/consul": "2.10.18",
  "@midwayjs/core": "2.10.18",
  "@midwayjs/decorator": "2.10.18",
  "@midwayjs/faas": "2.10.18",
  "@midwayjs/grpc": "2.10.18",
  "@midwayjs/logger": "2.10.18",
  "midway-schedule": "2.10.18",
  "midway": ["2.10.18", "2.10.19"],
  "@midwayjs/mock": "2.10.18",
  "@midwayjs/prometheus": "2.10.18",
  "@midwayjs/rabbitmq": "2.10.18",
  "@midwayjs/socketio": "2.10.18",
  "@midwayjs/task": ["2.10.18", "2.10.19"],
  "@midwayjs/typegoose": "2.10.18",
  "@midwayjs/version": ["2.10.18", "2.10.19"],
  "@midwayjs/express": "2.10.18",
  "@midwayjs/koa": "2.10.18",
  "@midwayjs/web": ["2.10.18", "2.10.19"]
}