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安装非常简单：
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接口来解决这个问题。它允许你只缓存数据的“元数据”（例如，只缓存书籍ID数组），然后在反序列化时，根据这些元数据重新从数据库中加载完整的对象。
实现
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提供了两种开箱即用的缓存策略：
-
SyncCache
(同步/阻塞式缓存): 当缓存未命中时，会立即执行get()
方法计算数据，然后缓存并返回结果。适用于需要实时数据的场景，如API接口。 -
AsyncCache
(异步/非阻塞式缓存): 当缓存未命中时，会派发一个Job到后台异步计算数据并写入缓存，同时立即返回一个空状态（如null
、空集合或空数组）。适用于可以接受短暂数据延迟的场景，如Web页面。
使用起来非常直观：
get($query); // 在Web页面中，可以先显示空数据，后台异步填充缓存，避免阻塞用户 $booksForWeb = resolve(AsyncCache::class)->get($query); // 可能返回空集合
此外，如果你需要获取数据的实时值，不经过任何缓存，可以直接调用实体自身的
get()方法：
$realtimeBooks = $query->get(); // 永远获取最新数据
便捷之道：自缓存实体 (SelfCacheable
)
为了进一步简化调用，
studocu/cacheable-entities提供了一个
SelfCacheableTrait。通过在你的实体类中使用这个Trait，你可以直接在实体实例上调用缓存方法，而无需通过
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绝对值得一试。它将帮助你告别缓存地狱，让你的应用在性能和可维护性上都迈上一个新台阶！
