Egg.js 核心概念

egg-project
├── package.json
├── app.js (可选)
├── agent.js (可选)
├── app
|   ├── router.js
│   ├── controller
│   |   └── home.js
│   ├── service (可选)
│   |   └── user.js
│   ├── middleware (可选)
│   |   └── response_time.js
│   ├── schedule (可选)
│   |   └── my_task.js
│   ├── public (可选)
│   |   └── reset.css
│   ├── view (可选)
│   |   └── home.tpl
│   └── extend (可选)
│       ├── helper.js (可选)
│       ├── request.js (可选)
│       ├── response.js (可选)
│       ├── context.js (可选)
│       ├── application.js (可选)
│       └── agent.js (可选)
├── config
|   ├── plugin.js
|   ├── config.default.js
│   ├── config.prod.js
│   ├── config.test.js (可选)
│   ├── config.local.js (可选)
│   └── config.unittest.js (可选)
└── test
    ├── middleware
    |   └── response_time.test.js
    └── controller
        └── home.test.js

// app.js
module.exports = (app) => {
  // 监听服务启动事件
  app.once("server", (server) => {
    console.log("HTTP server started on port %d", server.address().port)
    // 可以在此处集成 WebSocket 服务
  })

  // 监听错误事件
  app.on("error", (err, ctx) => {
    app.logger.error(err)
    // 可以将错误信息发送到监控系统
  })

  // 监听请求事件
  app.on("request", (ctx) => {
    ctx.logger.info("Request received: %s %s", ctx.method, ctx.url)
  })

  // 监听响应事件
  app.on("response", (ctx) => {
    const used = Date.now() - ctx.starttime
    ctx.logger.info("Response sent: %s %s in %dms", ctx.method, ctx.url, used)
  })
}

// 方式一：在启动脚本中获取
// app.js
module.exports = (app) => {
  app.cache = new Cache()
}

// 方式二：在 Controller 中通过 this.app 获取
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.app.cache.get(this.ctx.query.id)
  }
}

// 方式三：在 Context 中通过 ctx.app 获取
// app/controller/user.js
class UserController extends Controller {
  async fetch() {
    this.ctx.body = this.ctx.app.cache.get(this.ctx.query.id)
  }
}

// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    // 创建匿名 Context
    const ctx = app.createAnonymousContext()
    try {
      await ctx.service.source.sync()
      app.logger.info("[App] 数据源同步成功")
    } catch (e) {
      app.logger.error("[App] 数据源同步失败:", e)
      throw e
    }
  })
}

// 方式一：在中间件中作为参数传入
async function loggerMiddleware(ctx, next) {
  console.log(`Request URL: ${ctx.url}`)
  await next()
}

// 方式二：在 Controller 中通过 this.ctx 获取
class UserController extends Controller {
  async info() {
    const { ctx } = this
    ctx.body = `User ID: ${ctx.params.id}`
  }
}

// 方式三：在 Service 中通过 this.ctx 获取
class UserService extends Service {
  async find(uid) {
    const { ctx, app } = this
    // ...
  }
}

// app/controller/user.js
class UserController extends Controller {
  async profile() {
    const { ctx } = this
    // 获取路由参数 /users/:id
    const userId = ctx.params.id
    // 获取查询参数 /users/123?role=admin
    const role = ctx.query.role
    // 获取请求头
    const userAgent = ctx.header["user-agent"]
    // 获取 POST/PUT 请求体
    const { name, age } = ctx.request.body

    ctx.body = { id: userId, role, name, age, userAgent }
  }
}

// app/controller/home.js
class HomeController extends Controller {
  async index() {
    const { ctx } = this
    ctx.body = "<h1>Hello, Egg.js!</h1>"
    ctx.type = "text/html"
  }

  async create() {
    const { ctx } = this
    ctx.status = 201
    ctx.body = { message: "User created successfully" }
  }

  async oldPath() {
    const { ctx } = this
    ctx.redirect("/new-path", 301)
  }
}

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

class UserController extends Controller {
  async create() {
    const { ctx, service } = this
    // 校验参数
    ctx.validate({
      username: { type: "string" },
      password: { type: "string" }
    })

    // 调用 service 创建用户
    const user = await service.user.create(ctx.request.body)

    // 设置响应
    ctx.status = 201
    ctx.body = { id: user.id }
  }
}

module.exports = UserController

// app/service/user.js
const Service = require("egg").Service

class UserService extends Service {
  async create(payload) {
    const { app } = this
    const result = await app.mysql.insert("users", payload)
    return { id: result.insertId }
  }

  async find(id) {
    const { app, ctx } = this
    const user = await app.mysql.get("users", { id })
    if (!user) {
      ctx.throw(404, "User not found")
    }
    return user
  }
}

module.exports = UserService

// app/middleware/auth.js
module.exports = (options) => {
  return async function auth(ctx, next) {
    const token = ctx.get("Authorization")
    if (token) {
      const user = await ctx.service.user.findByToken(token)
      if (user) {
        ctx.user = user
        await next()
      } else {
        ctx.status = 401
        ctx.body = "Unauthorized"
      }
    } else {
      ctx.status = 401
      ctx.body = "Unauthorized"
    }
  }
}

// config/config.default.js - 应用级中间件
module.exports = {
  middleware: ["errorHandler", "auth"]
}

// app/router.js - 路由级中间件
module.exports = (app) => {
  const { router, controller, middleware } = app
  const auth = middleware.auth()

  router.get("/api/user/profile", auth, controller.user.profile)
}

// app/extend/helper.js
const moment = require("moment")

module.exports = {
  formatTime(time) {
    return moment(time).format("YYYY-MM-DD HH:mm:ss")
  },

  relativeTime(time) {
    return moment(new Date(time * 1000)).fromNow()
  }
}

<!-- app/view/home.tpl -->
<div>{{ helper.formatTime(item.create_time) }}</div>

// config/config.default.js
module.exports = {
  logger: {
    level: "INFO",
    consoleLevel: "INFO",
    dir: "/path/to/your/log/dir"
  }
}

// config/plugin.js
const path = require("path")

module.exports = {
  // 启用 egg-mysql 插件
  mysql: {
    enable: true,
    package: "egg-mysql"
  },

  // 启用本地开发的插件
  myPlugin: {
    enable: true,
    path: path.join(__dirname, "../lib/plugin/my-plugin")
  }
}

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

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

  async subscribe() {
    const { ctx } = this
    try {
      await ctx.service.data.sync()
      ctx.logger.info("[Schedule] 数据同步成功")
    } catch (err) {
      ctx.logger.error("[Schedule] 数据同步失败:", err)
    }
  }
}

module.exports = SyncData

// app/extend/application.js
const RPC_CLIENT = Symbol("Application#rpcClient")

module.exports = {
  get rpcClient() {
    if (!this[RPC_CLIENT]) {
      this[RPC_CLIENT] = { invoke: async (service, method) => ({ ok: true }) }
    }
    return this[RPC_CLIENT]
  }
}

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

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Egg Debug",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "debug"],
      "console": "integratedTerminal",
      "protocol": "auto",
      "port": 9229
    }
  ]
}

# 启动调试模式
$ npm run debug

# 打开 Chrome 浏览器，访问 chrome://inspect

<!-- 在表单中添加 Token -->
<form method="POST" action="/upload">
  <input type="hidden" name="_csrf" value="{{ ctx.csrf }}" />
</form>

// 在 AJAX 中添加 Token
fetch("/api/data", {
  method: "POST",
  headers: {
    "x-csrf-token": csrfToken
  }
})

// config/config.default.js
module.exports = {
  security: {
    xframe: { value: "DENY" },
    hsts: { enable: true, maxAge: 31536000 }
  }
}

// app.js
module.exports = (app) => {
  app.beforeStart(async () => {
    const ctx = app.createAnonymousContext()
    await ctx.service.source.sync()
  })
}

// app.js
module.exports = (app) => {
  app.loader.loadToApp(app.baseDir + "/my-directory", "myModule")
}