后端前端Web框架開(kāi)發(fā)工具【免費(fèi)下載鏈接】redwoodRedwoodGraphQL項(xiàng)目地址https://gitcode.com/gh_mirrors/re/redwood點(diǎn)擊查看免費(fèi)下載導(dǎo)讀RedwoodJS Mailer 是 RedwoodJS 框架內(nèi)置的端到端郵件解決方案它把「郵件模板渲染」與「郵件投遞」徹底解耦為renderer渲染器與handler處理器兩層抽象前者負(fù)責(zé)把 React 組件變成可供發(fā)送的 HTML/純文本字符串后者負(fù)責(zé)把渲染結(jié)果交給 Nodemailer、Amazon SES、Resend 等真實(shí)投遞服務(wù)。本文將基于 mailer.md 的完整內(nèi)容結(jié)合倉(cāng)庫(kù)中packages/mailer的源碼實(shí)現(xiàn)系統(tǒng)講解 Mailer 的架構(gòu)、yarn rw setup mailer初始化流程、mailer.send的實(shí)戰(zhàn)用法、test/development/production 三種模式的行為差異以及如何與 RedwoodJS Studio 的模板預(yù)覽和本地收件箱協(xié)作。設(shè)計(jì)目標(biāo)為什么要單獨(dú)做一個(gè) MailerRedwoodJS 設(shè)計(jì) Mailer 時(shí)遵循一個(gè)核心理念發(fā)送郵件不只是「發(fā)出」這么簡(jiǎn)單投遞環(huán)節(jié)與內(nèi)容準(zhǔn)備環(huán)節(jié)同樣重要。圍繞這個(gè)理念Mailer 被要求滿足以下能力與 mailer.md 一一對(duì)應(yīng)支持 Resend、SendGrid、Postmark、Amazon SES 等主流第三方郵件服務(wù)支持以 Nodemailer 作為自托管的開(kāi)源方案按用例選擇不同的 Provider例如事務(wù)郵件走 Resend、摘要郵件走 SES單封郵件可以顯式指定投遞方式在開(kāi)發(fā)與測(cè)試環(huán)境中以「沙箱」方式安全發(fā)送避免郵件意外泄漏到真實(shí)收件箱郵件可同時(shí)包含文本與 HTML并基于 React Email、MJML 等流行工具編寫模板未來(lái)可擴(kuò)展更多方式可做單元測(cè)試校驗(yàn) to、from、cc、subject、正文等字段與 RedwoodJS Studio 集成用于設(shè)計(jì)模板與實(shí)時(shí)預(yù)覽。因此RedwoodJS Mailer 不是「僅僅發(fā)一封郵件」的工具而是一套完整的郵件設(shè)計(jì)、開(kāi)發(fā)與測(cè)試端到端套件。架構(gòu)概覽Renderer 與 Handler 兩層抽象Mailer 的核心由兩部分組成見(jiàn) mailer.mdRenderer渲染器把 React 組件轉(zhuǎn)換為可發(fā)送的文本或 HTML 字符串Handler處理器接收渲染后的內(nèi)容并將其交給實(shí)際的投遞服務(wù)Nodemailer、SES 等發(fā)給收件人。在源碼層面這兩類抽象分別定義在 handler.ts 與 renderer.ts 中AbstractMailHandler要求實(shí)現(xiàn)send(renderedContent, sendOptions, handlerOptions?, utilities?)與internal()兩個(gè)方法AbstractMailRenderer要求實(shí)現(xiàn)render(template, options, utilities?)與internal()兩個(gè)方法。Mailer主類見(jiàn) mailer.ts持有handlers、renderers、defaults與mode四個(gè)關(guān)鍵狀態(tài)并在構(gòu)造時(shí)完成模式判定與配置校驗(yàn)。官方 Renderer當(dāng)前倉(cāng)庫(kù)內(nèi)置兩個(gè) renderer見(jiàn) mailer.mdreact-email renderer基于 React EmailSupportedOutputFormats為both | html | text默認(rèn)輸出both。源碼中通過(guò)react-email/render的render函數(shù)分別生成 pretty HTMLplainText: false與純文本plainText: truemjml-react renderer基于 MJMLSupportedOutputFormats僅支持html通過(guò)renderToMjml與mjml2html生成 HTML且若renderingResult.errors非空會(huì)直接拋出錯(cuò)誤。:::important 提示 郵件客戶端對(duì) HTML 的渲染表現(xiàn)差異極大這是業(yè)界公認(rèn)的痛點(diǎn)文檔建議使用成熟的 React 郵件組件庫(kù)編寫模板以產(chǎn)出在各類客戶端下渲染一致的郵件。 :::官方 Handler當(dāng)前倉(cāng)庫(kù)內(nèi)置四個(gè) handler見(jiàn) mailer.mdin-memory handler內(nèi)存處理器通常用于測(cè)試。源碼中維護(hù)一個(gè)inbox數(shù)組send時(shí)把完整發(fā)送選項(xiàng)與渲染后的文本/HTML 內(nèi)容壓入 inbox并返回messageID: in-memory-N同時(shí)提供clearInbox()方法nodemailer handler基于 Nodemailer。HandlerConfig.transport可以是 SMTP 傳輸配置對(duì)象、SMTPTransport.Options或連接字符串HandlerOptions即nodemailer.SendMailOptions在調(diào)用sendMail時(shí)以展開(kāi)方式覆蓋基礎(chǔ)發(fā)送選項(xiàng)studio handler把郵件發(fā)送到 RedwoodJS Studio 內(nèi)置的本地 SMTP 收件箱內(nèi)部實(shí)際復(fù)用了 NodemailerHandlerhostlocalhost、port4319、secure: false并在發(fā)送失敗時(shí)打印引導(dǎo)信息提示使用yarn rw studio查看resend handler基于 Resend SDK構(gòu)造函數(shù)接收{(diào) apiToken }發(fā)送時(shí)會(huì)把字符串類型的附件內(nèi)容轉(zhuǎn)換為 utf8 Buffer 再提交并透?jìng)鱰ags等 Resend 專屬選項(xiàng)。除此之外社區(qū)還維護(hù)了大量第三方 renderer 與 handler可以在 npm、RedwoodJS 論壇等社區(qū)渠道中搜索獲取。關(guān)鍵配置文件與目錄約定Mailer 的核心配置文件是api/src/lib/mailer.tsyarn rw setup mailer生成的內(nèi)容與 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, })配置結(jié)構(gòu)說(shuō)明與 types.ts 中的MailerConfig類型對(duì)應(yīng)handling.handlers對(duì)象key 是任意自定義名稱value 是 handler 實(shí)例handling.default生產(chǎn)環(huán)境默認(rèn)使用的 handler key必填。源碼 mailer.ts 中若未配置會(huì)拋出No default handler configured若指向未注冊(cè)的 handler 會(huì)拋出The specified default handler ... is not definedrendering.renderers對(duì)象key 為任意名稱value 為 renderer 實(shí)例rendering.default生產(chǎn)環(huán)境默認(rèn)使用的 renderer key必填校驗(yàn)邏輯同上defaults可選的默認(rèn)發(fā)送選項(xiàng)詳見(jiàn)下文test/development可選的模式級(jí)配置logger可選的日志器未提供時(shí)降級(jí)為console源碼中會(huì)用.child({ module: mailer })派生子日志器。另外Mailer 約定將郵件 React 組件放在api/src/mail目錄下例如歡迎郵件的組件路徑應(yīng)為api/src/mail/Welcome/Welcome.tsx。Mailer 完整配置參數(shù)速查配置項(xiàng)類型必填說(shuō)明handling.handlersRecordstring, AbstractMailHandler是注冊(cè)的全部 handlerkey 為自定義名handling.defaultstring是生產(chǎn)模式默認(rèn) handlerhandling.optionsRecordstring, HandlerOptions否各 handler 的默認(rèn) handlerOptions發(fā)送時(shí)與調(diào)用方傳入的選項(xiàng)做淺合并rendering.renderersRecordstring, AbstractMailRenderer是注冊(cè)的全部 rendererkey 為自定義名rendering.defaultstring是生產(chǎn)模式默認(rèn) rendererrendering.optionsRecordstring, RendererOptions否各 renderer 的默認(rèn)渲染選項(xiàng)defaultsPartialMailBasicSendOptions否全局默認(rèn)發(fā)送選項(xiàng)test.whenboolean \| () boolean否判定是否進(jìn)入測(cè)試模式缺省為NODE_ENV testtest.handlerstring \| null否測(cè)試模式使用的 handler缺省嘗試自動(dòng)加載 in-memory handlerdevelopment.whenboolean \| () boolean否判定是否進(jìn)入開(kāi)發(fā)模式缺省為NODE_ENV ! productiondevelopment.handlerstring \| null否開(kāi)發(fā)模式使用的 handler缺省嘗試自動(dòng)加載 studio handlerloggerLogger \| Console否日志器缺省為consoletest.handler/development.handler設(shè)為null表示顯式關(guān)閉該模式下的郵件處理no-op這一點(diǎn)在源碼中體現(xiàn)為send時(shí)若handlerKey null直接返回空結(jié)果mailer.ts?？焖匍_(kāi)始yarn rw setup mailer新創(chuàng)建的 RedwoodJS 應(yīng)用默認(rèn)不會(huì)安裝 Mailer需要執(zhí)行 CLI 命令初始化見(jiàn) mailer.mdyarn rw setup mailer該命令源碼位于 packages/cli/src/commands/setup/mailer會(huì)完成三件事生成api/src/lib/mailer.ts配置文件內(nèi)容即上文模板安裝redwoodjs/mailer-core、redwoodjs/mailer-handler-nodemailer、redwoodjs/mailer-renderer-react-email等運(yùn)行時(shí)依賴把redwoodjs/mailer-handler-in-memory作為devDependency自動(dòng)加入供測(cè)試模式使用。實(shí)戰(zhàn)用法在 Service 中發(fā)送郵件以教程中的博客站點(diǎn)為例假設(shè)我們實(shí)現(xiàn)了「聯(lián)系我們」功能表單收集 name、email、message 并寫入數(shù)據(jù)庫(kù)現(xiàn)在希望把每次提交同時(shí)抄送一封到內(nèi)部收件箱見(jiàn) mailer.md。在api/src/services/contacts.ts中更新 Serviceimport { 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 }這段代碼做了兩件事從src/lib/mailer導(dǎo)入 Mailer 實(shí)例從src/mail/Example/Example導(dǎo)入郵件模板組件調(diào)用mailer.send(template, sendOptions)第一個(gè)參數(shù)是模板組件可傳入基于用戶輸入的 props第二個(gè)參數(shù)是發(fā)送選項(xiàng)指定 to、from、subject 等。發(fā)送選項(xiàng)詳解mailer.send的發(fā)送選項(xiàng)對(duì)應(yīng)MailSendOptions類型見(jiàn) types.ts常用字段如下字段類型說(shuō)明toMailAddress \| MailAddress[]必填收件人MailAddress可以是字符串或{ name?, address }cc/bccMailAddress \| MailAddress[]可選抄送/密送fromMailAddress發(fā)件人可被defaults.from兜底replyToMailAddress回復(fù)地址subjectstring必填主題headersRecordstring, string自定義郵件頭attachmentsMailAttachment[]附件{ filename?, path?, content? }handlerstring指定本次發(fā)送使用的 handler覆蓋默認(rèn)rendererstring指定本次發(fā)送使用的 renderer覆蓋默認(rèn)郵件地址既可以直接傳字符串inboxexample.com也可以傳{ name: Redwood, address: helloredwoodjs.com }對(duì)象源碼 utils.ts 中的convertAddress會(huì)把后者規(guī)范化為name address格式。使用 defaults 設(shè)置全局默認(rèn)值上例中replyTo是為了滿足業(yè)務(wù)邏輯而單獨(dú)指定的。但如果大多數(shù)郵件都想默認(rèn)設(shè)置replyTo: no-replyexample.com就不必每封郵件重復(fù)書寫而是在api/src/lib/mailer.ts的配置中聲明defaultsdefaults: { replyTo: no-replyexample.com, },在底層extractDefaultsutils.ts會(huì)在構(gòu)造時(shí)把defaults中的地址統(tǒng)一轉(zhuǎn)換為字符串格式并補(bǔ)齊空數(shù)組每次發(fā)送時(shí)constructCompleteSendOptionsutils.ts會(huì)把單次發(fā)送選項(xiàng)與defaults合并規(guī)則是「調(diào)用方顯式傳入的選項(xiàng)優(yōu)先未傳入的字段回落到 defaults」——例如未傳cc時(shí)使用defaults.cc、未傳from時(shí)使用defaults.from。需要特別注意的是合并校驗(yàn)邏輯to、subject、from三個(gè)字段是強(qiáng)制的。如果既沒(méi)在發(fā)送選項(xiàng)中傳入、也沒(méi)有在defaults中配置會(huì)分別拋出Missing from address、Missing subject、Missing to address錯(cuò)誤。環(huán)境模式test / development / productionMailer 會(huì)在創(chuàng)建時(shí)根據(jù)條件自動(dòng)判定當(dāng)前所處模式mailer.tsmode只有三種取值見(jiàn) types.tstest | development | production。不同模式下即使調(diào)用了相同的send郵件也會(huì)被路由到不同的 handler從而保證開(kāi)發(fā)與測(cè)試過(guò)程中不會(huì)意外發(fā)出真實(shí)郵件。Testing 模式當(dāng)NODE_ENV為test時(shí)進(jìn)入測(cè)試模式。此模式下所有郵件都會(huì)改走測(cè)試 handler而忽略生產(chǎn)默認(rèn) handler 以及send/sendWithoutRendering調(diào)用中顯式指定的 handler見(jiàn) mailer.md。默認(rèn)行為Mailer 創(chuàng)建時(shí)會(huì)嘗試加載redwoodjs/mailer-handler-in-memory包若可用則以 InMemoryMailHandler 作為測(cè)試 handler否則測(cè)試 handler 變?yōu)槭裁炊疾蛔龅?no-op。yarn rw setup mailer已自動(dòng)把該包加入 devDependencies。這一點(diǎn)在源碼 mailer.ts 中得到印證require(redwoodjs/mailer-handler-in-memory)失敗時(shí)會(huì)記錄警告日志。如需手動(dòng)控制測(cè)試模式行為在mailer.ts中加入test: { when: process.env.NODE_ENV test, handler: someOtherHandler, }when可以是布爾值也可以是返回布爾值的函數(shù)決定 Mailer 創(chuàng)建時(shí)是否進(jìn)入測(cè)試模式handler指定測(cè)試模式使用的 handler必須是handling.handlers中已注冊(cè)的名稱設(shè)為null則關(guān)閉處理。從源碼看若指定的 handler key 未注冊(cè)構(gòu)造時(shí)會(huì)直接拋錯(cuò)The specified test handler ... is not defined因此這里的值必須與 handlers 注冊(cè)表中的 key 嚴(yán)格一致。Development 模式與測(cè)試模式類似當(dāng)NODE_ENV不是production時(shí)自動(dòng)進(jìn)入開(kāi)發(fā)模式默認(rèn)判定條件為process.env.NODE_ENV ! production見(jiàn) mailer.ts。開(kāi)發(fā)模式行為與測(cè)試模式相似默認(rèn)嘗試使用redwoodjs/mailer-handler-studio包。手動(dòng)配置方式development: { when: process.env.NODE_ENV ! production, handler: someOtherHandler, },:::tip 開(kāi)發(fā)模式下推薦配合 Mailer Studio 使用它提供一個(gè)本地郵件收件箱讓郵件發(fā)送到本地機(jī)器即可查看結(jié)果同時(shí)提供渲染模板的實(shí)時(shí)預(yù)覽作為最終用戶看到的樣式的參考。 :::Production 模式當(dāng) test 與 development 的判定條件均不滿足時(shí)即NODE_ENV production且未自定義when進(jìn)入生產(chǎn)模式。此模式下不會(huì)對(duì)郵件做任何重路由郵件直接交給默認(rèn) handlerhandling.default投遞除非在send的發(fā)送選項(xiàng)中顯式指定handler。用測(cè)試模式驗(yàn)證郵件in-memory 收件箱實(shí)戰(zhàn)測(cè)試模式最大的價(jià)值在于可以放心斷言郵件內(nèi)容。沿用上面的聯(lián)系表單示例在api/src/services/contacts/contacts.test.ts中編寫如下測(cè)試見(jiàn) mailer.mddescribe(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() }) })測(cè)試的核心抓手是mailer.getTestHandler()它返回當(dāng)前測(cè)試 handler源碼見(jiàn) mailer.ts優(yōu)先返回test.handler配置的實(shí)例否則返回自動(dòng)加載的 fallback 實(shí)例。InMemoryMailHandler 的inbox數(shù)組源碼見(jiàn) in-memory handler記錄了每一封被「發(fā)送」的郵件包含完整發(fā)送選項(xiàng)to、cc、bcc、from、replyTo、subject、headers、attachments渲染后的textContent與htmlContent元信息handler、handlerOptions、renderer、rendererOptions來(lái)自MailUtilities。上面測(cè)試的斷言邏輯可以拆成三點(diǎn)確實(shí)發(fā)了一封郵件testHandler.inbox.length為 1發(fā)送選項(xiàng)正確通過(guò) inline snapshot 斷言 to、from、replyTo、subject、handler、renderer 等字段與預(yù)期完全一致注意快照中replyTo為String這正是replyTo: input.email傳入測(cè)試輸入的結(jié)果渲染內(nèi)容正確htmlContent與textContent分別匹配快照保證模板渲染的正文符合預(yù)期。利用InMemoryMailHandler.clearInbox()in-memory handler還可以在多個(gè)測(cè)試用例之間重置收件箱避免郵件互相污染。與 RedwoodJS Studio 集成RedwoodJS Studio 與 Mailer 深度集成目標(biāo)是不僅提供發(fā)送能力還提供更順暢的開(kāi)發(fā)體驗(yàn)見(jiàn) mailer.md。模板實(shí)時(shí)預(yù)覽Studio 提供郵件模板預(yù)覽功能模板會(huì)隨代碼改動(dòng)實(shí)時(shí)重渲染并且可以傳入一個(gè) JSON payload 作為模板組件的 props。這些預(yù)覽是近似效果但通常足以覆蓋 90% 的樣式核對(duì)需求。本地收件箱在開(kāi)發(fā)模式下使用默認(rèn)的redwoodjs/mailer-handler-studiohandler 時(shí)郵件會(huì)被發(fā)送到 Studio 內(nèi)部運(yùn)行的本地 SMTP 收件箱端口 4319。這意味著你可以在開(kāi)發(fā)環(huán)境中跑通完整的郵件收發(fā)流程而不必自建本地收件箱也不必依賴在線臨時(shí)收件箱服務(wù)。從源碼看StudioMailHandler 內(nèi)部就是封裝了指向localhost:4319的 NodemailerHandlerstudio handler若本地 SMTP 不可用會(huì)打印引導(dǎo)提示「Sent an email to the void! You can view this email during development with Redwood Studio:yarn rw studio」。自定義 Renderer 或 Handler如果官方內(nèi)置的 handler / renderer 無(wú)法滿足你的服務(wù)或技術(shù)棧需求完全可以自行實(shí)現(xiàn)并開(kāi)源回饋社區(qū)見(jiàn) mailer.md。實(shí)現(xiàn)的關(guān)鍵是滿足redwoodjs/mailer-core包中定義的接口自定義renderer繼承AbstractMailRenderer實(shí)現(xiàn)render(template, options, utilities?)返回{ html, text }以及internal()返回內(nèi)部狀態(tài)自定義handler繼承AbstractMailHandler實(shí)現(xiàn)send(renderedContent, sendOptions, handlerOptions?, utilities?)返回MailResult可含messageID與handlerInformation以及internal()。官方實(shí)現(xiàn)的 handlers 位于 packages/mailer/handlers、renderers 位于 packages/mailer/rendererscore 接口定義位于 packages/mailer/core都可以作為編寫自定義實(shí)現(xiàn)的直接參考。小結(jié)RedwoodJS Mailer 通過(guò) renderer/handler 的兩層抽象把「郵件內(nèi)容生產(chǎn)」與「郵件投遞」徹底分離讓你可以在任意 Service 中一行式發(fā)送模板郵件按單封郵件指定 Resend、SES 或 Nodemailer在測(cè)試模式用 in-memory 收件箱做精確斷言在開(kāi)發(fā)模式借助 Studio 本地收件箱與實(shí)時(shí)模板預(yù)覽完成調(diào)試在生產(chǎn)模式直連默認(rèn)投遞渠道。這套設(shè)計(jì)把郵件從「發(fā)出去就完事」提升為可設(shè)計(jì)、可預(yù)覽、可測(cè)試的完整工程能力。贊分享后端前端Web框架開(kāi)發(fā)工具【免費(fèi)下載鏈接】redwoodRedwoodGraphQL項(xiàng)目地址https://gitcode.com/gh_mirrors/re/redwood點(diǎn)擊查看免費(fèi)下載相關(guān)推薦RedwoodJS Mailer 完全指南端到端的郵件發(fā)送、渲染、測(cè)試與 Studio 集成RedwoodJS Mailer 完全指南端到端的郵件發(fā)送、渲染、測(cè)試與 Studio 集成 導(dǎo)讀 RedwoodJS Mailer 是 RedwoodJS后端前端Web框架開(kāi)發(fā)工具Jinja 沙箱Sandbox完全指南用 SandboxedEnvironment 安全渲染不可信模板Jinja 沙箱Sandbox完全指南用 SandboxedEnvironment 安全渲染不可信模板 本指南以 Jinja 官方文檔 docs/sand后端RedwoodJS渲染器模板渲染與頁(yè)面生成的終極指南RedwoodJS渲染器模板渲染與頁(yè)面生成的終極指南 RedwoodJS是一個(gè)基于React和GraphQL的全棧JavaScript框架提供了強(qiáng)大的模板渲后端前端Web框架開(kāi)發(fā)工具上一篇SpacetimeDB 瀏覽器快速入門用內(nèi)聯(lián) JavaScript 構(gòu)建實(shí)時(shí) Web 應(yīng)用下一篇惡意 npm 包檢測(cè)的威脅建模與標(biāo)準(zhǔn)映射Anthropic-Cybersecurity-Skills 中 detecting-malicious-npm-packages 技能實(shí)戰(zhàn)解析創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考