Egg 框架扩展机制全解析:Application、Context、Request、Response 与 Helper 五大扩展点实战指南
Egg 框架扩展机制全解析:Application、Context、Request、Response 与 Helper 五大扩展点实战指南
导读
本文系统讲解 Egg.js 框架的五大扩展点——Application、Context、Request、Response 与 Helper,说明如何通过 app/extend/ 目录下的约定文件为这些核心对象注入自定义方法与属性,并结合本仓库 @eggjs/core 的加载器源码剖析扩展文件在应用启动时是如何被收集、合并到对应原型上的。读完本文,你将掌握 Egg 扩展文件的标准写法、Symbol + Getter 的属性缓存技巧,以及按运行环境(如 unittest)条件加载扩展的高级用法,能够独立为业务框架封装可复用的能力。
为什么要理解 Egg 的扩展机制
Egg.js 基于 Koa 构建,但它并不是把 Koa 的能力"封死"在框架内部,而是开放出多个扩展点,让开发者在不改动框架源码的前提下增强框架本身的能力。扩展的对象包括:
- Application(应用级,全局唯一)
- Context(请求级上下文)
- Request(请求级)
- Response(请求级)
- Helper(工具函数容器)
这些扩展点覆盖了应用生命周期中的不同作用域:app 全局只有一个,适合挂载全局连接、单例工具等;ctx 每个请求都会新生成一个实例,适合存放与当前请求相关的数据。合理利用这些扩展点,可以显著减少重复代码,让 Controller、Middleware、Service 之间的能力共享变得自然。
注:本仓库中该文档对应的正是 site/docs/basics/extend.md,下面所有代码示例与该文档保持完全一致,并结合源码补充实现细节。
Application 扩展
对象定位与访问方式
app 对象与 Koa 中的全局 Application 对象是同一层面的概念。整个应用只有一个 app 实例,由 Egg 在应用启动时创建。访问方式有三种:
- 通过
ctx.app访问; - 在 Controller、Middleware、Helper、Service 中通过
this.app访问,例如this.app.config即可读取配置对象; - 在
app.js入口函数中,app对象会作为第一个参数被注入:
// app.js
module.exports = (app) => {
// here you can use the app object
};
扩展原理:合并到 Application 原型
Egg 会将 app/extend/application.js 中定义的对象与 Koa 的 Application 原型合并,应用启动时基于扩展后的原型生成 app 对象。
从源码看,加载器在启动流程中显式调用了一系列"扩展加载"入口(packages/core/src/loader/egg_loader.ts):
await this.loadExtend('application', this.app); // 合并进 app
await this.loadExtend('request', this.app.request);
await this.loadExtend('response', this.app.response);
await this.loadExtend('context', this.app.context);
await this.loadExtend('helper', this.app.Helper.prototype);
而 loadExtend 的核心逻辑(packages/core/src/loader/egg_loader.ts)做了这样几件事:
- 通过
getExtendFilePaths(name)收集所有加载单元(应用、插件、框架)下的app/extend/{name}文件路径; - 对每个文件路径追加环境后缀(如
.prod、.unittest)作为可选扩展文件(详见下文"按环境扩展"); - 加载文件后,用
Object.getOwnPropertyNames(ext).concat(Object.getOwnPropertySymbols(ext))取出所有字符串键与 Symbol 键; - 用
Object.defineProperty将每个属性的完整描述符(含 getter/setter)拷贝到目标原型上,这意味着方法、getter、setter 都被完整保留,而不是简单地赋值。
值得注意的细节:扩展对象如果是 Class,加载器会自动使用其 prototype(if (isClass(ext)) ext = ext.prototype;),也就是说你也可以用类的方式组织扩展代码。另外,加载器保留了原有描述符的 get/set,避免扩展覆盖时丢失存取器语义。
扩展方法
如果想要一个 app.foo() 方法,只需在 app/extend/application.js 中导出:
// app/extend/application.js
module.exports = {
foo(param) {
// `this` 指向 app 对象,可以通过 this 访问 app 的其他方法或属性
},
};
这里 this 指向 app 实例本身,因此你可以在扩展方法内部自由调用 this.config、this.logger、this.messenger 等既有能力。
扩展属性(推荐 Symbol + Getter)
属性的计算通常只需要做一次,如果每次访问都重新计算,会随着访问次数增加而拖累应用性能。因此官方推荐使用 Symbol + Getter 的组合来做缓存。
例如,为 app 增加一个 Getter 属性 app.bar:
// app/extend/application.js
const BAR = Symbol('Application#bar');
module.exports = {
get bar() {
// `this` 指向 app 对象
if (!this[BAR]) {
// 真实场景中这里的计算可能更复杂
this[BAR] = this.config.xx + this.config.yy;
}
return this[BAR];
},
};
用 Symbol 作为私有缓存键可以避免属性名冲突(Symbol 天然唯一),同时不会污染对象的普通键名;Getter 则保证第一次访问时才计算,后续访问直接命中缓存。这与加载器"拷贝完整描述符"的实现正好配合——getter 语义在合并过程中被完整保留。
仓库的测试用例对 Symbol 键的扩展做了专门覆盖(如 packages/core/test/fixtures/extend-symbol/package.json 与 packages/core/test/loader/mixin/load_application_extend.test.ts),验证了 Symbol 属性同样能被正确合并到原型上。
Context 扩展
对象定位与访问方式
Context 是 Koa 中的上下文对象,属于请求级对象:客户端发来的每一个请求都会生成一个 Context 实例,通常简写为 ctx。在文档中,Context 与 ctx 指的都是 Koa 中的同一个上下文对象。
访问 ctx 的方式因所在位置而异:
- 在 Middleware 中,
this就是ctx,例如this.cookies.get('foo'); - 在 Controller 中分两种写法:使用 class 方式时通过
this.ctx访问;使用方法(函数)方式时直接使用入参ctx; - 在 Helper、Service 中,
this指向各自的对象,通过this.ctx访问 Context,例如this.ctx.cookies.get('foo')。
扩展方法与属性
Egg 会把 app/extend/context.js 中定义的对象与 Koa 的 Context 原型合并,在处理请求时基于扩展后的原型生成 ctx 对象。对应源码入口为 loadContextExtend(),合并进 this.app.context(见 packages/core/src/loader/egg_loader.ts)。
添加方法 ctx.foo():
// app/extend/context.js
module.exports = {
foo(param) {
// `this` 指向 ctx 对象,可以访问 ctx 的其他方法或属性
},
};
添加 Getter 属性 ctx.bar(同样是 Symbol + Getter 缓存模式):
// app/extend/context.js
const BAR = Symbol('Context#bar');
module.exports = {
get bar() {
// `this` 指向 ctx 对象
if (!this[BAR]) {
// 例如从请求头取值,真实场景中逻辑可能更复杂
this[BAR] = this.get('x-bar');
}
return this[BAR];
},
};
由于 ctx 是请求级对象,这里特别适合做"基于当前请求的惰性计算"——比如解析某个请求头、从 token 中解码用户信息并缓存到 Symbol 键上,后续在同一请求内多次访问都不会重复计算。
Request 扩展
对象定位与访问方式
Request 对象与 Koa 中的 Request 一致,是请求级对象,提供了大量方法帮助读取请求的属性。通过 ctx.request 访问:
ctx.request;
ctx 中很多属性和方法同样可以直接在 request 对象上访问,二者是等价的,例如 ctx.url === ctx.request.url。这些可通过 Request 别名访问的完整清单见 Koa 官方文档的 Request aliases 一节。
如何扩展
Egg 会把 app/extend/request.js 中定义的对象与框架内置的 request 原型合并(对应 loadRequestExtend(),合并进 this.app.request,见 packages/core/src/loader/egg_loader.ts),处理请求时生成基于扩展原型的 request 对象。
例如,为 request 增加一个读取自定义请求头 x-request-foo 的属性:
// app/extend/request.js
module.exports = {
get foo() {
return this.get('x-request-foo');
},
};
注意这里 this.get(...) 是 Koa Request 内置的取请求头方法,扩展代码里可以直接复用对象自身的既有能力。
Response 扩展
对象定位与访问方式
Response 对象与 Koa 中的 Response 一致,同样是请求级对象,通过 ctx.response 访问:
ctx.response;
与 Request 类似,ctx 中很多属性和方法也可以通过 Response 别名直接访问,例如 ctx.status = 404 与 ctx.response.status = 404 完全等价。
如何扩展
Egg 会把 app/extend/response.js 中定义的对象与框架内置的 response 原型合并(对应 loadResponseExtend(),见 packages/core/src/loader/egg_loader.ts)。
例如,为 response 增加一个 setter,把值写入响应头 x-response-foo:
// app/extend/response.js
module.exports = {
set foo(value) {
this.set('x-response-foo', value);
},
};
之后即可这样使用:this.response.foo = 'bar';。这也是加载器保留原始描述符中 set 语义的意义所在——扩展的 setter 会与原型上已有的 getter(如果有)正确共存。
Helper 扩展
Helper 的定位
Helper 提供一些有用的工具函数。把经常复用的函数写成独立函数放进 helper.js,可以将复杂逻辑集中在一处编写,避免散落在各处重复粘贴;同时,如此简单的函数也让编写测试用例变得更容易。
Egg 本身已经内置了一些 Helper 函数,开发者也可以编写自己的 Helper。框架内置的 Helper 类源码位于 packages/egg/src/app/extend/helper.ts,其中内置了 pathFor 与 urlFor 两个典型方法:
pathFor(name, params):根据路由名生成不带 host 的路径,内部调用this.app.router.url(name, params);urlFor(name, params):生成带 host 的完整 URL,内部基于ctx.protocol、ctx.host与pathFor拼接。
访问方式
通过 ctx.helper 访问 Helper 对象,例如:
// 假设 home 路由已在 app/router.js 中定义
app.get('home', '/', 'home.index');
// 用 helper 计算具体的 url 路径
ctx.helper.pathFor('home', { by: 'recent', limit: 20 });
// => /?by=recent&limit=20
如何扩展
Egg 会把 app/extend/helper.js 中定义的对象与框架内置的 helper 原型合并(对应 loadHelperExtend(),合并进 this.app.Helper.prototype,见 packages/core/src/loader/egg_loader.ts)。
例如,为 helper 增加一个方法 helper.foo():
// app/extend/helper.js
module.exports = {
foo(param) {
// `this` 指向 helper 对象,可以访问 helper 的其他方法或属性
// this.ctx => context 对象
// this.app => application 对象
},
};
由于 Helper 继承自 BaseContextClass,扩展方法内可以非常方便地通过 this.ctx、this.app 访问上下文与应用级能力,这也是官方建议把跨层复用的工具函数收拢到 Helper 的原因之一。
按运行环境扩展
除了常规的扩展文件,还可以按运行环境做可选扩展。例如,只想让 mockXX() 在单元测试(unittest)环境下可用:
// app/extend/application.unittest.js
module.exports = {
mockXX(k, v) {},
};
这个文件只会在 unittest 环境下被加载。同一规则适用于 Application、Context、Request、Response、Helper 等其他对象的扩展文件,对应环境约定见 site/docs/basics/env.md。
从源码可以确认这一机制的实际实现:loadExtend 在收集到基础文件路径后,会追加 .${serverEnv} 后缀路径(packages/core/src/loader/egg_loader.ts):
const filepaths = this.getExtendFilePaths(name);
const needUnittest = 'EGG_MOCK_SERVER_ENV' in process.env && this.serverEnv !== 'unittest';
for (const filepath of filepaths) {
filepaths.push(filepath + `.${this.serverEnv}`);
if (needUnittest) {
filepaths.push(filepath + '.unittest');
}
}
也就是说,当 serverEnv 为 prod 时,app/extend/application.prod.js 会被额外加载;而通过 mm.env() 模拟环境且当前 serverEnv 不是 unittest 时,.unittest 后缀文件也会被加载,从而让测试专用扩展在测试环境中自动生效。
关于 serverEnv 的取值:它由 config/env 文件、环境变量 EGG_SERVER_ENV 或 NODE_ENV 推导而来(见 packages/core/src/loader/egg_loader.ts)。默认映射关系如下:
| NODE_ENV | EGG_SERVER_ENV | 说明 |
|---|---|---|
| (未设置) | local | 本地开发环境 |
| test | unittest | 单元测试环境 |
| production | prod | 生产环境 |
因此,app/extend/xxx.prod.js 在生产环境生效、app/extend/xxx.unittest.js 在测试环境生效,其余环境同理,完全可以自定义如 sit 等环境名。
多个加载单元之间的合并顺序
Egg 的扩展文件并不只来自应用自身,插件与框架同样可以携带 app/extend/{name}.js。getExtendFilePaths 会遍历所有"加载单元"(应用、插件、框架),将它们各自的扩展文件路径全部收集起来,再依次合并到目标原型上(packages/core/src/loader/egg_loader.ts):
protected getExtendFilePaths(name: string): string[] {
return this.getLoadUnits().map((unit) => path.join(unit.path, 'app/extend', name));
}
从源码结构看,后加载的单元若定义了同名属性,会覆盖先加载的同名属性(加载器会通过 mergeRecord 记录并输出 debug 日志)。这意味着插件的扩展可以作为基础能力,应用层可以按需覆盖同名扩展,实现"插件提供默认实现、应用自定义覆写"的协作模式。仓库中还提供了"扩展对象为 Class"的测试夹具(如 packages/core/test/fixtures/extend-with-class/app/extend/application.js 与 packages/core/test/loader/mixin/load_extend_class.test.ts),印证了类写法同样受支持。
实战建议与最佳实践
综合文档与源码实现,在 Egg 应用中使用扩展机制时有几点建议:
- 方法用普通函数,属性用 Symbol + Getter 缓存。方法不需要缓存;而属性若每次访问都重算,性能会随访问频率下降,Symbol + Getter 是官方推荐的标准姿势。
- 按作用域选择扩展点。全局唯一的能力(数据库连接、配置封装、第三方客户端单例)放
application;与单个请求相关的能力(用户态解析、请求头加工)放context、request;响应相关的加工(统一响应头、序列化)放response;跨层复用的纯工具函数放helper。 - 善用环境后缀文件。把仅测试环境需要的 mock 能力放进
app/extend/application.unittest.js,生产包中不会误加载;同理可用.prod.js注入生产专属能力。 - 注意合并顺序与覆盖。插件、框架、应用的扩展会依次合并,应用层的同名扩展可以覆盖下层默认实现,但应避免无意的覆盖,保持扩展属性命名唯一(Symbol 键是避免冲突的天然手段)。
总结
Egg 的扩展机制是"约定优于配置"的典型体现:只需在 app/extend/ 下按 application.js、context.js、request.js、response.js、helper.js 的约定命名,框架的加载器就会在启动时自动完成原型合并(对应源码 packages/core/src/loader/egg_loader.ts)。结合环境后缀文件,还能实现按 unittest、prod 等环境条件加载。掌握这五个扩展点,你就能以极低的学习成本,为基于 Egg 的业务框架沉淀一套稳定、可测试、可覆盖的自有能力层。