Egg.js入门指南：新手必备的零基础教程

概述

Egg.js 是一个基于 Koa 构建的高性能 Node.js 应用框架，采用插件化设计，提供丰富的内置工具和插件，简化开发流程。框架支持多种应用场景，如 Web 应用开发、API 服务和微服务架构，并拥有活跃的社区支持。

Egg.js简介

什么是Egg.js

Egg.js 是一个基于 Koa 构建的框架，它采用了插件化的设计思路，旨在帮助开发者构建稳定、高性能的 Node.js 应用程序。Egg.js 以“约定优于配置”为核心设计理念，为开发者提供了大量的内置工具和插件，从而大大简化了开发流程。

Egg.js的特点和优势

1. 内置强大工具：Egg.js 内置了大量的工具和插件，如路由、中间件、日志、配置管理等，大大减少了开发者需要自己实现的功能。
2. 模块化设计：Egg.js 采用模块化设计，可以轻松地扩展和定制功能。
3. 性能优化：Egg.js 提供了丰富的性能优化工具，如缓存、压缩、HTTPS 等。
4. 开箱即用：Egg.js 提供了许多开箱即用的功能，可以快速搭建起一个基本的 Web 应用。
5. 社区支持：拥有活跃的社区和丰富的插件库，便于开发者在遇到问题时寻求帮助。

Egg.js的应用场景

1. Web 应用开发：Egg.js 是一个优秀的 Web 应用开发框架，可以用来快速开发高并发、高性能的 Web 应用。
2. API 服务：Egg.js 可以用来构建 RESTful API 服务，支持多种数据格式（如 JSON、XML）。
3. 微服务开发：Egg.js 支持微服务架构，可以方便地拆分和集成各种微服务。
4. 前后端分离：Egg.js 适合前后端分离的项目，可以和各种前端框架（如 React、Vue）无缝对接。

环境搭建

安装Node.js

1. 访问 Node.js 的官方下载页面（https://nodejs.org/）。
2. 根据你的操作系统选择合适的版本进行下载。
3. 安装完成后，可以在命令行中输入 node -v 和 npm -v 检查是否安装成功。

node -v
npm -v

初始化Egg.js项目

1. 全局安装 Egg CLI 工具：

npm install -g egg-init

1. 使用 Egg CLI 创建一个新的 Egg.js 项目：

egg-init my-egg-app

1. 进入项目目录并安装依赖：

cd my-egg-app
npm install

项目结构与配置文件介绍

• app: 应用的核心代码目录。
  • controller: 控制器目录，存放请求处理逻辑。
  • middleware: 中间件目录，存放自定义的中间件。
  • service: 服务目录，存放业务逻辑。
• config: 配置文件目录。
  • config.default.js: 默认配置文件。
  • config.${env}.js: 环境配置文件（如开发环境、测试环境、生产环境）。
• public: 静态资源目录。
• test: 测试代码目录。

示例代码：

// config.default.js
module.exports = app => {
  // 默认配置
  app.config.keys = 'my-secret-key';
};

快速上手

创建第一个Egg.js应用

1. 创建一个新的 Egg.js 项目，按照之前介绍的步骤操作。
2. 在 app/controller 目录下创建一个 index.js 文件，这是应用的第一个控制器：

// app/controller/index.js
module.exports = class IndexController {
  async index(ctx) {
    ctx.body = 'Hello, Egg.js!';
  }
};

示例代码：

// app/controller/index.js
class IndexController {
  async index(ctx) {
    ctx.body = 'Hello, Egg.js!';
  }
}

module.exports = IndexController;

路由配置与请求处理

路由配置一般在 config/router.js 文件中进行：

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

示例代码：

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

中间件的使用与自定义

Egg.js 支持定义中间件来处理请求。中间件一般定义在 app/middleware 目录下，然后在 config/config.default.js 中进行配置：

// app/middleware/logger.js
module.exports = () => {
  return async (ctx, next) => {
    console.log(`${ctx.method} ${ctx.url}`);
    await next();
  };
};

示例代码：

// config/config.default.js
module.exports = app => {
  // 中间件配置
  app.middleware.use('logger');
};

数据处理与数据库集成

使用Egg.js处理数据请求

1. 在 app/controller 目录下创建控制器来处理数据请求：

// app/controller/user.js
module.exports = class UserController {
  async list(ctx) {
    const list = [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' },
    ];
    ctx.body = list;
  }
};

示例代码：

// app/controller/user.js
class UserController {
  async list(ctx) {
    const list = [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' },
    ];
    ctx.body = list;
  }
}

module.exports = UserController;

连接数据库与CRUD操作

使用 Egg.js 连接数据库通常需要安装相应的数据库驱动，例如连接 MySQL 数据库需要安装 egg-mysql 插件：

npm install egg-mysql

配置数据库连接：

// config/config.default.js
module.exports = app => {
  app.config.mysql = {
    client: 'mysql',
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'root',
    database: 'test',
  };
};

示例代码：

// config/config.default.js
module.exports = app => {
  app.config.mysql = {
    client: 'mysql',
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'root',
    database: 'test',
  };
};

CRUD 操作示例：

// app/service/user.js
module.exports = class UserService {
  async getUserById(ctx, id) {
    const { client } = ctx.app.mysql;
    const result = await client.query('SELECT * FROM users WHERE id = ?', [id]);
    return result[0];
  }
};

示例代码：

// app/service/user.js
module.exports = class UserService {
  async getUserById(ctx, id) {
    const { client } = ctx.app.mysql;
    const result = await client.query('SELECT * FROM users WHERE id = ?', [id]);
    return result[0];
  }
};

数据验证与错误处理

数据验证可以使用 egg-joi 插件实现：

npm install egg-joi

在控制器中进行数据验证：

// app/controller/user.js
module.exports = class UserController {
  async list(ctx) {
    ctx.assert(ctx.query.id, 400, 'id is required');
    const id = ctx.query.id;
    const user = await ctx.service.user.getUserById(id);
    ctx.body = user;
  }
};

示例代码：

// app/controller/user.js
class UserController {
  async list(ctx) {
    ctx.assert(ctx.query.id, 400, 'id is required');
    const id = ctx.query.id;
    const user = await ctx.service.user.getUserById(id);
    ctx.body = user;
  }
}

module.exports = UserController;

错误处理可以通过中间件来实现：

// app/middleware/errorHandler.js
module.exports = () => {
  return async (ctx, next) => {
    try {
      await next();
    } catch (err) {
      ctx.body = { error: err.message };
      ctx.status = err.status || 500;
    }
  };
};

示例代码：

// app/middleware/errorHandler.js
module.exports = () => {
  return async (ctx, next) => {
    try {
      await next();
    } catch (err) {
      ctx.body = { error: err.message };
      ctx.status = err.status || 500;
    }
  };
};

性能优化与部署

环境变量与配置管理

使用环境变量可以方便地管理不同环境的配置。Egg.js 支持多种环境变量设置方式，例如：

export NODE_ENV=production
export MYSQL_HOST=localhost
export MYSQL_PORT=3306

在配置文件中使用环境变量：

// config/config.default.js
module.exports = app => {
  app.config.mysql = {
    client: 'mysql',
    host: process.env.MYSQL_HOST || 'localhost',
    port: process.env.MYSQL_PORT || 3306,
    user: 'root',
    password: 'root',
    database: 'test',
  };
};

示例代码：

// config/config.default.js
module.exports = app => {
  app.config.mysql = {
    client: 'mysql',
    host: process.env.MYSQL_HOST || 'localhost',
    port: process.env.MYSQL_PORT || 3306,
    user: 'root',
    password: 'root',
    database: 'test',
  };
};

启用HTTPS和SSL

安装 egg-https 插件来启用 HTTPS：

npm install egg-https

配置 SSL 证书：

// config/config.default.js
module.exports = app => {
  app.config.https = {
    key: fs.readFileSync('/path/to/server.key'),
    cert: fs.readFileSync('/path/to/server.crt'),
  };
};

示例代码：

// config/config.default.js
module.exports = app => {
  app.config.https = {
    key: fs.readFileSync('/path/to/server.key'),
    cert: fs.readFileSync('/path/to/server.crt'),
  };
};

项目打包与部署到服务器

打包项目：

npm run build

打包后，项目会生成 dist 目录，里面包含了构建好的代码。

部署到服务器：

1. 将打包后的代码上传到服务器。
2. 在服务器上安装 Node.js 和依赖：

cd /path/to/your/project
npm install

1. 启动项目：

npm start

实战案例与调试技巧

实战项目分析

一个完整的 Egg.js 项目通常包括以下几个部分：

1. 路由配置：定义每个端点和对应的处理函数。
2. 控制器：处理 HTTP 请求，调用服务进行具体业务逻辑处理。
3. 服务：处理业务逻辑，与数据库交互。
4. 中间件：处理请求的公共逻辑，如日志记录、错误处理等。
5. 配置文件：管理不同环境下的配置信息。

示例代码：

// config/router.js
module.exports = function (app) {
  const { router, controller } = app;
  router.get('/', controller.index.index);
  router.get('/users', controller.user.list);
};

// app/controller/user.js
class UserController {
  async list(ctx) {
    const users = await ctx.service.user.getAllUsers();
    ctx.body = users;
  }
}

module.exports = UserController;

// app/service/user.js
class UserService {
  async getAllUsers() {
    const { client } = ctx.app.mysql;
    const result = await client.query('SELECT * FROM users');
    return result;
  }
}

module.exports = UserService;

// app/middleware/logger.js
module.exports = () => {
  return async (ctx, next) => {
    console.log(`${ctx.method} ${ctx.url}`);
    await next();
  };
};

常见调试方法与技巧

1. 使用断点调试：在代码中设置断点，使用调试工具（如 Chrome DevTools）进行调试。
2. 日志记录：在关键位置记录日志，帮助定位问题。
3. 单元测试：编写单元测试，确保代码的正确性。
4. 性能分析：使用性能分析工具（如 Chrome DevTools、Node.js 的 process.hrtime()）分析性能瓶颈。

示例代码：

// app/controller/user.js
class UserController {
  async list(ctx) {
    console.log('Listing users...');
    const users = await ctx.service.user.getAllUsers();
    ctx.body = users;
  }
}

常见问题与解决方案

1. 请求处理超时：增加超时时间或优化代码逻辑。

// config/config.default.js
module.exports = app => {
  app.config.httpTimeout = 30000;
};

1. 中间件未生效：确保中间件在配置文件中被正确注册。

// config/config.default.js
module.exports = app => {
  app.middleware.use('logger');
};

1. 数据库连接失败：检查数据库连接配置和数据库服务状态。

// config/config.default.js
module.exports = app => {
  app.config.mysql = {
    client: 'mysql',
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'root',
    database: 'test',
  };
};

1. 端口冲突：检查是否有其他服务占用端口。

netstat -an | grep 3000

通过以上内容，你已经掌握了 Egg.js 的基本使用方法和常见问题解决方案，可以开始构建自己的高性能 Web 应用了。