在Hyperf框架中启用缓存功能并不复杂，核心是利用官方提供的cache组件并结合Redis驱动完成配置与调用。Hyperf自带轻量的缓存抽象层，支持多种驱动，其中Redis是最常用的分布式缓存方案。
一、安装缓存与Redis依赖
Hyperf默认使用文件系统缓存，如果要使用Redis，需要先通过Composer引入对应的组件包。框架的缓存功能由hyperf/cache提供，而Redis驱动依赖hyperf/redis以及连接池支持。执行下面命令即可完成基础依赖安装：
composer require hyperf/cache composer require hyperf/redis
安装完成后，Hyperf会自动注册缓存相关的配置项和注解。如果你使用的是Hyperf骨架项目，cache.php配置文件通常已存在于config/autoload目录中；若没有，可以手动创建。Redis的连接配置则位于config/autoload/redis.php，这两个文件共同决定了缓存如何工作。
需要注意的是，Hyperf的Redis客户端基于Swoole协程实现，因此无需担心传统PHP-FPM下连接阻塞的问题。每个Worker进程会维护自己的Redis连接池，在高并发场景中复用连接，降低TCP握手开销。
二、配置缓存驱动为Redis
打开config/autoload/cache.php文件，可以看到default配置项以及多个handler驱动定义。我们要做的就是将默认驱动指向redis，并填写正确的Redis服务器信息。下面是一个典型的配置示例：
<?php
return [
'default' => 'redis',
'handlers' => [
'redis' => [
'class' => HyperfCacheHandlerRedisHandler::class,
'pool' => 'default',
],
],
'cache' => [
'namespace' => 'hyperf',
],
];
上面的配置中，default设置为redis后，所有通过CacheInterface调用的操作都会走RedisHandler。该Handler内部使用名为default的Redis连接池，这个池子在redis.php中定义。如果您的Redis不在本地，需要同步修改redis.php里的host和port。
redis.php的配置结构如下，其中default池对应缓存使用的实例：
<?php
return [
'default' => [
'host' => env('REDIS_HOST', '127.0.0.1'),
'port' => env('REDIS_PORT', 6379),
'auth' => env('REDIS_AUTH', null),
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
],
],
];
这种分离式配置让缓存驱动和Redis实例解耦，当业务需要多个Redis集群时，只需新增pool并在cache.php里指定不同pool名称即可，维护起来十分清晰。
三、在代码中读写Redis缓存
Hyperf推荐使用依赖注入获取缓存接口，而不是直接使用静态门面。在Service或Controller中注入HyperfCacheCacheInterface，就能调用set、get、delete等方法。下面展示一个用户信息服务中使用缓存的例子：
<?php
declare(strict_types=1);
namespace AppService;
use HyperfCacheCacheInterface;
class UserService
{
private CacheInterface $cache;
public function __construct(CacheInterface $cache)
{
$this->cache = $cache;
}
public function getUserInfo(int $userId): array
{
$key = 'user_info_' . $userId;
// 先尝试从Redis读取
$data = $this->cache->get($key);
if ($data !== null) {
return $data;
}
// 模拟数据库查询
$data = ['id' => $userId, 'name' => 'test'];
// 写入缓存，3600秒过期
$this->cache->set($key, $data, 3600);
return $data;
}
}
以上代码演示了最基础的缓存穿透防护逻辑：每次读取用户信息前先查Redis，命中就直接返回，未命中再查库并回写。set方法的第三个参数接收秒级过期时间，有效避免冷数据常驻内存。
除了手动控制，Hyperf还提供@Cacheable注解，可以用在方法上自动完成缓存代理。例如给getUserInfo方法加上注解后，框架会在调用前拦截，根据key策略查缓存，未命中才执行方法体。不过注解方式对返回值序列化有要求，复杂对象需提前处理，因此简单场景用手动注入更直观。
四、常见问题与避坑建议
很多人在集成时会遇到Class not found或驱动不生效的情况，通常是因为配置文件没发布或者缓存组件未加载。可以通过php bin/hyperf.php vendor:publish命令确认配置已生成，并重启服务让协程容器重新读取配置。
另一个易错点是序列化问题。Hyperf的RedisHandler默认使用PHP的serialize处理值，如果写入的是数组或对象，读取时会自动还原；但若其他语言服务也操作同一Redis，需注意格式不互通。此时可改用string类型手动json_encode，保持跨平台友好。
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 缓存始终为空 | default驱动仍是file | 检查cache.php中default值 |
| 连接Redis超时 | host或port配置错误 | 核对redis.php环境配置 |
| 数据写入后马上失效 | 过期时间传参为null | 明确设置正整数秒数 |
整体来看，Hyperf的Redis缓存集成属于开箱即用型，只要理清配置映射关系，半小时内就能在生产项目跑通。后续可结合注解缓存与分布式锁，进一步撑起高并发读场景。