本文將從實(shí)例的角度，一步步地搭建出一個(gè) Egg.js 應(yīng)用，讓你能快速的入門 Egg.js。
環(huán)境準(zhǔn)備
- 操作系統(tǒng)：支持 macOS，Linux，Windows
- 運(yùn)行環(huán)境：建議選擇 LTS 版本，最低要求 8.x。
快速初始化
我們推薦直接使用腳手架，只需幾條簡(jiǎn)單指令，即可快速生成項(xiàng)目（npm >=6.1.0）:
$ mkdir egg-example && cd egg-example
$ npm init egg --type=simple
$ npm i
|
啟動(dòng)項(xiàng)目:
$ npm run dev
$ open http://localhost:7001
|
逐步搭建
通常你可以通過(guò)上一節(jié)的方式，使用 npm init egg 快速選擇適合對(duì)應(yīng)業(yè)務(wù)模型的腳手架，快速啟動(dòng) Egg.js 項(xiàng)目的開發(fā)。
但為了讓大家更好的了解 Egg.js，接下來(lái)，我們將跳過(guò)腳手架，手動(dòng)一步步的搭建出一個(gè) Hacker News。
注意：實(shí)際項(xiàng)目中，我們推薦使用上一節(jié)的腳手架直接初始化。
初始化項(xiàng)目
先來(lái)初始化下目錄結(jié)構(gòu)：
$ 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 開發(fā)或 MVC，肯定猜到我們第一步需要編寫的是 Controller 和 Router。
// 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);
};
|
加一個(gè)配置文件：
// config/config.default.js
exports.keys = <此處改為你自己的 Cookie 安全字符串>;
|
此時(shí)目錄結(jié)構(gòu)如下：
egg-example
├── app
│ ├── controller
│ │ └── home.js
│ └── router.js
├── config
│ └── config.default.js
└── package.json
|
完整的目錄結(jié)構(gòu)規(guī)范參見(jiàn)目錄結(jié)構(gòu)。
好，現(xiàn)在可以啟動(dòng)應(yīng)用來(lái)體驗(yàn)下
$ npm run dev
$ open http://localhost:7001
|
注意：Controller 有 class 和 exports 兩種編寫方式，本文示范的是前者，你可能需要參考 Controller 文檔。Config 也有 module.exports 和 exports 的寫法，具體參考 Node.js modules 文檔。
靜態(tài)資源
Egg 內(nèi)置了 static 插件，線上環(huán)境建議部署到 CDN，無(wú)需該插件。
static 插件默認(rèn)映射 /public/* -> app/public/* 目錄
此處，我們把靜態(tài)資源都放到 app/public 目錄即可：
app/public
├── css
│ └── news.css
└── js
├── lib.js
└── news.js
|
模板渲染
絕大多數(shù)情況，我們都需要讀取數(shù)據(jù)后渲染模板，然后呈現(xiàn)給用戶。故我們需要引入對(duì)應(yīng)的模板引擎。
框架并不強(qiáng)制你使用某種模板引擎，只是約定了 View 插件開發(fā)規(guī)范，開發(fā)者可以引入不同的插件來(lái)實(shí)現(xiàn)差異化定制。
更多用法參見(jiàn) View。
在本例中，我們使用 Nunjucks 來(lái)渲染，先安裝對(duì)應(yīng)的插件 egg-view-nunjucks ：
$ npm i egg-view-nunjucks --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',
},
};
|
注意：是 config 目錄，不是 app/config!
為列表頁(yè)編寫模板文件，一般放置在 app/view 目錄下
<!-- app/view/news/list.tpl -->
<html>
<head>
<title>Hacker News</title>
<link rel="stylesheet" href="/public/css/news.css" />
</head>
<body>
<ul class="news-view view">
{% for item in list %}
<li class="item">
<a href="{{ item.url }}">{{ item.title }}</a>
</li>
{% endfor %}
</ul>
</body>
</html>
|
添加 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);
};
|
啟動(dòng)瀏覽器，訪問(wèn) http://localhost:7001/news 即可看到渲染后的頁(yè)面。
提示：開發(fā)期默認(rèn)開啟了 development 插件，修改后端代碼后，會(huì)自動(dòng)重啟 Worker 進(jìn)程。
編寫 service
在實(shí)際應(yīng)用中，Controller 一般不會(huì)自己產(chǎn)出數(shù)據(jù)，也不會(huì)包含復(fù)雜的邏輯，復(fù)雜的過(guò)程應(yīng)抽象為業(yè)務(wù)邏輯層 Service。
我們來(lái)添加一個(gè) Service 抓取 Hacker News 的數(shù)據(jù) ，如下：
// 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;
|
框架提供了內(nèi)置的 HttpClient 來(lái)方便開發(fā)者使用 HTTP 請(qǐng)求。
然后稍微修改下之前的 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;
|
還需增加 app/service/news.js 中讀取到的配置：
// config/config.default.js
// 添加 news 的配置項(xiàng)
exports.news = {
pageSize: 5,
serverUrl: 'https://hacker-news.firebaseio.com/v0',
};
|
編寫擴(kuò)展
遇到一個(gè)小問(wèn)題，我們的資訊時(shí)間的數(shù)據(jù)是 UnixTime 格式的，我們希望顯示為便于閱讀的格式。
框架提供了一種快速擴(kuò)展的方式，只需在 app/extend 目錄下提供擴(kuò)展腳本即可，具體參見(jiàn)擴(kuò)展。
在這里，我們可以使用 View 插件支持的 Helper 來(lái)實(shí)現(xiàn)：
// app/extend/helper.js
const moment = require('moment');
exports.relativeTime = time => moment(new Date(time * 1000)).fromNow();
|
在模板里面使用：
<!-- app/view/news/list.tpl -->
{{ helper.relativeTime(item.time) }}
|
編寫 Middleware
假設(shè)有個(gè)需求：我們的新聞?wù)军c(diǎn)，禁止百度爬蟲訪問(wèn)。
聰明的同學(xué)們一定很快能想到可以通過(guò) 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,
]
};
|
現(xiàn)在可以使用 curl http://localhost:7001/news -A "Baiduspider" 看看效果。
更多參見(jiàn)中間件文檔。
配置文件
寫業(yè)務(wù)的時(shí)候，不可避免的需要有配置文件，框架提供了強(qiáng)大的配置合并管理功能：
- 支持按環(huán)境變量加載不同的配置文件，如 config.local.js， config.prod.js 等等。
- 應(yīng)用/插件/框架都可以配置自己的配置文件，框架將按順序合并加載。
- 具體合并邏輯可參見(jiàn)配置文件。
// 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;
|
單元測(cè)試
單元測(cè)試非常重要，框架也提供了 egg-bin 來(lái)幫開發(fā)者無(wú)痛的編寫測(cè)試。
測(cè)試文件應(yīng)該放在項(xiàng)目根目錄下的 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
|
執(zhí)行測(cè)試：
就這么簡(jiǎn)單，更多請(qǐng)參見(jiàn) 單元測(cè)試。
后記
短短幾章內(nèi)容，只能講 Egg 的冰山一角，我們建議開發(fā)者繼續(xù)閱讀其他章節(jié)：
- 關(guān)于骨架類型，參見(jiàn)骨架說(shuō)明
- 提供了強(qiáng)大的擴(kuò)展機(jī)制，參見(jiàn)插件。
- 一個(gè)大規(guī)模的團(tuán)隊(duì)需要遵循一定的約束和約定，在 Egg 里我們建議封裝適合自己團(tuán)隊(duì)的上層框架，參見(jiàn) 框架開發(fā)。
- 這是一個(gè)漸進(jìn)式的框架，代碼的共建，復(fù)用和下沉，竟然可以這么的無(wú)痛，建議閱讀 漸進(jìn)式開發(fā)。
- 寫單元測(cè)試其實(shí)很簡(jiǎn)單的事，Egg 也提供了非常多的配套輔助，我們強(qiáng)烈建議大家測(cè)試驅(qū)動(dòng)開發(fā)，具體參見(jiàn) 單元測(cè)試。
免費(fèi)AI編程助手
更多建議：