- content
说明
cacheResult(…) 用于在不同sql之间缓存一些数据量小但特别慢的执行结果.
缓存实现为 TtlCache(支持每个 key 独立 TTL 的内存缓存): 读路径惰性过期(短至 1 秒也精确生效), 后台由全局共享守护线程回收无人访问的过期条目, 无需人工维护.
语法
cacheResult(select ...) [on cacheable=true and clearCache=false and clearAllCache=false and cacheType=memory and ttl=900]
- cacheable
默认为 true, 表示是否开启缓存结果.
- clearCache
默认为 false, 表示是否先清空该sql的缓存.
- clearAllCache
默认为 false, 表示是否清空所有sql缓存.
- cacheType
可选 memory(默认, 内存缓存) / file(文件缓存) / none(禁用缓存).
- ttl
可选, 正整数秒, 省略时用默认值(memory=900 秒, file=86400 秒).
ttl 与缓存条目分桶
缓存 key = 子sql + “#ttl=” + 生效TTL, 因此:
- 同一子sql声明不同 ttl 时, 视为相互独立的缓存条目, 互不覆盖——每条的新鲜度契约不被其他调用方篡改;
- 期望
ttl=1的敏感调用方查到的条目, 要么是 1 秒内的新数据, 要么不存在(触发回源), 不会拿到远旧的缓存值; - clearCache 清除该调用(同 ttl)的条目; 未指定 ttl 时, 两种默认 ttl 的条目都会被清.
ttl 取值范围为 1 ~ 315360000(10 年); 非法值(非数字 / 非正数 / 空串 / 超上限)在 sql 解析期即报错, 消息带默认值引导, 例如:
ttl 必须为正整数(秒), 当前值: AAA; 省略该参数则用默认值: memory=900秒, file=86400秒
ttl 不能超过上限(10年=315360000秒), 当前值: 999999999999; 省略该参数则用默认值: memory=900秒, file=86400秒
示例
-- 敏感数据: 1 秒短缓存(防重复击穿)
cacheResult(select * from t_order where status = 1) on ttl=1
-- 准实时报表: 5 分钟
cacheResult(select * from t_report) on ttl=300
-- 静态字典: 1 天; 与上面的 5 分钟条目是不同缓存条目, 互不干扰
cacheResult(select * from t_dict) on ttl=86400
-- 回源后强制刷新此 sql 的缓存再查
cacheResult(select * from t_order where status = 1) on clearCache=true
-- 文件缓存(跨重启复用), 索引有效期 1 天
cacheResult(select * from t_big) on cacheType=file
注意事项
- 单条结果超过 5 万行(memory)或 50 万行(file)时不写入缓存, 防止撑爆内存;
- 缓存容量上限 1 万条, 超限时优先淘汰最接近过期的条目(尽力而为, 极端并发下可能短暂超限);
- file 模式在临时目录(sybn_sql_cache)落盘 json, TTL 到期仅失效索引条目, 磁盘文件需运维定期清理;
- 每次回源写入都按本次调用的 ttl 重新起算, 显式声明的 ttl 会被完整保留.
