Coolify 邮件最佳实践：ShouldQueue、afterCommit 与 Mailable 测试断言的落地解析

Coolify 邮件最佳实践ShouldQueue、afterCommit 与 Mailable 测试断言的落地解析【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中的 Laravel 邮件最佳实践规则.agents/skills/laravel-best-practices/rules/mail.md为主体逐条讲解五条核心规则让 Mailable 类实现ShouldQueue使入队成为默认行为、在事务内使用afterCommit()避免竞态、对入队邮件使用assertQueued()而非assertSent()断言、为事务性邮件选用 Markdown Mailable以及将“内容测试”与“发送测试”分离。结合 Coolify 的通知系统源码app/Notifications/目录及其测试用例读者可以掌握这些规则在多通道通知场景下的实际落点与验证方式。规则一在 Mailable 类上实现ShouldQueue让入队成为默认行为原始规则说明Makes queueing the default regardless of how the mailable is dispatched. No need to rememberMail::queue()at every call site —Mail::send()also queues it.核心思想是入队与否应该由 Mailable 类自身声明而不是依赖每个调用点记住Mail::queue()。只要 Mailable或 Notification类实现了Illuminate\Contracts\Queue\ShouldQueue无论调用方使用Mail::send()、Mail::to()-send()还是notify()消息都会被投递到队列由 worker 异步执行。调用方代码因此被简化为统一的同步写法而性能与削峰特性则始终生效。Coolify 中的落地一个基类收口全部邮件通知Coolify 把这个规则做成了架构级约定。所有自定义邮件通知都继承自 CustomEmailNotification该基类一次性声明了队列行为与失败重试策略class CustomEmailNotification extends Notification implements ShouldQueue { use Queueable; public $backoff [10, 20, 30, 40, 50]; public $tries 5; public $maxExceptions 5; }从源码结构看这一设计带来三层收益所有子类天然入队。app/Notifications/下的 DeploymentFailed.php、InvitationLink.php、EmailChangeVerification.php、RestartLimitReached.php 等数十个通知均继承该基类无需逐个标注ShouldQueue。统一的重试退避$backoff [10, 20, 30, 40, 50]表示失败后按 10/20/30/40/50 秒递增延迟重试$tries 5与$maxExceptions 5共同约束最大尝试次数避免 SMTP 瞬时故障如 DNS 抖动、端口被限流导致通知直接丢失。发送方完全解耦以 TransactionalEmailChannel 为例其send()方法内部使用的是同步的Mail::send()——但因为 Notification 已实现ShouldQueue整个 channel 的发送逻辑实际运行在队列 worker 进程中HTTP 请求不会阻塞等待 SMTP 握手// app/Notifications/Channels/TransactionalEmailChannel.php Mail::send( [], [], fn (Message $message) mail_from_message($message, $settings) -to($email) -subject($mailMessage-subject) -html((string) $mailMessage-render()) );此外Coolify 还通过onQueue(high)把事务性邮件路由到独立命名队列仓库app/目录下共有 55 处onQueue(high)调用例如 InvitationLink 构造函数中的$this-onQueue(high)邀请邮件、改邮验证邮件这类时效性强的消息不会与低优先级任务争抢 worker。另一个细节是 Test.php 通知类额外引入了Illuminate\Queue\Middleware\RateLimited队列中间件对“发送测试邮件”这类可被滥用的入口做了速率保护。规则二在事务内使用afterCommit()派发 Mailable原始规则说明A queued mailable dispatched inside a transaction may process before the commit. Use$this-afterCommit()in the constructor.这是一个典型的竞态问题如果notify()/Mail::queue()发生在未提交的事务中队列 job 可能在commit()之前被 worker 执行。此时 job 内读取数据库会看到事务前的旧状态甚至查不到待创建的行导致邮件内容基于不成立的数据生成或者依赖外键的操作直接失败。解决方案是在 Mailable/Notification 构造函数中调用$this-afterCommit()需要类使用Queueabletrait把 job 的推送推迟到当前事务提交之后。Coolify 的实际用例RestartLimitReachedRestartLimitReached 通知在应用因超过重启上限被停止时发出其派发链路运行在可能包含事务的请求/事件处理流程中构造函数开头即为// app/Notifications/Application/RestartLimitReached.php构造函数节选 public function __construct(public BaseModel $resource) { $this-onQueue(high); $this-afterCommit(); $environment data_get($resource, environment) ?? data_get($resource, application.environment) ?? data_get($resource, service.environment); // ... 从资源中提取 project_uuid / environment_uuid / resource_url 等 }注意它把afterCommit()放在构造函数最前面随后才读取$resource的关联数据——因为resource_url、restart_count等字段都来自可能尚未持久化的模型状态推迟到提交后执行才能保证 job 序列化时数据自洽。仓库中还存在一种等价但更粗粒度的替代写法让监听器实现ShouldQueueAfterCommit。例如 ProxyStatusChangedNotificationclass ProxyStatusChangedNotification implements ShouldQueueAfterCommit { public function __construct() {} }两者取舍afterCommit()是 per-Mailable 的显式声明适合“同一 Mailable 有时在事务中、有时不在”的场景ShouldQueueAfterCommit则是类级约定适合几乎总在事件/事务流中触发的监听器。规则三入队 Mailable 应使用assertQueued()而不是assertSent()原始规则说明Mail::assertSent()only catches synchronous mail. Queued mailables failassertSentwith a Did you mean to use assertQueued()? hint.错误写法Mailable 实现了ShouldQueue时Mail::assertSent(OrderShipped::class);正确写法Mail::assertQueued(OrderShipped::class);原理是Mail::fake()之后同步send会进入 “sent” 记录集入队queue会进入 “queued” 记录集二者互不相通。对入队邮件使用assertSent()断言必然失败且 Laravel 会返回 “Did you mean to use assertQueued()?” 的提示——这个提示本身就是框架在为这条规则兜底。对应到 Coolify 的测试层Coolify 的测试主要面向 Notification 层因为邮件只是其多通道通知之一使用的是同构的Notification::fake()/assertSentTo*API。例如 ApiTokenExpirationWarningTest 验证了“发送次数”这一关键维度Notification::fake(); // ... Notification::assertSentTo($this-team, ApiTokenExpiringNotification::class); Notification::assertSentToTimes($this-team, ApiTokenExpiringNotification::class, 1); // 第二次触发后 Notification::assertSentToTimes($this-team, ApiTokenExpiringNotification::class, 2);[EmailChangeVerificationTest](https://link.gitcode.com/i/dfb206bc4cb177e540020c23f0df3b08)同样在每个用例开头Notification::fake()从而让“生成 6 位验证码”“确认改邮成功”等业务断言与“通知是否真的发出”完全隔离。如果你的自定义邮件直接通过Mailfacade 派发不经过 Notification 通道则应遵循文档规则入队场景断言Mail::assertQueued()同步场景断言Mail::assertSent()不要混用。规则四事务性邮件优先使用 Markdown Mailable原始规则说明Markdown mailables auto-generate both HTML and plain-text versions, use responsive components, and allow global style customization. Generate with--markdownflag.Markdown Mailablephp artisan make:mail Xxx --markdownemails/xxx的价值在于只维护一份 Markdown 模板Laravel 自动渲染出 HTML 与纯文本两个版本内置header、button、table等响应式组件并支持通过主题路径统一调整全部事务邮件的视觉风格。对“验证邮件、邀请邮件、密码重置”这类高频、低定制度的事务邮件这是维护成本最低的选择。Coolify 的运行时配置与现状对照config/mail.php 保留了完整的 Markdown 邮件配置段markdown [ theme default, paths [ resource_path(views/vendor/mail), ], ],default env(MAIL_MAILER, array)还说明本地/测试环境默认走arraytransport邮件只收集不落盘、不发送这为规则五中的测试隔离提供了前提。需要如实说明的是从源码看Coolify 当前的邮件正文实现走的是Blade 视图 MailMessage-view()路线而非 Markdown Mailable。例如 EmailChangeVerification 的toMail()$mail new MailMessage; $mail-subject(Coolify: Verify Your New Email Address); $mail-view(emails.email-change-verification, [ newEmail $this-newEmail, verificationCode $this-verificationCode, expiryMinutes $expiryMinutes, ]);对应的视图模板位于resources/views/emails/含email-change-verification.blade.php、invitation-link.blade.php、reset-password.blade.php、application-restart-limit-reached.blade.php等。可以推断这一选择源于 Coolify 邮件需要携带按钮、多语言文案与自定义发件人头等较重的定制需求而文档推荐的 Markdown Mailable 模式仍适合新增的简单事务邮件——config/mail.php中的主题与views/vendor/mail组件路径配置即为该路线预留了全局样式定制入口。规则五将“内容测试”与“发送测试”分离原始规则说明Content tests: instantiate the mailable directly, callassertSeeInHtml(). Sending tests: useMail::fake()andassertSent()/assertQueued(). Dont mix them — it conflates concerns and makes tests brittle.两类测试回答的是两个不同问题混在一起会让任何一个变化改模板文案、改派发通道都牵连另一类用例测试类型回答的问题典型写法内容测试邮件正文是否包含期望内容、变量是否正确填充直接newMailable调用assertSeeInHtml()/assertDontSeeInHtml()发送测试该 Mailable 是否按预期被派发发送/入队、次数是否正确Mail::fake()或Notification::fake()assertSent()/assertQueued()内容测试示例可直接复制的骨架it(renders the verification code and expiry in the email body, function () { $user User::factory()-create(); $notification new EmailChangeVerification($user, 123456, newexample.com, now()-addMinutes(10)); $mail $notification-toMail($user); expect((string) $mail-render()) -toContain(123456) -toContain(newexample.com); });发送测试示例与 EmailChangeVerificationTest 风格一致it(generates a 6-digit verification code when requesting email change, function () { Notification::fake(); $user User::factory()-create(); $user-requestEmailChange(newemailexample.com); $user-refresh(); expect($user-pending_email)-toBe(newemailexample.com) -and($user-email_change_code)-toMatch(/^\d{6}$/); });注意第二个用例只断言业务状态验证码生成、过期时间写入完全不关心邮件“是否发出”——这正是规则强调的“不混用”发送链路的变化不会使内容断言变脆反之亦然。支撑链路速览从规则到 Coolify 的完整发送管线为了让上述五条规则可以对照验证这里补充 Coolify 邮件发送的运行时链路均可在仓库中直接查看运行时发件人配置set_transanctional_email_settings() 依据instanceSettings()中resend_enabled/smtp_enabled决定走 Resend 还是 SMTP并通过ConfigurationRepository::updateMailConfig()更新运行期mail配置mail_from_message()负责设置 From 头并对 ProtonMail 服务器做了 From 头换行长度特判prevent_mail_from_header_folding上限 998 字符。SMTP 传输构建SmtpTransportFactory 根据smtp_host/smtp_port/smtp_encryptionnone/starttls/tls构建EsmtpTransportnone模式下显式setAutoTls(false)并支持smtp_ehlo_domainEHLO 本地域与smtp_timeout超时设置。邮箱归一化normalize_email_identity() 对 gmail.com/googlemail.com 地址去除后缀与.用于收件人身份比对——这是与发送测试“发给谁”直接相关的边界逻辑。通道兜底TransactionalEmailChannel 在smtp_enabled与resend_enabled均未开启时静默返回并支持newEmail属性覆盖默认收件人改邮验证邮件需发给新地址而非账号当前地址。小结规则一ShouldQueue在 Coolify 中收敛为基类 CustomEmailNotification 的统一实现附带退避重试参数配合onQueue(high)实现优先级分离规则二afterCommit()可见于 RestartLimitReached 等事务敏感通知的构造函数规则三assertQueued()与规则五内容/发送测试分离直接对应tests/Feature/下 ApiTokenExpirationWarningTest、EmailChangeVerificationTest 等用例的写法规则四Markdown Mailable在本仓库中体现为 config/mail.php 的主题配置预留现有正文仍以 Blade 视图实现属于可按项目风格取舍的选项而非硬性现状。五条规则共同指向同一个工程目标让“发不发、何时发、发到哪”这些决策从调用点与测试细节中抽离集中到 Mailable 类、队列配置与测试分层这三个可审查的位置。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考