后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载RedwoodJS 内置的 Mailer 是一个端到端的邮件设计与交付框架它通过Renderer渲染器把 React 组件转成 HTML/纯文本再通过Handler处理器交给 Nodemailer、Resend、SES 等具体服务发出并针对开发、测试、生产三种环境自动切换发送通道防止邮件泄漏。读完本文你将掌握yarn rw setup mailer的完整初始化流程、api/src/lib/mailer.ts的每一项配置、如何在 Service 中发送模板邮件、如何用 InMemory 处理器做快照级单元测试以及如何接入 Redwood Studio 的模板预览与本地收件箱。本文以仓库中的 version-6.x/mailer.md 文档为主线并结合packages/mailer下的核心源码、四个官方处理器、两个官方渲染器及 CLI 生成模板进行源码级印证。设计目标为什么 Mailer 不只是发一封邮件RedwoodJS Mailer 的设计出发点是把发送邮件这个动作拆成一条可组合、可测试、可切换的流水线。官方文档明确列出了它的设计约束这些约束直接决定了下面要讲的架构形态可对接主流第三方服务如 Resend、SendGrid、Postmark、Amazon SES 等可自托管通过 Nodemailer 作为开源自建方案按场景选通道例如事务邮件走 Resend、摘要邮件走 SES调用方可以在发信时按需指定 handler开发/测试环境安全隔离在 sandbox 中发送绝不意外泄露真实邮件支持 React 模板体系基于 React Email 或 MJML 编写 HTML/纯文本邮件并预留更多模板方案可单元测试断言 to、from、cc、subject、正文等字段与 RedwoodJS Studio 深度集成用于模板设计与预览。如文档所说RedwoodJS Mailer 是一整套端到端的邮件设计、开发与测试工具包其核心由handlers与renderers两类抽象组成配合api/src/lib/mailer.ts配置文件完成装配。总体架构Handler × Renderer × 三种运行模式官方文档给出了一张 Mailer Flow 示意图见 docs/static/img/mailer/flow.svg完整描绘了邮件从模板组件到最终投递的路径整条链路在源码 packages/mailer/core/src/mailer.ts 的Mailer类中实现。Mailer在构造时做三件事确定运行模式this.mode this.isTest() ? test : this.isDevelopment() ? development : production见 mailer.ts#L52-L56校验并装载 handlers / renderers同时为测试与开发模式准备回退处理器抽取默认发送参数extractDefaults。调用mailer.send(...)时send方法根据当前 mode 决定实际使用哪个 handlertest 模式用测试 handlerdevelopment 模式用开发 handlerproduction 模式才使用发送选项中指定的或默认的生产 handler见 mailer.ts#L164-L180。这种模式驱动的路由机制正是开发/测试不泄露真实邮件这一设计目标的技术基础。两种核心抽象Renderer 与 HandlerRenderer渲染器负责把 React 组件渲染成可供邮件客户端使用的字符串HTML 与纯文本。抽象基类AbstractMailRenderer定义在 packages/mailer/core/src/renderer.ts其契约非常简单abstract render( template: unknown, options: MailRendererOptionsunknown, utilities?: MailUtilities, ): MailRenderedContent abstract internal(): Recordstring, unknownHandler处理器负责把渲染后的内容交给真实投递服务。抽象基类AbstractMailHandler定义在 packages/mailer/core/src/handler.tsabstract send( renderedContent: MailRenderedContent, sendOptions: MailSendOptionsComplete, handlerOptions?: Recordstring | number | symbol, unknown, utilities?: MailUtilities, ): PromiseMailResult | MailResult abstract internal(): Recordstring, unknown注意MailRenderedContent同时包含html与text两个字段见 packages/mailer/core/src/types.ts#L9-L12因此任何官方渲染器都会尽量同时产出两种格式任何官方 handler 也会把两种格式一并投递。官方 Renderer 一览Mailer 目前官方提供两个渲染器目录均在 packages/mailer/renderersRenderer依赖技术源码位置redwoodjs/mailer-renderer-react-emailReact Emailredwoodjs/mailer-renderer-mjml-reactMJMLFaire/mjml-react以 React Email 渲染器为例其实现位于 packages/mailer/renderers/react-email/src/index.ts它支持outputFormat选项取值both | html | text默认bothhtml分支使用reactEmailRender(template, { pretty: true, plainText: false })text分支使用plainText: true从而基于同一份组件同时产出两种正文格式。官方文档特别强调邮件客户端在 HTML 渲染上出了名的不一致因此强烈建议使用 React Email、MJML 这类健壮的组件库来编写邮件模板以保证跨客户端的视觉效果一致性。官方 Handler 一览Mailer 目前官方提供四个处理器目录在 packages/mailer/handlersHandler用途源码位置redwoodjs/mailer-handler-in-memory内存收件箱典型用于测试packages/mailer/handlers/in-memoryredwoodjs/mailer-handler-nodemailer基于 Nodemailer 的通用 SMTP 发送packages/mailer/handlers/nodemailerredwoodjs/mailer-handler-studio把邮件送入 Redwood Studio内部仍走 Nodemailerpackages/mailer/handlers/studioredwoodjs/mailer-handler-resend对接 Resend 云服务packages/mailer/handlers/resend以 Nodemailer handler 为例见 packages/mailer/handlers/nodemailer/src/index.ts它的配置HandlerConfig接受transport可以是SMTPTransport、SMTPTransport.Options或连接字符串与可选的defaults构造时即调用nodemailer.createTransport(config.transport, config.defaults)。send方法把MailSendOptionsComplete中的to/cc/bcc/from/replyTo/subject/headers/attachments与渲染出的text/html一起传给transporter.sendMail并返回{ messageID: result.messageId, handlerInformation: result }。Resend handler见 packages/mailer/handlers/resend/src/index.ts则略有不同它通过new Resend(apiToken)创建云客户端发送时把replyTo映射为 Resend API 的reply_to并把字符串形式的附件内容转成 UTF-8Buffer后随请求发出同时支持 Resend 特有的tags选项用于邮件打标。InMemoryMailHandler见 packages/mailer/handlers/in-memory/src/index.ts最为简单它维护一个inbox数组send时把完整发送参数、textContent、htmlContent以及utilities中携带的handler、renderer信息一并压入 inbox并返回形如in-memory-1的messageID同时提供clearInbox()方法便于测试间重置。这正是文档中测试断言的落点。如果你的目标服务不在官方列表里也可以参考以上实现自行编写 handler/renderer接口契约就在redwoodjs/mailer-corepackages/mailer/core中完成后可以开源回馈社区。关键文件与目录约定Mailer 的核心配置文件是api/src/lib/mailer.ts。文档给出了初始化后的默认形态这与 CLI 生成的模板 packages/cli/src/commands/setup/mailer/templates/mailer.ts.template 完全一致import { Mailer } from redwoodjs/mailer-core import { NodemailerMailHandler } from redwoodjs/mailer-handler-nodemailer import { ReactEmailRenderer } from redwoodjs/mailer-renderer-react-email import { logger } from src/lib/logger export const mailer new Mailer({ handling: { handlers: { // TODO: Update this handler config or switch it out for a different handler completely nodemailer: new NodemailerMailHandler({ transport: { host: localhost, port: 4319, secure: false, }, }), }, default: nodemailer, }, rendering: { renderers: { reactEmail: new ReactEmailRenderer(), }, default: reactEmail, }, logger, })配置结构说明类型定义见 packages/mailer/core/src/types.ts#L65-L85handling.handlers一个以任意字符串为 key、handler 实例为 value 的映射表handling.default生产模式下默认使用的 handler key必须提供否则构造时会抛出No default handler configuredhandling.options可选为每个 handler 提供默认的 handlerOptions发送时会与调用方的 handlerOptions 浅合并见 mailer.ts#L218-L224rendering.renderers与rendering.default同理渲染器的注册表与默认项defaults可选全局默认发送参数to与subject除外见下文默认发送参数小节development/test可选覆盖两种非生产模式的行为logger可选缺省时回退为console且 Mailer 会为 logger 挂一个{ module: mailer }的子上下文见 mailer.ts#L47-L49。Mailer 还约定你的邮件模板组件放在api/src/mail目录下。例如欢迎邮件应位于api/src/mail/Welcome/Welcome.tsx。这保证了配置在lib、模板在mail的目录约定清晰可循。初始化yarn rw setup mailer新建的 RedwoodJS 应用默认不包含 Mailer但初始化非常简单只需运行yarn rw setup mailer该命令会完成两件事对应 packages/cli/src/commands/setup/mailer/mailer.js 及其 handler mailerHandler.js安装必要依赖包括redwoodjs/mailer-core、redwoodjs/mailer-handler-nodemailer、redwoodjs/mailer-renderer-react-email并且会把redwoodjs/mailer-handler-in-memory作为devDependency自动加入以便测试模式默认可用生成初始配置即上文api/src/lib/mailer.ts模板。该命令还支持两个可选参数--force别名-f覆盖已存在的配置文件--skip-examples只生成必需文件跳过示例模板。初始化之后邮件模板组件如Welcome.tsx需要你自己在api/src/mail下创建命令本身不会替你生成业务模板。发送邮件一个完整的 Contact Us 实战官方文档用一个博客站点的联系我们功能作为示例表单提交的 name、email、message 落库后同时向内部邮箱发送一封通知邮件。改造后的 Service 如下import { mailer } from src/lib/mailer import { ContactUsEmail } from src/mail/Example/Example // ... export const createContact: MutationResolvers[createContact] async ({ input, }) { const contact await db.contact.create({ data: input, }) // Send email await mailer.send( ContactUsEmail({ name: input.name, email: input.email, // Note the date is hardcoded here for the sake of test snapshot consistency when: new Date(0).toLocaleString(), }), { to: inboxexample.com, subject: New Contact Us Submission, replyTo: input.email, from: contact-usexample.com, } ) return contact }这段代码做了三件事导入Mailer 单例与邮件模板组件调用mailer.send第一个参数是模板组件可传入基于用户输入的 props第二个参数是发送选项发送选项中的to、subject、replyTo、from决定邮件收件人、主题、回复地址与发件人。发送选项的类型契约send的第二个参数类型是MailSendOptions见 packages/mailer/core/src/types.ts#L111-L118它继承MailSendWithoutRenderingOptions在 types.ts#L89-L102 中定义了完整的字段集字段类型必填说明toMailAddress \| MailAddress[]是收件人MailAddress可以是纯字符串或{ name?, address }对象ccMailAddress \| MailAddress[]否抄送bccMailAddress \| MailAddress[]否密送fromMailAddress否可由 defaults 提供发件人若最终缺失会抛Missing from addressreplyToMailAddress否回复地址subjectstring是主题缺失会抛Missing subjectheadersRecordstring, string否自定义邮件头attachmentsMailAttachment[]否附件MailAttachment支持filename、path、content字符串或 Bufferhandlerhandler key否覆盖生产模式下的 handlerrendererrenderer key否覆盖默认渲染器默认发送参数 defaults示例里显式写了replyTo但如果大量邮件都想默认使用replyTo: no-replyexample.com不必每处重复。可以在api/src/lib/mailer.ts中通过defaults统一设置defaults: { replyTo: no-replyexample.com, },源码对defaults的处理在 packages/mailer/core/src/utils.ts 的extractDefaults中cc/bcc/replyTo/from会被预先通过convertAddress转换成标准字符串形如Name address或裸地址attachments与headers缺省为空数组/空对象。注意defaults的类型是PartialOmitMailBasicSendOptions, to | subjecttypes.ts#L78即不能把to、subject放进 defaults——这两项必须每次发送时显式指定。发送时constructCompleteSendOptionsutils.ts#L61-L130会把本次发送选项与defaults合并本次显式给出的字段优先未给出的字段回退到 defaults最终形成一份完整的MailSendOptionsComplete。若合并后仍缺少from、subject或to会分别抛出对应的错误。三种运行模式的自动分流Mailer 会根据NODE_ENV自动选择模式各模式的判定与 handler 路由逻辑见 mailer.ts#L319-L345模式触发条件邮件去向test默认NODE_ENV test测试 handler默认 in-memorydevelopment默认NODE_ENV ! production开发 handler默认 Studioproduction上述均不满足发送选项指定的 handler未指定则用handling.default每个模式的when都可以是一个布尔值或返回布尔的函数handler则指定该模式下使用的 handler key。send/sendWithoutRendering内部都通过switch (this.mode)选取 handler如果选出的 handler 为null则直接返回空结果{}即no-op 不发信mailer.ts#L182-L185。测试模式InMemory 收件箱与快照断言当NODE_ENV为test时Mailer 进入测试模式所有邮件无论调用时指定了哪个 handler都会改走测试 handler。默认行为是创建 Mailer 时检查redwoodjs/mailer-handler-in-memory是否可用mailer.ts#L66-L90可用则自动装载InMemoryMailHandler作为测试 handler并打印一条 warn 日志不可用则测试 handler 退化为 no-op邮件不投递、不落库由于yarn rw setup mailer已把 in-memory 包加入 devDependencies正常项目默认即有可用的测试收件箱。如果需要显式控制测试模式可在api/src/lib/mailer.ts中加入test: { when: process.env.NODE_ENV test, handler: someOtherHandler, }when布尔值或返回布尔值的函数决定 Mailer 创建时是否进入测试模式handler测试模式下实际使用的 handler key若设为null则测试模式下完全不发信。在测试代码中可以通过mailer.getTestHandler()拿到测试 handlermailer.ts#L347-L356进而读取inbox做断言。文档给出的完整测试示例describe(contacts, () { scenario(creates a contact, async () { const result await createContact({ input: { name: String, email: String, message: String }, }) expect(result.name).toEqual(String) expect(result.email).toEqual(String) expect(result.message).toEqual(String) // Mail const testHandler mailer.getTestHandler() as InMemoryMailHandler expect(testHandler.inbox.length).toBe(1) const sentMail testHandler.inbox[0] expect({ ...sentMail, htmlContent: undefined, textContent: undefined, }).toMatchInlineSnapshot( { attachments: [], bcc: [], cc: [], from: contact-usexample.com, handler: nodemailer, handlerOptions: undefined, headers: {}, htmlContent: undefined, renderer: reactEmail, rendererOptions: {}, replyTo: String, subject: New Contact Us Submission, textContent: undefined, to: [ inboxexample.com, ], } ) expect(sentMail.htmlContent).toMatchSnapshot() expect(sentMail.textContent).toMatchSnapshot() }) })这个测试覆盖了三层断言发送数量inbox.length为 1确认恰好发了一封发送选项通过内联快照断言to、from、replyTo、subject、cc/bcc/headers/attachments以及handler、renderer等元信息与期望一致渲染结果htmlContent与textContent分别用toMatchSnapshot()锁定保证模板改动不会悄悄破坏产出。值得注意的是InMemoryMailHandler会把utilities中的handler、rendererkey 一并记录到 inbox 条目里in-memory/src/index.ts#L32-L40因此快照里能看到handler: nodemailer、renderer: reactEmail——即使在测试模式下也保留了生产环境会走哪个通道的可观测信息。官方核心测试 packages/mailer/core/src/tests/mailer.test.ts 也用 Mock handler/renderer 验证了模式切换、默认 handler 校验等行为可作为深入阅读的起点。开发模式Studio 本地收件箱与实时预览与测试模式类似Mailer 还提供开发模式。当NODE_ENV不是production时自动进入默认尝试加载redwoodjs/mailer-handler-studio作为开发 handlermailer.ts#L91-L115把邮件送入 Redwood Studio 内置的本地 SMTP 收件箱。可通过如下配置自定义development: { when: process.env.NODE_ENV ! production, handler: someOtherHandler, },配置语义与test完全一致when决定是否进入开发模式handler指定该模式使用的 handlernull表示不发信。Template Previews 模板预览开发模式下Studio 可以提供邮件模板的实时预览你更新模板代码时预览会自动重新渲染还可以提供一个 JSON payload 作为模板组件的 props。官方文档明确指出预览是近似效果但对大多数场景足以覆盖 90% 的观感判断。Local Inbox 本地收件箱使用默认的 Studio 开发 handler 时你应用里发出的每封邮件都会进入 Studio 内置的本地 SMTP 收件箱。这样你可以在本地完整跑通发送 - 收件 - 查看流程无需自建本地邮箱也不必借助在线临时邮箱服务。:::warning Redwood Studio 目前仍是实验性功能处于持续开发中。上述 UI 可能与最新版本略有差异功能细节也可能会随时间调整。 :::生产模式直达默认通道当NODE_ENV既不是test也不是development时Mailer 进入生产模式。此模式下不会重定向任何邮件邮件直接交给发送选项中指定的 handler未指定则使用handling.default配置的默认 handler。这也是配置文件中default字段为什么是必填项的原因——生产模式的兜底通道完全由它决定。另外Mailer还暴露了sendWithoutRendering方法mailer.ts#L252-L317当你已经有现成的 HTML/文本内容、不需要渲染器时可以直接把内容交给 handler 发送同样支持按模式分流与 defaults 合并。此外还有一组 getter 可用于编程式访问当前环境下的实际通道getTestHandler()、getDevelopmentHandler()、getDefaultProductionHandler()、getDefaultHandler()与getDefaultRenderer()。自定义 Handler 与 Renderer扩展生态如果官方 handler/renderer 无法满足你的技术栈Mailer 并不阻止你自建。做法是阅读现有实现作为参照handlerspackages/mailer/handlersrendererspackages/mailer/renderers实现AbstractMailHandler/AbstractMailRenderer定义的接口位于 packages/mailer/core 的redwoodjs/mailer-core包中并实现internal()方法暴露实例内部状态在你的api/src/lib/mailer.ts中注册并设为默认或按模式指定可以把自己的实现开源分享给 RedwoodJS 社区也欢迎在社区论坛中交流。一个自定义 handler 的最小形态可以参考 mailer.test.ts 里的MockMailHandler继承AbstractMailHandler实现send与internal即可。Mailer构造时会自动校验你注册的默认 handler/renderer 是否真实存在于映射表中不存在会直接抛错从而避免生产环境出现配置了却发不出的隐性故障。小结RedwoodJS Mailer 的价值在于把邮件能力做成了与框架一体的工程化组件api/src/lib/mailer.ts一处装配api/src/mail目录统一管理模板send一条 API 覆盖渲染与投递而 test/development/production 三态路由保证了从开发、测试到上线的全链路安全。配合 InMemory 收件箱做快照级测试、Studio 做模板预览与本地收件它确实是官方文档所说的端到端设计、开发与测试的完整邮件工具包。若需深入实现细节可从 packages/mailer/core 的Mailer类及其单元测试读起再逐层查看你所用 handler 与 renderer 的具体实现。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐RedwoodJS Mailer 完全指南端到端的邮件发送、渲染、测试与 Studio 集成RedwoodJS Mailer 完全指南端到端的邮件发送、渲染、测试与 Studio 集成 导读 RedwoodJS Mailer 是 RedwoodJS后端前端Web框架开发工具RedwoodJS Mailer 完全指南从模板渲染到多环境投递的端到端邮件方案RedwoodJS Mailer 完全指南从模板渲染到多环境投递的端到端邮件方案 RedwoodJS Mailer 是 RedwoodJS 内置的端到端邮件发后端前端Web框架开发工具RedwoodJS Mailer 全指南从模板渲染、多 Provider 投递到测试与开发沙箱RedwoodJS Mailer 全指南从模板渲染、多 Provider 投递到测试与开发沙箱 导读 RedwoodJS Mailer 是 RedwoodJS后端前端Web框架开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
