docs: quickstart/egg.md

geekdada · geekdada · commit c154cb9f1347 · 2019-05-15T15:22:44.000+08:00
diff --git a/docs/quickstart/README.md b/docs/quickstart/README.md
diff --git a/docs/quickstart/egg.md b/docs/quickstart/egg.md
@@ -0,0 +1,306 @@
+---
+title: Your first Egg application
+---
+
+It's time to get your hands dirty. In this guide, we'll walk you through every step of building a (really) simple Egg application.
+
+:::tip Tips
+- This guide is for beginners who want to get started with an Egg application from scratch.
+- Most of the plugins are included in Egg by default. You can switch them on/off in the configurations.
+- More information can be found in [Guide](../guide/README.md).
+:::
+
+## TodoMVC
+
+We'll build a [TodoMVC](http://todomvc.com/) application from scratch, using Egg.
+
+The complete version can be found at [eggjs/examples/todomvc](https://github.com/eggjs/examples/tree/master/todomvc).
+
+<!-- ![](./images/todomvc.png) -->
+
+## Creating an Egg aplication
+
+### Preparation
+
+- **OS**: All operating systems are supported, but `macOS` is recommended.
+- **Node.js**: If you are new to Node.js, there's an [installation guide here](./prepare.md).
+
+### Scaffolding
+
+There's a [tool](../workflow/development/init.md) for scaffolding Egg applications.
+
+:::tip Tips
+The examples below use $ to represent the terminal prompt in a UNIX-like OS, it might be different in some occasions.
+:::
+
+```bash
+$ mkdir demo && cd demo
+$ npm init egg --type=simple
+$ npm install
+```
+
+### Directory
+
+The `demo` directory will be looking like this. They are generated by following [the directory rules](../guide/directory.md) of an Egg application. We strongly recommend you to follow it when creating new folders.
+
+```bash
+demo
+├── app
+│   ├── controller # Controllers
+│   │   └── home.js
+│   └── router.js # Routers
+├── config # Configurations
+│   ├── config.default.js
+│   └── plugin.js
+├── test # Testing files
+├── README.md
+└── package.json
+```
+
+### `Controller`
+
+[Controller](../guide/controller.md) is responsible for **parsing user requests**, **handling them** and **response back**.
+
+```js
+// app/controller/home.js
+const { Controller } = require('egg');
+
+class HomeController extends Controller {
+  async index() {
+    const { ctx } = this;
+    ctx.body = 'hi, egg';
+  }
+}
+
+module.exports = HomeController;
+```
+
+Every controller needs to mount to a certain `URL` which tells Egg when to handle incoming requests. In the case below, `/` would be handled with the controller you just wrote.
+
+```js
+// app/router.js
+/**
+ * @param {Egg.Application} app - egg application
+ */
+module.exports = app => {
+  const { router, controller } = app;
+  router.get('/', controller.home.index);
+};
+```
+
+### Local Development
+
+Egg comes with a [tool](../workflow/development/development.md) for local development.
+
+- Getting your application up;
+- Watching file changes;
+- Generating `d.ts` files if you're using TypeScript;
+
+To start your application:
+
+```bash
+$ npm run dev
+```
+
+Next, go to `http://127.0.0.1:7001` in your browser.
+
+### Template Rendering
+
+In most cases, we want to present web pages to users, using template rendering. But Egg doesn't come with this feature enabled by default. You have to choose a *template engine plugin* and enable it by yourself.
+
+:::tip What is plugin?
+The plugin system is a special feature of Egg. It makes the core application simple, yet stable and highly efficient. You can use plugins for business logic reusing and building an eco-system.
+
+Go to [Development - Plugins](../guide/plugin.md) to see more.
+:::
+
+In this guide, we'll be using [Nunjucks](https://mozilla.github.io/nunjucks/) to render our pages.
+
+To start, you need to install [egg-view-nunjucks] first.
+
+```bash
+$ npm i egg-view-nunjucks --save
+```
+
+Then, enable it.
+
+```js
+// config/plugin.js
+exports.nunjucks = {
+  enable: true,
+  package: 'egg-view-nunjucks'
+};
+```
+
+Every template file should be located in `app/view` and its enclosing folders.
+
+```html
+<!-- app/view/home.tpl -->
+<html>
+  ...
+  <script src="/public/main.js"></script>
+</html>
+```
+
+Lastly, change your `Controller` into this.
+
+```js
+class HomeController extends Controller {
+  async index() {
+    const { ctx } = this;
+    // 渲染模板 `app/view/home.tpl`
+    await ctx.render('home.tpl');
+  }
+}
+```
+
+### Static Files
+
+Normally, static files are served through:
+
+- Content Deliver Network (recommend);
+- Current application;
+
+Egg comes with a handy plugin [egg-static] for serving static files in current application.
+
+egg-static would mount the folder `app/public` to the route `/public` by default.
+
+:::warning Warning
+- Files served by `egg-static` will be responsed with a `maxAge` header which indicates the browsers to cache for a year by default.
+- [CSRF mechanism](../ecosystem/security/csrf.md) is open by default. `AJAX` requests need to have a valid `token` so that they can be handled properly. If you are using axios, here's an example:
+
+```js
+// app/public/main.js
+axios.defaults.headers.common['x-csrf-token'] = Cookies.get('csrfToken');
+```
+:::
+
+### Configurations
+
+It's quite common for developers to manage a bunch of [configurations](../guide/config.md). Egg's configuration feature would definately be helpful.
+
+For example, to use [egg-view-nunjucks], you will have to add a few lines to `config/config.default.js`.
+
+```js
+// config/config.default.js
+config.view = {
+  defaultViewEngine: 'nunjucks',
+  mapping: {
+    '.tpl': 'nunjucks',
+    '.html': 'nunjucks',
+  },
+};
+```
+
+:::warning Warning
+It's `./config`, not `./app/config`!
+:::
+
+### `Service`
+
+Normally, business logics are in the [Service](../guide/service.md). They can be called by the `Controller`.
+
+Here is an example for creating a todo item.
+
+```js
+// app/service/todo.js
+const { Service } = require('egg');
+
+class TodoService extends Service {
+  /**
+   * create todo
+   * @param {Todo} todo - todo info without `id`, but `title` required
+   */
+  async create(todo) {
+    // validate
+    if (!todo.title) this.ctx.throw(422, 'task title required');
+
+    // normalize
+    todo.id = Date.now().toString();
+    todo.completed = false;
+
+    this.store.push(todo);
+    return todo;
+  }
+}
+```
+
+Then, call it in `Controller`.
+
+```js
+// app/controller/todo.js
+class TodoController extends Controller {
+  async create() {
+    const { ctx, service } = this;
+
+    // params validate, need `egg-validate` plugin
+    // ctx.validate({ title: { type: 'string' } });
+
+    ctx.status = 201;
+    ctx.body = await service.todo.create(ctx.request.body);
+  }
+}
+```
+
+### RESTful
+
+Egg has [built-in support](../guide/router.md#RESTful-风格的-URL-定义) for RESTful routing.
+
+```js
+// app/router.js
+module.exports = app => {
+  const { router, controller } = app;
+
+  // RESTful mapping
+  router.resources('/api/todo', controller.todo);
+};
+```
+
+The controller `controller.todo` must implement these functions:
+
+```js
+// app/controller/todo.js
+class TodoController extends Controller {
+  // `GET /api/todo`
+  async index() {}
+
+  // `POST /api/todo`
+  async create() {}
+
+  // `PUT /api/todo`
+  async update() {}
+
+  // `DELETE /api/todo`
+  async destroy() {}
+}
+```
+
+### Unit Testing
+
+It is highly recommended to do the unit testing. Egg comes with [a tool](../workflow/development/unittest.md) for you to test your application.
+
+```js
+// test/app/controller/todo.test.js
+const { app, mock, assert } = require('egg-mock/bootstrap');
+
+describe('test/app/controller/todo.test.js', () => {
+  it('should add todo', () => {
+    return app.httpRequest()
+      .post('/api/todo')
+      .send({ title: 'Add one' })
+      .expect('Content-Type', /json/)
+      .expect('X-Response-Time', /\d+ms/)
+      .expect(201)
+      .expect(res => {
+        assert(res.body.id);
+        assert(res.body.title === 'Add one');
+        assert(res.body.completed === false);
+      });
+  });
+});
+```
+
+[Node.js]: http://nodejs.org
+[egg-static]: https://github.com/eggjs/egg-static
+[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
+[Nunjucks]: https://mozilla.github.io/nunjucks/
diff --git a/docs/zh/quickstart/egg.md b/docs/zh/quickstart/egg.md
@@ -163,7 +163,7 @@ class HomeController extends Controller {
 在本例中，我们使用 `Vue` 来写对应的前端逻辑，可以直接参见示例代码。
 
 :::warning 注意事项
-- `static` 插件，线上会默认设置一年的 `magAge`。
+- `static` 插件，线上会默认设置一年的 `maxAge`。
 - 框架默认开启了 [CSRF 防护](../ecosystem/security/csrf.md)，故 `AJAX` 请求需要带上对应的 `token`：
 
 ```js
