Egg 渐进式开发实战:从应用扩展代码到插件再到框架的演进之路

原创2026-09-20 12:45:331,447 阅读
文章标签:后端Web框架

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 两种加载方式。面对"功能先写在哪、什么时候拆出去"的问题,官方给出的答案是:不要一步到位,而是随着代码成熟度逐步演进。

演进阶梯可以概括为:

  1. 应用内代码:功能逻辑直接写在应用目录中,快速验证业务价值;
  2. 插件原型(path 模式):按插件目录规范组织代码,但留在应用内部(lib/plugin),便于随时修改;
  3. 独立插件(package 模式):功能稳定后抽取为 npm 模块,供多个项目通过 npm install 复用;
  4. 企业框架:沉淀一批插件与配置后,抽象出适合团队业务场景的框架,统一技术选型与默认配置。

这套演进思路正是 Egg "渐进式"哲学的落地:每一步都建立在可运行、可测试的代码之上,而不是推翻重来。

二、Step 1:在应用内直接实现功能

假设我们要编写一段分析 UA(User-Agent)的代码,实现两个能力:

  • ctx.isAndroid
  • ctx.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:

  1. 删除目录 lib/plugin/egg-ua,应用内不再保留插件源码;
  2. 在 package.json 中声明依赖 egg-ua(作为 npm 依赖安装);
  3. 将 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 依据如下顺序查找插件(详见 插件开发 中的"插件的寻址规则"):

  1. 配置了 path 时,直接按 path 加载;
  2. 未配置 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 框架核心的精简、稳定与高效,也让团队协作与代码复用获得了结构性的提升。

登录后查看全文
egg