README

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

版本

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

安装

通过 Composer

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

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

Laravel 5.5+、6.x、7.x、8.x (5.5, 5.6, 5.7, 5.8, 6.x, 7.x, 8.x)

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

Laravel 5.0 - 5.4

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

Piece601\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider::class,

Laravel 4 (4.1, 4.2)

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

'Piece601\LaravelSqsFifoQueue\LaravelSqsFifoQueueServiceProvider',

Lumen 5, 6, 7, 8 (5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6.x, 7.x, 8.x)

打开 bootstrap/app.php 并在 "Register Service Providers" 部分下添加以下行

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

配置

Laravel/Lumen 5.1+, 6.x, 7.x, 8.x (5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6.x, 7.x, 8.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

现在，对于 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 Piece601\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。有关此功能的详细信息，请参阅特性拉取请求。

与标准的Laravel实现相比，这两者之间有两个区别。

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

用法

总的来说，使用此队列驱动程序与内置队列驱动程序相似。然而，当与Amazon的SQS FIFO队列一起工作时，还有一些额外的事项需要考虑。

消息组

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

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

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

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

去重

当将作业发送到SQS FIFO队列时，Amazon需要一种方法来确定作业是否是队列中已存在作业的重复。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，该bug导致使用具有\Illuminate\Bus\Queueable特质的所有队列的Mailable对象都使用later()方法。如果您受到影响，您需要将队列的allow_delay配置选项设置为true，即使它们不允许延迟。这将防止抛出异常。

高级使用

按作业分组和去重器

如果您需要更改特定作业的组或去重器，则需要访问onMessageGroup()和withDeduplicator()方法。这些方法通过Piece601\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 Piece601\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 Piece601\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 Piece601\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中注册一个新的带前缀的别名来创建。这个别名应该解析到一个实现Piece601\LaravelSqsFifoQueue\Contracts\Queue\Deduplicator接口的新对象实例。您可以定义一个新的实现该接口的类，或者创建一个新的Piece601\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 \Piece601\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 Piece601\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）。有关更多信息，请参阅许可文件。

piece601 / laravel-sqs-fifo-queue

维护者

详细信息