从 0.8.x 到 0.9.x：php-enqueue/enqueue-dev 平滑迁移实战指南

从 0.8.x 到 0.9.x：php-enqueue/enqueue-dev 平滑迁移实战指南

【免费下载链接】enqueue-dev Message Queue, Job Queue, Broadcasting, WebSockets packages for PHP, Symfony, Laravel, Magento. DEVELOPMENT REPOSITORY - provided by Forma-Pro 项目地址: https://gitcode.com/gh_mirrors/en/enqueue-dev

引言：为什么这次升级至关重要？

你是否正面临消息队列系统升级的困扰？是否担心升级过程中出现兼容性问题导致服务中断？本文将为你提供一份详尽的迁移指南，帮助你顺利将 php-enqueue/enqueue-dev 从 0.8.x 版本升级到 0.9.x 版本。通过本文，你将了解到：

• 核心接口变更及如何适配
• Symfony Bundle 配置的重大调整
• 处理器注册方式的变化
• 不同框架下的迁移要点
• 常见问题解决方案与最佳实践

核心接口变更

命名空间与接口重命名

0.9.x 版本对核心接口进行了重命名，移除了接口名中的 "Psr" 前缀，以更好地符合 PHP-FIG 标准。

0.8.x 接口	0.9.x 接口	说明
Interop\Queue\PsrProcessor	Interop\Queue\Processor	消息处理器接口
Interop\Queue\PsrMessage	Interop\Queue\Message	消息接口
Interop\Queue\PsrContext	Interop\Queue\Context	上下文接口

代码示例：处理器适配

0.8.x 版本：

use Interop\Queue\PsrProcessor;
use Interop\Queue\PsrMessage;
use Interop\Queue\PsrContext;

class MyProcessor implements PsrProcessor
{
    public function process(PsrMessage $message, PsrContext $context)
    {
        // 处理消息
        return self::ACK;
    }
}

0.9.x 版本：

use Interop\Queue\Processor;
use Interop\Queue\Message;
use Interop\Queue\Context;

class MyProcessor implements Processor
{
    public function process(Message $message, Context $context)
    {
        // 处理消息
        return self::ACK;
    }
}

Symfony Bundle 配置变更

配置结构调整

0.9.x 版本对 Symfony Bundle 的配置结构进行了重大调整，将客户端名称提升为根节点。

0.8.x 版本：

enqueue:
    transport:
        default: 'amqp:'

0.9.x 版本：

enqueue:
    default:
        transport: 'amqp:'
        client: ~

注意：default_processor_queue 客户端选项已被移除。

服务标签变更

处理器注册标签被细分为多个子类型，以支持更灵活的消息路由。

0.8.x 版本：

tags:
    - { name: 'enqueue.client.processor' }

0.9.x 版本：

tags:
    - { name: 'enqueue.command_subscriber' }  # 命令订阅者
    - { name: 'enqueue.topic_subscriber' }   # 主题订阅者
    - { name: 'enqueue.processor' }          # 通用处理器

命令订阅者返回结构调整

CommandSubscriberInterface 接口的 getSubscribedCommand 方法返回结构发生了变化。

0.8.x 版本：

public static function getSubscribedCommand()
{
    return [
        'processorName' => 'aCommandName',
        'queueName' => 'a_client_queue_name',
        'queueNameHardcoded' => true,
        'exclusive' => true,
    ];
}

0.9.x 版本：

public static function getSubscribedCommand()
{
    return [
        'command' => 'aSubscribedCommand',
        'processor' => 'aProcessorName',
        'queue' => 'a_client_queue_name',
        'prefix_queue' => true,
        'exclusive' => true,
    ];
}

不同框架的迁移要点

Laravel 框架

在 Laravel 框架中，主要需要更新配置文件和队列处理器。

配置文件调整：

// config/enqueue.php
return [
    'client' => [
        'transport' => [
            'default' => 'file://'.realpath(__DIR__.'/../storage/enqueue')
        ],
        'client' => [
            'router_topic' => 'default',
            'router_queue' => 'default',
            'default_queue' => 'default',
        ],
    ],
];

处理器注册：

$app->resolving(SimpleClient::class, function (SimpleClient $client, $app) {
    $client->bindTopic('enqueue_test', function(Message $message) {
        // 处理消息
        return Processor::ACK;
    });
    return $client;
});

Magento 框架

对于 Magento 框架，需要更新配置和处理器注册方式。

配置文件调整：

<!-- app/etc/local.xml -->
<config>
  <default>
    <enqueue>
      <processors>
        <foo-processor>
          <topic>a_topic</topic>
          <helper>acme/async_foo</helper>
        </foo-processor>
      </processors>
    </enqueue>
  </default>
</config>

处理器类调整：

use Interop\Queue\Message;
use Interop\Queue\Context;
use Interop\Queue\Processor;

class Acme_Module_Helper_Async_Foo implements Processor
{
    public function process(Message $message, Context $context)
    {
        // 处理消息
        return self::ACK;
    }
}

传输层适配

AMQP 传输层

如果你使用 AMQP 传输层，需要注意以下变更：

依赖调整：

composer require enqueue/amqp-ext:^0.9

连接工厂创建：

use Enqueue\AmqpExt\AmqpConnectionFactory;

$factory = new AmqpConnectionFactory([
    'host' => 'example.com',
    'port' => 5672,
    'vhost' => '/',
    'user' => 'user',
    'pass' => 'pass',
    'persisted' => false,
]);

Redis 传输层

Redis 传输层新增了对序列化器的支持：

use Enqueue\Redis\RedisConnectionFactory;

$factory = new RedisConnectionFactory([
    'dsn' => 'redis://localhost:6379',
    'serializer' => 'json', // 或 'php'
]);

迁移步骤与最佳实践

迁移流程图

详细步骤

1. 准备工作

   • 创建项目备份
   • 查看 UPGRADE.md 和 CHANGELOG.md，了解所有变更
   • 确保开发环境与生产环境一致

2. 更新依赖

   composer require enqueue/enqueue-dev:^0.9 --update-with-dependencies
   

3. 修改核心接口引用

   • 使用 IDE 的全局替换功能，将 PsrProcessor 替换为 Processor
   • 同样替换 PsrMessage 和 PsrContext

4. 调整配置文件

   • 根据框架类型，更新相应的配置文件
   • 特别注意 Symfony Bundle 的配置结构变化

5. 更新处理器注册

   • 修改服务标签
   • 调整命令订阅者返回结构

6. 测试消息生产与消费

   • 启动消息消费者：php bin/console enqueue:consume -vvv --setup-broker
   • 发送测试消息，验证整个流程是否正常

7. 部署与监控

   • 逐步部署到生产环境
   • 密切监控消息队列状态和应用日志

常见问题解决方案

1. 接口未找到错误

   • 确保所有文件都已更新，特别是自定义处理器和消息类
   • 清除缓存：php bin/console cache:clear

2. 配置错误

   • 使用 php bin/console debug:config enqueue 检查配置
   • 确保客户端名称作为根节点存在

3. 消息消费失败

   • 检查处理器返回值是否正确（ACK, REJECT, REQUEUE）
   • 查看详细日志：php bin/console enqueue:consume -vvv

结论与展望

从 0.8.x 到 0.9.x 的升级虽然涉及一些重大变更，但通过本文提供的指南，你可以平稳完成迁移过程。这次升级带来了更清晰的架构设计和更灵活的配置选项，为未来的功能扩展奠定了基础。

即将发布的 1.0 版本将进一步提升性能和稳定性，并引入更多高级特性。建议你关注官方仓库以获取最新动态：

• 项目仓库：https://gitcode.com/gh_mirrors/en/enqueue-dev
• 官方文档：https://php-enqueue.github.io/

如果你在迁移过程中遇到任何问题，欢迎在项目的 Issue 区提问，或参与 Gitter 讨论：https://gitter.im/php-enqueue/Lobby

附录：版本兼容性矩阵

组件	0.8.x 版本	0.9.x 版本	备注
PHP	>=7.1	>=7.2	提升了 PHP 版本要求
Symfony	^3.4 | ^4.0	^4.3 | ^5.0	增加了对 Symfony 5 的支持
Laravel	^5.5	^6.0	增加了对 Laravel 6+ 的支持
Doctrine DBAL	^2.5	^3.0	升级到 DBAL 3
消息队列接口	queue-interop/queue-interop:^0.7	queue-interop/queue-interop:^0.8	遵循最新的接口标准

通过这份详尽的迁移指南，你应该能够顺利完成 php-enqueue/enqueue-dev 从 0.8.x 到 0.9.x 的升级。记住，在进行任何重大升级前，一定要做好充分的测试和备份工作，以确保生产环境的稳定性。

【免费下载链接】enqueue-dev Message Queue, Job Queue, Broadcasting, WebSockets packages for PHP, Symfony, Laravel, Magento. DEVELOPMENT REPOSITORY - provided by Forma-Pro 项目地址: https://gitcode.com/gh_mirrors/en/enqueue-dev