Egg 框架扩展机制完全指南:Application、Context、Request、Response 与 Helper 五大扩展点实战

原创2026-09-20 16:37:432,317 阅读
文章标签:后端Web框架

Egg 框架扩展机制完全指南:Application、Context、Request、Response 与 Helper 五大扩展点实战

Egg 是构建在企业级 Node.js 与 Koa 之上的应用框架,其强大之处在于提供了统一、规范化的扩展机制:开发者可以在 app/extend/ 目录下对 Application、Context、Request、Response、Helper 这五类核心对象进行自定义扩展,从而在不侵入框架源码的前提下增强框架能力。本文基于仓库中的官方文档 docs/source/en/basics/extend.md,结合 Egg 的加载器与内置扩展源码,完整讲解每个扩展点的访问方式、扩展写法、属性缓存最佳实践以及按环境选择加载的进阶技巧,读完后你将能独立为自己的 Egg 应用或插件编写高复用、可测试的扩展能力。

一、扩展点总览:五类对象与两种用途

Egg 框架提供了多个扩展点来增强自身功能:

  • Application:全局应用对象,整个应用只有一个;
  • Context:请求上下文,每次请求生成一个实例;
  • Request:请求对象,请求级别,提供大量请求相关属性和方法;
  • Response:响应对象,请求级别,提供大量响应相关属性和方法;
  • Helper:工具函数容器,用于抽离公共逻辑。

在开发中,我们既可以使用框架已内置的扩展 API 来方便开发(例如 ctx.helper.pathFor()、ctx.curl()、ctx.logger),也可以对以上对象进行自定义扩展,进一步加强框架的功能。扩展本质上是把 app/extend/xxx.js 中导出的对象与对应内置对象的 prototype 进行合并,应用或请求处理时基于合并后的 prototype 生成实例。

从加载器源码可以清晰看到这五类扩展的加载顺序。在 lib/loader/app_worker_loader.js 的 load() 方法中:

load() {
  // app > plugin > core
  this.loadApplicationExtend();
  this.loadRequestExtend();
  this.loadResponseExtend();
  this.loadContextExtend();
  this.loadHelperExtend();
  // ...
}

扩展加载被置于整个应用加载流程的最前面,并且遵循 app > plugin > core 的覆盖优先级——即应用自身的扩展优先于插件,插件又优先于框架核心。这意味着应用可以覆写插件或框架提供的扩展方法。

二、Application 扩展:全局对象的增强

2.1 访问方式

app 对象指的是 Koa 的全局应用对象,全局只有一个,在应用启动时被创建。获取 app 对象的途径有三种:

  • 通过 ctx.app 获取;
  • 在 Controller、Middleware、Helper、Service 中通过 this.app 访问,例如 this.app.config 可以访问配置对象;
  • 在 app.js 中,app 对象会作为第一个参数注入到入口函数中:
// app.js
module.exports = app => {
  // 使用 app 对象
};

2.2 扩展方式

框架会把 app/extend/application.js 中定义的对象与 Koa Application 的 prototype 对象进行合并,在应用启动时基于扩展后的 prototype 生成 app 对象。

方法扩展

例如增加一个 app.foo() 方法:

// app/extend/application.js
module.exports = {
  foo(param) {
    // this 就是 app 对象,在其中可以调用 app 上的其他方法,或访问属性
  },
};

属性扩展(Symbol + Getter 模式)

属性的计算一般来说只需要进行一次,因此必须实现缓存,否则多次访问属性时会重复计算,降低应用性能。官方推荐的写法是 Symbol + Getter 模式。

例如增加一个 app.bar 属性 Getter:

// app/extend/application.js
const BAR = Symbol('Application#bar');

module.exports = {
  get bar() {
    // this 就是 app 对象,在其中可以调用 app 上的其他方法,或访问属性
    if (!this[BAR]) {
      // 实际情况肯定更复杂
      this[BAR] = this.config.xx + this.config.yy;
    }
    return this[BAR];
  },
};

为什么用 Symbol?因为 Symbol 是唯一标识,不会与对象上已有的属性名冲突,可以安全地把计算结果的缓存挂在实例自身,同时对外不可枚举、不可见。Getter 保证访问语法与普通属性一致(app.bar),而真正的计算逻辑只在首次访问时执行一次。

这一模式在 Egg 内置扩展中被大量实践。例如 app/extend/context.js 中 ctx.helper、ctx.cookies、ctx.httpclient 的实现:

get cookies() {
  if (!this[COOKIES]) {
    this[COOKIES] = new this.app.ContextCookies(this, this.app.keys, this.app.config.cookies);
  }
  return this[COOKIES];
},

get httpclient() {
  if (!this[CONTEXT_HTTPCLIENT]) {
    this[CONTEXT_HTTPCLIENT] = new this.app.ContextHttpClient(this);
  }
  return this[CONTEXT_HTTPCLIENT];
},

每个 Symbol 常量(如 Symbol('Context#cookies'))对应一个缓存槽位,首次访问时创建实例并缓存,后续访问直接返回,保证单次请求内实例唯一且无重复构造开销。

三、Context 扩展:请求上下文的增强

3.1 访问方式

Context 指的是 Koa 的请求上下文,是 请求级别 的对象——每次请求生成一个 Context 实例,通常简写为 ctx。在不同代码位置,获取 ctx 的方式不同:

  • middleware 中:this 就是 ctx,例如 this.cookies.get('foo');
  • controller 中:有两种写法,类写法通过 this.ctx 访问,方法写法直接通过 ctx 入参访问;
  • helper、service 中:this 指向 helper 或 service 对象本身,通过 this.ctx 访问 context 对象,例如 this.ctx.cookies.get('foo')。

3.2 扩展方式

框架会把 app/extend/context.js 中定义的对象与 Koa Context 的 prototype 对象进行合并,在处理请求时基于扩展后的 prototype 生成 ctx 对象。

方法扩展

例如增加一个 ctx.foo() 方法:

// app/extend/context.js
module.exports = {
  foo(param) {
    // this 就是 ctx 对象,在其中可以调用 ctx 上的其他方法,或访问属性
  },
};

属性扩展

属性的计算在同一次请求中只需要进行一次,一定要实现缓存,否则在同一次请求中多次访问时会重复计算,降低应用性能。同样推荐 Symbol + Getter 模式。

例如增加一个 ctx.bar 属性 Getter,从请求头中读取值:

// app/extend/context.js
const BAR = Symbol('Context#bar');

module.exports = {
  get bar() {
    // this 就是 ctx 对象,在其中可以调用 ctx 上的其他方法,或访问属性
    if (!this[BAR]) {
      // 例如,从 header 中获取,实际情况肯定更复杂
      this[BAR] = this.get('x-bar');
    }
    return this[BAR];
  },
};

Egg 内置的 Context 扩展非常丰富,除了上面提到的 cookies、httpclient、helper 之外,app/extend/context.js 还提供了:

  • ctx.logger / ctx.coreLogger / ctx.getLogger(name):带请求上下文的日志对象,错误日志会附带请求信息;
  • ctx.locals / ctx.state:模板渲染数据,ctx.locals 会合并 app.locals 且单次请求内只合并一次;
  • ctx.curl(url, options):快捷发起 HTTP 请求,等价于 this.httpclient.curl(...);
  • ctx.runInBackground(scope):在请求结束后继续运行后台任务(如写库、发通知),框架负责捕获异常并记录日志;
  • ctx.router:别名到 app.router,可配合 this.router.pathFor('post', { id: 12 }) 使用。

这些内置扩展本身就是学习自定义扩展的最佳范本。此外,app/extend/context.js 还通过 delegate 将 request 上的 acceptJSON、queries、accept、ip 以及 response 上的 realStatus 代理到了 ctx 上,实现了 ctx.ip 与 ctx.request.ip 等价的访问体验。

四、Request 扩展:请求对象的增强

4.1 访问方式

Request 对象与 Koa 的 Request 对象相同,是 请求级别 的对象,通过 ctx.request 访问:

ctx.request

ctx 上的很多属性和方法都被代理到了 request 对象上,对这些属性和方法,用 ctx 和用 request 访问是等价的,例如 ctx.url === ctx.request.url。Koa 内置代理 request 的完整属性和方法列表见官方文档的 "Request aliases" 一节。

4.2 扩展方式

框架会把 app/extend/request.js 中定义的对象与内置 request 的 prototype 对象进行合并,在处理请求时基于扩展后的 prototype 生成 request 对象。

例如增加一个 request.foo 属性 Getter,读取自定义请求头:

// app/extend/request.js
module.exports = {
  get foo() {
    return this.get('x-request-foo');
  },
};

值得注意的是,Egg 内置的 Request 扩展大量使用 Symbol 缓存来提升性能。app/extend/request.js 中 host、protocol、ips、ip 等属性的实现,正是"Symbol 缓存 + 首次计算"的教科书式写法:

get host() {
  if (this[HOST]) return this[HOST];
  // ...根据 proxy 配置和 header 计算 host...
  this[HOST] = host.split(/\s*,\s*/)[0];
  return this[HOST];
},

它还会根据 app.config.proxy 以及 hostHeaders、protocolHeaders、ipHeaders、maxIpsCount 等配置决定是否信任反向代理传来的 X-Forwarded-* 头,为自定义扩展提供了"如何安全读取请求头"的参考实现。此外内置的 query / queries 解析、acceptJSON 检测等方法都定义在 app/extend/request.js 中,可在自定义扩展里直接复用。

五、Response 扩展:响应对象的增强

5.1 访问方式

Response 对象与 Koa 的 Response 对象相同,是 请求级别 的对象,通过 ctx.response 访问:

ctx.response

ctx 上的很多属性和方法都被代理到了 response 对象上,对这些属性和方法,用 ctx 和用 response 访问是等价的,例如 ctx.status = 404 和 ctx.response.status = 404 等价。Koa 内置代理 response 的完整属性和方法列表见官方文档的 "Response aliases" 一节。

5.2 扩展方式

框架会把 app/extend/response.js 中定义的对象与内置 response 的 prototype 对象进行合并,在处理请求时基于扩展后的 prototype 生成 response 对象。

例如增加一个 response.foo 属性 setter,向响应头写入自定义值:

// app/extend/response.js
module.exports = {
  set foo(value) {
    this.set('x-response-foo', value);
  },
};

然后就可以这样使用:

this.response.foo = 'bar';

Egg 内置的 Response 扩展同样值得借鉴。app/extend/response.js 对 Koa 的 length、type 做了复写增强:type 的 MIME 类型转换引入了局部 LRU 缓存(new LRU(100))以提升高频转换性能;同时新增了 realStatus 属性——当业务用 302 重定向到全局错误页时,通过 ctx.realStatus = 500 记录真实状态码,保证访问日志能记录到真实的 500 而非 302。相关的行为在 test/app/extend/context.test.js 中有专门用例验证。

六、Helper 扩展:工具函数的容器

6.1 Helper 的价值

Helper 用来提供一些实用的 utility 函数。它的作用在于:

  • 将常用动作抽离到 helper.js 中成为独立函数,用 JavaScript 编写复杂逻辑,避免逻辑分散各处;
  • Helper 作为简单函数,更容易编写测试用例。

框架内置了一些常用的 Helper 函数(如 pathFor、urlFor、escape 等),我们也可以编写自定义 Helper。

6.2 访问方式

通过 ctx.helper 访问 helper 对象。例如利用内置的 pathFor 计算路由路径:

// 假设在 app/router.js 中定义了 home router
app.get('home', '/', 'home.index');

// 使用 helper 计算指定 url path
ctx.helper.pathFor('home', { by: 'recent', limit: 20 })
// => /?by=recent&limit=20

从源码看,内置 Helper 定义在 app/extend/helper.js,其中:

  • pathFor(name, params):内部调用 this.app.router.url(name, params),生成不带 host 的路径;
  • urlFor(name, params):基于 ctx.protocol 和 ctx.host 生成带 host 的完整 URL,例如 http://127.0.0.1:7001/index.htm?by=recent&limit=20。

6.3 扩展方式

框架会把 app/extend/helper.js 中定义的对象与内置 helper 的 prototype 对象进行合并,在处理请求时基于扩展后的 prototype 生成 helper 对象。

例如增加一个 helper.foo() 方法:

// app/extend/helper.js
module.exports = {
  foo(param) {
    // this 是 helper 对象,在其中可以调用其他 helper 方法
    // this.ctx => context 对象
    // this.app => application 对象
  },
};

在 Helper 内部,this 指向 helper 对象本身,且可以通过 this.ctx、this.app 访问上下文和全局应用对象,因此可以编写依赖请求数据或应用配置的工具函数。测试用例可参考 test/app/extend/helper.test.js,其中对内置 pathFor、urlFor、escape、shtml 等 Helper 均有覆盖验证。

七、按环境选择扩展:unittest 专属能力

除了常规扩展,还可以根据环境进行有选择的扩展。例如,只想在 unittest 环境中提供 mockXX() 方法以便 mock 方便测试:

// app/extend/application.unittest.js
module.exports = {
  mockXX(k, v) {
  }
};

这个文件只会在 unittest 环境下被加载。同理,对于 Application、Context、Request、Response、Helper 都可以使用这种"文件名带环境后缀"的方式针对某个环境进行扩展。

Egg 通过 EGG_SERVER_ENV 区分运行环境(详见 运行环境文档),常见的环境值与 NODE_ENV 的默认映射关系如下:

NODE_ENV EGG_SERVER_ENV 说明
(未设置) local 本地开发环境
test unittest 单元测试环境
production prod 生产环境

例如 NODE_ENV=production 且未指定 EGG_SERVER_ENV 时,EGG_SERVER_ENV 会被推断为 prod。你可以通过 app.config.env 获取当前环境值,也可以使用 config/config.{env}.js 加载不同环境下的差异化配置。因此,app/extend/application.unittest.js 这类文件只在 EGG_SERVER_ENV 为 unittest(通常由 NODE_ENV=test 触发)时被加载,是编写测试专属扩展、避免污染线上运行时的标准手段。

八、扩展机制总结与最佳实践

Egg 的扩展机制可以概括为一张清晰的流程:

  1. 放置文件:在 app/extend/ 目录下创建 application.js、context.js、request.js、response.js 或 helper.js,导出普通对象;
  2. 合并原型:加载器(见 lib/loader/app_worker_loader.js)按 app > plugin > core 优先级,将扩展对象合并进对应内置对象的 prototype;
  3. 生成实例:应用启动时生成基于扩展后 prototype 的 app,处理请求时生成基于扩展后 prototype 的 ctx、request、response、helper;
  4. 按环境裁剪:通过 application.unittest.js 这类文件名后缀,让扩展只在指定环境生效。

实践中的几条关键建议:

  • 方法扩展:直接导出函数,this 指向被扩展对象本身,可自由访问其属性和其他方法;
  • 属性扩展:务必采用 Symbol + Getter 做缓存,避免重复计算拖慢性能——这是 Egg 官方明确推荐、内置扩展普遍使用的模式(可对照 app/extend/request.js、app/extend/context.js 源码印证);
  • 注意对象生命周期:app 是全局单例,ctx、request、response、helper 是请求级别对象,在属性缓存时无需担心跨请求共享脏数据,但也不要把请求级数据挂到 app 上;
  • 善用内置 API:自定义扩展之前,先确认 Egg 是否已提供对应能力(如 ctx.curl、ctx.logger、ctx.runInBackground、ctx.helper.pathFor),避免重复造轮子;
  • 可测试性:Helper 这类纯函数化的扩展天然易测,配合 app.mockContext() 也可以对 Context 扩展编写单元测试(参考 test/app/extend/context.test.js 与 test/app/extend/helper.test.js)。

掌握这五大扩展点,你既可以在应用层复用它们快速开发业务能力,也可以在编写插件或二次封装框架时,通过扩展机制为上层应用提供统一、规范的 API——这正是 Egg "内置约定优于配置、面向扩展设计" 的核心体现。

登录后查看全文
egg