告别缓存地狱：如何用studocu/cacheable-entities优雅管理复杂数据缓存-composer-PHP中文网

告别缓存地狱：如何用studocu/cacheable-entities优雅管理复杂数据缓存

王林

发布： 2025-08-23 10:56:02

原创

490人浏览过

Composer在线学习地址：学习地址

引言：缓存，甜蜜的负担

作为php开发者，我们深知缓存的重要性。它能让你的应用像跑车一样飞驰，用户体验蹭蹭上涨。但就像任何强大的工具一样，如果使用不当，缓存也会变成一个“甜蜜的负担”。

想象一下这样的场景：你的Laravel应用中，首页需要展示“热门书籍”，用户个人中心需要“推荐课程”，API接口需要“最新文档列表”。为了提高响应速度，你自然会想到使用缓存。于是，你可能在控制器、服务层甚至模型中，到处散布着

Cache::remember()

登录后复制

、

Cache::put()

登录后复制

等调用。

起初，这看起来很有效。但很快，问题接踵而至：

缓存键散落各处，难以维护： 不同的地方可能使用不同的命名约定，或者硬编码缓存键。当某个数据结构改变时，你得像侦探一样，在整个代码库中搜索并更新相关的缓存键。
TTL（过期时间）管理混乱： 有的地方设置1小时，有的地方设置1天，甚至有的地方忘记设置。这不仅导致数据不一致，也增加了排查问题的难度。
复杂对象的序列化与反序列化： 当你直接缓存Eloquent集合时，可能会遇到序列化开销大、缓存空间占用多，甚至反序列化后丢失模型关联关系等问题。
同步与异步缓存策略的困境： 某些场景（如API）需要立即返回数据，即使缓存未命中也必须同步计算；而另一些场景（如Web页面）则可以接受返回空数据，并在后台异步填充缓存，以避免阻塞用户。如何优雅地在这两种策略之间切换？
缓存失效（Purge）操作复杂： 当源数据更新时，如何确保所有相关缓存都被正确清除？手动清除很容易遗漏。

这些痛点，相信很多开发者都深有体会。它们不仅拖慢了开发效率，也为项目的长期维护埋下了隐患。那么，有没有一种更优雅、更统一的方式来管理这些缓存呢？

解决方案：

studocu/cacheable-entities

登录后复制

登场！

正是为了解决上述问题，StuDocu团队开发并开源了

studocu/cacheable-entities

登录后复制

这个包。它提供了一个“可缓存实体”（Cacheable Entity）的抽象层，将缓存相关的职责从业务逻辑中抽离出来，实现统一管理。

其核心思想是：将一个需要缓存的数据查询或计算逻辑封装成一个独立的“实体”，这个实体自身知道如何生成缓存键、设置过期时间，以及如何获取数据。

安装

使用Composer安装非常简单：

<pre class="brush:php;toolbar:false;">composer require studocu/cacheable-entities

登录后复制

定义一个可缓存实体 (

Cacheable

登录后复制

)

要让一个类成为可缓存实体，它需要实现

StuDocu\CacheableEntities\Contracts\Cacheable

登录后复制

接口。这个接口要求你定义三个核心方法：

```
getCacheTTL(): int
```
登录后复制
: 返回缓存的过期时间（秒）。
```
getCacheKey(): string
```
登录后复制
: 返回缓存的唯一键。
```
get(): mixed
```
登录后复制
: 返回实际需要缓存的数据。这是当缓存未命中时，系统会调用的方法来计算数据。

让我们看一个获取“推荐书籍”的例子：

<pre class="brush:php;toolbar:false;"><?php

use Illuminate\Database\Eloquent\Collection;
use StuDocu\CacheableEntities\Contracts\Cacheable;

class RecommendedBooksQuery implements Cacheable
{
    public function getCacheTTL(): int
    {
        // 缓存24小时
        return 3600 * 24;
    }

    public function getCacheKey(): string
    {
        // 统一的缓存键命名，方便管理
        return "books:popular.v1";
    }

    public function get(): Collection
    {
        // 实际的业务逻辑，从数据库查询热门书籍
        return Book::query()
            ->wherePopular()
            ->orderByDesc('document_popularity_scores.score')
            ->take(config('popular.books.limit'))
            ->get();
    }
}

登录后复制

现在，我们的“推荐书籍”查询逻辑及其缓存策略被清晰地封装在一个类中，一目了然。

更进一步：序列化与反序列化 (

SerializableCacheable

登录后复制

)

直接缓存Eloquent Collection可能会导致缓存体积过大，或者在反序列化时丢失关联关系。

studocu/cacheable-entities

登录后复制

提供了一个

SerializableCacheable

登录后复制

接口来解决这个问题。它允许你只缓存数据的“元数据”（例如，只缓存书籍ID数组），然后在反序列化时，根据这些元数据重新从数据库中加载完整的对象。

存了个图

视频图片解析/字幕/剪辑，视频高清保存/图片源图提取

查看详情

实现

SerializableCacheable

登录后复制

接口需要定义两个方法：

```
serialize(mixed $value): mixed
```
登录后复制
: 在数据即将被缓存前调用，用于将原始数据转换为适合缓存的格式。
```
unserialize(mixed $value): mixed
```
登录后复制
: 在从缓存中读取数据后调用，用于将缓存中的格式恢复为原始数据结构。

<pre class="brush:php;toolbar:false;"><?php

// ... (省略部分use和类定义)
use StuDocu\CacheableEntities\Contracts\SerializableCacheable;

class RecommendedBooksQuery implements Cacheable, SerializableCacheable
{
    // ... (getCacheTTL, getCacheKey, get 方法不变)

    /**
     * @param Collection<Book> $value
     * @return array<int>
     */
    public function serialize(mixed $value): array
    {
        // 只缓存书籍的ID数组
        return $value->pluck('id')->all();
    }

    /**
     * @param int[] $value
     * @return Collection<int, Book>
     */
    public function unserialize(mixed $value): Collection
    {
        // 从缓存的ID数组中，重新加载书籍对象
        // 注意：这里需要处理可能存在的顺序问题，例如使用 array_flip + sortBy
        if (!is_array($value) || empty($value)) {
            return Collection::empty();
        }

        $booksFastAccess = array_flip($value); // 用于快速查找原始顺序

        return Book::query()
            ->findMany($value)
            ->sortBy(fn (Book $book) => $booksFastAccess[$book->id] ?? 999) // 恢复原始顺序
            ->values();
    }
}

登录后复制

通过这种方式，我们不仅减小了缓存的体积，还确保了在反序列化时能够获取到最新、完整的书籍对象，避免了潜在的数据不一致问题。如果反序列化过程中发现缓存值损坏（例如格式错误），你可以抛出

\StuDocu\CacheableEntities\Exceptions\CorruptSerializedCacheValueException

登录后复制

，系统会自动清除该缓存并重新计算。

缓存策略：同步与异步 (

SyncCache

登录后复制

AsyncCache

登录后复制

)

studocu/cacheable-entities

登录后复制

提供了两种开箱即用的缓存策略：

SyncCache
登录后复制
(同步/阻塞式缓存): 当缓存未命中时，会立即执行
```
get()
```
登录后复制
方法计算数据，然后缓存并返回结果。适用于需要实时数据的场景，如API接口。
AsyncCache
登录后复制
(异步/非阻塞式缓存): 当缓存未命中时，会派发一个Job到后台异步计算数据并写入缓存，同时立即返回一个空状态（如
```
null
```
登录后复制
、空集合或空数组）。适用于可以接受短暂数据延迟的场景，如Web页面。

使用起来非常直观：

<pre class="brush:php;toolbar:false;"><?php

use StuDocu\CacheableEntities\AsyncCache;
use StuDocu\CacheableEntities\SyncCache;

$query = new RecommendedBooksQuery();

// 在API接口中，需要立即获取结果，即使未命中也要同步计算
$booksForApi = resolve(SyncCache::class)->get($query);

// 在Web页面中，可以先显示空数据，后台异步填充缓存，避免阻塞用户
$booksForWeb = resolve(AsyncCache::class)->get($query); // 可能返回空集合

登录后复制

此外，如果你需要获取数据的实时值，不经过任何缓存，可以直接调用实体自身的

get()

登录后复制

方法：

<pre class="brush:php;toolbar:false;">$realtimeBooks = $query->get(); // 永远获取最新数据

登录后复制

便捷之道：自缓存实体 (

SelfCacheable

登录后复制

)

为了进一步简化调用，

studocu/cacheable-entities

登录后复制

提供了一个

SelfCacheable

登录后复制

Trait。通过在你的实体类中使用这个Trait，你可以直接在实体实例上调用缓存方法，而无需通过

SyncCache

登录后复制

或

AsyncCache

登录后复制

工具类。

<pre class="brush:php;toolbar:false;"><?php

// ... (省略部分use和类定义)
use StuDocu\CacheableEntities\Concerns\SelfCacheable;

class RecommendedBooksQuery implements Cacheable, SerializableCacheable
{
    use SelfCacheable; // 使用SelfCacheable Trait

    // ... (其他方法不变)
}

$query = new RecommendedBooksQuery();

// 异步获取缓存值
$booksAsync = $query->getCachedAsync();

// 同步获取缓存值
$booksSync = $query->getCached();

// 清除该实体的缓存
$query->forgetCache();

登录后复制

这种方式让代码更加简洁，逻辑更贴近业务实体本身。

其他亮点

缓存失效： 任何时候需要清除某个实体的缓存，只需调用
```
resolve(SyncCache::class)->forget($query);
```
登录后复制
或
```
SelfCacheable
```
登录后复制
中的
```
forgetCache()
```
登录后复制
方法。
默认值： 使用
```
SupportsDefaultValue
```
登录后复制
接口，可以为
```
AsyncCache
```
登录后复制
未命中时指定一个默认返回值，而不是
```
null
```
登录后复制
或空集合。
泛型注解： 支持PHPStan等静态分析工具的泛型注解，提升代码的可读性和类型安全性。