缓存
简介
你的应用程序执行的某些数据检索或处理任务可能会占用大量 CPU 或需要几秒钟才能完成。在这种情况下,通常会将检索到的数据缓存一段时间,以便在后续对相同数据的请求中可以快速检索。缓存的数据通常存储在非常快速的数据存储中,例如 Memcached 或 Redis。
幸运的是,Laravel 为各种缓存后端提供了一个富有表现力、统一的 API,让你可以利用它们极快的数据检索速度并加速你的 Web 应用程序。
配置
你的应用程序的缓存配置文件位于 config/cache.php。在此文件中,你可以指定默认情况下在整个应用程序中使用的缓存存储。Laravel 开箱即支持流行的缓存后端,如 Memcached、Redis、DynamoDB 和关系数据库。此外,还提供了一个基于文件的缓存驱动程序,而 array 和 null 缓存驱动程序为你的自动化测试提供了方便的缓存后端。
缓存配置文件还包含许多你可以查看的其他选项。默认情况下,Laravel 配置为使用 database 缓存驱动程序,该驱动程序将序列化的缓存对象存储在应用程序的数据库中。
驱动程序前置条件
数据库
当使用 database 缓存驱动程序时,你需要一个数据库表来包含缓存数据。通常,这包含在 Laravel 默认的 0001_01_01_000001_create_cache_table.php 数据库迁移中;但是,如果你的应用程序不包含此迁移,你可以使用 make:cache-table Artisan 命令来创建它:
php artisan make:cache-table
php artisan migrateMemcached
使用 Memcached 驱动程序需要安装 Memcached PECL 包。你可以在 config/cache.php 配置文件中列出所有 Memcached 服务器。此文件已经包含一个 memcached.servers 条目来帮助你入门:
'memcached' => [
// ...
'servers' => [
[
'host' => env('MEMCACHED_HOST', '127.0.0.1'),
'port' => env('MEMCACHED_PORT', 11211),
'weight' => 100,
],
],
],如果需要,你可以将 host 选项设置为 UNIX 套接字路径。如果这样做,port 选项应设置为 0:
'memcached' => [
// ...
'servers' => [
[
'host' => '/var/run/memcached/memcached.sock',
'port' => 0,
'weight' => 100
],
],
],Redis
在使用 Redis 缓存与 Laravel 之前,你需要通过 PECL 安装 PhpRedis PHP 扩展,或者通过 Composer 安装 predis/predis 包 (~2.0)。Laravel Sail 已经包含此扩展。此外,官方的 Laravel 应用程序平台,如 Laravel Cloud 和 Laravel Forge,默认安装了 PhpRedis 扩展。
有关配置 Redis 的更多信息,请查阅其 Laravel 文档页面。
DynamoDB
在使用 DynamoDB 缓存驱动程序之前,你必须创建一个 DynamoDB 表来存储所有缓存数据。通常,此表应命名为 cache。但是,你应该根据 cache 配置文件中 stores.dynamodb.table 配置项的值来命名该表。表名也可以通过 DYNAMODB_CACHE_TABLE 环境变量设置。
该表还应有一个字符串分区键,其名称对应于应用程序 cache 配置文件中 stores.dynamodb.attributes.key 配置项的值。默认情况下,分区键应命名为 key。
通常,DynamoDB 不会主动从表中移除过期的项目。因此,你应该在表上启用生存时间 (TTL)。配置表的 TTL 设置时,应将 TTL 属性名称设置为 expires_at。
接下来,安装 AWS SDK,以便你的 Laravel 应用程序可以与 DynamoDB 通信:
composer require aws/aws-sdk-php此外,你应该确保为 DynamoDB 缓存存储配置选项提供了值。通常,这些选项,如 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY,应在应用程序的 .env 配置文件中定义:
'dynamodb' => [
'driver' => 'dynamodb',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
'table' => env('DYNAMODB_CACHE_TABLE', 'cache'),
'endpoint' => env('DYNAMODB_ENDPOINT'),
],MongoDB
如果你正在使用 MongoDB,官方 mongodb/laravel-mongodb 包提供了一个 mongodb 缓存驱动程序,可以使用 mongodb 数据库连接进行配置。MongoDB 支持 TTL 索引,可用于自动清除过期的缓存项。
有关配置 MongoDB 的更多信息,请参阅 MongoDB 的缓存和锁文档。
缓存用法
获取缓存实例
要获取缓存存储实例,你可以使用 Cache 门面,我们将在本文档中使用它。Cache 门面提供了对 Laravel 缓存契约底层实现的便捷、简洁的访问:
<?php
namespace App\Http\Controllers;
use Illuminate\Support\Facades\Cache;
class UserController extends Controller
{
/**
* 显示应用程序的所有用户列表。
*/
public function index(): array
{
$value = Cache::get('key');
return [
// ...
];
}
}访问多个缓存存储
使用 Cache 门面,你可以通过 store 方法访问各种缓存存储。传递给 store 方法的键应对应于 cache 配置文件中 stores 配置数组中的存储之一:
$value = Cache::store('file')->get('foo');
Cache::store('redis')->put('bar', 'baz', 600); // 10 分钟从缓存中检索项目
Cache 门面的 get 方法用于从缓存中检索项目。如果缓存中不存在该项目,将返回 null。如果你愿意,可以向 get 方法传递第二个参数,指定如果项目不存在时希望返回的默认值:
$value = Cache::get('key');
$value = Cache::get('key', 'default');你甚至可以将闭包作为默认值传递。如果指定项目在缓存中不存在,将返回闭包的结果。传递闭包允许你延迟从数据库或其他外部服务检索默认值:
$value = Cache::get('key', function () {
return DB::table(/* ... */)->get();
});确定项目是否存在
has 方法可用于确定缓存中是否存在某个项目。如果项目存在但其值为 null,此方法也将返回 false:
if (Cache::has('key')) {
// ...
}递增/递减值
increment 和 decrement 方法可用于调整缓存中整数项目的值。这两种方法都接受一个可选的第二个参数,指示递增或递减项目值的数量:
// 如果值不存在则初始化...
Cache::add('key', 0, now()->plus(hours: 4));
// 递增或递减值...
Cache::increment('key');
Cache::increment('key', $amount);
Cache::decrement('key');
Cache::decrement('key', $amount);检索并存储
有时你可能希望从缓存中检索项目,但如果请求的项目不存在,也存储一个默认值。例如,你可能希望从缓存中检索所有用户,或者如果它们不存在,则从数据库中检索并将它们添加到缓存中。你可以使用 Cache::remember 方法执行此操作:
$value = Cache::remember('users', $seconds, function () {
return DB::table('users')->get();
});如果缓存中不存在该项目,将执行传递给 remember 方法的闭包,并将其结果放入缓存中。
你可以使用 rememberForever 方法从缓存中检索项目,如果不存在则永久存储它:
$value = Cache::rememberForever('users', function () {
return DB::table('users')->get();
});过时重新验证
当使用 Cache::remember 方法时,如果缓存值已过期,某些用户可能会遇到响应缓慢的情况。对于某些类型的数据,允许在后台重新计算缓存值的同时提供部分过时的数据是有用的,这可以防止某些用户在计算缓存值时遇到缓慢的响应。这通常被称为“过时-同时-重新验证”模式,而 Cache::flexible 方法提供了此模式的实现。
flexible 方法接受一个数组,该数组指定缓存值被视为“新鲜”的时间以及何时变为“过时”。数组中的第一个值表示缓存被视为新鲜的时间(秒),而第二个值定义在需要重新计算之前可以将其作为过时数据提供的时间。
如果在新鲜期内(第一个值之前)发出请求,则立即返回缓存而不重新计算。如果在过时期(两个值之间)发出请求,则向用户提供过时值,并注册一个延迟函数以在响应发送给用户后刷新缓存值。如果在第二个值之后发出请求,则缓存被视为已过期,并立即重新计算该值,这可能会导致用户响应较慢:
$value = Cache::flexible('users', [5, 10], function () {
return DB::table('users')->get();
});检索并删除
如果你需要从缓存中检索项目然后删除该项目,你可以使用 pull 方法。与 get 方法一样,如果缓存中不存在该项目,将返回 null:
$value = Cache::pull('key');
$value = Cache::pull('key', 'default');在缓存中存储项目
你可以使用 Cache 门面上的 put 方法在缓存中存储项目:
Cache::put('key', 'value', $seconds = 10);如果未将存储时间传递给 put 方法,则该项目将无限期存储:
Cache::put('key', 'value');除了将秒数作为整数传递,你还可以传递一个 DateTime 实例来表示缓存项的期望过期时间:
Cache::put('key', 'value', now()->plus(minutes: 10));不存在时存储
仅当缓存存储中尚不存在该项目时,add 方法才会将其添加到缓存中。如果该项目实际添加到缓存中,该方法将返回 true。否则,该方法将返回 false。add 方法是原子操作:
Cache::add('key', 'value', $seconds);延长项目生命周期
touch 方法允许你延长现有缓存项目的生命周期 (TTL)。如果缓存项存在且其过期时间成功延长,touch 方法将返回 true。如果缓存中不存在该项目,该方法将返回 false:
Cache::touch('key', 3600);你可以提供 DateTimeInterface、DateInterval 或 Carbon 实例来指定确切的过期时间:
Cache::touch('key', now()->addHours(2));永久存储项目
forever 方法可用于将项目永久存储在缓存中。由于这些项目不会过期,必须使用 forget 方法将它们从缓存中手动移除:
Cache::forever('key', 'value');NOTE
如果你使用的是 Memcached 驱动程序,当缓存达到其大小限制时,可能会移除“永久”存储的项目。
从缓存中移除项目
你可以使用 forget 方法从缓存中移除项目:
Cache::forget('key');你也可以通过提供零或负数秒的过期时间来移除项目:
Cache::put('key', 'value', 0);
Cache::put('key', 'value', -5);你可以使用 flush 方法清除整个缓存:
Cache::flush();你可以使用 flushLocks 方法清除缓存中的所有原子锁:
Cache::flushLocks();WARNING
刷新缓存不会考虑你配置的缓存“前缀”,并将从缓存中移除所有条目。在清除由其他应用程序共享的缓存时,请仔细考虑这一点。
缓存记忆化
Laravel 的 memo 缓存驱动程序允许你在单个请求或任务执行期间将解析的缓存值临时存储在内存中。这可以防止在同一执行中重复命中缓存,从而显著提高性能。
要使用记忆化缓存,调用 memo 方法:
use Illuminate\Support\Facades\Cache;
$value = Cache::memo()->get('key');memo 方法可选地接受一个缓存存储的名称,指定记忆化驱动程序将装饰的底层缓存存储:
// 使用默认缓存存储...
$value = Cache::memo()->get('key');
// 使用 Redis 缓存存储...
$value = Cache::memo('redis')->get('key');对于给定键的第一个 get 调用从缓存存储中检索值,但同一请求或任务中的后续调用将从内存中检索该值:
// 命中缓存...
$value = Cache::memo()->get('key');
// 不命中缓存,返回记忆化值...
$value = Cache::memo()->get('key');当调用修改缓存值的方法(如 put、increment、remember 等)时,记忆化缓存会自动忘记记忆化值,并将该修改方法调用委托给底层缓存存储:
Cache::memo()->put('name', 'Taylor'); // 写入底层缓存...
Cache::memo()->get('name'); // 命中底层缓存...
Cache::memo()->get('name'); // 记忆化,不命中缓存...
Cache::memo()->put('name', 'Tim'); // 忘记记忆化值,写入新值...
Cache::memo()->get('name'); // 再次命中底层缓存...缓存辅助函数
除了使用 Cache 门面,你还可以使用全局 cache 函数通过缓存检索和存储数据。当使用单个字符串参数调用 cache 函数时,它将返回给定键的值:
$value = cache('key');如果你向该函数提供一组键/值对和一个过期时间,它将在缓存中存储指定持续时间的值:
cache(['key' => 'value'], $seconds);
cache(['key' => 'value'], now()->plus(minutes: 10));当不带任何参数调用 cache 函数时,它返回一个 Illuminate\Contracts\Cache\Factory 实现的实例,允许你调用其他缓存方法:
cache()->remember('users', $seconds, function () {
return DB::table('users')->get();
});NOTE
在测试对全局 cache 函数的调用时,你可以像测试门面一样使用 Cache::shouldReceive 方法。
缓存标签
WARNING
当使用 file、dynamodb 或 database 缓存驱动程序时,不支持缓存标签。
存储带标签的缓存项目
缓存标签允许你标记缓存中的相关项目,然后刷新所有已分配给定标签的缓存值。你可以通过传递一个有序的标签名称数组来访问带标签的缓存。例如,让我们访问一个带标签的缓存并将一个值放入缓存:
use Illuminate\Support\Facades\Cache;
Cache::tags(['people', 'artists'])->put('John', $john, $seconds);
Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);访问带标签的缓存项目
如果不提供用于存储值的标签,则无法访问通过标签存储的项目。要检索带标签的缓存项,将相同顺序的标签列表传递给 tags 方法,然后使用你想要检索的键调用 get 方法:
$john = Cache::tags(['people', 'artists'])->get('John');
$anne = Cache::tags(['people', 'authors'])->get('Anne');移除带标签的缓存项目
你可以刷新所有分配了标签或标签列表的项目。例如,以下代码将移除所有标记为 people、authors 或两者的缓存。因此,Anne 和 John 都将从缓存中移除:
Cache::tags(['people', 'authors'])->flush();相比之下,下面的代码将仅移除标记为 authors 的缓存值,因此 Anne 将被移除,但 John 不会:
Cache::tags('authors')->flush();原子锁
WARNING
要利用此功能,你的应用程序必须使用 memcached、redis、dynamodb、database、file 或 array 缓存驱动程序作为应用程序的默认缓存驱动程序。此外,所有服务器必须与同一个中央缓存服务器通信。
管理锁
原子锁允许操作分布式锁而无需担心竞争条件。例如,Laravel Cloud 使用原子锁来确保一次只有一个远程任务在服务器上执行。你可以使用 Cache::lock 方法创建和管理锁:
use Illuminate\Support\Facades\Cache;
$lock = Cache::lock('foo', 10);
if ($lock->get()) {
// 锁定 10 秒...
$lock->release();
}get 方法也接受一个闭包。闭包执行后,Laravel 将自动释放锁:
Cache::lock('foo', 10)->get(function () {
// 锁定 10 秒并自动释放...
});如果在你请求时锁不可用,你可以指示 Laravel 等待指定的秒数。如果在指定时间限制内无法获取锁,将抛出 Illuminate\Contracts\Cache\LockTimeoutException 异常:
use Illuminate\Contracts\Cache\LockTimeoutException;
$lock = Cache::lock('foo', 10);
try {
$lock->block(5);
// 等待最多 5 秒后获取锁...
} catch (LockTimeoutException $e) {
// 无法获取锁...
} finally {
$lock->release();
}上面的示例可以通过向 block 方法传递闭包来简化。当向此方法传递闭包时,Laravel 将尝试在指定的秒数内获取锁,并在闭包执行后自动释放锁:
Cache::lock('foo', 10)->block(5, function () {
// 等待最多 5 秒后获取锁,持续 10 秒...
});跨进程管理锁
有时,你可能希望在一个进程中获取锁,并在另一个进程中释放它。例如,你可能在 Web 请求期间获取锁,并希望在该请求触发的排队任务结束时释放锁。在这种情况下,你应该将锁的作用域“所有者令牌”传递给排队任务,以便该任务可以使用给定的令牌重新实例化锁。
在下面的示例中,如果成功获取锁,我们将分发一个排队任务。此外,我们将通过锁的 owner 方法将锁的所有者令牌传递给排队任务:
$podcast = Podcast::find($id);
$lock = Cache::lock('processing', 120);
if ($lock->get()) {
ProcessPodcast::dispatch($podcast, $lock->owner());
}在我们应用程序的 ProcessPodcast 任务中,我们可以使用所有者令牌恢复和释放锁:
Cache::restoreLock('processing', $this->owner)->release();如果你希望在不考虑其当前所有者的情况下释放锁,可以使用 forceRelease 方法:
Cache::lock('processing')->forceRelease();并发限制
Laravel 的原子锁功能还提供了一些方法来限制闭包的并发执行。当你希望在整个基础设施中只允许一个运行实例时,使用 withoutOverlapping:
Cache::withoutOverlapping('foo', function () {
// 等待最多 10 秒后获取锁...
});默认情况下,锁会一直保持到闭包执行完成,并且该方法最多等待 10 秒来获取锁。你可以使用额外参数自定义这些值:
Cache::withoutOverlapping('foo', function () {
// 等待最多 5 秒后获取锁,持续 120 秒...
}, lockFor: 120, waitFor: 5);如果在指定的等待时间内无法获取锁,将抛出 Illuminate\Contracts\Cache\LockTimeoutException 异常。
如果你想要受控的并行度,请使用 funnel 方法设置最大并发执行数。funnel 方法适用于任何支持锁的缓存驱动程序:
Cache::funnel('foo')
->limit(3)
->releaseAfter(60)
->block(10)
->then(function () {
// 获取并发锁...
}, function () {
// 无法获取并发锁...
});funnel 键标识被限制的资源。limit 方法定义最大并发执行数。releaseAfter 方法设置在自动释放获取的插槽之前的安全超时时间(秒)。block 方法设置等待可用插槽的秒数。
如果你希望通过异常处理超时,而不是提供失败闭包,可以省略第二个闭包。如果在指定的等待时间内无法获取锁,将抛出 Illuminate\Cache\Limiters\LimiterTimeoutException 异常:
use Illuminate\Cache\Limiters\LimiterTimeoutException;
try {
Cache::funnel('foo')
->limit(3)
->releaseAfter(60)
->block(10)
->then(function () {
// 获取并发锁...
});
} catch (LimiterTimeoutException $e) {
// 无法获取并发锁...
}如果你想要为并发限制器使用特定的缓存存储,你可以在所需存储上调用 funnel 方法:
Cache::store('redis')->funnel('foo')
->limit(3)
->block(10)
->then(function () {
// 使用 "redis" 存储获取并发锁...
});NOTE
funnel 方法要求缓存存储实现 Illuminate\Contracts\Cache\LockProvider 接口。如果你尝试对不支持锁的缓存存储使用 funnel,将抛出 BadMethodCallException 异常。
缓存故障转移
failover 缓存驱动程序在与缓存交互时提供自动故障转移功能。如果 failover 存储的主缓存存储因任何原因发生故障,Laravel 将自动尝试使用列表中的下一个配置存储。这对于在缓存可靠性至关重要的生产环境中确保高可用性特别有用。
要配置故障转移缓存存储,请指定 failover 驱动程序,并提供按顺序尝试的存储名称数组。默认情况下,Laravel 在应用程序的 config/cache.php 配置文件中包含一个示例故障转移配置:
'failover' => [
'driver' => 'failover',
'stores' => [
'database',
'array',
],
],一旦你配置了使用 failover 驱动程序的存储,你需要在应用程序的 .env 文件中将故障转移存储设置为默认缓存存储,以使用故障转移功能:
CACHE_STORE=failover当缓存存储操作失败并激活故障转移时,Laravel 将调度 Illuminate\Cache\Events\CacheFailedOver 事件,允许你报告或记录缓存存储已发生故障。
添加自定义缓存驱动程序
编写驱动程序
要创建我们自己的自定义缓存驱动程序,首先我们需要实现 Illuminate\Contracts\Cache\Store 契约。因此,MongoDB 缓存实现可能如下所示:
<?php
namespace App\Extensions;
use Illuminate\Contracts\Cache\Store;
class MongoStore implements Store
{
public function get($key) {}
public function many(array $keys) {}
public function put($key, $value, $seconds) {}
public function putMany(array $values, $seconds) {}
public function increment($key, $value = 1) {}
public function decrement($key, $value = 1) {}
public function forever($key, $value) {}
public function forget($key) {}
public function flush() {}
public function getPrefix() {}
}我们只需要使用 MongoDB 连接实现这些方法中的每一个。有关如何实现这些方法的示例,请查看 Laravel 框架源代码中的 Illuminate\Cache\MemcachedStore。一旦我们的实现完成,我们可以通过调用 Cache 门面的 extend 方法来完成我们的自定义驱动程序注册:
Cache::extend('mongo', function (Application $app) {
return Cache::repository(new MongoStore);
});NOTE
如果你想知道将自定义缓存驱动程序代码放在哪里,你可以在 app 目录中创建一个 Extensions 命名空间。但是,请记住,Laravel 没有严格的应用程序结构,你可以根据自己的偏好自由组织应用程序。
注册驱动程序
要向 Laravel 注册自定义缓存驱动程序,我们将使用 Cache 门面上的 extend 方法。由于其他服务提供者可能在其 boot 方法中尝试读取缓存值,我们将在 booting 回调中注册我们的自定义驱动程序。通过使用 booting 回调,我们可以确保自定义驱动程序恰好在应用程序服务提供者的 boot 方法被调用之前,但在所有服务提供者的 register 方法被调用之后注册。我们将在应用程序的 App\Providers\AppServiceProvider 类的 register 方法中注册我们的 booting 回调:
<?php
namespace App\Providers;
use App\Extensions\MongoStore;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 注册任何应用程序服务。
*/
public function register(): void
{
$this->app->booting(function () {
Cache::extend('mongo', function (Application $app) {
return Cache::repository(new MongoStore);
});
});
}
/**
* 引导任何应用程序服务。
*/
public function boot(): void
{
// ...
}
}传递给 extend 方法的第一个参数是驱动程序的名称。这将对应于 config/cache.php 配置文件中的 driver 选项。第二个参数是一个应返回 Illuminate\Cache\Repository 实例的闭包。该闭包将传递一个 $app 实例,它是服务容器的实例。
扩展注册后,将应用程序 config/cache.php 配置文件中的 CACHE_STORE 环境变量或 default 选项更新为你的扩展名称。
事件
要在每次缓存操作时执行代码,你可以监听缓存分发的各种事件:
| 事件名称 |
|---|
Illuminate\Cache\Events\CacheFlushed |
Illuminate\Cache\Events\CacheFlushing |
Illuminate\Cache\Events\CacheFlushFailed |
Illuminate\Cache\Events\CacheLocksFlushed |
Illuminate\Cache\Events\CacheLocksFlushing |
Illuminate\Cache\Events\CacheLocksFlushFailed |
Illuminate\Cache\Events\CacheHit |
Illuminate\Cache\Events\CacheMissed |
Illuminate\Cache\Events\ForgettingKey |
Illuminate\Cache\Events\KeyForgetFailed |
Illuminate\Cache\Events\KeyForgotten |
Illuminate\Cache\Events\KeyWriteFailed |
Illuminate\Cache\Events\KeyWritten |
Illuminate\Cache\Events\RetrievingKey |
Illuminate\Cache\Events\RetrievingManyKeys |
Illuminate\Cache\Events\WritingKey |
Illuminate\Cache\Events\WritingManyKeys |
为了提高性能,你可以通过在应用程序的 config/cache.php 配置文件中为给定缓存存储将 events 配置选项设置为 false 来禁用缓存事件:
'database' => [
'driver' => 'database',
// ...
'events' => false,
],