数据交付
新鲜度，是一个请求参数。
每个数据端点都接受 freshness（cache | default | live）与 max_age（秒）。按次选择：钉死便宜的缓存读，交给平台在其新鲜度窗口内决策，或强制一次全新的上游抓取。每次响应都会如实上报服务层与本次计费。
三种策略，一个参数
freshness=cache
只读平台缓存——该模式下取数管道在结构上不可达。
- 时延
- 最快：单次缓存读，无上游跳转。
- 计费
- 按该能力的缓存档 Credits 计费——多数能力为基础价的一半。
- 未命中 / 失败
- 404 DATA_NOT_FOUND。不调用上游，也不会替你抓取。
freshness=default
平台在其新鲜度窗口内决策：新鲜缓存直接返回；超龄条目按 stale 返回并触发去重的后台刷新；否则向上游现场取数。
- 时延
- 缓存命中：快。上游取数：一次上游往返，并发调用者共享同一次抓取。
- 计费
- 缓存层服务（含 stale+刷新）按缓存档计费；现场取数与实体库命中按基础价。
- 未命中 / 失败
- 自动落到取数管道——除非所有供应商失败（502 UPSTREAM_ERROR），未命中对你不可见。
freshness=live
完全跳过缓存与实体库，直接调用供应商抓取最新数据，随后回填缓存。
- 时延
- 每次都是完整的上游往返——设计上就是最慢路径。
- 计费
- 基础价；定价规则配置了 live 倍率的能力按倍率计。
- 未命中 / 失败
- live 抓取失败返回 502 UPSTREAM_ERROR——绝不把旧数据伪装成新数据。
并排对比
| 维度 | cache | default | live |
|---|---|---|---|
| 数据来源 | 仅平台缓存 | 缓存 → 实体库 → 供应商 | 永远是供应商 |
| 时延 | 最低——无上游跳转 | 缓存命中低时延；取数时一次上游往返 | 每次调用都上游往返 |
| 计费 | 缓存档 Credits | 缓存服务按缓存档，取数按基础价 | 基础价 |
| 未命中时 | 404 DATA_NOT_FOUND | 转上游取数 | 502 UPSTREAM_ERROR |
max_age：按次的新鲜度窗口
max_age 限定缓存/入库条目允许多旧（秒）。优先级：freshness > max_age > 平台自身 TTL 窗口。设 max_age=0 可拒绝一切非本次抓取的数据。
GET /v1/x/users/newdev?max_age=300 # serve cache/db entries at most 5 minutes old; # anything older triggers acquisition (default mode)
每次响应都告诉你发生了什么
meta.freshness 上报生效模式、数据年龄（秒）、服务层（cache | db | upstream）以及超龄条目是否按 stale 返回；meta.billing 上报本次计费 Credits 与是否缓存命中——事后不用猜。
"meta": {
"freshness": { "mode": "default", "age_seconds": 781,
"source_layer": "cache", "stale": false },
"billing": { "amount_credits": 100, "cache_hit": true }
}控制台的用量台账按次拆出同样的数字，一个月的流量可以逐行对账。