Skip to content

Commit

Permalink
doc (loader.md): Add missing English translations (eggjs#2996)
Browse files Browse the repository at this point in the history
1) Add missing English translations about the explainations of start
process in details.
2) Format some words in a beautiful style.
  • Loading branch information
Maledong authored and killagu committed Sep 13, 2018
1 parent 6f5bf3d commit 4faf68f
Show file tree
Hide file tree
Showing 5 changed files with 228 additions and 12 deletions.
4 changes: 2 additions & 2 deletions History.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
### Notable changes

* **feature**
* support boot lifecyle, see https://github.com/eggjs/egg/issues/2520
* support boot lifecycle, see https://github.com/eggjs/egg/issues/2520
* `dnshttpclient` now use async function instead of Promise

* **fix**
Expand Down Expand Up @@ -50,7 +50,7 @@
* use cache-content-type

* **docs**
* add lifecyle doc
* add lifecycle doc
* add sequelize guide
* add allowDebugAtProd in document
* egg-scripts support windows
Expand Down
File renamed without changes.
131 changes: 131 additions & 0 deletions docs/assets/lifecycle_en.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
@startuml
start
: start master;
partition agent {
: fork agent worker;
: load plugin.js, config.js, extends;
: load agent.js;
note right
class mode
configDidLoad
async didLoad
async willReady
async didReady
async serverDidReady
====
method mode
beforeStart(deprecate)
end note
fork
: configDidLoad;
note left
all the files are loaded
To execute some sync logic
end note
: async didLoad;
note left
Files and configs are loaded
To execute some async tasks
E.g: Pull configs in async to load client,
or check the state of client
end note
fork again
: beforeStart(deprecate);
note right
Tasks mounted on beforeStart
Running in parallel at this time
end note
endfork
: async willReady;
note left
All the plug-ins are loaded,
All the plug-ins are normal,
To execute some tasks before request enters,
E.g: Pull some configs for applications
end note
: async didReady;
note right
agent is ready,
and it can work normally
====
The time is the same as 'ready',
The original 'ready' doesn't support AsyncFunction
end note
: emit 'agent-start';
}
partition app {
: start app workers;
: load plugin.js, config.js, extends;
: load app.js;
note right
class mode
configDidLoad
async didLoad
async willReady
async didReady
async serverDidReady
====
method mode
beforeStart(deprecate)
end note
fork
: configDidLoad;
note left
All the files are loaded,
The same sync logic as in app.js,
Some configs can be modified, the order of middlewares
end note
: load app/service;
: load app/middleware;
: load app/controller;
: load app/router.js;
: async DidLoad;
note left
Files and configs are loaded
To execute some async tasks
E.g: Pull configs in async to load client,
or check the state of client
end note
fork again
: beforeStart(deprecate);
note right
Tasks mounted on beforeStart
Running in parallel at this time
end note
end fork
: async WillReady;
note left
All the plug-ins are loaded,
All the plug-ins are normal,
To execute some tasks before request enters,
E.g: Pull some configs for applications
end note
: async DidReady;
note right
app is ready
HTTP server starts listening at the port
====
The time is the same as 'ready',
The original 'ready' doesn't support AsyncFunction
end note
: emit 'app-start';
}
: emit 'egg-ready';
: async serverDidReady;
note right
agent and all the apps are ready
requests are allowed
end note
: master receive SIGTERM;
fork
: agent beforeClose;
fork again
: app beforeClose;
note right
To execute in a reversed order against the inserting
DO NOT recommend in PROD env,
May not finish before the process ends
end note
endfork
stop
@enduml
76 changes: 76 additions & 0 deletions docs/source/en/advanced/loader.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,82 @@ 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:

- `configDidLoad`: When all the config files are loaded.
- `didLoad`: When all the files are 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.

Here're the definations:

```js
// app.js or agent.js
class AppBootHook {
constructor(app) {
}

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.
}
}

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/6897780/45463932-bb1f9800-b740-11e8-9f0c-d9649ae8abc0.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.Plug-in 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 plug-ins 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 [`egg-development`](https://github.com/eggjs/egg-development#loader-trace) to see the loading process.

### Loading File 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`.
Expand Down
29 changes: 19 additions & 10 deletions docs/source/zh-cn/advanced/loader.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,14 @@ plugin1 为 framework1 依赖的插件,配置合并后 object key 的顺序会

### 生命周期

框架提供了配置文件加载完成(`configDidLoad`), 文件加载完成(`didLoad`), 插件启动完毕(`willReady`), worker 准备就绪(`didReady`), 应用启动完成(`serverDidReady`), 应用即将关闭(`beforeClose`)这些生命周期函数。
框架提供了这些生命周期函数供开发人员处理:

- 配置文件加载完成(`configDidLoad`
- 文件加载完成(`didLoad`
- 插件启动完毕(`willReady`
- worker 准备就绪(`didReady`
- 应用启动完成(`serverDidReady`
- 应用即将关闭(`beforeClose`

定义如下:
```js
Expand All @@ -200,11 +207,11 @@ class AppBootHook {
}

configDidLoad() {
// Config,plugin files have did load.
// Config, plugin files have loaded.
}

async didLoad() {
// All files have did load, start plugin here.
// All files have loaded, start plugin here.
}

async willReady() {
Expand Down Expand Up @@ -234,26 +241,28 @@ module.exports = AppBootHook;

![](https://user-images.githubusercontent.com/6897780/42219323-24cbd7a8-7efe-11e8-86b9-cf280846aa9f.png)

使用 `beforeClose` 的时候需要注意,在框架的进程关闭处理中是有超时时间的,如果 worker 进程在接收到进程退出信号之后,没有在所规定的时间内退出,将会被强制关闭。
**使用 `beforeClose` 的时候需要注意,在框架的进程关闭处理中是有超时时间的,如果 worker 进程在接收到进程退出信号之后,没有在所规定的时间内退出,将会被强制关闭。**

如果需要调整超时时间的话,查看[此处文档](https://github.com/eggjs/egg-cluster)

弃用的方法:

## beforeStart
`beforeStart` 方法在 loading 过程中调用, 所有的方法并行执行。 一般用来执行一些异步方法, 例如检查连接状态等, 比如 [`egg-mysql`](https://github.com/eggjs/egg-mysql/blob/master/lib/mysql.js) 就用 `beforeStart` 来检查与 mysql 的连接状态。所有的 `beforeStart` 任务结束后, 状态将会进入 `ready` 。不建议执行一些耗时较长的方法, 可能会导致应用启动超时。
插件开发者应使用 `didLoad` 替换。应用开发者应使用 `willReady` 替换。

`beforeStart` 方法在 loading 过程中调用, 所有的方法并行执行。 一般用来执行一些异步方法, 例如检查连接状态等, 比如 [`egg-mysql`](https://github.com/eggjs/egg-mysql/blob/master/lib/mysql.js) 就用 `beforeStart` 来检查与 mysql 的连接状态。所有的 `beforeStart` 任务结束后, 状态将会进入 `ready` 。不建议执行一些耗时较长的方法, 可能会导致应用启动超时。插件开发者应使用 `didLoad` 替换。应用开发者应使用 `willReady` 替换。

## ready

`ready` 方法注册的任务在 load 结束并且所有的 `beforeStart` 方法执行结束后顺序执行, HTTP server 监听也是在这个时候开始, 此时代表所有的插件已经加载完毕并且准备工作已经完成, 一般用来执行一些启动的后置任务。
开发者应使用 `didReady` 替换。

## beforeClose
`beforeClose` 注册方法在 app/agent 实例的 `close` 方法被调用后, 按注册的逆序执行。一般用于资源的释放操作, 例如 [`egg`](https://github.com/eggjs/egg/blob/master/lib/egg.js) 用来关闭 logger , 删除监听方法等。
开发者不应该直接使用 `app.beforeClose`, 而是定义类的形式, 实现 `beforeClose` 方法。

__这个方法不建议在生产环境使用, 可能遇到未执行完就结束进程的问题。__
`beforeClose` 注册方法在 app/agent 实例的 `close` 方法被调用后, 按注册的逆序执行。一般用于资源的释放操作, 例如 [`egg`](https://github.com/eggjs/egg/blob/master/lib/egg.js) 用来关闭 logger , 删除监听方法等。开发者不应该直接使用 `app.beforeClose`, 而是定义类的形式, 实现 `beforeClose` 方法。

__这个方法不建议在生产环境使用, 可能遇到未执行完就结束进程的问题。__

可以使用 [`egg-development`](https://github.com/eggjs/egg-development#loader-trace) 来查看加载过程。
此外,我们可以使用 [`egg-development`](https://github.com/eggjs/egg-development#loader-trace) 来查看加载过程。

### 文件加载规则

Expand Down

0 comments on commit 4faf68f

Please sign in to comment.