Egg.js 深度解析与实战

┌─────────────────────────────────────────────────────────────┐
│                        应用层 (Application)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Controller │  │   Service   │  │  Middleware │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │    Router   │  │   Extend    │  │   Schedule  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
├─────────────────────────────────────────────────────────────┤
│                        框架层 (Framework)                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Loader    │  │   Router    │  │    Logger   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Config    │  │   Context   │  │  Security   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
├─────────────────────────────────────────────────────────────┤
│                        插件层 (Plugin)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ egg-mysql   │  │ egg-redis   │  │egg-security │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
├─────────────────────────────────────────────────────────────┤
│                      Koa 层 (Koa.js)                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              中间件洋葱模型 (Onion Model)             │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                      Node.js 运行时                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   HTTP(S)   │  │    Cluster  │  │    Event    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      Master 进程                             │
│              (进程管理、端口监听、负载均衡)                    │
└──────────────┬──────────────────────────────────────────────┘
               │
       ┌───────┼───────┬───────┬───────┐
       │       │       │       │       │
       ▼       ▼       ▼       ▼       ▼
    ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
    │Agent│ │Worker│ │Worker│ │Worker│ │Worker│
    │进程 │ │  1  │ │  2  │ │  3  │ │  N  │
    └─────┘ └─────┘ └─────┘ └─────┘ └─────┘
       │       │       │       │       │
       │       │       │       │       │
    后台任务  处理    处理    处理    处理
    定时任务  请求    请求    请求    请求

// app.js - Worker 向 Agent 发送消息
module.exports = (app) => {
  app.messenger.on("agent-event", (data) => {
    app.logger.info("[Worker] received from agent:", data)
  })

  // 向 Agent 发送消息
  app.messenger.sendToAgent("worker-event", { from: "worker" })
}

// agent.js - Agent 处理消息
module.exports = (agent) => {
  agent.messenger.on("worker-event", (data) => {
    agent.logger.info("[Agent] received from worker:", data)
    // 广播给所有 Worker
    agent.messenger.sendToApp("agent-event", { from: "agent" })
  })
}

node -v

# 创建项目目录
mkdir egg-example && cd egg-example

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

# 安装依赖
npm install

# 设置环境变量
export EGG_SERVER_ENV=prod  # 生产环境
export EGG_SERVER_ENV=local # 本地开发环境
export EGG_SERVER_ENV=unittest # 单元测试环境

// app/middleware/auth.js
module.exports = (options) => {
  return async function auth(ctx, next) {
    if (!ctx.state.user) {
      ctx.status = 401
      ctx.body = "Unauthorized"
      return
    }
    await next()
  }
}

// config/config.default.js
module.exports = {
  middleware: ["auth", "errorHandler"], // 按顺序执行
  auth: {
    match: "/api/*", // 只匹配 /api 开头的路径
    ignore: "/api/public/*" // 排除某些路径
  }
}

// app/router.js
module.exports = (app) => {
  const { router, controller, middleware } = app
  const auth = middleware.auth({ required: true })
  
  // 单个路由使用中间件
  router.get("/api/user/profile", auth, controller.user.profile)
  
  // 多个中间件串联
  router.post("/api/posts", auth, middleware.validate(), controller.post.create)
}

// app/router.js
module.exports = (app) => {
  const { router, controller } = app
  
  // 基础路由
  router.get("/", controller.home.index)
  router.post("/users", controller.user.create)
  router.put("/users/:id", controller.user.update)
  router.delete("/users/:id", controller.user.destroy)
  
  // 使用中间件
  router.get("/api/posts", app.middleware.auth(), controller.post.list)
}

// app/router.js
module.exports = (app) => {
  const { router, controller } = app
  
  // 自动生成 CRUD 路由
  // GET    /posts     -> controller.post.index
  // GET    /posts/:id -> controller.post.show
  // POST   /posts     -> controller.post.create
  // PUT    /posts/:id -> controller.post.update
  // DELETE /posts/:id -> controller.post.destroy
  router.resources("posts", "/api/posts", controller.post)
}

// app/router.js
module.exports = (app) => {
  const { router, controller } = app
  
  // 创建路由分组
  const apiRouter = router.namespace("/api/v1")
  
  apiRouter.get("/users", controller.user.list)
  apiRouter.post("/users", controller.user.create)
  // 实际路径: /api/v1/users
}

// app/controller/post.js
const { Controller } = require("egg")

class PostController extends Controller {
  async list() {
    const posts = await this.ctx.service.post.findAll()
    this.ctx.body = posts
  }
}

module.exports = PostController

// app/service/post.js
const { Service } = require("egg")

class PostService extends Service {
  async findAll() {
    // 假设从数据库获取数据
    return [{ id: 1, title: "Hello Egg.js" }]
  }
}

module.exports = PostService

// config/plugin.js
exports.mysql = {
  enable: true,
  package: "egg-mysql"
}

// config/config.default.js
module.exports = (appInfo) => {
  const config = {}
  config.keys = appInfo.name + "_1678886400000_1234"
  config.mysql = {
    client: {
      host: "127.0.0.1",
      port: 3306,
      user: "root",
      password: "password",
      database: "test"
    }
  }
  return config
}

// app/schedule/sync_data.js
const { Subscription } = require("egg")

class SyncData extends Subscription {
  static get schedule() {
    return {
      interval: "1h", // 每小时执行一次
      type: "worker" // 只在一个 worker 进程上执行
    }
  }

  async subscribe() {
    // 执行同步任务
    await this.ctx.service.data.sync()
  }
}

module.exports = SyncData

// app/extend/context.js
module.exports = {
  get isAjax() {
    return this.get("X-Requested-With") === "XMLHttpRequest"
  }
}

CREATE TABLE `posts` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(255) NOT NULL,
  `content` text,
  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

npm install egg-validate --save

// config/plugin.js
exports.validate = {
  enable: true,
  package: "egg-validate"
}

// app/controller/user.js
const { Controller } = require("egg")

class UserController extends Controller {
  async create() {
    const { ctx } = this
    
    // 定义校验规则
    const createRule = {
      username: { type: "string", required: true, min: 3, max: 20 },
      password: { type: "password", required: true, min: 6, max: 20 },
      email: { type: "email", required: true },
      age: { type: "int", required: false, min: 0, max: 150 }
    }
    
    // 校验参数
    ctx.validate(createRule, ctx.request.body)
    
    // 校验通过后继续处理
    const user = await ctx.service.user.create(ctx.request.body)
    ctx.status = 201
    ctx.body = user
  }
}

module.exports = UserController

// app/middleware/errorHandler.js
module.exports = (options, app) => {
  return async function errorHandler(ctx, next) {
    try {
      await next()
    } catch (err) {
      // 记录错误日志
      ctx.logger.error(err)
      
      // 所有异常都会触发 app 的 error 事件
      const status = err.status || 500
      const error = status === 500 ? "Internal Server Error" : err.message
      
      ctx.body = {
        code: status,
        message: error,
        data: null,
        timestamp: Date.now()
      }
      
      // 参数校验错误
      if (status === 422) {
        ctx.body.detail = err.errors
      }
      
      ctx.status = status
    }
  }
}

// app/extend/error.js
class BusinessException extends Error {
  constructor(message, code = 400) {
    super(message)
    this.name = "BusinessException"
    this.code = code
  }
}

module.exports = { BusinessException }

// 使用示例
// app/service/user.js
const { Service } = require("egg")
const { BusinessException } = require("../extend/error")

class UserService extends Service {
  async login(username, password) {
    const user = await this.app.mysql.get("users", { username })
    if (!user) {
      throw new BusinessException("用户不存在", 404)
    }
    // ...
  }
}

test
├── app
│   ├── controller
│   │   └── user.test.js
│   ├── service
│   │   └── user.test.js
│   └── middleware
│       └── auth.test.js
└── fixtures
    └── test-data.js

// test/app/controller/user.test.js
const { app, mock, assert } = require("egg-mock/bootstrap")

describe("test/app/controller/user.test.js", () => {
  before(async () => {
    // 初始化测试数据
  })

  after(async () => {
    // 清理测试数据
  })

  afterEach(mock.restore)

  it("should GET /api/users/:id", async () => {
    const res = await app
      .httpRequest()
      .get("/api/users/1")
      .set("Accept", "application/json")
      .expect(200)

    assert(res.body.id === 1)
  })

  it("should POST /api/users", async () => {
    const res = await app
      .httpRequest()
      .post("/api/users")
      .send({ username: "test", password: "123456" })
      .set("Accept", "application/json")
      .expect(201)

    assert(res.body.id !== undefined)
  })
})

// test/app/service/user.test.js
const { app, mock, assert } = require("egg-mock/bootstrap")

describe("test/app/service/user.test.js", () => {
  let ctx

  beforeEach(() => {
    ctx = app.mockContext()
  })

  it("should find user by id", async () => {
    const user = await ctx.service.user.find(1)
    assert(user !== null)
  })

  it("should create user", async () => {
    const result = await ctx.service.user.create({
      username: "testuser",
      password: "123456"
    })
    assert(result.insertId > 0)
  })
})

# 运行所有测试
npm test

# 运行测试覆盖率
npm run cov

# 运行特定测试文件
npm test test/app/controller/user.test.js

// app/service/post.js
const { Service } = require("egg")

class PostService extends Service {
  async getPost(id) {
    const redisKey = `post:${id}`
    // 1. 尝试从 Redis 获取缓存
    let post = await this.app.redis.get(redisKey)
    if (post) {
      return JSON.parse(post)
    }
    // 2. 缓存未命中，从数据库获取
    post = await this.app.mysql.get("posts", { id })
    if (post) {
      // 3. 存入 Redis，并设置 1 小时过期时间
      await this.app.redis.set(redisKey, JSON.stringify(post), "EX", 3600)
    }
    return post
  }
}

module.exports = PostService

// app/controller/home.js
const { Controller } = require("egg")

class HomeController extends Controller {
  async index() {
    const { ctx, service } = this
    // 并行获取用户数据和文章列表
    const [user, posts] = await Promise.all([
      service.user.getProfile(),
      service.post.getPostList()
    ])
    ctx.body = { user, posts }
  }
}

module.exports = HomeController

// config/config.default.js
config.security = {
  // Content Security Policy
  csp: {
    enable: true,
    policy: {
      'script-src': [
        ''self'', // 只允许同源脚本
        'https://cdn.bootcdn.net', // 允许来自 CDN 的脚本
      ],
    },
  },
  // X-Frame-Options
  xframe: {
    value: 'SAMEORIGIN', // 只允许同源页面嵌入
  },
};