EggJS 2.0 升级指南：从 Generator 到 Async/Await 的平滑迁移

EggJS 2.0 升级指南：从 Generator 到 Async/Await 的平滑迁移

egg Born to build better enterprise frameworks and apps with Node.js & Koa 项目地址: https://gitcode.com/gh_mirrors/eg/egg

前言

随着 Node.js 8 LTS 版本的发布，EggJS 框架也迎来了 2.0 的重大升级。本次升级的核心变化是全面支持 ES2017 的 Async Function（async/await），这为开发者带来了更优雅的异步编程体验。本文将详细介绍如何从 EggJS 1.x 平滑升级到 2.0 版本。

升级背景

在 Node.js 8 之前，EggJS 1.x 通过 co 库实现了基于 Generator 函数的异步编程方案。虽然这已经提供了类似 async/await 的编程体验，但仍存在一些固有缺陷：

1. 性能损耗：co 库的转换层带来了额外的性能开销
2. 错误堆栈不清晰：错误发生时难以追踪原始调用位置
3. 兼容性处理：需要支持多种 yieldable 类型

EggJS 2.0 基于这些痛点进行了全面改进：

• 完全兼容 1.x 的 Generator 函数写法
• 基于 Koa 2.x 实现原生 async/await 支持
• 仅支持 Node.js 8 及以上版本
• 性能提升约 30%（不包括 Node.js 自身的性能提升）
• 更清晰的错误堆栈信息

快速升级步骤

对于大多数应用来说，升级过程非常简单：

1. 确保 Node.js 版本 ≥ 8.9.0（推荐使用最新的 LTS 版本）
2. 修改 package.json 中 egg 的版本为 ^2.0.0
3. 检查并更新所有插件到最新版本（可选）
4. 重新安装依赖并运行测试

// package.json
{
  "dependencies": {
    "egg": "^2.0.0"
  }
}

完成这些步骤后，你的应用应该就能正常运行了，几乎不需要修改任何代码。

插件升级注意事项

egg-multipart 插件

文件上传处理方式有所变化：

// 旧版写法
const parts = ctx.multipart();
while ((part = yield parts) != null) {
  // 处理文件
}

// 新版写法
const parts = ctx.multipart();
while ((part = await parts()) != null) {
  // 处理文件
}

egg-userrole 插件

角色定义方式发生了变化：

// 旧版
app.role.use('user', function() {
  return !!this.user;
});

// 新版
app.role.use((ctx, scope) => {
  return !!ctx.user;
});

深度升级建议

虽然快速升级后应用可以正常运行，但为了获得最佳性能和开发体验，建议进行以下深度优化：

1. 使用 Koa 2 风格的中间件

EggJS 2.0 完全兼容 1.x 的中间件写法，但推荐迁移到 Koa 2 风格：

// 1.x 风格
module.exports = () => {
  return function* responseTime(next) {
    const start = Date.now();
    yield next;
    const delta = Math.ceil(Date.now() - start);
    this.set('X-Response-Time', delta + 'ms');
  };
};

// 2.0 风格
module.exports = () => {
  return async function responseTime(ctx, next) {
    const start = Date.now();
    await next();
    const delta = Math.ceil(Date.now() - start);
    ctx.set('X-Response-Time', delta + 'ms');
  };
};

2. 从 yieldable 到 awaitable

Promise 处理

// 直接替换
await echo('hi egg');

并行请求处理

// 旧版并行请求
const [news, user] = yield [
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
];

// 新版使用 Promise.all
const [news, user] = await Promise.all([
  ctx.service.news.list(topic),
  ctx.service.user.get(uid),
]);

对象形式的并行请求

// 服务层
class BizService extends Service {
  list(topic, uid) {
    return Promise.all([
      ctx.service.news.list(topic),
      ctx.service.user.get(uid),
    ]);
  }
}

// 控制器层
const [news, user] = await ctx.service.biz.list(topic, uid);

插件开发者升级指南

如果你是插件开发者，升级时需要注意：

1. 完成上述所有升级项
2. 考虑接口兼容性（可选）
3. 发布主版本更新

接口兼容性处理

对于需要同时支持 Generator 和 Async 的插件，可以使用框架提供的工具方法：

// 将各种形式的函数统一转换为 Async Function
task = app.toAsyncFunction(schedule.task);

版本发布规范

1. 使用主版本号更新
2. 修改 package.json：
   • 将 egg 的 devDependencies 设置为 ^2.0.0
   • 设置 engines.node 为 >=8.0.0
   • 更新 CI 配置
3. 更新 README 中的示例代码
4. 编写升级说明文档

对于需要维护旧版本的情况，可以使用 npm 的 dist-tag 功能：

npm publish --tag release-1.x

总结

EggJS 2.0 的升级带来了显著的性能提升和更好的开发体验。通过本文的指导，你可以根据实际情况选择快速升级或深度优化。对于新项目，建议直接使用 Async/Await 风格开发；对于老项目，可以逐步迁移，享受渐进式升级带来的便利。

记住，框架的"渐进式"理念让你可以按照自己的节奏完成升级，不必一次性修改所有代码。希望本文能帮助你顺利完成 EggJS 2.0 的升级之旅！

egg Born to build better enterprise frameworks and apps with Node.js & Koa 项目地址: https://gitcode.com/gh_mirrors/eg/egg