Symfony缓存必须通过getItem()获取CacheItem再set()并save()，直接set()报错；文件缓存需显式配置且依赖filesystem包；键名含.或/需替换为_；expiresAfter()优于expiresAt()；Redis过期时间截断为整秒。
缓存写入前必须先获取有效的 CacheItem
直接调用 set() 是无效的——Symfony 的 CacheInterface 不提供这个方法。你得先用 getItem() 拿到一个 CacheItem 实例，再调用它的 set()，最后用 save() 提交。
常见错误是把缓存当键值对直写：$cache->set('key', 'value') —— 这会报 Call to undefined method 错误。
-
getItem('my_data')返回的是带状态的对象，不是原始值 - 修改值必须调用
$item->set($value)，不能赋值给属性 -
save()才真正落盘；不调用它，前面所有操作都白忙 - 如果用
ArrayAdapter测试，save()后还得用getItem()+isHit()验证是否生效
开发环境默认禁用文件缓存，改配置才能看到 var/cache/dev 里的文件
Symfony 5.4+ 在 dev 环境下默认用 ArrayAdapter（内存缓存），不写磁盘。你以为改了 cache.yaml 就生效？其实会被 debug:container 中的 cache.adapter.filesystem 别名覆盖，但实际没启用。
要让文件缓存跑起来，得在 config/packages/cache.yaml 显式指定：
framework:
cache:
app: cache.adapter.filesystem
default_psr6_provider: 'cache.provider.filesystem'
否则你会遇到：缓存读写都“成功”，但 var/cache/dev 下空空如也，调试时完全摸不着头脑。
-
cache.adapter.filesystem依赖symfony/filesystem包，缺了会报Class not found - 目录权限问题常导致
Failed to write cache file，建议用chmod -R 777 var/cache快速排除（上线勿照搬） - 使用
cache.pool类型时，记得在服务定义里加public: true，否则 DI 容器不让你get()
CacheItem::expiresAfter() 和 expiresAt() 的时间单位容易搞反
expiresAfter(3600) 是秒，expiresAt(new \DateTime('+1 hour')) 是绝对时间——但很多人传 new \DateTime('+3600 seconds')，结果缓存 1 秒就过期。因为 DateTime 解析字符串精度高，+3600 seconds 实际可能跨了毫秒级偏差，被 Symfony 内部比较逻辑判为已过期。
- 优先用
expiresAfter()，语义清晰、无时区陷阱 - 如果必须用
expiresAt()，传new \DateTimeImmutable('+1 hour')更安全（避免意外修改） - Redis 后端对过期时间有整数秒截断，传
3600.5会变成 3600 秒，别指望毫秒级控制 - 测试时用
var_dump($item->getExpiresAt())看实际值，别只信自己写的字符串
缓存键名里含点号（.）或斜杠（/）可能触发 PSR-6 兼容性问题
某些缓存池实现（比如 cache.adapter.psr6 包装的第三方适配器）对键名有严格限制。用 user.profile.123 或 api/v1/users 当键，在 APCu 或 Memcached 上可能静默失败，或者返回空值而不报错。
根本原因是 PSR-6 规范未强制定义键格式，但底层驱动往往只接受字母、数字、下划线和短横线。
- 统一用
str_replace(['.', '/'], '_', $key)预处理键名 - 避免动态拼接出含 URL 片段的键，比如
cache_key_for_{$request->getPathInfo()} - 用
bin/console debug:container --parameter=cache.default_clearer查看当前活跃的清除器是否支持你的键结构 - 线上出问题时，先用
redis-cli KEYS "user*"（仅开发环境）确认键是否真的存进去了
缓存失效逻辑比写入更难验证，尤其是 tag-based 清除——一个 invalidateTags(['user']) 调用，背后可能涉及多个 pool、多个 provider，稍不注意就漏清。别依赖“应该清掉了”这种感觉。
