README

一个用于在 Magento 中可靠处理异步事件的框架。

异步：该模块使用 RabbitMQ（或 DB 队列）利用异步消息传递。
灵活：解耦事件和分发，为消息建模提供更大的灵活性。
可扩展：自动处理背压并提供异步故障转移模型。

安装

$ composer require mage-os/mageos-async-events

安装模块

$ bin/magento setup:upgrade

使用

定义异步事件

在模块的 etc/ 目录下创建一个新的 async_events.xml。

<?xml version="1.0"?>
<config
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:module:MageOS_AsyncEvents:etc/async_events.xsd"
>
    <async_event name="sales.order.created">
        <service class="Magento\Sales\Api\OrderRepositoryInterface" method="get"/>
    </async_event>
</config>

创建订阅

提示

要查看所有可用的事件接收器，请查看异步事件接收器

HTTP

curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "asyncEvent": {
        "event_name": "sales.order.created",
        "recipient_url": "https://example.com/order_created",
        "verification_token": "supersecret",
        "metadata": "http"
    }
}'

Amazon EventBridge

需要AWS 接收器包

curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "asyncEvent": {
        "event_name": "sales.order.created",
        "recipient_url": "arn:aws:events:ap-southeast-2:ACCOUNT_ID:rule/BUS_NAME",
        "verification_token": "supersecret",
        "metadata": "eventbridge"
    }
}'

派发异步事件

use \MageOS\AsyncEvents\Model\AsyncEventPublisher;

// ...

public function __construct(private readonly AsyncEventPublisher $asyncEventPublisher) {}

public function execute(Observer $observer): void
{
    /** @var Order $order */
    $order = $observer->getData('order');

    // arguments are the inputs required by the service class in the asynchronous
    // event definition in async_events.xml
    // e.g: Magento\Sales\Api\OrderRepositoryInterface::get
    $message = ['id' => $order->getId()];

    $this->asyncEventPublisher->publish('sales.order.created', $message);
}

确保以下消费者正在运行

bin/magento queue:consumer:start event.trigger.consumer
bin/magento queue:consumer:start event.retry.consumer

功能

跟踪

所有事件都使用 UUID 在单独的订阅级别进行记录。

从第一次投递尝试到最新尝试的所有信息都作为跟踪表呈现。事件有效负载也可供调查查看。

重试

事件会自动重试，并使用二次退避。默认重试限制为 5。最大退避时间为 60 秒。

重要

重试使用退避时需要 RabbitMQ。如果您使用 DB 队列，则二次退避不可用，您将必须实现自己的 \MageOS\AsyncEvents\Api\RetryManagementInterface

二次退避的计算方式为 min(60, pow($deathCount, 2));

要更改默认重试限制，请访问 Admin > Stores > Settings > Configuration > Advanced > System > Async Events 并更新 Maximum Deaths。

重放

可以独立于事件状态重放事件。这在调试或重放已耗尽所有重试的事件时非常有用。

重放将启动新的投递尝试链，如果它们再次失败，将尊重相同的重试机制。

Lucene 查询语法

默认情况下，所有事件都在 Elasticsearch 中进行索引。这允许您搜索事件，包括事件有效负载！

该模块支持Lucene 查询语法来查询事件数据，如属性。

以下属性在所有异步事件中都是可用的。

log_id
uuid
event_name
success
created

以下属性在不同类型的异步事件之间存在差异。

data

示例

假设您已配置以下事件

customer.created
customer.updated
customer.deleted
sales.order.created
sales.invoice.created
shipment.created
shipment.updated
shipment.deleted

您可以使用通配符如 event_name: customer.* 来查询所有客户事件，它匹配以下事件

customer.created
customer.updated
customer.deleted

您可以使用 *.created 来查询所有创建的事件，它匹配以下事件

customer.created
sales.order.created
sales.invoice.created
shipment.created

您可以使用其他可用的属性，如状态或 uuid，进一步缩小范围。

以下查询返回所有失败的客户事件：customer.* AND success: false

您可以将复杂的 lucene 查询组合起来检索事件历史记录，然后通过管理员网格作为 csv 导出，如果需要的话。

在事件有效负载中搜索

搜索事件有效负载取决于您正在搜索的事件。

以下示例事件负载中，四个属性被索引为属性。因此，您可以在 data.customer_email、data.customer_firstname、data.customer_lastname 和 data.increment_id 上进行查询。任何级别的数组内的属性都是不可搜索的。

{
    "data": {
        "customer_email": "roni_cost@example.com",
        "customer_firstname": "Veronica",
        "customer_lastname": "Costello",
        "increment_id": "CK00000001",
        "payment_additional_info": [
            {
                "key": "method_title",
                "value": "Check / Money order"
            }
        ]
    }
}

搜索所有客户电子邮件为 roni_cost@example.com 的事件

data.data.customer_email: roni_cost@example.com

搜索所有以 CK 开头且状态为成功的订单增量ID的事件

data.data.increment_id: CK* AND success: true

要关闭异步事件索引，请访问管理员 > 店铺 > 设置 > 配置 > 高级 > 系统 > 异步事件，并禁用 启用异步事件索引。

mage-os / mageos-async-events

维护者

详情