8.2 KiB
title: 快速入门
快速入门
本文将从实例的角度，一步步地搭建出一个 egg 应用，让你能快速的入门 egg。
环境准备
- 操作系统：支持 OSX，Linux，Windows(不建议)
- 运行环境：建议选择 LTS 版本，最低要求 6.x
快速初始化
通过脚手架快速生成项目:
$ npm i egg-init -g
$ egg-init egg-example --type=simple
$ cd egg-example
$ npm i
启动项目:
$ npm run dev
$ open localhost:7001
逐步搭建
通常你可以通过上一节的方式，使用 egg-init 快速选择适合对应业务模型的骨架，快速启动 egg 项目的开发。
接下来，我们将跳过脚手架，手动一步步的搭建出一个 egg hackernews。
初始化项目
先来初始化下目录结构：
$ mkdir egg-example
$ cd egg-example
$ npm init
$ npm i egg --save
$ npm i egg-bin --save-dev
添加 npm scripts 到 package.json：
{
"name": "egg-example",
"scripts": {
"dev": "egg-bin dev"
}
}
编写 controller
如果你熟悉 Web 开发或 MVC，肯定猜到我们第一步需要编写的是 controller 和 router。
// app/controller/home.js
module.exports = function* home() {
this.body = 'hi, egg';
};
配置路由映射：
// app/router.js
module.exports = app => {
app.get('/', 'home');
};
好，现在可以启动应用来体验下
$ npm run dev
$ open localhost:7001
静态资源
egg 内置了 static 插件，线上环境建议部署到 CDN，无需该插件。
static 插件默认映射 /public/* -> app/public/* 目录
此处，我们把静态资源都放到 app/public 目录即可：
app/public
├── css
│ └── news.css
└── js
├── lib.js
└── test.js
模板渲染
绝大多数情况，我们都需要读取数据后渲染模板，然后呈现给用户。故我们需要引入对应的模板引擎。
egg 并不强制你使用某种模板引擎，只是约定了 view 插件的规范，开发者可以引入不同的插件来实现差异化定制。
在本例中，我们使用 nunjucks 来渲染，先安装对应的插件 egg-view-nunjucks ：
$ npm i egg-view-nunjucks --save
开启插件：
// config/plugin.js
exports.view = {
enable: true,
package: 'egg-view-nunjucks'
};
为列表页编写模板文件，一般放置在 app/view 目录下
<!-- app/view/news/list.tpl -->
<html>
<head>
<title>Egg HackerNews Clone</title>
<link rel="stylesheet" href="/public/css/news.css" />
</head>
<body>
<div class="news-view view">
{% for item in list %}
<div class="item">
<a href="{{ item.url }}">{{ item.title }}</a>
</div>
{% endfor %}
</div>
</body>
<html/>
添加 controller 和 router
// app/controller/news.js
exports.list = function* newsList() {
const dataList = {
list: [
{ id: 1, title: 'this is news 1', url: '/news/1' },
{ id: 2, title: 'this is news 2', url: '/news/2' }
]
};
yield this.render('news/list.tpl', dataList);
};
// app/router.js
module.exports = app => {
app.get('/', 'home');
app.get('/news', 'news.list');
};
启动浏览器，访问 localhost:7001/news 即可看到渲染后的页面。
提示：开发期默认开启了 egg-development 插件，修改后端代码后，会自动重启 worker 进程。
编写 service
在实际应用中， controller 一般不会自己产出数据，也不会包含复杂的逻辑，复杂的过程应抽象为业务逻辑层 service。
我们来添加一个 service 抓取 HackerNews 的数据 ，如下：
// app/service/news.js
module.exports = app => {
class NewsService extends app.Service {
* list(page = 1) {
// read config
const { serverUrl, pageSize } = this.app.config.new;
// use build-in http client to GET hacker-news api
const { data: idList } = yield this.ctx.curl(`${serverUrl}/topstories.json`, {
data: {
orderBy: '"$key"',
startAt: `"${pageSize * (page - 1)}"`,
endAt: `"${pageSize * page - 1}"`,
},
dataType: 'json',
});
// parallel GET detail, see `yield {}` from co
const newsList = yield Object.keys(idList).map(key => {
const url = `${serverUrl}/item/${idList[key]}.json`;
return this.ctx.curl(url, { dataType: 'json' }).then(res => res.data);
});
return newsList;
}
}
return NewsService;
};
框架提供了内置的 http client 来方便开发者使用 http 请求。
然后稍微修改下之前的 controller：
// app/controller/news.js
exports.list = function* newsList() {
const page = this.query.page || 1;
const newsList = yield this.service.news.list(page);
yield this.render('news/list.tpl', { list: newsList });
};
编写扩展
遇到一个小问题，我们的资讯时间的数据是 UnixTime 格式的，我们希望显示为便于阅读的格式。
框架提供了一种快速扩展的方式，只需在 app/extend 目录下提供扩展脚本即可，具体参见 扩展。
在 egg-view-nunjucks 里面，我们可以通过扩展 helper 的方式来实现：
// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = time => moment(new Date(time * 1000)).fromNow();
在模板里面使用：
<!-- app/views/news/list.tpl -->
{{ helper.relativeTime(item.time) }}
编写 middleware
假设有个需求：我们的新闻站点，禁止百度爬虫访问。
聪明的同学们一定很快能想到可以通过 middleware 判断 UA，如下：
// app/middleware/robot.js
// options === app.config.robot
module.exports = (options, app) => {
return function* robotMiddleware(next) {
const source = this.get('user-agent') || '';
const match = options.ua.some(ua => ua.test(source));
if (match) {
this.status = 403;
this.message = 'go away, robot';
} else {
yield next;
}
}
};
// config/config.default.js
// mount middleware
exports.middleware = [
'robot'
];
// middleware config
exports.robot = {
ua: [
/Baiduspider/i,
]
};
现在可以使用 curl localhost:7001/news -A "Baiduspider" 看看效果。
配置文件
写业务的时候，不可避免的需要有配置文件，框架提供了强大的配置合并管理功能：
- 支持按环境变量加载不同的配置文件，如
config.local.js，config.prod.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/controller/news.js
exports.list = function* newsList() {
const config = this.app.config.news;
};
后记
短短几章内容，只能讲 egg 的冰山一角，我们建议开发者继续阅读其他章节：