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