Symfony 5 中实现邮件同步与异步发送的策略

本文旨在指导读者如何在 symfony 5 应用程序中灵活实现邮件的同步与异步发送。通过利用 symfony messenger 组件，创建自定义消息类和对应的处理器，并进行精确的路由配置，可以有效分离异步邮件逻辑，同时确保常规邮件发送的同步性，避免重复发送问题，从而优化用户体验和系统性能。

在现代 Web 应用中，邮件发送通常是耗时操作，将其异步化可以显著提升用户体验和应用响应速度。Symfony 5 及其更高版本通过集成 Mailer 和 Messenger 组件，提供了强大的邮件发送能力，并支持灵活的同步与异步处理。本文将详细介绍如何配置和实现这一机制，确保您能够根据业务需求选择合适的邮件发送模式。

理解 Symfony Messenger 与邮件发送机制

Symfony Mailer 组件在发送邮件时，默认会生成一个 Symfony\Component\Mailer\Messenger\SendEmailMessage 消息，并将其分发到 Messenger 总线。如果您的 Messenger 配置中将此消息路由到异步传输，那么所有通过 MailerInterface::send() 方法发送的邮件都将被异步处理。这在某些场景下是期望行为，但在需要同时支持同步和异步邮件发送时，则需要更精细的控制。

例如，如果您的 messenger.yaml 配置如下：

# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
        routing:
            'Symfony\Component\Mailer\Messenger\SendEmailMessage': async

登录后复制

此时，所有邮件都将通过 async 传输进行异步发送。为了实现选择性异步，我们需要引入自定义消息。

步骤一：创建异步邮件消息类

为了将邮件发送的具体数据封装起来，并使其能够在 Messenger 总线中传递，我们需要定义一个自定义的消息类。这个类将包含构建 TemplatedEmail 所需的所有信息。

// src/Message/EmailAsync.php
<?php

namespace App\Message;

class EmailAsync
{
    private string $subject;
    private string $bodyHtmlTemplate; // 对应 Twig 模板路径
    private string $bodyTextTemplate; // 对应纯文本模板路径
    private string $recipient;
    private array $context = [];
    private ?string $sender = null; // 可选，如果需要自定义发件人

    public function __construct(
        string $subject,
        string $bodyHtmlTemplate,
        string $bodyTextTemplate,
        string $recipient,
        array $context = [],
        ?string $sender = null
    ) {
        $this->subject = $subject;
        $this->bodyHtmlTemplate = $bodyHtmlTemplate;
        $this->bodyTextTemplate = $bodyTextTemplate;
        $this->recipient = $recipient;
        $this->context = $context;
        $this->sender = $sender;
    }

    // 为所有属性生成公共的 getter 方法
    public function getSubject(): string
    {
        return $this->subject;
    }

    public function getBodyHtmlTemplate(): string
    {
        return $this->bodyHtmlTemplate;
    }

    public function getBodyTextTemplate(): string
    {
        return $this->bodyTextTemplate;
    }

    public function getRecipient(): string
    {
        return $this->recipient;
    }

    public function getContext(): array
    {
        return $this->context;
    }

    public function getSender(): ?string
    {
        return $this->sender;
    }
}

登录后复制

步骤二：实现异步邮件消息处理器

消息处理器负责接收特定类型的消息，并执行相应的业务逻辑。对于 EmailAsync 消息，其处理器将使用 MailerInterface 来实际构建并发送邮件。

// src/MessageHandler/EmailAsyncHandler.php
<?php

namespace App\MessageHandler;

use App\Message\EmailAsync;
use Symfony\Component\Mime\Address;
use Symfony\Bridge\Twig\Mime\TemplatedEmail;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler; // Symfony 6+ 推荐，Symfony 5 仍可使用 MessageHandlerInterface

#[AsMessageHandler] // Symfony 6.0+ 推荐，替代 MessageHandlerInterface
class EmailAsyncHandler // implements MessageHandlerInterface // Symfony 5 兼容写法
{
    private MailerInterface $mailer;
    private string $defaultSenderEmail; // 从配置中获取默认发件人

    public function __construct(MailerInterface $mailer, string $defaultSenderEmail = 'noreply@example.com')
    {
        $this->mailer = $mailer;
        $this->defaultSenderEmail = $defaultSenderEmail;
    }

    public function __invoke(EmailAsync $emailAsync): void
    {
        $sender = $emailAsync->getSender() ?? $this->defaultSenderEmail;

        $emailToSend = (new TemplatedEmail())
            ->from(new Address($sender))
            ->to(new Address($emailAsync->getRecipient()))
            ->subject($emailAsync->getSubject())
            ->htmlTemplate($emailAsync->getBodyHtmlTemplate())
            ->textTemplate($emailAsync->getBodyTextTemplate())
            ->context($emailAsync->getContext());

        $this->mailer->send($emailToSend);
    }
}

登录后复制

注意事项：

• 在 Symfony 6.0 及更高版本中，推荐使用 #[AsMessageHandler] 属性来标记处理器，替代 implements MessageHandlerInterface。
• defaultSenderEmail 可以通过服务配置（例如 services.yaml）注入，确保发件人地址的灵活性。

步骤三：配置 Messenger 路由

现在，我们需要告诉 Symfony Messenger，当它遇到 App\Message\EmailAsync 类型的消息时，应该将其路由到 async 传输。同时，非常重要的一点是，不要将 Symfony\Component\Mailer\Messenger\SendEmailMessage 路由到异步传输，以确保通过 MailerInterface::send() 直接发送的邮件保持同步。

标签： php redis html 处理器 编码 app 工具 ai 路由 环境变量 邮箱 red