基于 Node.js 与 Koa 的企业级 Web 框架 Egg：多进程管理、插件机制与快速上手

后端Web框架【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa项目地址https://gitcode.com/gh_mirrors/egg11/egg点击查看免费下载本文以 README.zh-CN.md 为核心骨架展开围绕 Egg 的安装方式、核心特性多进程管理、插件机制、框架定制与快速启动流程并结合当前仓库的源码实现、内置插件与配置项进行深入解读帮助读者理解 Egg 的设计理念并快速搭建第一个应用。导读Egg 是面向企业级框架和应用而生的 Node.js Web 框架它基于 Koa 之上内置了多进程管理、插件机制、框架定制等能力让开发者从繁琐的进程调度、目录约定和基础设施搭建中解放出来。读完本文你将掌握 Egg 的安装与快速启动命令、理解其约定优于配置的目录结构与加载器机制并能依据内置插件清单和核心配置项独立搭建、运行并调试一个 Egg 应用。一、Egg 是什么Egg 由阿里开源项目描述为为企业级框架和应用而生的 Web 框架Born to build better enterprise frameworks and apps。与直接使用 Koa 编写应用不同Egg 定位为框架的框架A web frameworks framework for Node.js见 package.json即它既可以直接用来编写业务应用也可以作为底层被二次封装成企业内部的统一框架再供业务团队使用。Egg 在 Koa 的基础上主要解决了三类问题多进程管理Master 进程负责调度Agent 进程负责公共资源访问Worker 进程负责业务请求框架内置了完整的进程生命周期管理。约定优于配置通过固定的目录结构如app/controller、app/service、app/middleware、config等自动加载代码统一团队规范。高度可扩展通过插件Plugin与框架Framework两级扩展机制把通用能力沉淀为可复用单元。二、安装Egg 是一个 npm 包安装命令如下$ npm install egg --save当前仓库 package.json 中声明engines: { node: 6.0.0 }即要求 Node.js 6.x 及以上版本README 原文表述为支持 Node.js 6.x 以上版本。仓库当前版本为 1.21.0main指向index.js同时提供 TypeScript 类型声明index.d.ts。安装完成后egg包会通过其自身的依赖引入egg-core加载器与目录约定、egg-cluster多进程启动、egg-logger日志体系、egg-security安全防护等核心模块同时内置大量常用插件详见下文内置插件。三、核心特性README 总结了 Egg 的四大核心特性✔︎ 内置多进程管理✔︎ 高度可扩展的插件机制✔︎ 深度框架定制✔︎ 丰富的插件生态下面逐一结合仓库源码展开解读。1. 内置多进程管理Egg 采用 Master/Agent/Worker 的多进程模型由egg-cluster提供底层实现。index.js 中直接透出exports.startCluster require(egg-cluster).startCluster;三种进程角色分工如下Master 进程负责启动、监控、重启 Worker 与 Agent不处理业务请求Agent 进程单实例常驻用于承载跨 Worker 共享的公共资源如数据库连接、文件监听对应源码为 lib/agent.js它通过setInterval保持存活见 lib/agent.jsWorker 进程多实例每个 Worker 是一个完整的 Koa 应用实例负责处理 HTTP 请求对应源码为 lib/application.js。三个进程共享同一份EggApplication基类lib/egg.js通过options.type区分agent与application。进程间通过 lib/core/messenger.js 通信Agent 端封装了broadcast、sendTo、sendToApp、sendToAgent、sendRandom等消息方法见 lib/agent.js。此外框架还内置了基于 Leader/Follower 模式的cluster客户端封装见 lib/egg.js用于把共享资源的访问收敛到 Agent 侧避免多 Worker 重复建连。2. 高度可扩展的插件机制插件是 Egg 复用能力的核心单元。框架内置插件清单定义在 config/plugin.js全部默认开启插件包名职责onerroregg-onerror全局异常处理sessionegg-sessionSession 支持i18negg-i18n国际化watcheregg-watcher文件与目录监听multipartegg-multipart文件上传multipart 解析securityegg-security安全防护中间件与扩展developmentegg-development本地开发辅助logrotatoregg-logrotator日志文件切割scheduleegg-schedule定时任务staticegg-staticapp/public静态资源服务jsonpegg-jsonpJSONP 支持viewegg-view模板渲染插件配置格式统一为module.exports { // 以 onerror 为例 onerror: { enable: true, // 是否开启默认 true package: egg-onerror, // npm 包名 }, };对应依赖也全部声明在 package.json 的dependencies中例如egg-development、egg-i18n、egg-jsonp、egg-logrotator、egg-multipart、egg-onerror、egg-schedule、egg-security、egg-session、egg-static、egg-view、egg-watcher。3. 深度框架定制Egg 既可以用作应用框架也可以被二次封装成企业级框架即框架的框架。框架定制依赖egg-core提供的加载器Loader体系。仓库中的加载器定义在 lib/loader/lib/loader/app_worker_loader.jsApp Worker 的加载器按固定顺序加载扩展、自定义 App、Service、Middleware、Controller、Routerlib/loader/agent_worker_loader.jsAgent Worker 的加载器加载 Agent 扩展与自定义 Agent。其加载顺序见 lib/loader/app_worker_loader.js为load() { // app plugin core this.loadApplicationExtend(); this.loadRequestExtend(); this.loadResponseExtend(); this.loadContextExtend(); this.loadHelperExtend(); // app plugin this.loadCustomApp(); this.loadService(); this.loadMiddleware(); // app this.loadController(); this.loadRouter(); // 依赖 controller }加载顺序本身即是约定先扩展、后业务Router 最后加载因为依赖 Controller。在index.js中Egg 将Application、Agent、AppWorkerLoader、AgentWorkerLoader、Controller、Service、Subscription、BaseContextClass全部导出供上层框架复用见 index.js。4. 丰富的插件生态README 指出 Egg 拥有大量第三方插件可通过 GitHub 的egg-plugintopic 搜索详见 README 的文档和社区一节插件之间还有完整的插件依赖图。这些插件遵循统一的加载与配置约定可以被任意 Egg 应用或框架直接复用。四、文档与社区Egg 提供官方站点与文档见 README 的文档和社区一节。本文所在仓库同时维护了中英文两套文档源位于 docs/source/zh-cn/ 与 docs/source/en/覆盖入门intro、基础basics、核心core、进阶advanced、教程tutorials等板块。其中与快速上手最直接相关的是 docs/source/zh-cn/intro/quickstart.md理解框架目录约定可阅读 docs/source/zh-cn/basics/structure.md。另外CONTRIBUTING.md中文版见 CONTRIBUTING.zh-CN.md说明了贡献规范版本演进记录见 History.md开源协议为 MIT见 LICENSE。五、快速开始README 给出了从零搭建一个 Egg 应用的四步流程下面逐条展开。1. 安装脚手架工具$ npm install egg-init -gegg-init是 Egg 官方脚手架工具全局安装后提供项目初始化命令。2. 初始化项目$ egg-init --type simple showcase cd showcase--type simple指定初始化一个最简单的 Egg 应用模板showcase为项目目录名。初始化完成后进入项目目录。3. 安装依赖$ npm install安装项目依赖包括egg框架本身及其内置插件。4. 启动开发服务器$ npm run dev以开发模式启动应用启动后默认监听 7001 端口该端口来自 config/config.default.js 中的默认集群配置config.cluster { listen: { path: , port: 7001, hostname: , }, };5. 访问应用$ open http://localhost:7001在浏览器中打开http://localhost:7001即可看到欢迎页。提示开发模式下egg-development插件会提供代码热重载等辅助能力见 config/plugin.js修改代码后无需手动重启。六、骨架项目的目录约定使用egg-init生成的 simple 模板会遵循 Egg 的目录约定详见 docs/source/zh-cn/basics/structure.mdegg-project ├── package.json ├── app.js (可选) ├── agent.js (可选) ├── app │ ├── router.js │ ├── controller │ │ └── home.js │ ├── service (可选) │ │ └── user.js │ ├── middleware (可选) │ │ └── response_time.js │ ├── schedule (可选) │ │ └── my_task.js │ ├── public (可选) │ │ └── reset.css │ ├── view (可选) │ │ └── home.tpl │ └── extend (可选) │ ├── helper.js (可选) │ ├── request.js (可选) │ ├── response.js (可选) │ ├── context.js (可选) │ ├── application.js (可选) │ └── agent.js (可选) ├── config │ ├── plugin.js │ ├── config.default.js │ ├── config.prod.js │ ├── config.test.js (可选) │ ├── config.local.js (可选) │ └── config.unittest.js (可选) └── test ├── middleware │ └── response_time.test.js └── controller └── home.test.js其中框架约定的目录职责为app/router.js配置 URL 路由规则对应文档 docs/source/zh-cn/basics/router.mdapp/controller/**解析用户输入并返回结果对应 docs/source/zh-cn/basics/controller.mdapp/service/**编写业务逻辑层可选但建议使用对应 docs/source/zh-cn/basics/service.mdapp/middleware/**编写中间件可选对应 docs/source/zh-cn/basics/middleware.mdapp/public/**放置静态资源由内置插件egg-static提供服务app/extend/**扩展框架能力对应 docs/source/zh-cn/basics/extend.mdconfig/config.{env}.js按环境编写配置对应 docs/source/zh-cn/basics/config.mdconfig/plugin.js配置需要加载的插件test/**单元测试对应 docs/source/zh-cn/core/unittest.mdapp.js与agent.js自定义启动初始化对应 docs/source/zh-cn/basics/app-start.md。由内置插件约定的目录包括app/schedule/**用于定时任务egg-schedule 约定app/view/**用于模板文件模板插件约定如 nunjucks。如需自定义目录规范可参照 Loader API见 docs/source/zh-cn/advanced/loader.md。这些目录之所以能自动生效正是上文所述的加载器机制启动时AppWorkerLoader会按照固定顺序把app目录下的约定文件加载并挂载到应用实例上。七、核心配置速览Egg 的默认配置集中在 config/config.default.js了解其中几项对日常开发非常有用1. Cookie 签名密钥keys: ,keys用于签名和加密 Cookie可以配置多个以逗号分隔的密钥。生产环境必须显式配置否则app.keys会直接抛错Please set config.keys first见 lib/application.js在local/unittest环境下则会输出提示引导开发者补充配置。2. 反向代理proxy: false, protocolHeaders: x-forwarded-proto, ipHeaders: x-forwarded-for,当应用部署在 Nginx 等反向代理之后时需要把proxy设为true框架才会信任x-forwarded-*系列头来识别真实协议与客户端 IP。3. bodyParserconfig.bodyParser { enable: true, encoding: utf8, formLimit: 100kb, jsonLimit: 100kb, strict: true, queryString: { arrayLimit: 100, depth: 5, parameterLimit: 1000, }, };bodyParser控制请求体的解析formLimit与jsonLimit为表单/JSON 请求体的体积上限超限返回 413strict为true时 JSON 解析器只接受数组与对象。4. 日志config.logger { dir: path.join(appInfo.root, logs, appInfo.name), level: INFO, appLogName: ${appInfo.name}-web.log, coreLogName: egg-web.log, agentLogName: egg-agent.log, errorLogName: common-error.log, };日志默认输出到$root/logs/{appname}目录应用日志、核心日志、Agent 日志与错误日志分开存放。代码中可通过app.logger、app.coreLogger、app.getLogger(name)访问不同 logger见 lib/egg.js。5. 核心中间件config.coreMiddleware [ meta, siteFile, notfound, bodyParser, overrideMethod, ];框架内置了 5 个核心中间件对应实现在 app/middleware/ 目录meta注入x-readtime响应时间头见 app/middleware/meta.js、siteFile响应站点文件如默认的 favicon、notfound404 处理、bodyParser请求体解析、overrideMethodHTTP 方法覆盖。八、从源码理解 Egg 的启动链路为了更深入地理解快速开始背后发生了什么可以串联上面提到的关键源码入口index.js 导出startCluster来自egg-cluster开发命令npm run dev即通过它启动集群进程角色Master 拉起一个 Agent 与多个 WorkerAgent 实例由 lib/agent.js 创建Application 实例由 lib/application.js 创建两者都继承自 lib/egg.js 的EggApplication加载与约定EggApplication构造时调用this.loader.loadConfig()加载插件与配置随后对应 Worker 的 Loader 执行load()按序加载约定目录见 lib/loader/app_worker_loader.js就绪与配置落盘应用 ready 后框架会把合并后的配置 dump 到run/{type}_config.json见 lib/egg.js并把路由表 dump 到run/router.json见 lib/application.js方便排查最终生效的配置到底是什么容错EggApplication捕获unhandledRejection见 lib/egg.jsApplication对非法请求返回 400见 lib/application.jsAgent捕获uncaughtException见 lib/agent.js保证进程异常不会静默丢失。九、更进一步运行示例README 指向的 egg-examples 示例仓库可参考本仓库的 test/bench/hello/ 内置了一个极简 hello 应用含 controller 与 router可作为最小可运行样例阅读。阅读测试仓库的 test/ 目录覆盖了 Agent、Application、中间件、核心模块等大量测试如 test/app/extend/application.test.js有助于理解各 API 的预期行为。框架定制如需把 Egg 二次封装为企业内部框架可参考 test/fixtures/custom-egg/ 中的自定义框架示例。贡献代码遵循 CONTRIBUTING.zh-CN.md 提交 issue 与 PR。结语从安装到启动仅需四条命令但 Egg 的价值远不止能跑起来内置的多进程模型让应用天然具备横向扩展能力约定式的目录结构与加载器让团队代码风格统一插件与框架两级扩展让能力可以持续沉淀复用。掌握本文的安装、特性、快速开始与核心配置你就已经具备了独立搭建和探索 Egg 应用的起点。赞分享后端Web框架【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa项目地址https://gitcode.com/gh_mirrors/egg11/egg点击查看免费下载相关推荐s3-lambda架构解析理解其无状态设计与并发控制原理s3 lambda架构解析理解其无状态设计与并发控制原理 在当今大数据时代处理海量S3存储对象成为了许多开发者的日常挑战。 s3 lambda 作为一款强大后端Web框架Egg 框架定制开发指南基于 Loader 与多进程模型构建企业级框架Egg 框架定制开发指南基于 Loader 与多进程模型构建企业级框架 导读 本文讲解 Egg 提供的「框架定制」能力当团队需要统一技术选型、默认配置、部署后端Web框架30-seconds-of-python项目使用Python轻松实现日期加减操作30 seconds of python项目使用Python轻松实现日期加减操作 在日常开发中日期处理是每个Python开发者都会遇到的常见需求。无论是计算后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考