Skip to content

Commit

Permalink
docs: fix typo in docs (#563)
Browse files Browse the repository at this point in the history
  • Loading branch information
huacnlee authored and atian25 committed Mar 14, 2017
1 parent 497b9a9 commit d131f23
Show file tree
Hide file tree
Showing 46 changed files with 616 additions and 611 deletions.
2 changes: 1 addition & 1 deletion docs/_config.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
title: egg
title: Egg.js
subtitle: "Born to build better enterprise frameworks and apps"
description: "Born to build better enterprise frameworks and apps"
language:
Expand Down
2 changes: 1 addition & 1 deletion docs/source/_data/guide_toc.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Intro:
What is egg: /intro/index.html
What is Egg: /intro/index.html
Egg and Koa: /intro/egg-and-koa.html
Get Start: /intro/quickstart.html
Basics:
Expand Down
6 changes: 3 additions & 3 deletions docs/source/en/basics/env.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Runtime Environment

# Runtime Environment

There could be all kinds of difference during various stages of a web application development, but the application itself should be stateless, so EGG provide environment variables to cope with such difference.
There could be all kinds of difference during various stages of a Web application development, but the application itself should be stateless, so EGG provide environment variables to cope with such difference.

EGG framework provides a variable named `env` for setting up the runtime environment. The `env` could be used to determine which configuration file should be applied, or you can perform any operations by detecting the `env` directly.

Expand All @@ -27,7 +27,7 @@ You can also load different configuration file for different environment by addi

## Difference with NODE_ENV

Lots of node applications use `NODE_ENV` for environment setting, but `EGG_SERVER_ENV` distinguishes the environments much more specific. Generally speaking, there are local environment, unit test environment, test environment, production environment during the application development. Test and production environment are **Server Environment** and their `NODE_ENV` should be set to `production` , just like how npm make use of `NODE_ENV`. when you depoly applications in test and production environment, you don't install the devDependencies, so `production` should be applied.
Lots of Node.js applications use `NODE_ENV` for environment setting, but `EGG_SERVER_ENV` distinguishes the environments much more specific. Generally speaking, there are local environment, unit test environment, test environment, production environment during the application development. Test and production environment are **Server Environment** and their `NODE_ENV` should be set to `production` , just like how npm make use of `NODE_ENV`. when you depoly applications in test and production environment, you don't install the devDependencies, so `production` should 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)

Expand All @@ -47,4 +47,4 @@ Set `EGG_SERVER_ENV` to `sit` (also set `NODE_ENV = production` as recommend), t

## Difference with Koa

We are using `app.env` to distinguishes the environments in koa, and `app.env` defualt to `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 distinguishes the environments, `app.env` is no logger used.
We are using `app.env` to distinguishes the environments in Koa, and `app.env` defualt to `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 distinguishes the environments, `app.env` is no logger used.
4 changes: 2 additions & 2 deletions docs/source/en/faq.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
title: FAQ
---

If you have questions that is not contained below, please check [egg issues](https://github.com/eggjs/egg/issues).
If you have questions that is not contained below, please check [Egg issues](https://github.com/eggjs/egg/issues).

## Why my config don't work ?

Expand Down Expand Up @@ -47,6 +47,6 @@ There are two kinds of common csrf errors:
- `missing csrf token`
- `invalid csrf token`

By default [egg-security](https://github.com/eggjs/egg-security/) plugin built in egg requires CSRF validation against all 'unsafe' request such as `POST`, `PUT`, `DELETE` requests.
By default [egg-security](https://github.com/eggjs/egg-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 correct csrf token in request. For more implentation details, see [./core/security.md#csrf].
58 changes: 29 additions & 29 deletions docs/source/en/intro/egg-and-koa.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
title: egg and koa
title: 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/blog/zalgo.html): Asynchronous functions may call callback function response data synchronously which would bring inconsistency.
- [release zalgo](https://oren.github.io/blog/zalgo.html): Asynchronous functions may call callback function response data synchronously which would bring inconsistency.

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

### Generator and co

#### Asynchronous programming model in synchronous way on basis of Generator and Promise.
#### Asynchronous programming model in synchronous way on basis of Generator and Promise.

As metioned before, we can write asynchronous code in synchronous way with the help of Generator and Promise. The most popular library implementing this feature is [co]. the core principle of [co] can be described by lines of code below:

Expand Down Expand Up @@ -50,7 +50,7 @@ run(main());

With the run function, asynchronous code can be written in synchronous way in main function in the example above. If you want to know more about Generator, you can have a look at [this document](https://github.com/dead-horse/koa-step-by-step#generator)

Compared with the run function, [co] has `yield [Object / Array / thunk / Generator Function / Generator]`, and builds a Promise with wrapping a Generator Function. [co] is also the underlying library of koa 1 providing the asynchronous feature. Every middleware in koa 1 must be a `generator function`.
Compared with the run function, [co] has `yield [Object / Array / thunk / Generator Function / Generator]`, and builds a Promise with wrapping a Generator Function. [co] is also the underlying library of Koa 1 providing the asynchronous feature. Every middleware in Koa 1 must be a `generator function`.

### Async function

Expand All @@ -76,17 +76,17 @@ fn().then(res => console.log(res)).catch(err => console.error(err.stack));

Other than the features supported by [co], async function can not await a `Promise` array (You can wrap it with `Promise.all`), await `thunk` is not avaliable either.

Though async function has not been published with the spec yet, it is supported in the V8 runtime built in node 7.x, you can use it without flag parameter after 7.6.0 version.
Though async function has not been published with the spec yet, it is supported in the V8 runtime built in Node.js 7.x, you can use it without flag parameter after 7.6.0 version.

## Koa

> Koa 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.
> Koa 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 style of koa and express are very similar, The underlying base library is the same, [HTTP library](https://github.com/jshttp). There are several significant differences between them. Besides the asynchronous solution by default metioned above, there are the following points.
The design style of Koa and Express are very similar, The underlying base library is the same, [HTTP library](https://github.com/jshttp). There are several significant differences between them. Besides the asynchronous solution by default metioned above, there are the following points.

### Midlleware

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

- Middleware onion diagram:

Expand All @@ -96,16 +96,16 @@ The middleware in koa is different from express, koa use the onion model:

![](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 implementing post-processing logic. You can obviously feel the advantage of koa middleware model comparing to the compress middleware implementing in koa and express.
All the requests will be executed twice during one middleware. Compared to Express middleware, it is very easy to implementing post-processing logic. You can obviously feel the advantage of Koa middleware model comparing to the compress middleware implementing in Koa and Express.

- [koa-compress](https://github.com/koajs/compress/blob/master/index.js) for koa.
- [compression](https://github.com/expressjs/compression/blob/master/index.js) for express.
- [koa-compress](https://github.com/koajs/compress/blob/master/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 attach all the relative things to the object. Such as [traceId](https://github.com/eggjs/egg-tracer/blob/1.0.0/lib/tracer.js#L12) that runs through the request lifetime (which will be called anywhere afterward) could be attached. It is more semantic other than request and response.
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 attach all the relative things to the object. Such as [traceId](https://github.com/eggjs/egg-tracer/blob/1.0.0/lib/tracer.js#L12) that runs through the request lifetime (which will be called anywhere afterward) could be attached. It is more semantic other than request and response.

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

- `get request.query`
- `get request.hostname`
Expand All @@ -130,16 +130,16 @@ function* onerror(next) {

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

## Egg inherit from koa
## Egg inherit from Koa

As the above words, koa is an excellent framework. However, it is not enough to building an enterprise-class application.
As the above words, Koa is an excellent framework. However, it is not enough to building an enterprise-class application.

Egg is built around the koa. On the basis of koa model, egg implements enhancements one step further.
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`:
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
Expand All @@ -166,13 +166,13 @@ More about extension, please check [Exception](../basics/extend.md) section.

### Plugin

As is known to all, Many middlewares are imported to provide different kind 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 more easy to write stand alone features.
As is known to all, Many middlewares are imported to provide different kind 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 more easy 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.
- middleware:add one or more middlewares, provide pre or post processing logic for request.
- config:configure the default value in different environments.

Stand alone module plugin can provide rich features with high maintenancability. You can almost forget the configuration as the plugin supports configuring the default value in different environments.

Expand All @@ -182,22 +182,22 @@ More about plugin, please check [plugin](../advanced/plugin.md) section.

### Roadmap

#### egg 1.x
#### Egg 1.x

The node LTS version now does not support async function,so egg is based on koa 1.x. On the basis of this, egg has added full async function support. Egg is completely compatible with middlewares in koa 2.x, all application layer are implemented based on [async function](../tutorials/async-function.md).
The Node.js LTS version now does not support async function,so Egg is based on Koa 1.x. On the basis of this, Egg has added full async function support. Egg is completely compatible with middlewares in Koa 2.x, all application layer are implemented based on [async function](../tutorials/async-function.md).

- The underlying is based on koa 1.x, asynchronous solution is based on generator function wrapped by [co].
- Official plugin and core of egg are written in generator function, keep supporting node LTS version, use [co] when necessary to be compatiable with async function.
- Application developers can choose either async function(node 7.6+) or generator function(node 6.0+), **we recommend generator function way for ensuring you application can be runned on node LTS version**.
- The underlying is based on Koa 1.x, asynchronous solution is based on generator function wrapped by [co].
- Official plugin and core of Egg are written in generator function, keep supporting Node.js LTS version, use [co] when necessary to be compatiable with async function.
- Application developers can choose either async function (Node.js 7.6+) or generator function (Node.js 6.0+), **we recommend generator function way for ensuring you application can be runned on Node.js LTS version**.

#### egg next
#### Egg next

Egg will transfer core to koa 2.x until node LTS supports async function, compatibility with generator function will also be kept.
Egg will transfer core to Koa 2.x until Node.js LTS supports async function, compatibility with generator function will also be kept.

- The underlying will be based on koa 2.x, asynchronous solution will be based on async function.
- The underlying will be based on Koa 2.x, asynchronous solution will be based on async function.
- Official plugin and core of egge will be written in async function.
- Recommend user transfer business layer to async function.
- node 6.x will be no longer supported.
- Node.js 6.x will be no longer supported.

[co]: https://github.com/tj/co
[Async function]: https://github.com/tc39/ecmascript-asyncawait
Expand Down
Loading

0 comments on commit d131f23

Please sign in to comment.