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

引言：缓存，甜蜜的负担

作为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

)

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

StuDocuCacheableEntitiesContractsCacheable

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

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

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

<pre class="brush:php;toolbar:false;"><?php  use IlluminateDatabaseEloquentCollection; use StuDocuCacheableEntitiesContractsCacheable;  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 StuDocuCacheableEntitiesContractsSerializableCacheable;  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();     } }

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

StuDocuCacheableEntitiesExceptionsCorruptSerializedCacheValueException

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

缓存策略：同步与异步 (

SyncCache

AsyncCache

)

studocu/cacheable-entities

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

SyncCache

(同步/阻塞式缓存): 当缓存未命中时，会立即执行
```
get()
```
方法计算数据，然后缓存并返回结果。适用于需要实时数据的场景，如API接口。
AsyncCache

(异步/非阻塞式缓存): 当缓存未命中时，会派发一个Job到后台异步计算数据并写入缓存，同时立即返回一个空状态（如
```
NULL
```
、空集合或空数组）。适用于可以接受短暂数据延迟的场景，如Web页面。

使用起来非常直观：

<pre class="brush:php;toolbar:false;"><?php  use StuDocuCacheableEntitiesAsyncCache; use StuDocuCacheableEntitiesSyncCache;  $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 StuDocuCacheableEntitiesConcernsSelfCacheable;  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等静态分析工具的泛型注解，提升代码的可读性和类型安全性。