缓存键必须包含API版本号，如v1_users_list、v2_users_list，避免版本混淆；配合Cache-Control头与X-API-Version标识；支持按版本前缀批量清理；存取时需校验版本字段，防止误用旧版缓存数据。
缓存键里必须带 API 版本号
不把版本号嵌进缓存 key，就等于没做版本控制。比如 /v1/users 和 /v2/users 返回结构不同，但若都用 get_users_list 作 key，旧版缓存可能污染新版响应。
正确做法是把版本号作为 key 的固定前缀或组成部分：
-
v1_users_list、v2_users_list - 或更通用：
api_v1_users?limit=10→cache_v1_users_limit_10 - 避免仅靠 URL 路径生成 key（如
md5('/v1/users')），因为路径可能相同但语义已变（比如 v1 接口被悄悄重写）
用 Cache-Control 响应头配合服务端版本标记
HTTP 缓存头本身不认“API 版本”，但能帮你规避 CDN 或浏览器缓存住错误版本。关键是在返回响应时显式声明该版本的有效期和不可复用性：
- 对
v1接口：设Cache-Control: public, max-age=300, stale-while-revalidate=60 - 对
v2接口：改用Cache-Control: public, max-age=60, must-revalidate，强制客户端在过期后重新校验 - 同时在响应头加自定义字段，如
X-API-Version: v2，方便调试时一眼识别缓存来源
缓存失效不能只靠时间，要支持按版本批量清理
光靠 max-age 不够——上线 v2 时，你得立刻让所有 v1_* key 失效，而不是等它自然过期。
立即学习“PHP免费学习笔记（深入）”；
- Redis 中可用
SCAN配合模式匹配：SCAN 0 MATCH v1_* COUNT 1000，再逐个DEL - 更稳妥的是用前缀隔离：所有 v1 缓存统一加
api:v1:前缀，清理时DEL api:v1:*（注意 Redis 不支持通配符DEL，需脚本或用redis-cli --scan --pattern 'api:v1:*' | xargs redis-cli del） - 别依赖 PHP 的
apcu_clear_cache()全局清空——它不分版本，会误伤其他接口
PHP 实现中容易漏掉的兼容点
很多开发者写了版本 key，却在反序列化或中间件里忽略版本校验逻辑，导致缓存数据被错误解包。
- 存缓存前：用
json_encode(['version' => 'v2', 'data' => $result])封装，别裸存数组 - 取缓存后：先检查
json_decode($cached, true)['version'] === 'v2'，不匹配就跳过并回源 - 如果用了
opcache缓存 PHP 脚本本身，确保v1和v2的路由文件物理路径不同（如api/v1/users.phpvsapi/v2/users.php），否则 opcache 可能复用旧编译结果
实际最难控的不是怎么设，而是「哪些地方读了缓存但没校验版本」——尤其在封装好的 SDK 或通用响应中间件里，很容易漏掉这层判断。
