跳到主要内容
版本:3.0.0

EggJS

Midway 可以使用 EggJS 作为上层 Web 框架,EggJS 提供了非常多常用的插件和 API,帮助用户快速构建企业级 Web 应用。本章节内容,主要介绍 EggJS 在 Midway 中如何使用自身的能力。

描述
包含独立主框架
包含独立日志

安装依赖

$ npm i @midwayjs/web@3 egg --save
$ npm i @midwayjs/egg-ts-helper --save-dev

针对 EggJS 场景,这些包列举如下。

  "dependencies": {
"@midwayjs/web": "^3.0.0",
"@midwayjs/core": "^3.0.0",
"egg": "^2.0.0",
"egg-scripts": "^2.10.0"
},
"devDependencies": {
"@midwayjs/egg-ts-helper": "^1.0.1",
},
@midwayjs/web必须,Midway EggJS 适配层
@midwayjs/core必须,Midway 核心包
egg必须,EggJS 依赖包,提供定义等其他能力
egg-scripts可选,EggJS 启动脚本
@midwayjs/egg-ts-helper可选,EggJS 定义生成工具

也可以直接使用脚手架创建示例。

# npm v6
$ npm init midway --type=egg-v3 my_project

# npm v7
$ npm init midway -- --type=egg-v3 my_project

开启组件

import { Configuration, App } from '@midwayjs/core';
import * as web from '@midwayjs/web';
import { join } from 'path';

@Configuration({
imports: [web],
importConfigs: [join(__dirname, './config')],
})
export class MainConfiguration {
@App()
app: web.Application;

async onReady() {
// ...
}
}

和默认 EggJS 的不同之处

  • 1、从 v3 开始,midway 提供了更多的组件,大部分 egg 内置插件默认禁用
  • 2、baseDir 默认调整为 src 目录,服务器上为 dist 目录
  • 3、禁用 egg-logger,全部替换为 @midwayjs/logger,不可切换

整个架构如下:

目录结构

除了 Midway 提供的目录结构外,EggJS 还有一些特殊的目录结构(不可变),整个结构如下。

➜  my_midway_app tree
.
├── src
| ├── app.ts ## EggJS 扩展 Worker 生命周期文件(可选)
| ├── agent.ts ## EggJS 扩展 Agent 生命周期文件(可选)
| ├── app ## EggJS 固定的根目录(可选)
| │ ├── public ## EggJS 静态托管插件的默认目录(可配)
| │ | └── reset.css
| │ ├── view (可选) ## EggJS 模板渲染的默认目录(可配)
| │ | └── home.tpl
| │ └── extend (可选) ## EggJS 扩展目录(可配)
| │ ├── helper.ts (可选)
| │ ├── request.ts (可选)
| │ ├── response.ts (可选)
| │ ├── context.ts (可选)
| │ ├── application.ts (可选)
| │ └── agent.ts (可选)
| │
| ├── config
| | ├── plugin.ts
| | ├── config.default.ts
| │ ├── config.prod.ts
| | ├── config.test.ts (可选)
| | ├── config.local.ts (可选)
| | └── config.unittest.ts (可选)
│ ├── controller ## Midway 控制器目录(推荐)
│ ├── service ## Midway 服务目录(推荐)
│ └── schedule ## Midway 定时器目录(推荐)

├── typings ## EggJS 定义生成目录
├── test
├── package.json
└── tsconfig.json

以上是 EggJS 的目录结构全貌,其中包含了很多 EggJS 特有的目录,有一些在 Midway 体系中已经有相应的能力替代,可以直接替换。整个结构,基本上等价于将 EggJS 的目录结构移动到了 src 目录下。

由于 EggJS 是基于约定的框架,整个工程的目录结构是固定的,这里列举一些常用的约定目录。

src/app/public/**用于放置静态资源,可选,具体参见内置插件 egg-static
src/config/config.{env}.ts用于编写配置文件,具体参见配置
src/config/plugin.js用于配置需要加载的插件,具体参见插件
test/**具体参见单元测试
src/app.jssrc/agent.js用于自定义启动时的初始化工作,可选,具体参见启动自定义。关于agent.js的作用参见Agent机制

配置定义

Midway 在脚手架中提供了标准的 EggJS 的 TS 配置写法,MidwayConfig 中包括了 egg 中配置的定义和属性提示,结构如下。

// src/config/config.default.ts
import { MidwayConfig, MidwayAppInfo } from '@midwayjs/core';

export default (appInfo: MidwayAppInfo) => {
return {
// use for cookie sign key, should change to your own and keep security
keys: appInfo.name + '_xxxx',
egg: {
port: 7001,
},
// security: {
// csrf: false,
// },
} as MidwayConfig;
};

通过这样返回方法的形式,在运行期会被自动执行,合并进完整的配置对象。

这个函数的参数为 MidwayAppConfig 类型,值为以下内容。

appInfo说明
pkgpackage.json
name应用名,同 pkg.name
baseDir应用代码的 src (本地开发)或者 dist (上线后)目录
appDir应用代码的目录
HOME用户目录,如 admin 账户为 /home/admin
root应用根目录,只有在 local 和 unittest 环境下为 baseDir,其他都为 HOME。
信息

注意,这里的 baseDirappDir 和 EggJS 应用有所区别。

使用 Egg 插件

插件是 EggJS 的特色之一,@midwayjs/web 也支持 EggJS 的插件体系,但是在有 Midway 组件的情况下,尽可能优先使用 Midway 组件。

插件一般通过 npm 模块的方式进行复用。

$ npm i egg-mysql --save

然后需要在应用或框架的 src/config/plugin.js 中声明开启。

如果有 export default ,请写在其中。

import { EggPlugin } from 'egg';
export default {
static: false, // default is true
mysql: {
enable: true,
package: 'egg-mysql'
}
} as EggPlugin;

如果没有 export default ,可以直接导出。

// src/config/plugin.ts
// 使用 mysql 插件
export const mysql = {
enable: true,
package: 'egg-mysql',
};

在开启插件之后,我们就可以在业务代码中使用插件提供的功能了。一般来说,插件会将对象挂载到 EggJS 的 appctx 之上,然后直接使用。

app.mysql.query(sql, values);           // egg 提供的方法

在 Midway 中可以通过 @App 获取 app 对象,以及在请求作用域中通过 @Inject() ctx 获取 ctx 对象,所以我们可以通过注入来获取插件对象。

import { Provide, Inject, Get } from '@midwayjs/core';
import { Application, Context } from '@midwayjs/web';

@Provide()
export class HomeController {

@App()
app: Application;

@Inject()
ctx: Context;

@Get('/')
async home() {
this.app.mysql.query(sql, values); // 调用 app 上的方法(如果有的话)
this.ctx.mysql.query(sql, values); // 调用挂载在 ctx 上的方法(如果有的话)
}
}

此外,还可以通过 @Plugin 装饰器来直接注入 app 挂载的插件,默认情况下,如果不传参数,将以属性名作为 key。

import { Provide, Get, Plugin } from '@midwayjs/core';

@Provide()
export class HomeController {

@Plugin()
mysql: any;

@Get('/')
async home() {
this.mysql.query(sql, values);
}
}
信息

@Plugin() mysql 等价于 app.mysql@Plugin 的作用就是从 app 对象上拿对应属性名的插件,所以 @Plugin() xxx 就等于 app['xxx']

Web 中间件

中间件样例如下:

import { Middleware, IMiddleware } from '@midwayjs/core';
import { Context, NextFunction } from '@midwayjs/web';

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

resolve() {
return async (ctx: Context, next: NextFunction) => {
const startTime = Date.now();
await next();
console.log(Date.now() - startTime);
};
}

}
警告

注意

1、如果要继续使用 EggJS 传统的函数式写法,必须将文件放在 src/app/middleware

2、egg 自带的内置中间件已经集成

应用中间件。

// src/configuration.ts
import { App, Configuration } from '@midwayjs/core';
import * as egg from '@midwayjs/web';
import { ReportMiddleware } from './middleware/user.middleware';

@Configuration({
imports: [egg]
// ...
})
export class MainConfiguration {

@App()
app: egg.Application;

async onReady() {
this.app.useMiddleware(ReportMiddleware);
}
}

更多用法请参考 Web 中间件

中间件顺序

由于 egg 也有自己的中间件逻辑,在新版本中,我们将中间件加载顺序做了一定的处理,执行顺序如下:

  • 1、egg 框架中的中间件
  • 2、egg 插件通过 config.coreMiddleware 添加的顺序
  • 3、业务代码配置在 config.middleware 中配置的顺序
  • 4、app.useMiddleware 添加的顺序

因为 midway 的中间件会后置加载,所以我们可以在 onReady 中进行自定义排序。

BodyParser

egg 自带 bodyParser 功能,默认会解析 Post 请求,自动识别 jsonform 类型。

如需 text 或者 xml,可以自行配置。

默认的大小限制为 1mb,可以单独对每项配置大小。

// src/config/config.default
export default {
// ...
bodyParser: {
formLimit: '1mb',
jsonLimit: '1mb',
textLimit: '1mb',
xmlLimit: '1mb',
},
}

注意,使用 Postman 做 Post 请求时的类型选择:

postman

定时任务

v3 开始请参考 bull 组件

如需兼容之前的 egg 定时任务 ,请照下列方法。

首先安装 midway-schedule 依赖。

$ npm i midway-schedule --save

添加到插件中即可。

// src/config/plugin.ts
export default {
schedule: true,
schedulePlus: {
enable: true,
package: 'midway-schedule',
},
};

使用请参考上一版本文档。

日志

v3 开始无法使用 egg-logger,请参考 日志 章节。

异常处理

EggJS 框架通过 onerror 插件提供了统一的错误处理机制,会作为 Midway 的兜底错误逻辑,和 错误过滤器 不冲突。

对一个请求的所有处理方法(Middleware、Controller、Service)中抛出的任何异常都会被它捕获,并自动根据请求想要获取的类型返回不同类型的错误(基于 Content Negotiation)。

请求需求的格式环境errorPageUrl 是否配置返回内容
HTML & TEXTlocal & unittest-onerror 自带的错误页面,展示详细的错误信息
HTML & TEXT其他重定向到 errorPageUrl
HTML & TEXT其他onerror 自带的没有错误信息的简单错误页(不推荐)
JSON & JSONPlocal & unittest-JSON 对象或对应的 JSONP 格式响应,带详细的错误信息
JSON & JSONP其他-JSON 对象或对应的 JSONP 格式响应,不带详细的错误信息

onerror 插件的配置中支持 errorPageUrl 属性,当配置了 errorPageUrl 时,一旦用户请求线上应用的 HTML 页面异常,就会重定向到这个地址。

src/config/config.default.ts

// src/config/config.default.ts
module.exports = {
onerror: {
// 线上页面发生异常时,重定向到这个页面上
errorPageUrl: '/50x.html',
},
};

扩展 Application/Context/Request/Response

增加扩展逻辑

虽然 MidwayJS 并不希望直接将属性挂载到 koa 的 Context,App 上(会造成管理和定义的不确定性),但是 EggJS 的这项功能依旧可用。

文件位置如下。

➜  my_midway_app tree
.
├── src
│ ├── app
│ │ └── extend
│ │ ├── application.ts
│ │ ├── context.ts
│ │ ├── request.ts
│ │ └── response.ts
│ ├── config
│ └── interface.ts
├── test
├── package.json
└── tsconfig.json

内容和原来的 EggJS 相同。

// src/app/extend/context.ts
export default {
get hello() {
return 'hello world';
},
};

增加扩展定义

Context 请使用 Midway 的方式来扩展,请查看 扩展上下文定义

其余的部分,沿用 egg 的方式,请在 src/interface.ts 中扩展。

// src/interface.ts
declare module 'egg' {
interface Request {
// ...
}
interface Response {
// ...
}
interface Application {
// ...
}
}
信息

业务自定义扩展的定义请 不要放在根目录 typings 下,避免被 ts-helper 工具覆盖掉。

使用 egg-scripts 部署

由于 EggJS 提供了默认的多进程部署工具 egg-scripts ,Midway 也继续支持这种方式,如果上层是 EggJS,推荐这种部署方式。

首先在依赖中,确保安装 egg-scripts 包。

$ npm i egg-scripts --save

添加 npm scriptspackage.json

在上面的代码构建之后,使用我们的 startstop 命令即可完成启动和停止。

"scripts": {
"start": "egg-scripts start --daemon --title=********* --framework=@midwayjs/web",
"stop": "egg-scripts stop --title=*********",
}
信息

********* 的地方是你的项目名。

注意:egg-scripts 对 Windows 系统的支持有限,参见 #22

启动参数

$ egg-scripts start --port=7001 --daemon --title=egg-server-showcase

Copy

如上示例,支持以下参数:

  • --port=7001 端口号,默认会读取环境变量 process.env.PORT,如未传递将使用框架内置端口 7001。
  • --daemon 是否允许在后台模式,无需 nohup。若使用 Docker 建议直接前台运行。
  • --env=prod 框架运行环境,默认会读取环境变量 process.env.EGG_SERVER_ENV, 如未传递将使用框架内置环境 prod。
  • --workers=2 框架 worker 线程数,默认会创建和 CPU 核数相当的 app worker 数,可以充分的利用 CPU 资源。
  • --title=egg-server-showcase 用于方便 ps 进程时 grep 用,默认为 egg-server-${appname}。
  • --framework=yadan 如果应用使用了自定义框架,可以配置 package.json 的 egg.framework 或指定该参数。
  • --ignore-stderr 忽略启动期的报错。
  • --https.key 指定 HTTPS 所需密钥文件的完整路径。
  • --https.cert 指定 HTTPS 所需证书文件的完整路径。
  • 所有 egg-cluster 的 Options 都支持透传,如 --port 等。

更多参数可查看 egg-scriptsegg-cluster 文档。

信息

使用 egg-scripts 部署的日志会存放在 用户目录比如 /home/xxxx/logs

启动环境

原有 egg 使用 EGG_SERVER_ENV 中作为环境标志,在 Midway 中请使用 MIDWAY_SERVER_ENV

State 类型定义

在 egg 底层的 koa 的 Context 中有一个特殊的 State 属性,通过和 Context 类似的方式可以扩展 State 定义。

// src/interface.ts

declare module '@midwayjs/web/dist/interface' {
interface Context {
abc: string;
}

interface State{
bbb: string;
ccc: number;
}
}

配置

默认配置

// src/config/config.default
export default {
// ...
egg: {
port: 7001,
},
}

@midwayjs/web 所有参数如下:

配置项类型描述
portnumber必填,启动的端口
keystringBuffer
certstringBuffer
castringBuffer
hostnamestring监听的 hostname,默认 127.1
http2boolean可选,http2 支持,默认 false
queryParseModesimple|extended默认为 extended
queryParseOptionsqs.IParseOptions解析选项,当使用'simple'模式解析时可用

以上的属性,对本地和使用 bootstrap.js 部署的应用生效。

修改端口

提示

注意,这个方式只会对本地研发,以及使用 bootstrap.js 文件部署的项目生效。

默认情况下,我们在 config.default 提供了 7001 的默认端口参数,修改它就可以修改 egg http 服务的默认端口。

比如我们修改为 6001

// src/config/config.default
export default {
// ...
egg: {
port: 6001,
},
}

默认情况下,单测环境由于需要 supertest 来启动端口,我们的 port 配置为 null

// src/config/config.unittest
export default {
// ...
egg: {
port: null,
},
}

此外,也可以通过 midway-bin dev --ts --port=6001 的方式来临时修改端口,此方法会覆盖配置中的端口。

全局前缀

此功能请参考 全局前缀

Https 配置

在大多数的情况,请尽可能使用外部代理的方式来完成 Https 的实现,比如 Nginx。

在一些特殊场景下,你可以通过配置 SSL 证书(TLS 证书)的方式,来直接开启 Https。

首先,你需要提前准备好证书文件,比如 ssl.keyssl.pem,key 为服务端私钥,pem 为对应的证书。

然后配置即可。

// src/config/config.default
import { readFileSync } from 'fs';
import { join } from 'path';

export default {
// ...
egg: {
key: join(__dirname, '../ssl/ssl.key'),
cert: join(__dirname, '../ssl/ssl.pem'),
},
}

favicon 设置

默认情况下,浏览器会发起一个 favicon.ico 的请求。

// src/config/config.default
import { readFileSync } from 'fs';
import { join } from 'path';

export default {
// ...
siteFile: {
'/favicon.ico': readFileSync(join(__dirname, 'favicon.png')),
},
}

如果开启了 @midwayjs/static-file 组件,那么会优先使用组件的静态文件托管。

修改上下文日志

可以单独修改 egg 框架的上下文日志。

export default {
egg: {
contextLoggerFormat: info => {
const ctx = info.ctx;
return `${info.timestamp} ${info.LEVEL} ${info.pid} [${ctx.userId} - ${Date.now() - ctx.startTime}ms ${ctx.method}] ${info.message}`;
}
// ...
},
};

Query 数组解析

默认情况下,ctx.query 会解析为忽略数组的情况,而 ctx.queries 会严格的将所有的字段都变成数组。

如果调整 queryParseMode ,则可以使 ctx.query 变为两者之间的结构(querystring 的结果)。

// src/config/config.default
export default {
// ...
egg: {
// ...
queryParseMode: 'simple',
queryParseOptions: {
arrayLimit: 100,
},
},
}

常见问题

1、生成 ts 定义

Midway 提供了 @midwayjs/egg-ts-hepler 工具包,用于快速生成 EggJS 开发时所依赖的定义。

$ npm install @midwayjs/egg-ts-helper --save-dev

package.json 中加入对应的 ets 命令即可,一般来说,我们会在 dev 命令前加入,以保证代码的正确性。

  "scripts": {
"dev": "cross-env ets && cross-env NODE_ENV=local midway-bin dev --ts",
},
信息

在第一次编写代码前,需要执行一次此命令才能有 ts 定义生成。

EggJS 生成的定义在 typings 目录中。

➜  my_midway_app tree
.
├── src ## midway 项目源码
├── typings ## EggJS 定义生成目录
├── test
├── package.json
└── tsconfig.json

2、EggJS 中 Configuration 的特殊情况

在 EggJS 下, configuration.ts 中的生命周期只会在 worker 下加载执行。如果在 Agent 有类似的需求,请直接使用 EggJS 自身的 agent.ts 处理。

3、异步初始化配置无法覆盖插件配置

onConfigLoad 生命周期会在 egg 插件(若有)初始化之后执行,所以不能用于覆盖 egg 插件所使用的配置。

4、默认的 csrf 错误

在 post 请求,特别是第一次时用户会发现一个 csrf 报错。原因是 egg 在框架中默认内置了安全插件 egg-security, 默认开启了 csrf 校验。

我们可以在配置中关闭它,但是更好的是去了解它之后再做选择。

export const security = {
csrf: false,
};

5、不存在定义的问题

一些 egg 插件未提供 ts 定义,导致使用会出现未声明方法的情况,比如 egg-mysql。 image.png 可以使用 any 绕过。

await (this.app as any).mysql.query(sql);

或者可以自行增加扩展定义。