快速初始化
mkdir egg-example && cd egg-example
npm init egg --type=simple
npm i
启动项目
npm run dev
open localhost:7001
手动逐步搭建
mkdir egg-example
cd egg-example
npm init
npm i egg --save
npm i gee-bin --save-dev
添加npm scripts到package.json
{
"name": "egg-example",
"scripts": {
"dev": "egg-bin dev"
}
}
编写Controller
// app/controller/home.js
const Controller = require('egg').Controller;
class HomeController extends Controller {
async index() {
this.ctx.body = 'Hello world';
}
}
module.exports = HomeController;
配置路由映射：
// app/router.js
module.exports = app => {
const { router, controller } = app;
router.get('/', controller.home.index);
};
此时文件目录结构
egg-example
├── app
│ ├── controller
│ │ └── home.js
│ └── router.js
├── config
│ └── config.default.js
└── package.json
运行
npm run dev
open localhost:7001
打开 localhost:7001 看到页面
hello world
此时目录多了一个文件夹public
static插件默认映射/public/*目录
app/public
├── css
│ └── news.css
└── js
├── lib.js
└── news.js
Egg内置了static插件，先上环境建议部署到CDN，无需该插件
egg-example
├── app
│ ├── controller
│ │ └── home.js
│ ├── public
│ └── router.js
├── config
│ └── config.default.js
└── package.json
模板渲染
在本例中，我们使用Nunjucks来渲染，先安装对应的插件egg-view-nunjucks
npm i egg-view-numjucks --save
开启插件:
// config/plugin.js
exports.nunjucks = {
enable: true,
package: 'egg-view-nunjucks'
};
// config/config.default.js
exports.keys = <此处改为你自己的 Cookie 安全字符串>;
// 添加 view 配置
exports.view = {
defaultViewEngine: 'nunjucks',
mapping: {
'.tpl': 'nunjucks',
},
};
为列表页编写模板文件，一般放置在app/view目录下
Hacker News
{% for item in list %}
-
{{ item.title }}
{% endfor %}
添加Controller和Router
// 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);
};
此时文件目录结构
egg-example
├── app
│ ├── controller
│ │ └── home.js
│ │ └── news.js
│ ├── public
│ ├── view
│ │ └── news
│ │ └── list.tpl
│ └── router.js
├── config
│ └── config.default.js
│ └── plugin.js
└── package.json
在实际应用中,Controller一般不会自己产出数据，也不会包含复杂的逻辑，复杂的过程应抽象为业务逻辑层Service
添加一个Service抓取Hacker News的数据
// 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来方便开发者使用HTTP请求
修改下之前的Controller
// 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;
还需在config.default.js中读取配置
// config/config.default.js
// 添加 news 的配置项
exports.news = {
pageSize: 5,
serverUrl: 'https://hacker-news.firebaseio.com/v0',
};
接口需要翻墙才能请求成功
此时文件目录
egg-example
├── app
│ ├── controller
│ │ └── home.js
│ │ └── news.js
│ ├── extend
│ │ └── helper.js
│ ├── public
│ ├── service
│ │ └── news.js
│ ├── view
│ │ └── news
│ │ └── list.tpl
│ └── router.js
├── config
│ └── config.default.js
│ └── plugin.js
└── package.json
编写扩展
框架提供了一种快速扩展的方式，只需在 app/extend 目录下提供扩展脚本即可。
例子
npm i moment --save
// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = time => moment(new Date(time * 1000)).fromNow();
在模板里面使用
{{ helper.relativeTime(item.time) }}
编写Middleware
假设有个需求：我们的新闻站点，禁止百度爬虫访问。
聪明的同学们一定很快能想到可以通过 Middleware 判断 User-Agent，如下：
// 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,
]
};
配置文件
- 支持按环境变量加载不同的配置文件，如
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/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。
// 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：
{
"scripts": {
"test": "egg-bin test",
"cov": "egg-bin cov"
}
}
$ npm i egg-mock --save-dev
执行测试：
$ npm test