随机图片 API 的客户端设计：先定随机语义，再谈缓存与降级
本文只讨论随机图片类接口在客户端侧可自行决定的工程问题：随机语义的边界、响应头需要核对什么、两层缓存怎么分、失败时如何降级，以及图片许可为何要单独确认。API.PLUS 动漫壁纸接口的路径、参数、配额与许可条款本次材料未提供，需以官方文档核对；文中的代码是未执行的占位示例。
- 随机接口最大的设计分歧在“随机”的语义：每次请求独立随机，还是可用种子复现，二者决定了去重与重试能否成立。
- 缓存要分两层：图片字节可以长缓存，但随机结果本身不应被 CDN 缓存，否则随机性会退化成固定值。
- 重试随机接口会拿到不同结果，因此重试应放在渲染路径之外，并配一个本地兜底集合。
随机图片 API 常被简化成一句 GET /random，但真正决定它能否长期用在产品里的，是客户端侧的三件事：随机语义、缓存与降级、图片许可。本文只覆盖开发者自己能决定的这部分工程约束。API.PLUS 动漫壁纸接口的具体路径、参数名、配额与图片许可条款，本次材料未提供正文说明，需以官方文档为准；下文代码是占位示例，未实际执行。
一、“随机”的语义要先定下来#
同样是随机图片接口，至少存在两种语义，客户端设计完全不同。
- 每次请求独立随机：连续两次请求大概率返回不同图片。好处是实现简单，代价是无法复现，出问题时难以定位到底返回过什么。
- 可复现随机：带种子或固定批次，同一参数组合返回同一结果。适合截图、测试与“今日壁纸”这类需要稳定展示的场景，但需要接口侧支持，是否支持待核实。
还有一个容易忽略的点：分类过滤发生在服务端还是客户端。如果接口只能返回全量随机、由客户端按标签筛，那么带宽与配额都会被浪费在最终被丢弃的图片上。这属于推断性判断，需对照接口文档确认过滤参数是否存在。
去重则完全可以由客户端完成：在本地保留最近 N 条的 URL 或内容哈希，命中则丢弃。注意这依赖接口返回可识别的标识；若响应里没有图片 ID，只能退化为用 URL 或字节哈希去重，这是客户端妥协，不是接口承诺。
二、响应里该核对哪几个字段#
| 字段或行为 | 为什么要看 | 缺失时怎么办 |
|---|---|---|
Content-Type | 响应可能是 JSON 包装，也可能是 302 直出图片字节，解析方式不同 | 两种都兼容，先看类型再决定解析 |
| 重定向 | 是否跟随重定向，决定你记录的是接口地址还是真实图片地址 | 显式配置跟随策略，记录最终 URL |
Cache-Control | 随机接口若被中间层缓存，随机性会退化为固定值 | 客户端请求时主动绕开缓存 |
| CORS 头 | 浏览器端直连需要，服务端调用不需要 | 改为服务端代理 |
| 计数或配额头 | 存在则可做用量观测；具体头名待核实 | 自行统计请求数 |
三、缓存分两层，不要混在一起#
图片字节和“取随机”这个动作应该分开对待。图片本身若 URL 稳定，适合长时间缓存，甚至落到本地磁盘或对象存储；而“取随机”的请求不应经过共享缓存。可行的折中是预取队列：后台提前取若干张放入队列，前端展示时从队列取。代价是可能取到最终没用上的图片，浪费配额；配额上限本次未提供，需自行按文档估算。
四、降级比重试更重要#
随机接口有个特性：重试不是幂等的，重试会得到另一张图。因此在渲染路径上直接重试，等于把首屏时间交给了不确定的网络。更稳的做法是：
- 给请求设置超时，超时即走兜底，不阻塞首屏。
- 准备一个本地兜底图集，至少保证页面不出现空白。
- 把重试放到后台，成功后再替换当前展示。
五、许可要单独确认#
接口可以正常返回图片，不等于这些图片可以商用或再分发。动漫壁纸的版权归属通常涉及原作方、画师与转载站点多方，是否允许缓存到自己的服务器、是否要求标注作者与来源，都需要看授权条款而不是接口文档的功能描述。
示例：带超时与去重的取图函数#
以下代码为未执行的示例，域名、密钥与参数名均为占位，实际取值待核实。
// 未执行示例：占位域名与占位密钥，端点/参数/配额请以官方文档为准
const BASE_URL = "https://api.example.com"; // 占位地址，非真实端点
const KEY = "YOUR_KEY";
async function pickWallpaper(recent = []) {
const url = new URL("/random", BASE_URL);
url.searchParams.set("tag", "anime"); // 参数名待核实
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), 3000); // 超时直接走兜底
try {
const res = await fetch(url, {
headers: { Authorization: `Bearer ${KEY}` },
signal: ctrl.signal,
cache: "no-store", // 不让中间层缓存“随机”这个动作
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const type = res.headers.get("content-type") || "";
const item = type.includes("application/json")
? await res.json()
: { url: res.url }; // 302 直出时退化为最终 URL
if (!item.url) throw new Error("响应中没有图片地址");
if (recent.includes(item.url)) return null; // 交给调用方决定重试或兜底
return item.url;
} finally {
clearTimeout(timer);
}
}接入前的核对清单#
- 确认“随机”是否可复现，以及分类过滤在服务端还是客户端。
- 确认响应形态（JSON 还是直出字节）与重定向策略。
- 确认配额与计费口径，再决定预取队列深度。
- 确认图片许可范围，特别是能否缓存到自有服务器。
把这些客户端约束先定下来，再去填接口细节，比反过来容易得多。
