# 快速入门

手把手快速从0到1搭建一个基础的Egg.js应用

# 基础环境

  • 操作系统：macOS、Linux、Windows均可
  • Nodejs环境

# 环境检测

## 查看npm版本
npm version

# 快速搭建


## 创建根目录，并切换进入
mkdir egg-demo && cd egg-demo

## 项目初始化
npm init egg --type=simple

## 下载依赖
npm i

## 开发环境下启动
npm run dev

## 浏览器访问
http://localhost:7001

# 手动搭建

# 项目初始化

和基础的node项目一样，先初始化目录结构

## 创建目录
mkdir egg-demo

## 切换进入

cd egg-demo

## node项目初始化

npm init

## 下载egg依赖包

npm install egg --save

## 开发环境下，安装启动依赖包

npm install egg-bin --save-dev

由于在开发环境下启动，运行了npm run dev指令，所以需要在根目录下的package.json文件中配置dev命令脚本

{
    "name":"egg-demo",
    "scripts":{
        "dev":"egg-bin dev"
    }
}

其实上面的配置，在通过快速搭建egg基础项目时，可以看到类似的配置

# 编写控制器

当你有了解过Web开发或者MVC的开发模式，在项目结构中肯定会有Controller层和Router路由层，当然Spring框架的路由注解会代替Router


// app/controller/home.js

const Controller= require('egg').Controller;

// 定义类

class HomeController extends Controller{
    // 定义方法
    async index(){
        const {ctx}=this;
        ctx.body='hi egg demo'
    }
}


// 模块导出

module.export=HomeController

# 配置路由

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
};

这个时候回头看，项目的基本结构：

egg-demo
├── app
│   ├── controller
│   │   └── home.js
│   └── router.js
├── config
│   └── config.default.js
└── package.json

# 启动项目

## 开发环境下启动
npm run dev

# 初次体验

当执行npm run dev指令后，在console控制台可以看到相关的启动日志，我们可以通过访问http://localhost:7001来查看egg-demo是都正常启动

# 静态资源

Egg 内置了 static 插件，线上环境建议部署到 CDN，无需该插件。

static 插件默认映射 /public/ -> app/public/ 目录

此处，我们把静态资源都放到 app/public 目录即可：


app/public
├── css
│   └── news.css
└── js
    ├── lib.js
    └── news.js

# 模板渲染

绝大多数情况，需要读取数据后渲染模板，然后呈现给用户。故我们需要引入对应的模板引擎。

框架并不强制你使用某种模板引擎，只是约定了 View 插件开发规范，开发者可以引入不同的插件来实现差异化定制。

在本例中，我们使用 Nunjucks 来渲染，先安装对应的插件 egg-view-nunjucks ：

## 安装模块
$ npm i egg-view-nunjucks --save

模块安装完成后，需要修改插件的参数配置来开启插件


// config/plugin.js 注意：是 config 目录，不是 app/config!
exports.nunjucks = {
  enable: true,
  package: 'egg-view-nunjucks'
};
// config/config.default.js
exports.keys = '<此处改为你自己的 Cookie 安全字符串,建议hash值>';
// 添加 view 配置
exports.view = {
  defaultViewEngine: 'nunjucks',
  mapping: {
    '.tpl': 'nunjucks',
  },
};

为列表页编写模板文件，一般放置在 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层的页面访问逻辑

// 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;

添加Router层中，路由的相关配置

// 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 即可看到渲染后的页面。

开发期默认开启了 development 插件，修改后端代码后，会自动重启 Worker 进程，即：热加载

# 编写 service

在实际应用中，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;

还需增加 app/service/news.js 中读取到的配置：

// config/config.default.js
// 添加 news 的配置项
exports.news = {
  pageSize: 5,
  serverUrl: 'https://hacker-news.firebaseio.com/v0',
};

# 编写扩展

遇到一个小问题，资讯时间的数据是 UnixTime 格式的，我们希望显示为便于阅读的格式。

框架提供了一种快速扩展的方式，只需在 app/extend 目录下提供扩展脚本即可，具体参见扩展。

在这里，可以使用 View 插件支持的 Helper 来实现：

## 安装依赖
$ npm i moment --save

// 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

假设有个需求：新闻站点禁止百度爬虫访问。

聪明的朋友们一定很快能想到可以通过 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) {
    // 设置禁止访问的http状态码
      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,
  ]
};

现在可以使用 curl http://localhost:7001/news -A "Baiduspider" 看看效果。

其实这里的middleware就是egg框架中一个非常重要的概念——中间件，就我自己的经验来看，项目中很多特定的授权、校验都可以通过中间件来完成

# 配置文件

写业务的时候，不可避免的需要有配置文件，框架提供了强大的配置合并管理功能：

支持按环境变量加载不同的配置文件，如 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"
  }
}

安装依赖

## 下载mock包
npm i egg-mock --save-dev
## 执行测试：
npm test

基础的单元测试mock可以通过这样出处理，复杂一点的可能需要去使用postman实际调用，至此，欢迎走进egg框架大门，愿你一帆风顺~

最近更新: 1/19/2021, 11:03:12 PM

目录结构