缓存 X API 响应:按数据变化速度定 TTL

17 min readSocialAPI 工程团队

缓存 X API 响应:按数据变化速度定 TTL

对任何按计划调 API 的东西来说,缓存是能拿到的最便宜的优化。它同时也是最容易引入「看起来像上游问题」的 bug 的地方——看板上的过期数字、每次过期都来一波惊群、以及一个一直涨到把进程撑死的缓存。

唯一真正要紧的决策是 TTL,而★所有东西用同一个 TTL 永远是错的★,因为你缓存的那些东西变化速度差得极远。推文正文永不改变。它的点赞数每几秒就变。把两者都缓存五分钟,意味着一个在被浪费地重取、另一个是错的。

如果你要定的是「长期存什么」而不是「缓存什么」,表结构决策是这件事的另一半。有个免费 demo 端点,可以拿真实响应结构来估算条目大小。


按易变程度定 TTL

响应 变化频率 TTL 理由
推文正文、作者、created_at ★永不★ 几小时到几天 发布后不可变
互动计数 一直在变 1–5 分钟 过期数字肉眼可见是错的
用户资料(bio、头像) 很少 1–6 小时 改动不频繁
粉丝数 慢,而且上游已缓存 15–60 分钟 平台自己就已经缓存了
粉丝/关注列表 慢,取起来贵 几小时 成本压倒新鲜度
搜索结果 一直在变 1–2 分钟 新命中就是它的意义
热榜 每几分钟 5 分钟 匹配上游刷新节奏

★最省调用的那个拆分:把内容和计数分开缓存。★ 它们在同一个响应里来,所以本能是缓存整个响应——但那样你要么每分钟重取一次不可变的正文,要么把过期计数供一小时。

def cache_tweet(tweet):
    # 不可变的那一半: 长 TTL
    cache.set(f"tweet:content:{tweet['id']}", {
        "text": tweet["text"],
        "author_id": tweet.get("author_id"),
        "created_at": tweet["created_at"],
    }, ttl=86400)

    # 易变的那一半: 短 TTL
    cache.set(f"tweet:metrics:{tweet['id']}", {
        "like_count": tweet.get("like_count"),
        "retweet_count": tweet.get("retweet_count"),
        "view_count": tweet.get("view_count"),
    }, ttl=120)

★注意 followers_count 在上游就已经被缓存了。★ 资料页上那个数字不是实时的——它按平台自己的节奏刷新。把它缓存 15 分钟,在已有的陈旧度之外几乎没增加什么,这让它异常地适合缓存。


惊群,它会立刻出现

一个缓存项过期了。同一秒内来了二十个请求。二十个全部 miss,二十个全部去调 API。 你把一次过期变成了二十个请求,而在高负载下这比没有缓存更糟。

import threading, time

_locks = {}
_locks_guard = threading.Lock()

def get_or_fetch(key, fetch, ttl):
    hit = cache.get(key)
    if hit is not None:
        return hit

    with _locks_guard:
        lock = _locks.setdefault(key, threading.Lock())

    with lock:                       # 每个 key 只取一次
        hit = cache.get(key)         # ← 复查: 可能已经有人填好了
        if hit is not None:
            return hit
        value = fetch()
        cache.set(key, value, ttl=ttl)
        return value

★锁里面那第二个 cache.get 就是全部意义所在。★ 没有它,每个在锁上排队的线程拿到锁之后都会自己去取一遍——你只是把惊群串行化了,没有阻止它。有了它,第一个线程填好缓存,其余全部立刻返回。

实测 20 个线程抢同一个 key:带复查 → 1 次取数;不带复查 → 20 次取数。

跨多进程或多机器时,同样的模式需要分布式锁——Redis 的 SET key value NX EX 30,而那个 TTL 很重要,它保证崩掉的持有者不会永久堵住这个 key。


供过期数据,而不是失败

有了缓存之后,它能做一件比「减少调用」更有用的事:★在 API 不响应时让你还能继续服务。★

def get_with_fallback(key, fetch, ttl, stale_ttl=3600):
    entry = cache.get_raw(key)                 # 含过期元数据
    if entry and not entry.expired:
        return entry.value

    try:
        value = fetch()
        cache.set(key, value, ttl=ttl)
        return value
    except (RateLimited, Timeout, ServiceUnavailable):
        if entry and entry.age < stale_ttl:
            return entry.value                 # 过期的、标注了的、可用的
        raise

★两分钟前的互动数胜过一个错误页。★ 重要的是标注它:把这条数据的年龄和数据一起返回,让 UI 能说「截至 2 分钟前」而不是把过期数字当成当前值。★一个默默展示旧数据的看板,比一个承认自己旧了的看板更糟。★

★只捕获真正是暂时性的失败。★ 在 404 上回退到过期数据会掩盖一次真实的删除;在 401 上会掩盖一个坏掉的 key。 限流、超时和 5xx 才是对的集合——区别在哪些错误该重试。


不会撞车的缓存键

import hashlib, json

def cache_key(endpoint: str, params: dict) -> str:
    # 排序, 让 {"a":1,"b":2} 和 {"b":2,"a":1} 产生同一个键
    canonical = json.dumps(params, sort_keys=True, separators=(",", ":"))
    digest = hashlib.sha256(canonical.encode()).hexdigest()[:16]
    return f"api:{endpoint}:{digest}"

★给参数排序比看起来重要。★ 字典顺序会随构造顺序变化,所以同一个逻辑请求可以产出两个键——在没有任何可见原因的情况下把你的命中率砍半。

不要把原始参数放进键里。 用户名和查询词可能含有缓存会特殊处理的字符,而很长的查询会让键变得笨重。哈希一下就同时绕开了这两点。

★绝不要把 API key 放进缓存键★,而且要小心把 per-user 数据缓存在共享键下。最经典的缓存 bug 就是一个用户看到了另一个用户的结果。


在写入时失效,不要只靠过期

TTL 处理一般情况。当你知道某样东西变了,不要等:

def record_deletion(tweet_id):
    cache.delete(f"tweet:content:{tweet_id}")
    cache.delete(f"tweet:metrics:{tweet_id}")
    cache.set(f"tweet:deleted:{tweet_id}", True, ttl=86400)  # 负缓存

★负缓存是大家会跳过的那部分。★ 如果一个账号不存在,把「它不存在」这个事实缓存一小时,就能让你不必每分钟再问一遍。没有它,★你最贵的请求往往是那些什么都不返回的请求★——一个检查已删除账号的监控循环会永远地敲 API,而404 有好几种值得区分的原因。

负缓存的 TTL 要比正缓存短。 封号可以被撤销,你不会想把「不存在」缓存一整天。


给内存设上界

★一个没有淘汰机制的进程内字典缓存,就是一个动机良好的内存泄漏。★

from cachetools import TTLCache
# 有界: 到容量上限时淘汰最旧的
cache = TTLCache(maxsize=10_000, ttl=300)

按你的工作集定 maxsize,不要乐观地定。 如果你监控 200 个账号,10,000 条绰绰有余。如果你在解析来自流量的任意用户查询,一个无界缓存最终会吃掉一切——★而崩溃是几天后才来的,这让它很难和你加的那个缓存联系起来。★

超过一个进程就换 Redis。 两个 worker 各有自己的进程内缓存,命中率互不相干,而且可能对同一个键供出不同的值——这会产出极难复现的 bug 报告。


要测量,否则你在猜

class Stats:
    def __init__(self):
        self.hits = self.misses = self.stale = 0
    def ratio(self):
        total = self.hits + self.misses
        return self.hits / total if total else 0.0

★命中率低于约 50%,通常意味着 TTL 对你的访问模式来说太短了★,或者你的键在碎片化。两者在你能看见之后都容易修,看不见就无从下手。

定期把这个比率和你的 API 调用数一起记下来。 调用数是你在付的钱;比率告诉你缓存是不是它变化的原因。


我们的 API 按请求计费,所以一个 TTL 定对的缓存直接转化成更小的账单——而大部分节省来自上面那个「不可变 / 易变」的拆分。用 Google 一键注册送 $0.20 额度、不用信用卡,如果你想在真实负载上量一量这个差别。


常见问题

X API 响应该缓存多久? 按易变程度定,不要用一个全局数字。 推文正文几小时到几天、互动计数 1–5 分钟、资料几小时、搜索结果一两分钟。

为什么不能所有东西用一个 TTL? 因为你缓存的东西变化速度不同。 单一 TTL 要么供出过期计数、要么无谓地重取不可变正文——通常两者同时发生。

价值最高的那个缓存改动是什么? ★把每条推拆成「长 TTL 的不可变内容」和「短 TTL 的易变指标」。★ 它们一起来,但不该一起过期。

推文正文缓存一天安全吗? 安全。 正文、作者、创建时间发布后不变。编辑功能存在于一个短窗口内,所以如果你在意那个,就把很新的帖子的 TTL 压到一小时以内。

粉丝数能缓存多久? 15 到 60 分钟都很从容,因为★这个数字在上游就已经被缓存了★。你是在给一个本来就不实时的数字增加很少的陈旧度。

什么是缓存惊群? 很多请求同时 miss 同一个刚过期的键、全部去调 API。 一次过期变成几十个请求,在高负载下比没有缓存更糟。

怎么阻止惊群? 每个键一把锁,并且在锁里面再查一次缓存。 ★没有那个复查,你只是把惊群串行化了,没有阻止它。★

锁里面的复查为什么必要? 因为否则每个在锁上排队的线程拿到锁时都会去取。 复查让它们看到第一个线程刚刚存进去的值。

跨多进程怎么做? 分布式锁——Redis 的 SET key NX EX 30。锁上那个 TTL 很重要,它保证崩掉的持有者不会无限期堵住那个键。

API 失败时该供过期数据吗? 暂时性失败该,而且要标注年龄。 两分钟前的计数胜过错误页,只要 UI 说明了它有多旧。

哪些失败该触发过期回退? 限流、超时、5xx。 不包括 404(那会掩盖真实删除),也不包括 401(那会掩盖坏掉的 key)。

缓存键怎么构造才安全? 给参数排序、规范化序列化、然后哈希。 未排序的字典会为同一个请求产出不同的键,静默地把命中率砍半。

API key 该放进缓存键吗? 不该。 绝不要在包含凭据的键下缓存,而且要小心把 per-user 数据缓存在共享键下——用户看到彼此的结果,就是这个 bug 的经典形态。

什么是负缓存? 把「某样东西不存在」这个事实缓存起来。 没有它,一个检查已删除账号的循环会永远调 API,而那些调用什么都不返回。

负缓存该存多久? 比正缓存短——几分钟,不是一天。 封号会被撤销,你不想把一个不存在的账号缓存过那个时点。

什么时候该主动失效而不是等过期? 任何你得知某样东西变了的时候——检测到删除、改名、你刚取到的资料更新。TTL 是兜底,不是唯一机制。

用进程内缓存还是 Redis? 单 worker 用进程内;一有两个就上 Redis。 各自独立的进程内缓存可能对同一个键供出不同的值,调试起来很痛苦。

maxsize 该设多大? 按工作集定。 两百个被监控的账号需要很少;缓存来自用户流量的任意查询则必须有明确上界,否则会一直涨。

无界的字典缓存真的有问题吗? ★有——它是内存泄漏。★ 故障几天后才以 OOM 的形式出现,这让它很难和你加的那个缓存联系起来。

命中率应该期待多少? 取决于访问模式,但低于约 50% 通常意味着 TTL 太短或键在碎片化。两者在测量之后都容易修。

缓存该记什么日志? 命中、未命中、供出过期数据的次数,以及你的 API 总调用数。 调用数是账单;比率解释它。

缓存对限流有帮助吗? ★直接有——缓存命中不是一个请求。★ 它常常是不动你业务逻辑就降到限流以下的最便宜办法,而且和有上限的并发配合得很好。

搜索结果能缓存吗? 可以,短时间——一到两分钟。 新命中就是搜索的意义,所以长 TTL 违背目的,但对重复的相同查询仍能省一些。

翻页的响应该缓存吗? 按页缓存,键里带上游标。 缓存一个拼装好的多页结果,意味着一页变了就让整个失效。

最常见的缓存错误是什么? ★用一个 TTL 缓存整个响应。 它保证你「计数太旧」和「正文取得太勤」同时发生,而且在有人注意到一个错误数字之前完全不可见。★


把不可变和易变拆开、按键加锁、测量命中率——三个改动,而大部分节省来自第一个。用 Google 注册送 $0.20 额度、不绑卡。