README

此 Laravel/Lumen 包提供 Amazon SQS FIFO 队列的队列驱动。虽然 Laravel 默认支持 Amazon SQS 标准队列，但 FIFO 队列略有不同，且 Laravel 无法正确处理。这就是这个包的作用所在。

版本

此包已在 Laravel 4.1 到 Laravel 7.x 上进行过测试，尽管它可能在发布后的版本上继续工作。本节将更新以反映已测试的版本。

安装

通过 Composer

$ composer require shiftonelabs/laravel-sqs-fifo-queue

一旦更新了 composer 并安装了包，就需要加载服务提供者。

Laravel 5.5+、6.x、7.x（5.5、5.6、5.7、5.8、6.x、7.x）

此包使用自动包发现。服务提供者将自动注册。

Laravel 5.0 - 5.4

打开 config/app.php 并将以下行添加到 providers 数组中

ShiftOneLabs\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider::class,

Laravel 4（4.1、4.2）

打开 app/config/app.php 并将以下行添加到 providers 数组中

'ShiftOneLabs\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider',

Lumen 5、6、7（5.0、5.1、5.2、5.3、5.4、5.5、5.6、5.7、5.8、6.x、7.x）

打开 bootstrap/app.php 并在 "注册服务提供者" 部分下添加以下行

$app->register(ShiftOneLabs\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider::class);

配置

Laravel/Lumen 5.1+、6.x、7.x（5.1、5.2、5.3、5.4、5.5、5.6、5.7、5.8、6.x、7.x）

如果使用 Lumen，在项目根目录下创建一个 config 目录（如果尚未创建）。然后，将 vendor/laravel/lumen-framework/config/queue.php 复制到 config/queue.php。

现在，对于 Laravel 和 Lumen，打开 config/queue.php 并将以下条目添加到 connections 数组中。

'sqs-fifo' => [
    'driver' => 'sqs-fifo',
    'key' => env('SQS_KEY'),
    'secret' => env('SQS_SECRET'),
    'prefix' => env('SQS_PREFIX'),
    'suffix' => env('SQS_SUFFIX'),
    'queue' => 'your-queue-name',    // ex: queuename.fifo
    'region' => 'your-queue-region', // ex: us-east-2
    'group' => 'default',
    'deduplicator' => 'unique',
    'allow_delay' => env('SQS_ALLOW_DELAY'),
],

示例 .env 文件

SQS_KEY=ABCDEFGHIJKLMNOPQRST
SQS_SECRET=1a23bc/deFgHijKl4mNOp5qrS6TUVwXyz7ABCDef
SQS_PREFIX=https://sqs.us-east-2.amazonaws.com/123456789012
SQS_ALLOW_DELAY=false

如果您希望这成为默认连接，还可以在 >= 5.7 的 .env 文件中设置 QUEUE_CONNECTION=sqs-fifo，或在 .env 文件中设置 QUEUE_DRIVER=sqs-fifo（对于 < 5.7）。

Laravel/Lumen 5.0

如果使用 Lumen，在项目根目录下创建一个 config 目录（如果尚未创建）。然后，将 vendor/laravel/lumen-framework/config/queue.php 复制到 config/queue.php。

现在，对于 Laravel 和 Lumen，打开 config/queue.php 并将以下条目添加到 connections 数组中

'sqs-fifo' => [
    'driver' => 'sqs-fifo',
    'key'    => env('SQS_KEY'),
    'secret' => env('SQS_SECRET'),
    'queue'  => env('SQS_PREFIX').'/your-queue-name',
    'region' => 'your-queue-region',
    'group' => 'default',
    'deduplicator' => 'unique',
    'allow_delay' => env('SQS_ALLOW_DELAY'),
],

示例 .env 文件

SQS_KEY=ABCDEFGHIJKLMNOPQRST
SQS_SECRET=1a23bc/deFgHijKl4mNOp5qrS6TUVwXyz7ABCDef
SQS_PREFIX=https://sqs.us-east-2.amazonaws.com/123456789012
SQS_ALLOW_DELAY=false

如果您希望这成为默认连接，还可以在 .env 文件中设置 QUEUE_DRIVER=sqs-fifo。

Laravel 4

打开 app/config/queue.php 并将以下条目添加到 connections 数组中

'sqs-fifo' => array(
    'driver' => 'sqs-fifo',
    'key'    => 'your-public-key',   // ex: ABCDEFGHIJKLMNOPQRST
    'secret' => 'your-secret-key',   // ex: 1a23bc/deFgHijKl4mNOp5qrS6TUVwXyz7ABCDef
    'queue'  => 'your-queue-url',    // ex: https://sqs.us-east-2.amazonaws.com/123456789012/queuename.fifo
    'region' => 'your-queue-region', // ex: us-east-2
    'group' => 'default',
    'deduplicator' => 'unique',
    'allow_delay' => false,
),

如果您希望这成为默认连接，还可以更新 'default' 键为 'sqs-fifo'。

Capsule

如果您在 Lumen/Laravel 之外使用 illuminate\queue 组件 Capsule

use Illuminate\Queue\Capsule\Manager as Queue;
use ShiftOneLabs\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider;

$queue = new Queue;

$queue->addConnection([
    'driver' => 'sqs-fifo',
    'key'    => 'your-public-key',   // ex: ABCDEFGHIJKLMNOPQRST
    'secret' => 'your-secret-key',   // ex: 1a23bc/deFgHijKl4mNOp5qrS6TUVwXyz7ABCDef
    /**
     * Set "prefix"/"suffix" and/or "queue" depending on version, as described for Laravel versions above
     * 'prefix' => 'your-prefix',
     * 'suffix' => 'your-suffix',
     * 'queue' => 'your-queue-name',
     */
    'region' => 'your-queue-region', // ex: us-east-2
    'group' => 'default',
    'deduplicator' => 'unique',
    'allow_delay' => false,
], 'sqs-fifo');

// Make this Capsule instance available globally via static methods... (optional)
$queue->setAsGlobal();

// Register the 'queue' alias in the Container, then register the SQS FIFO provider.
$app = $queue->getContainer();
$app->instance('queue', $queue->getQueueManager());
(new LaravelSqsFifoQueueServiceProvider($app))->register();

凭证

如果使用 AWS 凭据的替代选项（例如使用 AWS 凭据文件），则可以省略 key 和 secret 配置选项。有关替代选项的更多信息，请参阅AWS PHP SDK 指南。

AWS STS 会话令牌

如果需要指定 AWS STS 临时会话令牌，可以添加 'token' => env('AWS_SESSION_TOKEN'), 配置选项。这对于某些特定环境（如 AWS Lambda）是必需的。

队列后缀

《suffix》配置选项用于在不指定环境后缀的情况下支持不同环境的队列。例如，如果您有一个 emails-staging.fifo 队列和一个 emails-production.fifo 队列，您可以根据环境将 suffix 配置设置为 -staging 或 -production，然后您的代码可以继续使用 emails.fifo，无需了解环境。因此，Job::dispatch()->onQueue('emails.fifo') 将使用配置中定义的 suffix 所对应的队列，即可能是 emails-staging.fifo 或 emails-production.fifo。

此功能是在 Laravel 7.x 中引入到普通 SQS 队列的，主要用于支持 Laravel Vapor。更多详情请查看功能 pull 请求。

标准 Laravel 实现与这个实现之间有两个不同之处

此包支持从 Laravel 5.1 开始的队列后缀。
SQS FIFO 队列必须以 .fifo 后缀结尾。如上例所示，配置中定义的任何 suffix 都将位于所需的 .fifo 后缀之前。请不要在后缀配置或队列名称中指定 .fifo，否则队列名称将无法正确生成。

用法

就大部分而言，此队列驱动程序的用法与内置队列驱动程序相同。但是，当与亚马逊的 SQS FIFO 队列一起工作时，有一些额外的事项需要考虑。

消息组

除了可以为每个连接有多个队列名称之外，SQS FIFO 队列还允许每个 FIFO 队列有多个“消息组”。这些消息组用于将相关的作业分组在一起，并且每个组中的作业将按照 FIFO 顺序进行处理。这很重要，因为您的队列性能可能取决于正确分配消息组的能力。如果您有 100 个作业在队列中，并且它们都属于一个消息组，那么一次只能有一个队列工作者能够处理这些作业。然而，如果它们可以逻辑上分为 5 个消息组，那么您可以有 5 个队列工作者同时处理来自队列的作业（每个组一个）。FIFO 排序是按消息组进行的。

目前，默认情况下，所有排队作业都将合并成一个组，该组在配置文件中定义。在上面的配置中，所有排队作业都将作为 default 组的一部分发送。可以使用 onMessageGroup() 方法更改每个作业的组，这将在下面进一步解释。

组 ID 必须不为空，不得超过 128 个字符，并且可以包含字母数字字符和标点符号（!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~）。

在未来的版本中，消息组将能够分配给一个函数，如下面的去重器。

去重

向 SQS FIFO 队列发送作业时，亚马逊需要一种方法来确定作业是否是队列中已存在的作业的副本。SQS FIFO 队列有一个 5 分钟的去重间隔，这意味着如果在间隔内发送了重复的消息，它将成功接受（没有错误），但不会交付或处理。

确定重复消息通常有两种方式：要么无论内容如何都认为所有消息都是唯一的，要么如果消息具有相同的内容，则认为它们是重复的。

此包通过 deduplicator 配置选项处理去重。

要使所有消息都被视为唯一的，将 deduplicator 设置为 unique。

要使内容相同的消息被视为重复项，有两种选择，具体取决于FIFO队列的配置方式。如果FIFO队列在Amazon中已启用基于内容去重功能，则应将deduplicator设置为sqs。这告诉连接依赖Amazon来确定内容唯一性。然而，如果基于内容去重功能被禁用，则应将deduplicator设置为content。注意，如果基于内容去重被禁用，且将deduplicator设置为sqs，则在尝试向队列发送作业时将生成错误。

总结

sqs - 当同一内容的消息应被视为重复项且SQS FIFO队列上启用了基于内容去重时使用。
content - 当同一内容的消息应被视为重复项但SQS FIFO队列上禁用了基于内容去重时使用。
unique - 当所有消息都应被视为唯一时，无论内容如何。

如果需要不同的去重算法，可以在容器中注册自定义去重方法。

最后，默认情况下，所有队列作业将使用配置文件中定义的去重器。可以使用withDeduplicator()方法按作业更改此设置。

延迟作业

SQS FIFO队列不支持按消息延迟，只支持按队列延迟。所需的延迟在Amazon控制台设置队列时定义。尝试在发送到FIFO队列的作业上设置延迟将没有任何效果。为了延迟作业，可以将作业push()到已定义有交付延迟的SQS FIFO队列。

由于不支持按消息延迟，使用later()方法将作业推送到SQS FIFO队列将默认抛出BadMethodCallException异常。但是，可以使用allow_delay配置选项更改此行为。

将队列的allow_delay配置选项设置为true将允许later()方法将作业推送到该队列而不会抛出异常。然而，发送到later()方法的延迟参数将被完全忽略，因为延迟时间是在SQS队列本身上定义的。

注意：Laravel 5.4.36 - 5.6.35中存在一个bug，会导致所有使用\Illuminate\Bus\Queueable特质的队列Mailable对象都使用later()方法。如果您受此影响，则需要将队列的allow_delay配置选项设置为true，即使它们不允许延迟。这将防止抛出异常。

高级用法

按作业组和去重器

如果您需要更改特定作业的组或去重器，您将需要访问onMessageGroup()和withDeduplicator()方法。这些方法通过ShiftOneLabs\LaravelSqsFifoQueue\Bus\SqsFifoQueueable特提供。一旦将此特添加到您的作业类中，就可以更改特定作业的组/和/或去重器，而不会影响队列上的任何其他作业。

代码示例

作业

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use ShiftOneLabs\LaravelSqsFifoQueue\Bus\SqsFifoQueueable;

class ProcessCoin implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SqsFifoQueueable, SerializesModels;

    //
}

用法

dispatch(
    (new \App\Jobs\ProcessCoin())
        ->onMessageGroup('quarter')
        ->withDeduplicator('unique')
);

注意：Laravel 4通常不支持将作业实例传递到队列，但此包可以。作业实例将被转换为仅类名，因此队列系统将继续工作，但在转换之前，消息组和去重器将从前一个作业实例中提取出来。

通知

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;
use Illuminate\Contracts\Queue\ShouldQueue;
use ShiftOneLabs\LaravelSqsFifoQueue\Bus\SqsFifoQueueable;

class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable, SqsFifoQueueable;

    //
}

用法

$user->notify(
    (new InvoicePaid($invoice))->onMessageGroup($invoice->id)
);

邮件

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Contracts\Queue\ShouldQueue;
use ShiftOneLabs\LaravelSqsFifoQueue\Bus\SqsFifoQueueable;

class OrderShipped extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels, SqsFifoQueueable;

    //
}

用法

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue(new OrderShipped($order)->onMessageGroup($order->number));

自定义去重器

去重器通过生成发送到队列的去重ID来工作。如果两个消息生成相同的去重ID，则第二个消息被视为重复项，并且在5分钟去重间隔内，将不会交付该消息。

如果您有一些需要用于生成去重ID的自定义逻辑，您可以注册自己的自定义去重器。去重器存储在IoC容器中，前缀为queue.sqs-fifo.deduplicator。例如，unique去重器被别名为queue.sqs-fifo.deduplicator.unique。

自定义去重器是通过在IoC中注册一个新的带前缀的别名来创建的。这个别名应该解析为一个实现了ShiftOneLabs\LaravelSqsFifoQueue\Contracts\Queue\Deduplicator接口的新对象实例。您可以定义一个新的类来实现这个接口，或者创建一个新的ShiftOneLabs\LaravelSqsFifoQueue\Queue\Deduplicators\Callback实例，该实例接受一个执行去重逻辑的Closure。定义的Closure应接受两个参数：$payload和$queue，其中$payload是发送到队列的json_encoded()消息，而$queue是消息发送到的队列名称。生成的ID不能超过128个字符，可以包含字母数字字符和标点符号（!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~）。

例如，如果您想要创建一个random去重器，该去重器会随机选择一些作业作为重复项，您可以在您的AppServiceProvider的register()方法中添加以下行：

$this->app->bind('queue.sqs-fifo.deduplicator.random', function ($app) {
    return new \ShiftOneLabs\LaravelSqsFifoQueue\Queue\Deduplicators\Callback(function ($payload, $queue) {
        // Return the deduplication id generated for messages. Randomly 0 or 1.
        return mt_rand(0,1);
    });
}

或者，如果您更喜欢创建一个新的类，您的类将如下所示：

namespace App\Deduplicators;

use ShiftOneLabs\LaravelSqsFifoQueue\Contracts\Queue\Deduplicator;

class Random implements Deduplicator
{
    public function generate($payload, $queue)
    {
        // Return the deduplication id generated for messages. Randomly 0 or 1.
        return mt_rand(0,1);
    }
}

然后您可以在您的AppServiceProvider中这样注册这个类：

$this->app->bind('queue.sqs-fifo.deduplicator.random', App\Deduplicators\Random::class);

注册了这个别名后，您可以更新配置中的deduplicator键，使用值random，或者您可以通过在作业上调用withDeduplicator('random')来为单个作业设置去重器。

贡献

欢迎贡献。请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件patrick@shiftonelabs.com联系，而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

redgirasol / laravel-sqs-fifo-queue

维护者

详细信息