后端Web框架【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa项目地址https://gitcode.com/gh_mirrors/egg11/egg点击查看免费下载导读本文基于 Egg 框架的 Framework Built-in Objects 官方文档系统梳理框架中面向开发者高频使用的九类内置对象从 Koa 继承的 Application、Context、Request、Response以及框架扩展出的 Controller、Service、Helper、Config、Logger。这些对象贯穿 Egg 应用的每一个文件是阅读后续控制器、服务、中间件、调度任务等文档的前提。读完本文你将掌握每个内置对象的生命周期定位应用级/请求级、全部获取途径与适用场景并能结合源码理解它们底层是如何被装载、实例化与关联的。一、内置对象全景谁继承自 Koa谁由 Egg 扩展框架在 Koa 之上构建内置对象分为两类继承自 Koa 的对象Application、Context、Request、Response。它们的语义与 Koa 保持一致Egg 在此基础上做了能力增强例如 Application 增加了 Loader 装载机制、Context 挂载了 Service 与 Helper。Egg 扩展出的对象Controller、Service、Helper、Config、Logger、Subscription。这些对象承载了 Egg 的约定式目录结构与工程化能力在后续文档控制器、服务、中间件、调度等中会反复出现。从源码看lib/egg.js 中this.Controller BaseContextClass;、this.Service BaseContextClass;说明 Controller 与 Service 的基类实际是同一个BaseContextClass而 lib/core/base_context_class.js 进一步为它注入了基于当前 Context 的loggergetter。这意味着三类对象天然共享同一套“上下文感知”设计。二、Application全局单例应用对象Application 是应用级全局单例对象一个应用只实例化一次。它继承自 Koa 的 Application是挂载全局方法、对象与配置的容器。你可以通过 框架扩展 在插件或应用层面对其进行扩展。2.1 获取方式一Loader 回调参数几乎所有由 Loader 装载的文件Controller、Service、Schedule 等都会导出一个以app为参数的函数Loader 调用该函数时注入 app应用启动脚本app-start.md// app.js module.exports app { app.cache new Cache(); };控制器文件controller.md// app/controller/user.js module.exports app { return class UserController extends app.Controller { * fetch() { this.ctx.body app.cache.get(this.ctx.query.id); } }; };说明* fetch()为 generator 函数写法Egg 同时支持async fetch()两种写法均被框架支持。2.2 获取方式二通过 Context 与实例属性与 Koa 一致在 Context 上可通过ctx.app访问 Application// app/controller/user.js module.exports app { return class UserController extends app.Controller { * fetch() { this.ctx.body this.ctx.app.cache.get(this.ctx.query.id); } }; };在继承自 Controller / Service 基类的实例对象中通过this.app访问// app/controller/user.js module.exports app { return class UserController extends app.Controller { * fetch() { this.ctx.body this.app.cache.get(this.ctx.query.id); } }; };2.3 源码佐证Application 的装载与常用成员从 lib/application.js 可以看到Application 构造函数中调用this.loader.load()完成目录装载并执行配置 dump同时通过 lib/egg.js 挂载了messenger、httpclient、loggers、Controller、Service、BaseContextClass等核心成员。此外app.config.keysconfig/config.default.js用于 Cookie 签名与加密若缺失会在keysgetter 中抛出错误提示lib/application.js。三、Context请求级上下文Context 是请求级对象继承自 Koa.Context。每收到一个请求框架就实例化一个 Context封装用户的请求信息并提供读取请求参数、设置响应信息的便捷方法。框架会把所有 Service 挂载到 Context 实例上一些插件也会在 Context 上挂载额外方法与对象例如 egg-sequelize 会把所有 Model 挂载到 Context。3.1 获取方式Middleware、Controller、ServiceContext 最常见的获取场景是中间件、控制器与服务中控制器内的获取方式见上文示例this.ctx服务中的获取方式与控制器一致this.ctx。Egg 中间件同时兼容 Koa v1 与 Koa v2 两种写法访问 Context 的方式略有差异// Koa v1 function* middleware(next) { // this 是 Context 实例 console.log(this.query); yield next; } // Koa v2 async function middleware(ctx, next) { // ctx 是 Context 实例 console.log(ctx.query); }中间件细节可参考 middleware.md。3.2 非请求场景createAnonymousContext()在某些非请求场景下如启动预加载、定时任务前处理我们需要访问 Service / Model 等挂在 Context 上的对象此时可使用app.createAnonymousContext()创建一个匿名的 Context 实例// app.js module.exports app { app.beforeStart(function* () { const ctx app.createAnonymousContext(); // 在应用启动前预加载 yield ctx.service.posts.load(); }); }从 lib/egg.js 的实现看该方法会构造一份 mock 的 request 对象默认 host 为127.0.0.1、method 为GET、url 为/并允许传入req覆盖 headers、query、socket 等字段最后通过createContext生成匿名上下文。测试用例 test/lib/egg.test.js 与 test/app/extend/application.test.js 均对该能力做了验证。3.3 调度任务中的 ContextSchedule 中的每个任务都会以一个 Context 实例作为参数方便在调度逻辑中直接调用服务// app/schedule/refresh.js exports.task function* (ctx) { yield ctx.service.posts.refresh(); };四、Request 与 Response请求/响应级对象Request是请求级对象继承自 Koa.Request封装 Node.js 原生 HTTP Request提供一组获取 HTTP 请求常用参数的辅助方法。Response是请求级对象继承自 Koa.Response封装 Node.js 原生 HTTP Response提供一组设置 HTTP 响应的辅助方法。4.1 获取方式与等价写法在 Context 实例上可以通过ctx.request与ctx.response获取当前请求的 Request 与 Response// app/controller/user.js module.exports app { return class UserController extends app.Controller { * fetch() { const { app, ctx } this; const id ctx.request.query.id; ctx.response.body app.cache.get(id); } }; };使用要点Koa 会把 Request 与 Response 的部分方法和属性代理到 Context 上见 Koa.Context因此ctx.request.query.id与ctx.query.id等价ctx.response.body ...与ctx.body ...等价。注意获取 POST 请求体应使用ctx.request.body而不是ctx.body。4.2 源码佐证Egg 对 Request/Response 的扩展Egg 在 app/extend/request.js 中为 Request 扩展了queries数组形式的多值参数解析、acceptJSON判断客户端是否接受 JSON 响应支持.json结尾路径、响应类型与 Accept 头三种判定见 app/extend/request.js等能力在 app/extend/response.js 中扩展了length计算与响应类型工具同时在 app/extend/context.js 通过 delegates 把acceptJSON、queries、ip、realStatus等属性代理到 Context 上。这些扩展在 test/app/extend/request.test.js 与 test/app/extend/response.test.js 中有完整测试覆盖。五、Controller控制器基类Egg 提供了 Controller 基类并推荐所有 Controller 继承它。Controller 基类拥有以下属性属性说明ctx当前请求的 Context 实例appApplication 实例config应用配置service应用的所有 servicelogger针对当前控制器封装的 logger 对象在控制器文件中有两种引用 Controller 基类的方式// app/controller/user.js // 方式一从 app 实例获取推荐 module.exports app { return class UserController extends app.Controller { // 实现 }; }; // 方式二从 egg 模块获取 const egg require(egg); module.exports class UserController extends egg.Controller { // 实现 };从 lib/egg.js 可以看出app.Controller与egg.Controller指向同一个BaseContextClass基类两种写法完全等价推荐方式一以避免在应用与框架间产生循环依赖问题。六、Service服务基类Egg 提供 Service 基类并推荐所有 Service 继承。Service 基类的字段与 Controller 基类相同ctx、app、config、service、logger获取方式类似// app/service/user.js // 方式一从 app 实例获取推荐 module.exports app { return class UserService extends app.Service { // 实现 }; }; // 方式二从 egg 模块获取 const egg require(egg); module.exports class UserService extends egg.Service { // 实现 };Service 的详细约定可参考 service.md。七、Helper通用工具函数容器Helper 用于提供有用的工具函数把常用的函数统一放入app/extend/helper.js用 JavaScript 编写复杂逻辑避免逻辑散落各处同时更便于编写测试用例。Helper 本身是一个类字段与 Controller 基类相同且每次请求都会实例化因此 Helper 上的所有函数都能拿到当前请求的 Context。7.1 获取方式ctx.helper 与模板中使用在 Context 实例上通过ctx.helper获取当前请求的 Helper// app/controller/user.js module.exports app { return class UserController extends app.Controller { * fetch() { const { app, ctx } this; const id ctx.query.id; const user app.cache.get(id); ctx.body ctx.helper.formatUser(user); } }; };此外Helper 实例也可以在模板中访问例如从模板中调用 security 插件提供的shtml方法// app/view/home.nj {{ helper.shtml(value) }}7.2 自定义 Helper 方法通过框架扩展可以自定义 Helper 方法如上面示例中的formatUser// app/extend/helper.js module.exports { formatUser(user) { return only(user, [ name, phone ]); } };7.3 源码佐证Helper 的装载与内置方法从 lib/application.js 可以看到app.Helper会创建一个继承BaseContextClass的 Helper 类并将${baseDir}/app/extend/helper.js中的方法装载到 Helper 原型上app/extend/context.js 中的ctx.helpergetter 会在首次访问时new this.app.Helper(this)完成实例化。框架本身也在 app/extend/helper.js 内置了pathFor(name, params)生成路由的路径与urlFor(name, params)生成带 host 的完整 URL两个方法可直接在控制器或模板中使用。八、Config配置对象Egg 推荐遵循配置与代码分离的原则把硬编码的业务参数放入配置文件配置文件支持不同运行环境使用不同配置。框架、插件与应用层级的配置都可以通过 Config 对象访问。详细的配置机制请阅读 Configuration。获取方式通过app.config从 Application 实例获取在 Controller、Service 或 Helper 实例中通过this.config获取。框架启动时会把最终合并的配置 dump 到run/${type}_config.json见 lib/egg.js便于排查配置来源同时dump.ignoreconfig/config.default.js会在 dump 时忽略password、keys等敏感字段。九、Logger日志对象家族Egg 内置了强大的 logger可以很方便地把各种级别的日志输出到对应日志文件。每个 logger 对象提供 5 个级别的方法注原文列出的 4 个方法之外还有logger.debug()共 5 个logger.debug()logger.info()logger.warn()logger.error()Egg 提供了多个 Logger 对象下面介绍各自的获取方式与适用场景。9.1 App Loggerapp.logger应用级日志例如在启动阶段记录一些数据、记录业务相关信息都可以使用 App Logger。对应日志文件为$HOME/logs/{appname}/{appname}-web见 lib/egg.js。9.2 App CoreLoggerapp.coreLogger开发应用时不应通过 CoreLogger 打印日志——它供框架与插件打印应用级日志使用便于与业务日志区分CoreLogger 打印的日志会写入与 Logger 不同的文件egg-web见 lib/egg.js。9.3 Context Loggerctx.logger与请求强相关会在日志前面带上当前请求的相关信息如[$userId/$ip/$traceId/${cost}ms $method $url]利用这些信息可以快速从日志中定位某个请求并把一个请求内的所有日志串联起来。测试用例 test/lib/core/logger.test.js 展示了通过ctx.logger.error输出错误日志并落盘到common-error.log的完整链路。9.4 Context CoreLoggerctx.coreLogger与 Context Logger 的区别在于只有插件和框架会通过它打日志。9.5 Controller Logger 与 Service Loggerthis.logger在 Controller 和 Service 实例中通过this.logger获取。它们本质上是 Context Logger但会额外在日志中加入文件路径便于定位日志打印位置。实现上lib/core/base_context_class.js 为基类注入了基于BaseContextLogger的loggergetter而 lib/core/base_context_logger.js 会在日志正文前追加[${pathName}]前缀。十、Subscription订阅模型基类Subscription 是订阅模型包括消息队列中的 consumer 或定时调度。egg 导出 Subscription 基类const Subscription require(egg).Subscription; class Schedule extends Subscription { // 该方法必须实现 // subscribe 可以是 generator 函数或 async 函数 * subscribe() {} }官方推荐插件开发者基于该模型实现能力例如 Schedule 就是典型应用。通过它可以把“订阅 / 消费”的通用模式抽象出来让消息消费者与调度任务共享同一套生命周期约定。十一、对象关系速查与实战建议对象生命周期主要获取途径典型用途Application应用级单例Loader 回调参数、ctx.app、this.app挂载全局方法/对象、启动逻辑Context请求级中间件参数、this.ctx、createAnonymousContext()请求信息封装、Service 访问Request请求级ctx.request部分属性代理到 ctx读取请求参数Response请求级ctx.response部分属性代理到 ctx设置响应Controller请求级实例app.Controller/egg.Controller继承处理业务路由Service请求级实例app.Service/egg.Service继承业务逻辑分层Helper请求级实例ctx.helper通用工具函数Config应用级app.config、this.config环境化配置读取Logger应用级/请求级app.logger、ctx.logger、this.logger等分级日志输出Subscription模型基类egg.Subscription继承调度/消息消费实战建议分清生命周期Application 与 Config 是应用级、全局共享Context、Request、Response、Controller、Service、Helper 是请求级每次请求重新实例化——不要在请求级对象上缓存跨请求共享的全局状态。优先使用推荐写法Controller / Service 优先采用module.exports app class ... extends app.Controller/Service的写法与 Loader 注入机制天然契合。日志按场景选择业务日志用app.logger/ctx.logger/this.logger框架与插件日志用coreLogger系列保持日志通道清晰隔离。非请求场景善用匿名上下文启动预加载、定时任务等场景通过app.createAnonymousContext()获取带 Service 能力的 Context避免手动拼接。这十类内置对象是 Egg 约定式开发的地基理解它们的生命周期与获取方式后续阅读 controller.md、service.md、middleware.md、extend.md 等文档时就能做到心中有数、随取随用。赞分享后端Web框架【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa项目地址https://gitcode.com/gh_mirrors/egg11/egg点击查看免费下载相关推荐TinyExpr终极指南如何在C项目中快速集成轻量级数学表达式引擎TinyExpr终极指南如何在C项目中快速集成轻量级数学表达式引擎 你是否曾经需要在C/C项目中动态计算数学表达式面对复杂的表达式解析需求你是否厌倦了后端Web框架Egg 框架内置对象完全指南Application、Context、Controller、Service 与 Logger 等核心对象的生命周期与获取方式Egg 框架内置对象完全指南Application、Context、Controller、Service 与 Logger 等核心对象的生命周期与获取方式 本后端Web框架Egg 单元测试完全指南从 Vitest 配置到 Controller / Service / Extend 实战Egg 单元测试完全指南从 Vitest 配置到 Controller / Service / Extend 实战 本文是 Egg 框架应用单元测试的实战指南后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考