Redis

简介

Redis 是一个开源的高级键值存储。由于键可以包含字符串、哈希、列表、集合和有序集合，它也常被称为数据结构服务器。

在 Laravel 中使用 Redis 之前，我们建议你通过 PECL 安装并使用 PhpRedis PHP 扩展。相比「用户态」PHP 包，该扩展安装更复杂，但对于重度使用 Redis 的应用可能带来更好的性能。若你使用 Laravel Sail，该扩展已预装在应用的 Docker 容器中。

若无法安装 PhpRedis 扩展，可通过 Composer 安装 predis/predis 包。Predis 是一个完全用 PHP 编写的 Redis 客户端，无需任何额外扩展：

shell

composer require predis/predis

配置

你可通过 config/database.php 配置文件配置应用的 Redis 设置。在该文件中，你会看到一个 redis 数组，其中包含应用所使用的 Redis 服务器：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'default' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_DB', '0'),
    ],

    'cache' => [
        'url' => env('REDIS_URL'),
        'host' => env('REDIS_HOST', '127.0.0.1'),
        'username' => env('REDIS_USERNAME'),
        'password' => env('REDIS_PASSWORD'),
        'port' => env('REDIS_PORT', '6379'),
        'database' => env('REDIS_CACHE_DB', '1'),
    ],

],

配置文件中定义的每台 Redis 服务器都必须有名称、主机和端口，除非你用单个 URL 表示该 Redis 连接：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'default' => [
        'url' => 'tcp://127.0.0.1:6379?database=0',
    ],

    'cache' => [
        'url' => 'tls://user:password@127.0.0.1:6380?database=1',
    ],

],

配置连接协议

默认情况下，Redis 客户端连接 Redis 服务器时使用 tcp 协议；不过，你可以在 Redis 服务器的配置数组中指定 scheme 配置项，以使用 TLS / SSL 加密：

php

'default' => [
    'scheme' => 'tls',
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
],

集群

若应用使用 Redis 服务器集群，应在 Redis 配置的 clusters 键中定义这些集群。该配置键默认不存在，因此需要在应用的 config/database.php 配置文件中自行创建：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
    ],

    'clusters' => [
        'default' => [
            [
                'url' => env('REDIS_URL'),
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'username' => env('REDIS_USERNAME'),
                'password' => env('REDIS_PASSWORD'),
                'port' => env('REDIS_PORT', '6379'),
                'database' => env('REDIS_DB', '0'),
            ],
        ],
    ],

    // ...
],

默认情况下，由于 options.cluster 配置值为 redis，Laravel 会使用原生 Redis 集群。Redis 集群是很好的默认选择，因为它能优雅地处理故障转移。

在使用 Predis 时，Laravel 也支持客户端分片。不过，客户端分片不处理故障转移；因此，它主要适用于可从其他主数据存储获取的临时缓存数据。

若希望使用客户端分片而非原生 Redis 集群，可在应用的 config/database.php 配置文件中移除 options.cluster 配置值：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'clusters' => [
        // ...
    ],

    // ...
],

Predis

若希望应用通过 Predis 包与 Redis 交互，应确保 REDIS_CLIENT 环境变量的值为 predis：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'predis'),

    // ...
],

除默认配置选项外，Predis 还支持可为每台 Redis 服务器定义的额外连接参数。要使用这些额外配置选项，请将它们添加到应用 config/database.php 配置文件中的 Redis 服务器配置里：

php

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_write_timeout' => 60,
],

PhpRedis

默认情况下，Laravel 使用 PhpRedis 扩展与 Redis 通信。Laravel 用于与 Redis 通信的客户端由 redis.client 配置项的值决定，该值通常对应 REDIS_CLIENT 环境变量：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    // ...
],

除默认配置选项外，PhpRedis 还支持以下额外连接参数：name、persistent、persistent_id、prefix、read_timeout、retry_interval、max_retries、backoff_algorithm、backoff_base、backoff_cap、timeout 和 context。你可将这些选项中的任意项添加到 config/database.php 配置文件中的 Redis 服务器配置里：

php

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'read_timeout' => 60,
    'context' => [
        // 'auth' => ['username', 'secret'],
        // 'stream' => ['verify_peer' => false],
    ],
],

重试与退避配置

可使用 retry_interval、max_retries、backoff_algorithm、backoff_base 和 backoff_cap 选项配置 PhpRedis 客户端如何尝试重新连接 Redis 服务器。支持以下退避算法：default、decorrelated_jitter、equal_jitter、exponential、uniform 和 constant：

php

'default' => [
    'url' => env('REDIS_URL'),
    'host' => env('REDIS_HOST', '127.0.0.1'),
    'username' => env('REDIS_USERNAME'),
    'password' => env('REDIS_PASSWORD'),
    'port' => env('REDIS_PORT', '6379'),
    'database' => env('REDIS_DB', '0'),
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
    'backoff_algorithm' => env('REDIS_BACKOFF_ALGORITHM', 'decorrelated_jitter'),
    'backoff_base' => env('REDIS_BACKOFF_BASE', 100),
    'backoff_cap' => env('REDIS_BACKOFF_CAP', 1000),
],

在短暂的连接失败后，Laravel 会自动对安全的读命令重试一次。你可使用 command_retries 选项配置所有 Redis 命令的重试次数：

php

'default' => [
    // ...
    'command_retries' => env('REDIS_COMMAND_RETRIES', 0),
],

Predis 3.4.0 及更高版本通过 Retry 类支持内置的重试与退避配置。你可使用 max_retries 选项配置重试，并使用 retry 选项配置退避策略。retry 选项应为以以下策略类之一为键的数组：NoBackoff、EqualBackoff 或 ExponentialBackoff：

php

use Predis\Retry\Strategy\ExponentialBackoff;

'default' => [
    'url' => env('REDIS_URL'),
    // ...
    'retry' => [
        ExponentialBackoff::class => [
            env('REDIS_BACKOFF_BASE', 100),
            env('REDIS_BACKOFF_CAP', 1000),
            true, // Enable jitter...
        ],
    ],
    'max_retries' => env('REDIS_MAX_RETRIES', 3),
],

在 Predis 配合 Redis 集群使用时，可在集群配置的 parameters 选项中定义重试配置：

php

use Predis\Retry\Strategy\NoBackoff;

'clusters' => [
    'default' => [
        // ...
    ],
],

'options' => [
    'cluster' => env('REDIS_CLUSTER', 'redis'),
    'parameters' => [
        'retry' => [
            NoBackoff::class => [],
        ],
        'max_retries' => env('REDIS_MAX_RETRIES', 3),
    ],
],

Unix Socket 连接

Redis 连接也可配置为使用 Unix socket 而非 TCP。对于与应用位于同一服务器上的 Redis 实例，这可通过消除 TCP 开销提升性能。要配置 Redis 使用 Unix socket，请将 REDIS_HOST 环境变量设为 Redis socket 的路径，并将 REDIS_PORT 环境变量设为 0：

ini

REDIS_HOST=/run/redis/redis.sock
REDIS_PORT=0

PhpRedis 序列化与压缩

PhpRedis 扩展也可配置为使用多种序列化器和压缩算法。这些算法可通过 Redis 配置的 options 数组进行设置：

php

'redis' => [

    'client' => env('REDIS_CLIENT', 'phpredis'),

    'options' => [
        'cluster' => env('REDIS_CLUSTER', 'redis'),
        'prefix' => env('REDIS_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_').'_database_'),
        'serializer' => Redis::SERIALIZER_MSGPACK,
        'compression' => Redis::COMPRESSION_LZ4,
    ],

    // ...
],

当前支持的序列化器包括：Redis::SERIALIZER_NONE（默认）、Redis::SERIALIZER_PHP、Redis::SERIALIZER_JSON、Redis::SERIALIZER_IGBINARY 和 Redis::SERIALIZER_MSGPACK。

支持的压缩算法包括：Redis::COMPRESSION_NONE（默认）、Redis::COMPRESSION_LZF、Redis::COMPRESSION_ZSTD 和 Redis::COMPRESSION_LZ4。

与 Redis 交互

你可通过在 Redis facade 上调用各种方法与 Redis 交互。Redis facade 支持动态方法，这意味着你可以在 facade 上调用任意 Redis 命令，该命令会直接传递给 Redis。本例中，我们将通过在 Redis facade 上调用 get 方法来执行 Redis GET 命令：

php

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Redis;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     */
    public function show(string $id): View
    {
        return view('user.profile', [
            'user' => Redis::get('user:profile:'.$id)
        ]);
    }
}

如上所述，你可以在 Redis facade 上调用任意 Redis 命令。Laravel 使用魔术方法将命令传递给 Redis 服务器。若 Redis 命令需要参数，应将这些参数传给 facade 的对应方法：

php

use Illuminate\Support\Facades\Redis;

Redis::set('name', 'Taylor');

$values = Redis::lrange('names', 5, 10);

或者，你可使用 Redis facade 的 command 方法将命令传递给服务器，该方法接受命令名作为第一个参数，以及值数组作为第二个参数：

php

$values = Redis::command('lrange', ['name', 5, 10]);

使用多个 Redis 连接

应用的 config/database.php 配置文件允许你定义多个 Redis 连接 / 服务器。你可使用 Redis facade 的 connection 方法获取特定 Redis 连接：

php

$redis = Redis::connection('connection-name');

要获取默认 Redis 连接的实例，可在不传任何额外参数的情况下调用 connection 方法：

php

$redis = Redis::connection();

事务

Redis facade 的 transaction 方法为 Redis 原生的 MULTI 和 EXEC 命令提供了便捷封装。transaction 方法仅接受一个闭包作为参数。该闭包会收到一个 Redis 连接实例，并可向该实例发出任意命令。闭包内发出的所有 Redis 命令将在单个原子事务中执行：

php

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::transaction(function (Redis $redis) {
    $redis->incr('user_visits', 1);
    $redis->incr('total_visits', 1);
});

WARNING

定义 Redis 事务时，不能从 Redis 连接中检索任何值。请记住，事务会作为单个原子操作执行，且该操作要等到整个闭包完成其命令的执行后才会执行。

Lua 脚本

eval 方法提供了另一种在单个原子操作中执行多条 Redis 命令的方式。不过，eval 的优势在于能在该操作期间与 Redis 键值交互并检查它们。Redis 脚本使用 Lua 编程语言编写。

eval 方法起初可能有些令人生畏，但我们会用一个基础示例来破冰。eval 方法需要若干参数。首先，应将 Lua 脚本（作为字符串）传给该方法；其次，应传入脚本所交互的键的数量（整数）；再次，应传入这些键的名称；最后，还可传入脚本中需要访问的其他额外参数。

本例中，我们将递增一个计数器，检查其新值，并在第一个计数器的值大于五时递增第二个计数器。最后返回第一个计数器的值：

php

$value = Redis::eval(<<<'LUA'
    local counter = redis.call("incr", KEYS[1])

    if counter > 5 then
        redis.call("incr", KEYS[2])
    end

    return counter
LUA, 2, 'first-counter', 'second-counter');

WARNING

有关 Redis 脚本的更多信息，请参阅 Redis 文档。

管道命令

有时你可能需要执行数十条 Redis 命令。与其为每条命令单独向 Redis 服务器发起一次网络往返，你可使用 pipeline 方法。pipeline 方法接受一个参数：接收 Redis 实例的闭包。你可将所有命令发往该 Redis 实例，它们会同时发送到 Redis 服务器，以减少与服务器的网络往返。命令仍会按发出顺序执行：

php

use Redis;
use Illuminate\Support\Facades;

Facades\Redis::pipeline(function (Redis $pipe) {
    for ($i = 0; $i < 1000; $i++) {
        $pipe->set("key:$i", $i);
    }
});

发布 / 订阅

Laravel 为 Redis 的 publish 和 subscribe 命令提供了便捷接口。这些 Redis 命令允许你监听给定「频道」上的消息。你可从另一个应用，甚至使用另一种编程语言向该频道发布消息，从而轻松实现应用与进程间的通信。

首先，我们使用 subscribe 方法设置频道监听器。由于调用 subscribe 方法会启动一个长时间运行的进程，我们将把该方法调用放在 Artisan 命令中：

php

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Redis;

class RedisSubscribe extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'redis:subscribe';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Subscribe to a Redis channel';

    /**
     * Execute the console command.
     */
    public function handle(): void
    {
        Redis::subscribe(['test-channel'], function (string $message) {
            echo $message;
        });
    }
}

现在我们可以使用 publish 方法向频道发布消息：

php

use Illuminate\Support\Facades\Redis;

Route::get('/publish', function () {
    // ...

    Redis::publish('test-channel', json_encode([
        'name' => 'Adam Wathan'
    ]));
});

通配符订阅

使用 psubscribe 方法，你可以订阅通配符频道，这在捕获所有频道上的所有消息时很有用。频道名称会作为第二个参数传给所提供的闭包：

php

Redis::psubscribe(['*'], function (string $message, string $channel) {
    echo $message;
});

Redis::psubscribe(['users.*'], function (string $message, string $channel) {
    echo $message;
});

Redis ​

简介 ​

配置 ​

配置连接协议 ​

集群 ​

Predis ​

PhpRedis ​

重试与退避配置 ​

Unix Socket 连接 ​

PhpRedis 序列化与压缩 ​

与 Redis 交互 ​

使用多个 Redis 连接 ​

事务 ​

Lua 脚本 ​

管道命令 ​

发布 / 订阅 ​

通配符订阅 ​