用 dict + time.time() 手动管理过期时间最直接，核心是在 getitem 或 get() 中惰性检查时间戳，写入时存值与过期时间，读取时比对当前时间并清理过期项。
用 dict + time.time() 手动管理过期时间最直接
不需要引入外部库，核心逻辑就是存值时附带一个过期时间戳，读取时先比对当前时间。关键不是“怎么存”，而是“什么时候判断过期”——必须在 __getitem__ 或 get() 里检查，不能只靠后台清理。
常见错误是写个定时线程定期扫描删除，这既增加复杂度又容易漏删（比如刚写入就过期）。更稳妥的做法是惰性删除：查的时候发现过期就 del self._data[key] 并抛 KeyError 或返回 None。
- 写入时：存
{'value': v, 'expires_at': time.time() + ttl_seconds} - 读取时：先检查
entry['expires_at'] ，过期则 <code>del并跳过返回 - 注意浮点时间精度问题，
time.time()在某些系统上可能有微秒级抖动，但对秒级 TTL 影响可忽略
用 heapq 实现带自动清理的最小堆索引
当 KV 对数量大（>10k）、且频繁插入+少量查询时，纯惰性删除会导致内存持续增长。这时可以维护一个最小堆，按 expires_at 排序，每次操作前先 heappop() 所有已过期项。
难点在于堆里的过期项可能已被手动删除（比如调用了 pop()），所以不能无脑 pop。正确做法是：堆中只存 (expires_at, key)，每次操作前循环检查堆顶，若对应 key 已不存在或未过期，则 break；否则 heappop() 并继续。
立即学习“Python免费学习笔记（深入）”；
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- 堆本身不存 value，只作索引，避免重复存储
- 删除操作（
__delitem__）需同步从堆中逻辑移除——实际不删堆元素，而是在堆顶检查时跳过无效项 - 这个方案适合写少读多、TTL 差异大的场景；如果所有 key TTL 都是 60 秒，堆收益很小
避免用 threading.Timer 为每个 key 启动独立定时器
这是初学者最容易踩的坑：给每个 key 创建一个 Timer(ttl, lambda: del_key(key))。看似精准，实则灾难——10 万个 key 就是 10 万个线程对象，Python 的 GIL 和线程调度开销会直接拖垮性能，且无法可靠回收（Timer 启动后无法取消或跟踪状态）。
真正需要精确到毫秒级过期通知的场景极少。绝大多数缓存类需求（如 session、token 存储）接受“首次访问时惰性失效”。如果真需要主动通知，应改用单个后台线程 + 有序队列（如上面的 heapq 方案），而非分散式 Timer。
-
threading.Timer的回调函数执行时机不可控，可能延迟数秒 - 即使设置
daemon=True，进程退出时 Timer 也不保证执行完毕 - 调试困难：过期行为变成异步、非确定性，单元测试极难覆盖
用 weakref 辅助清理但不能替代过期逻辑
weakref.WeakValueDictionary 看起来像解药——它会在 value 被 GC 时自动删除 key。但注意：它只响应 Python 的引用计数/垃圾回收，和“时间过期”完全无关。你无法控制它什么时候触发，也无法设置 TTL。
它唯一适用的场景是：value 本身生命周期由其他代码管理（比如某个对象销毁时，你希望 KV 自动失效）。如果你存的是 int、str、bytes 这类不可变对象，WeakValueDictionary 根本不会清理它们——因为这些对象被全局缓存，永远不会被 GC。
- 不要试图用
weakref.ref(lambda: ...)包裹闭包来模拟定时，这只会制造难以追踪的引用循环 - 混合使用
WeakValueDictionary和时间过期逻辑毫无意义，徒增复杂度 - 真要减少内存占用，优先考虑限制总容量（LRU）或明确调用
clear_expired()批量清理
过期逻辑的边界一定要划清：是“写入即承诺存活 TTL 秒”，还是“最多存活 TTL 秒”。前者必须用时间戳硬校验，后者才可能用弱引用或概率淘汰。大多数业务场景属于前者，别被“自动”二字带偏。
