Egg 渐进式开发实战:从应用扩展代码到插件再到框架的演进之路
Egg 渐进式开发实战:从应用扩展代码到插件再到框架的演进之路
导读
Egg 为开发者提供了**插件(Plugin)与框架(Framework)两层复用机制,其中插件又支持 path 与 package 两种加载模式。本文以"分析 UA 实现 ctx.isIOS / ctx.isAndroid"为起点,完整走一遍 Egg 官方推荐的渐进式开发(Progressive Development)**流程:从应用内直接编写代码,到以 path 模式在应用内孵化插件原型,再到抽成独立 npm 插件,最终沉淀为团队级框架。读完本文,你将掌握一条可复用的"代码 → 插件 → 框架"演进路径,理解 config/plugin.js 中 path 与 package 的取舍、eggPlugin 声明规范以及 egg.framework 的框架指定机制,并了解如何用 npm link 在发布前做本地联调验证。
一、为什么要渐进式开发:复用机制的演进阶梯
Egg 同时提供了 插件开发 与 框架开发 两层抽象,且插件存在 path 与 package 两种加载方式。面对"功能先写在哪、什么时候拆出去"的问题,官方给出的答案是:不要一步到位,而是随着代码成熟度逐步演进。
演进阶梯可以概括为:
- 应用内代码:功能逻辑直接写在应用目录中,快速验证业务价值;
- 插件原型(
path模式):按插件目录规范组织代码,但留在应用内部(lib/plugin),便于随时修改; - 独立插件(
package模式):功能稳定后抽取为 npm 模块,供多个项目通过npm install复用; - 企业框架:沉淀一批插件与配置后,抽象出适合团队业务场景的框架,统一技术选型与默认配置。
这套演进思路正是 Egg "渐进式"哲学的落地:每一步都建立在可运行、可测试的代码之上,而不是推翻重来。
二、Step 1:在应用内直接实现功能
假设我们要编写一段分析 UA(User-Agent)的代码,实现两个能力:
ctx.isAndroidctx.isIOS
按照 应用结构 与 扩展开发 的约定,最直接的方式是在应用的 app/extend/context.js 中扩展 Context 对象。目录结构如下:
example-app
├── app
│ ├── extend
│ │ └── context.js
│ └── router.js
├── test
│ └── index.test.js
└── package.json
核心代码:
// app/extend/context.js
module.exports = {
get isIOS() {
const iosReg = /iphone|ipad|ipod/i;
return iosReg.test(this.get('user-agent'));
},
get isAndroid() {
const androidReg = /android/i;
return androidReg.test(this.get('user-agent'));
},
};
app/extend/context.js 中定义的属性会挂载到 Context 的原型上,因此在路由、控制器、中间件等任意持有 ctx 的地方都可以直接使用 ctx.isIOS / ctx.isAndroid。
为什么第一步要写在应用内,而不是直接写成一个插件?因为功能初期的形态往往并不完美:接口设计可能要调整、正则可能要考虑更多机型、边界情况还没有暴露。此时若直接封装成插件独立维护,每次改动都要经历发布、升级依赖的过程,成本很高。渐进式开发的原则是:先把逻辑写对、写稳,再考虑复用边界。
在仓库中,扩展机制由 lib/loader/app_worker_loader.js 的 load() 流程驱动,其中 loadContextExtend() 负责按 "app > plugin > core" 的优先级合并 Context 扩展;对应的测试可参考 test/app/extend/context.test.js。
三、Step 2:插件原型——以 path 模式在应用内孵化
这个 UA 判断逻辑显然具有通用性(任何 Web 应用都可能需要),可以写成插件。但既然功能还不够完善,直接独立出去又难以维护,Egg 给出的折中方案是:把代码整理成插件的格式,但暂不拆出应用。
做法是新建 lib/plugin/egg-ua 目录,把扩展文件"原样搬进去":
example-app
├── app
│ └── router.js
├── config
│ └── plugin.js
├── lib
│ └── plugin
│ └── egg-ua
│ ├── app
│ │ └── extend
│ │ └── context.js
│ └── package.json
├── test
│ └── index.test.js
└── package.json
关键操作有三步:
1. 移动扩展文件
将 app/extend/context.js 移动到 lib/plugin/egg-ua/app/extend/context.js,代码本身无需任何改动——插件中的应用目录(app)与普通应用遵循相同的加载约定。
2. 通过 eggPlugin 声明插件
在 lib/plugin/egg-ua/package.json 中声明插件身份:
{
"eggPlugin": {
"name": "ua"
}
}
eggPlugin.name 是插件的唯一标识(注意不是 npm 包名),后续的依赖关系、加载顺序都以此为准。关于 eggPlugin 节点可配置的字段,详见 插件开发:
{String} name:插件名(必填),用于声明依赖关系;{Array} dependencies:强依赖插件列表,缺失则应用启动失败;{Array} optionalDependencies:可选依赖插件列表,未开启仅告警;{Array} env:限定插件只在指定运行环境开启(环境类型见 运行环境)。
3. 在 config/plugin.js 中用 path 挂载
// config/plugin.js
const path = require('path');
exports.ua = {
enable: true,
path: path.join(__dirname, '../lib/plugin/egg-ua'),
};
这里使用的就是 path 加载模式:插件尚未发布到 npm,通过绝对路径直接指向应用内部的 lib/plugin/egg-ua 目录即可加载。这样既享受了插件的目录规范(app/extend 等目录自动被加载),又保留了就地修改的灵活性。
path 与 package 的区别:
path是绝对路径引入,适合内置插件——如应用内部抽取但还没发布到 npm 的插件,或应用要覆盖框架自带插件;package是 npm 模块引入,是最常见的方式。两者在config/plugin.js的配置项中互斥。
四、Step 3:抽成独立插件——以 package 模式发布复用
经过一段时间迭代,egg-ua 的功能趋于完善,此时就可以把它抽取为一个独立的插件模块。抽取后的 egg-ua 拥有自己的目录结构、测试夹具与测试用例:
egg-ua
├── app
│ └── extend
│ └── context.js
├── test
│ ├── fixtures
│ │ └── test-app
│ │ ├── app
│ │ │ └── router.js
│ │ └── package.json
│ └── ua.test.js
└── package.json
可以看到,独立插件本质上是一个"迷你应用":仍然有 app/extend 目录,但没有独立的 Router 和 Controller(路由与应用强绑定、不具备通用性,且多插件支持路由容易引发冲突);测试时通过 test/fixtures/test-app 构造一个最小应用来验证插件行为,这也是 Egg 插件测试的标准形态。
随后修改原应用 example-app:
- 删除目录
lib/plugin/egg-ua,应用内不再保留插件源码; - 在
package.json中声明依赖egg-ua(作为 npm 依赖安装); - 将
config/plugin.js的加载方式从path改为package:
// config/plugin.js
exports.ua = {
enable: true,
package: 'egg-ua',
};
改动极小,但代码的归属与生命周期发生了变化:egg-ua 从"应用内实现细节"变成了"可独立版本化、可被多个项目共享的 npm 模块"。
发布前用 npm link 做本地联调
在把插件发布到 npm 之前,官方推荐使用 npm link 在本地完成集成验证:
$ cd example-app
$ npm link ../egg-ua
$ npm i
$ npm test
npm link ../egg-ua 把本地插件目录链接为应用的 node_modules 依赖,随后安装依赖并运行测试,即可在不发布的情况下验证插件与应用的真实协作效果。
插件的寻址规则
应用切换到 package 模式后,Loader 依据如下顺序查找插件(详见 插件开发 中的"插件的寻址规则"):
- 配置了
path时,直接按path加载; - 未配置
path时按package名查找,查找顺序为:- 应用根目录下的
node_modules; - 应用所依赖框架路径下的
node_modules; - 当前路径下的
node_modules(主要用于兼容单元测试场景)。
- 应用根目录下的
另外,插件加载是有依赖顺序的:应用在加载所有插件前,会先读取各插件 package.json 中的 eggPlugin.dependencies 与 eggPlugin.optionalDependencies,据此计算加载顺序——这也是插件区别于"靠使用者手工排顺序"的 Koa 中间件的重要特性。仓库中 test/fixtures/apps/loader-plugin-dep 等 fixture 即用于验证这类依赖解析场景。
五、Step 4:沉淀为框架——团队级技术方案抽象
重复上面的过程,团队会积累出一批插件与配置,当多数项目都在使用它们时,就到了考虑把它们抽象为一个框架(Framework)的时刻。框架的意义在于:统一技术选型、统一默认配置、统一部署方案、统一代码风格,让应用只关注自身业务代码。
抽取 example-framework
首先在框架目录中声明插件依赖与默认配置:
example-framework
├── config
│ ├── config.default.js
│ └── plugin.js
├── lib
│ ├── agent.js
│ └── application.js
├── test
│ ├── fixtures
│ │ └── test-app
│ └── framework.test.js
├── README.md
├── index.js
└── package.json
操作要点:
- 将
egg-ua等插件的依赖声明与开关配置从应用中移除,改到框架的package.json(dependencies)与config/plugin.js(exports.ua = { enable: true, package: 'egg-ua' })中统一管理; - 应用则从
config/plugin.js中删除egg-ua的声明、从package.json中删除egg-ua依赖,转而依赖框架。
应用侧:通过 egg.framework 指定框架
修改应用的 package.json,声明框架依赖并指定框架名:
{
"name": "progressive",
"version": "1.0.0",
"private": true,
"egg": {
"framework": "example-framework"
},
"dependencies": {
"example-framework": "*"
}
}
关键配置是 egg.framework:Loader 会从 node_modules 中查找该模块作为框架,并加载其导出的 Application / Agent 类(默认框架为 egg 本身)。
框架同样可以在发布前用 npm link 本地联调:
$ cd example-app
$ npm link ../egg-framework
$ npm i
$ npm test
框架的底层原理:Symbol.for('egg#eggPath') 与多级继承
框架机制并非魔法,而是建立在类继承与约定之上。在当前仓库的源码中可以找到直接证据:
- lib/application.js 与 lib/agent.js 中,Egg 自身的
Application/Agent分别通过get [EGG_LOADER]()返回默认的AppWorkerLoader/AgentWorkerLoader,通过get [EGG_PATH]()返回框架路径; - lib/egg.js 中基类
EggApplication同样以path.join(__dirname, '..')暴露自己的EGG_PATH。
自定义框架的原理是:每一层框架都继承上一层框架,并覆盖 EGG_PATH 返回自身目录。Loader 遍历原型链即可获取每一层框架的路径,从而支持"部门框架 → 企业框架 → Egg"这类多级框架继承。框架目录本身会被视为一个 loadUnit,其下的 app、config 等目录都会被加载。框架若需自定义加载逻辑,还可以通过 Symbol.for('egg#loader') 覆盖 Loader——从 lib/loader/app_worker_loader.js 可以看到,AppWorkerLoader 的加载顺序为:extend(application/request/response/context/helper)→ 自定义 app 逻辑 → service → middleware → controller → router。
仓库中 test/fixtures/custom-egg(自定义框架 fixture)与 test/fixtures/apps/aliyun-egg(演示了一个真实形态的第三方框架及其 lib/plugins、lib/agent.js、index.js 结构)可以作为阅读框架实现细节的参考。完整的框架定制 API 说明见 框架开发。
六、演进准则与最佳实践
回顾整个渐进式开发流程,可以总结出几条明确的判断准则:
- 应用内可复用的代码,先放入
lib/plugin:按插件格式组织,但不拆出,保持修改成本最低; - 插件功能稳定后,拆分为独立的 node module:通过
package模式加载,用npm link做发布前联调; - 复用性较强的应用,可沉淀为独立插件:让多个项目通过
npm install直接复用; - 当应用沉淀为特定业务场景的解决方案时,抽象为框架发布:团队其他项目只需依赖框架并升级版本,即可获得统一能力;
- 无论应用、插件还是框架,单元测试都是必须的,并尽量达到 100% 覆盖率:这是代码能够安全地从应用内迁出、再升级为框架的前提。
渐进式开发的价值在于"让复用以最自然的方式发生":一开始不需要任何架构决策,随着代码成熟度提升,复用边界逐渐清晰,插件化、模块化乃至框架化水到渠成——正如 框架开发 文档所述,当某个项目中的差异化实践被验证为最佳实践后,就可以下沉到框架中,其他项目仅需升级框架版本即可同步受益。这既保证了 Egg 框架核心的精简、稳定与高效,也让团队协作与代码复用获得了结构性的提升。