Egg.js入门：新手必读教程

Egg.js 是一个基于 Koa 的 Web 框架，简化了应用程序的开发流程，使得开发者可以更加专注于业务逻辑的实现。本文将详细介绍 Egg.js 的特点、应用场景以及如何搭建开发环境，帮助读者快速入门 Egg.js。

什么是Egg.js

Egg.js 是一个用 TypeScript 构建的基于 Koa 的 Web 框架，它简化了应用程序的开发流程，使得开发者可以更加专注于业务逻辑的实现。Egg.js 提供了丰富的插件和中间件支持，使得开发效率大大提高。

Egg.js的特点和优势

• 插件化架构：Egg.js 采用插件化的设计，使得开发者能够方便地扩展和定制功能。例如，可以使用 egg-mysql 插件来实现数据库连接功能。
• 路由和控制器分离：Egg.js 通过路由和控制器分离的方式，增强了代码的可读性和可维护性。例如，控制器和路由定义分别在 controller 和 router 目录下。
• 自动加载中间件：框架会自动加载配置的中间件，使得中间件的管理更加方便。例如，可以使用 egg-logger 插件自动加载日志中间件。
• 多环境支持：Egg.js 支持多种环境的部署，包括开发、测试、生产等。例如，可以通过 config.development.js 和 config.production.js 文件来配置不同环境下的配置。
• 强大的社区支持：Egg.js 拥有活跃的社区，在遇到问题时可以快速找到解决方案。

Egg.js的应用场景

• Web 应用开发：无论是简单的 RESTful API 还是复杂的 Web 应用，Egg.js 都能胜任。例如，可以使用 Egg.js 创建一个 RESTful API 服务。
• 前后端分离开发：Egg.js 支持前后端分离开发，可以与 React、Vue 等前端框架无缝集成。例如，可以将 Egg.js 用于后端服务，前端使用 React 或 Vue 进行开发。
• 微服务架构：Egg.js 可以用于构建微服务架构，支持服务间的通讯和协调。例如，可以使用 Egg.js 分别创建不同的微服务，并定义服务间的通信协议。

安装Node.js

要使用 Egg.js，首先需要安装 Node.js。Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境，允许开发者使用 JavaScript 编写服务器端应用程序。

1. 访问 Node.js 官方网站 下载最新版本的 Node.js。
2. 安装完毕后，可以通过以下命令验证 Node.js 是否安装成功：

node -v
npm -v

安装Egg.js

安装 Egg.js 需要使用 npm（Node.js 的包管理工具）。运行以下命令来安装 Egg.js：

npm install -g egg-init

创建第一个Egg.js项目

使用 egg-init 命令创建一个新的 Egg.js 项目。例如，创建一个名为 my-egg-app 的项目：

egg-init my-egg-app

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

cd my-egg-app
npm install

启动开发服务器：

npm run dev

此时，你应该可以在浏览器中访问 http://localhost:7001，并看到默认的 "Hello World!" 页面。

应用目录结构

一个典型的 Egg.js 项目包含以下目录结构：

my-egg-app/
├── app/
│   ├── controller/
│   ├── middleware/
│   ├── router/
│   └── service/
├── config/
│   ├── config.default.js
│   ├── config.development.js
│   ├── config.test.js
│   └── config.production.js
├── package.json
└── README.md

• app 目录：存放应用代码，包括控制器、服务、中间件等。
• config 目录：存放配置文件，其中 config.default.js 是默认配置文件。
• package.json：项目的 npm 配置文件。
• README.md：项目的说明文档。

配置文件详解

配置文件位于 config 目录下，这些文件定义了应用的运行时配置。

基础配置

config.default.js 文件包含了一些基础配置，例如：

module.exports = appInfo => {
  const config = {};

  // 配置端口号
  config.port = 7001;

  // 配置数据库连接
  config.mysql = {
    client: {
      host: 'localhost',
      port: '3306',
      user: 'root',
      password: 'root',
      database: 'test',
    },
    dialect: 'mysql',
    // 是否自动迁移数据库
    autoMigrate: true,
  };

  return config;
};

环境配置

config.development.js 用于配置开发环境：

module.exports = appInfo => {
  const config = {};

  // 开发环境允许跨域请求
  config.cors = {
    allowMethods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
    allowHeaders: 'Content-Type, Authorization, X-Requested-With',
  };

  return config;
};

中间件与插件

Egg.js 支持丰富的中间件和插件，这些中间件和插件可以方便地进行扩展和定制。

中间件

中间件是处理请求和响应的函数。每个中间件可以访问请求和响应对象，也可以调用下一个中间件处理请求。

const Koa = require('koa');
const app = new Koa();

app.use(async (ctx, next) => {
  console.log(`Processing request ${ctx.request.method} ${ctx.request.url}`);
  await next();
  console.log(`Response sent with status ${ctx.status}`);
});

app.use(async ctx => {
  ctx.body = 'Hello World!';
});

app.listen(7001);

插件

插件是自定义的功能模块，可以方便地扩展 Egg.js 的功能。例如，安装 egg-mysql 插件：

npm install egg-mysql --save

然后在 config.default.js 中配置：

module.exports = appInfo => {
  const config = {};

  config.mysql = {
    client: {
      host: 'localhost',
      port: '3306',
      user: 'root',
      password: 'root',
      database: 'test',
    },
    dialect: 'mysql',
    // 是否自动迁移数据库
    autoMigrate: true,
  };

  return config;
};

创建RESTful API

创建一个新的控制器 app/controller/hello.js：

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

class HelloController extends Controller {
  async index() {
    const { ctx } = this;
    ctx.body = 'Hello World!';
  }
}

module.exports = HelloController;

在 config/router.js 中配置路由：

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

使用Egg.js处理文件上传

在 config/config.default.js 中启用文件上传中间件：

module.exports = appInfo => {
  const config = {};

  config.multipart = {
    whitelist: ['image/*'],
    fileSize: '10mb',
  };

  return config;
};

创建控制器 app/controller/file.js 用于处理文件上传：

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

class FileController extends Controller {
  async upload() {
    const { ctx } = this;
    if (!ctx.request.is('multipart')) {
      ctx.body = {
        code: 500,
        message: 'Not a multipart request.',
      };
      return;
    }

    const file = ctx.request.files[0];

    ctx.body = {
      code: 200,
      message: 'Upload success.',
      data: {
        name: file.name,
        type: file.type,
        size: file.size,
      },
    };
  }
}

module.exports = FileController;

在 config/router.js 中配置路由：

module.exports = app => {
  const { router, controller } = app;
  router.post('/upload', controller.file.upload);
};

使用Egg.js实现简单的权限控制

创建一个中间件 app/middleware/auth.js 用于处理权限验证：

module.exports = ctx => {
  async function authMiddleware(next) {
    const { ctx } = this;
    if (!ctx.session.user) {
      ctx.body = {
        code: 401,
        message: 'Unauthorized.',
      };
      return;
    }
    await next();
  }
  return authMiddleware;
};

在 config/config.default.js 中启用中间件：

module.exports = appInfo => {
  const config = {};

  config.middleware = [
    'auth',
  ];

  return config;
};

创建控制器 app/controller/protected.js 用于保护的 API：

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

class ProtectedController extends Controller {
  async index() {
    const { ctx } = this;
    ctx.body = 'Protected content.';
  }
}

module.exports = ProtectedController;

在 config/router.js 中配置路由：

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

常见错误排查

• 端口被占用：检查是否有其他进程占用了当前端口。例如，可以通过 lsof -i :7001 命令查看端口是否被占用。
• 配置错误：检查配置文件中的配置是否正确。例如，确保 config.default.js 中的数据库配置信息是正确的。
• 依赖安装问题：确保所有依赖都已正确安装。例如，运行 npm install 确保所有依赖都已安装。

调试技巧

• 使用断点调试：在开发工具中设置断点进行调试。例如，可以在 app/controller/hello.js 文件中设置断点进行调试。
• 日志输出：通过输出日志来排查问题。例如，可以在 config/config.default.js 中配置日志输出。
• 单元测试：编写单元测试来确保代码的正确性。例如，可以使用 egg-mock 插件编写单元测试。

日志管理

Egg.js 提供了强大的日志管理功能。可以在 config/config.default.js 中配置日志输出：

module.exports = appInfo => {
  const config = {};

  config.logger = {
    level: 'info',
    app: true,
    env: true,
  };

  return config;
};

Egg.js学习资源推荐

• Egg.js 官方文档：详细的官方文档，包含了从入门到进阶的所有内容。
• 慕课网：提供了丰富的 Egg.js 教程，适合不同水平的学习者。

社区与贡献指南

• Egg.js 社区：加入 Egg.js 社区，与其他开发者交流经验、解决问题。
• 贡献代码：可以通过提交 Issue 或 Pull Request 的方式为 Egg.js 贡献代码。