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

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

引言：缓存，甜蜜的负担

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

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

Cache::remember()

Cache::put()

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

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

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

解决方案：

studocu/cacheable-entities

登场！

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

studocu/cacheable-entities

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

安装

使用Composer安装非常简单：

composer require studocu/cacheable-entities

定义一个可缓存实体 (

Cacheable

)

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

StuDocu\CacheableEntities\Contracts\Cacheable

• getCacheTTL(): int

  : 返回缓存的过期时间（秒）。

• getCacheKey(): string

  : 返回缓存的唯一键。

• get(): mixed

  : 返回实际需要缓存的数据。这是当缓存未命中时，系统会调用的方法来计算数据。

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

wherePopular()
            ->orderByDesc('document_popularity_scores.score')
            ->take(config('popular.books.limit'))
            ->get();
    }
}

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

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

SerializableCacheable

)

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

studocu/cacheable-entities

SerializableCacheable

SCNet智能助手

SCNet超算互联网平台AI智能助手

下载

实现

SerializableCacheable

• serialize(mixed $value): mixed

  : 在数据即将被缓存前调用，用于将原始数据转换为适合缓存的格式。

• unserialize(mixed $value): mixed

  : 在从缓存中读取数据后调用，用于将缓存中的格式恢复为原始数据结构。

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

    /**
     * @param int[] $value
     * @return Collection
     */
    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

1. SyncCache

   (同步/阻塞式缓存): 当缓存未命中时，会立即执行

   get()

   方法计算数据，然后缓存并返回结果。适用于需要实时数据的场景，如API接口。

2. AsyncCache

   (异步/非阻塞式缓存): 当缓存未命中时，会派发一个Job到后台异步计算数据并写入缓存，同时立即返回一个空状态（如

   null

   、空集合或空数组）。适用于可以接受短暂数据延迟的场景，如Web页面。

使用起来非常直观：

get($query);

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

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

get()

$realtimeBooks = $query->get(); // 永远获取最新数据

便捷之道：自缓存实体 (

SelfCacheable

)

为了进一步简化调用，

studocu/cacheable-entities

SelfCacheable

SyncCache

AsyncCache

getCachedAsync();

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

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

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

其他亮点

• 缓存失效： 任何时候需要清除某个实体的缓存，只需调用

  resolve(SyncCache::class)->forget($query);

  或

  SelfCacheable

  中的

  forgetCache()

  方法。
• 默认值： 使用

  SupportsDefaultValue

  接口，可以为

  AsyncCache

  未命中时指定一个默认返回值，而不是

  null

  或空集合。
• 泛型注解： 支持PHPStan等静态分析工具的泛型注解，提升代码的可读性和类型安全性。

总结与展望

studocu/cacheable-entities

• 统一缓存策略： 集中管理缓存键和TTL，避免散乱和不一致。
• 优化复杂对象缓存： 通过序列化/反序列化机制，高效处理Eloquent模型等复杂数据。
• 灵活的缓存策略： 轻松应对同步和异步缓存需求。
• 提升代码可维护性： 缓存逻辑与业务逻辑解耦，代码更清晰、易于理解和测试。
• 简化操作： 提供便捷的缓存获取和失效方法。

如果你正在为应用中的缓存管理而头疼，或者希望构建一个更健壮、更易于维护的大型PHP应用，那么

studocu/cacheable-entities