本文旨在指导读者如何在 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
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
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() 直接发送的邮件保持同步。
# config/packages/messenger.yaml
framework:
messenger:
transports:
# 定义异步传输，通常使用 DSN 从环境变量获取连接字符串
async: '%env(MESSENGER_TRANSPORT_DSN)%'
routing:
# 将自定义的 EmailAsync 消息路由到异步传输
'App\Message\EmailAsync': async
# 保持 Symfony\Component\Mailer\Messenger\SendEmailMessage 不被路由到异步
# 这样，通过 MailerInterface::send() 直接发送的邮件将默认同步处理
# 如果不在这里明确指定，它会走默认的同步处理流程。
# 如果需要对所有邮件做统一处理，可以考虑在这里添加一个 'sync' 传输，
# 或者干脆不配置它，让其走默认的同步处理。
# 'Symfony\Component\Mailer\Messenger\SendEmailMessage': sync # 示例：明确路由到同步传输通过上述配置，只有 EmailAsync 消息才会被推入异步队列。而任何直接调用 MailerInterface::send() 发送的 TemplatedEmail，由于其对应的 SendEmailMessage 未被路由到异步传输，将会在当前请求中同步发送。
步骤四：在服务中实现同步与异步发送
现在，您可以在应用程序的不同服务中根据需要选择同步或异步发送邮件。
1. 异步发送邮件
在需要异步发送邮件的服务中，您应该注入 MessageBusInterface，并分发 EmailAsync 消息。
// src/Service/MailManagerAsync.php
bus = $bus;
$this->defaultSenderEmail = $defaultSenderEmail;
}
/**
* 异步发送邮件
*
* @param string $subject 邮件主题
* @param string $bodyHtmlTemplate HTML 模板路径
* @param string $bodyTextTemplate 纯文本模板路径
* @param string $to 收件人邮箱
* @param array $context 传递给模板的上下文数据
* @param string|null $sender 可选，自定义发件人邮箱
*/
public function sendAsyncEmail(
string $subject,
string $bodyHtmlTemplate,
string $bodyTextTemplate,
string $to,
array $context = [],
?string $sender = null
): void {
$emailAsync = new EmailAsync(
$subject,
$bodyHtmlTemplate,
$bodyTextTemplate,
$to,
$context,
$sender ?? $this->defaultSenderEmail
);
$this->bus->dispatch($emailAsync);
}
}2. 同步发送邮件
对于需要同步发送的邮件，您只需注入 MailerInterface 并直接调用其 send() 方法即可。
// src/Service/MailManagerSync.php
mailer = $mailer;
$this->defaultSenderEmail = $defaultSenderEmail;
}
/**
* 同步发送邮件
*
* @param string $subject 邮件主题
* @param string $bodyHtmlTemplate HTML 模板路径
* @param string $bodyTextTemplate 纯文本模板路径
* @param string $to 收件人邮箱
* @param array $context 传递给模板的上下文数据
* @param string|null $sender 可选，自定义发件人邮箱
*/
public function sendSyncEmail(
string $subject,
string $bodyHtmlTemplate,
string $bodyTextTemplate,
string $to,
array $context = [],
?string $sender = null
): void {
$email = (new TemplatedEmail())
->from(new Address($sender ?? $this->defaultSenderEmail))
->to(new Address($to))
->subject($subject)
->htmlTemplate($bodyHtmlTemplate)
->textTemplate($bodyTextTemplate)
->context($context);
$this->mailer->send($email);
}
}总结与注意事项
通过上述方法，您已经成功在 Symfony 应用程序中实现了邮件的同步与异步发送分离：
- 自定义消息和处理器：这是实现选择性异步的关键。它允许您精确控制哪些邮件流程应通过 Messenger 队列处理。
- Messenger 路由配置：只将自定义的异步消息路由到异步传输，而让 MailerInterface::send() 产生的默认消息（SendEmailMessage）保持同步处理，避免了重复发送和不必要的队列化。
- 服务分离：创建不同的服务（或在同一服务中提供不同方法）来处理同步和异步邮件发送，使得代码结构更清晰，易于维护。
重要提示：
-
Messenger 消费者：对于异步邮件，您需要运行 Messenger 消费者进程来处理队列中的消息。在生产环境中，这通常通过 Supervisor 或 Systemd 等工具管理：
php bin/console messenger:consume async --time-limit=3600
- 错误处理：在消息处理器中，应考虑增加健壮的错误处理机制，例如日志记录、重试策略或将失败消息发送到单独的失败队列。
- 环境变量：确保 MESSENGER_TRANSPORT_DSN 环境变量已正确配置，指向您的消息队列服务（如 RabbitMQ, Redis, Doctrine 等）。
- 默认发件人：建议将默认发件人邮箱配置为应用程序参数，并在服务中注入，以提高灵活性。
遵循这些步骤和最佳实践，您将能够在 Symfony 应用中高效且灵活地管理邮件发送，从而提升整体性能和可靠性。
