Egg 框架扩展机制完全指南:Application、Context、Request、Response 与 Helper 五大扩展点实战
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 的扩展机制可以概括为一张清晰的流程:
- 放置文件:在
app/extend/目录下创建application.js、context.js、request.js、response.js或helper.js,导出普通对象; - 合并原型:加载器(见 lib/loader/app_worker_loader.js)按
app > plugin > core优先级,将扩展对象合并进对应内置对象的 prototype; - 生成实例:应用启动时生成基于扩展后 prototype 的
app,处理请求时生成基于扩展后 prototype 的ctx、request、response、helper; - 按环境裁剪:通过
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 "内置约定优于配置、面向扩展设计" 的核心体现。