Symfony Messenger 延迟消息的传输配置

Symfony Messenger 的延迟消息经常被误解成“给消息加一个等待时间”这么简单。实际排查时至少要拆成四层：消息是否被路由到异步 transport、单条消息是否带了 DelayStamp、失败后的重试策略如何等待，以及最终失败消息是否进入独立的 failure transport。

官方地址：https://symfony.com/doc/current/messenger.html

要让消息延迟处理，先把消息送入异步 transport，再用 DelayStamp 表达单条消息的初始延迟；不要把 retry strategy 的等待时间当成正常消息的定时调度。下面按“提前消费”的现场，把四类配置拆开。

问题现场：消息为什么没有等到预期时间

假设订单创建后要发送一封提醒邮件，业务代码给消息加了五秒延迟，但 worker 几乎马上就处理了它。第一反应通常是怀疑 DelayStamp 失效，实际上更常见的原因是消息仍在同步总线上，或者消息虽然路由到了 transport，却没有使用支持延迟的传输实现。

先记住这个时间线：应用 dispatch 消息，Messenger 根据 routing 决定是否写入 transport；只有进入队列后，worker 才会在可消费的时间点取出消息。DelayStamp 描述的是消息何时变得可处理，不是 PHP 当前请求阻塞多久。

初步判断：先把异步 transport 配通

下面是一份最小的 YAML 配置。它把 async 指向 Doctrine transport，并把消息类路由到这个 transport。示例中的注释说明每个参数的职责，避免把路由配置和延迟配置混在一起。

# config/packages/messenger.yaml
framework:
  messenger:
    transports:
      async: 'doctrine://default?queue_name=async'
    routing:
      # 只有路由到 transport 后，worker 才会异步消费消息
      'App\\Message\\SendReminder': async

如果使用的是 AMQP 或 Redis，也可以把 DSN 放进环境变量，避免把连接凭据写进配置文件。Symfony 官方文档列出了 Doctrine、AMQP、Redis 等传输方式；选择 transport 时要先考虑已有基础设施、延迟能力和运维方式。

# .env.local
# DSN 只描述连接与队列，凭据应由部署环境注入
MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages

# 启动独立 worker，持续消费 async transport
php bin/console messenger:consume async --time-limit=3600

动手验证：用 DelayStamp 设置单条消息延迟

确认路由正确后，再把延迟放到 dispatch 调用点。DelayStamp 的单位是毫秒，下面的 5000 表示至少等待五秒再进入处理阶段。

bus->dispatch(
            new SendReminder($orderId),
            [new DelayStamp(5000)]
        );
    }
}

这里的延迟不是可靠的业务闹钟。它受 worker 拉取、transport 实现和基础设施调度影响，适合“稍后再处理”的消息。如果需求是精确到某个未来时间点的业务日程，应单独使用调度系统或持久化计划，而不是无限叠加 DelayStamp。

定位原因：延迟配置和重试配置不是一回事

排查时最容易混淆的是两个 delay。DelayStamp 处理正常消息的首次延迟；retry_strategy.delay 只在 handler 抛出异常后生效。它们可以同时存在，但表达的是两条不同的时间线。

# config/packages/messenger.yaml
framework:
  messenger:
    transports:
      async:
        dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
        retry_strategy:
          # 失败后最多再尝试三次
          max_retries: 3
          # 第一次重试等待 1000 毫秒
          delay: 1000
          # 后续等待按 1s、2s、4s 增长
          multiplier: 2
          # 防止指数增长超过十秒
          max_delay: 10000
          # 给重试时间增加少量抖动，避免同时重试
          jitter: 0.1

如果外部服务返回了临时限流，重试等待可以适当拉长；如果异常是参数永久错误，则不应靠增加重试次数解决。对于明确不可恢复的错误，可以在 handler 中抛出 UnrecoverableMessageHandlingException，让消息停止普通重试流程。

修复方案：按职责拆分 transport 和失败队列

当提醒邮件和支付回调共享同一个队列时，一个慢 handler 可能拖住另一类消息。更稳妥的配置是按延迟要求和失败处理方式拆分 transport，并给重要消息设置独立失败队列。

# config/packages/messenger.yaml
framework:
  messenger:
    # 没有在 transport 内单独声明时，失败消息进入这里
    failure_transport: failed
    transports:
      notifications:
        dsn: '%env(MESSENGER_NOTIFICATION_DSN)%'
        retry_strategy:
          # 通知允许有限次数重试，避免失败时无限占用 worker
          max_retries: 5
          delay: 2000
          multiplier: 2
          max_delay: 60000
      failed: 'doctrine://default?queue_name=failed'
    routing:
      # 把通知类消息放到专用 transport，降低互相影响
      'App\\Message\\SendReminder': notifications

如果多个消息流共享 Doctrine 表，最好为不同 transport 指定不同的 queue_name。如果使用 AMQP，延迟队列的创建和相关参数也依赖传输配置；关闭自动建队列前要确认基础设施已经准备好，否则延迟消息可能无法按预期落到可消费的位置。

验证结果：用消息时间线复查而不是只看一条日志

修复后不要只看“dispatch 成功”。可以按下面的时间线复查：第一，dispatch 后消息是否进入目标 transport；第二，正常路径是否等过 DelayStamp 的时间；第三，handler 失败时是否按 retry strategy 重试；第四，超过最大次数后是否出现在 failure transport。

# 查看失败 transport 中的消息，默认展示一部分记录
php bin/console messenger:failed:show --stats

# 只重试指定的失败消息；先确认外部依赖已经恢复
php bin/console messenger:failed:retry 20 --force

# 消费专用 transport，并限制本次 worker 的运行时间
php bin/console messenger:consume notifications --time-limit=3600

这组命令是运维动作，不代表消息一定会成功。重试前要先处理真正的外部原因；否则失败消息会再次回到 failure transport，反而增加排查噪声。

常见误区速查

总结：把四个时间点分别说清

Symfony Messenger 的延迟配置可以用四句话记住：DSN 决定消息写到哪里，routing 决定是否异步，DelayStamp 决定单条正常消息何时可处理，retry strategy 决定失败后如何等待。再配合 failure transport，才能把失败消息留下来并形成可恢复闭环。

相关问题

DelayStamp 可以替代定时任务吗？

它适合短暂、相对宽松的延迟处理，不适合作为需要精确触发时间、可取消和可审计的业务日程系统。

为什么配置了 retry_strategy 仍然没有重试？

先检查异常是否被标记为不可恢复，再确认消息确实由 worker 从 transport 消费，以及 transport 没有在达到次数前被删除。

Doctrine transport 和 Redis transport 怎么选？

已有数据库、吞吐量适中且希望减少基础设施时可以从 Doctrine 开始；高频队列通常要结合 Redis 的容量、持久化和运维方案评估，不能只按连接字符串决定。