动漫壁纸随机图片 API：玩法、缓存与失败路径怎么设计

随机图片 API 的接入代码往往只有几行，真正决定体验的是另外三件事：密钥不出前端、按展示位置控制图片体积、随机请求失败时不让用户看到破图。本文只讨论这些通用工程问题。API.PLUS 的具体端点、参数名、配额与授权条款本次没有材料，需以其官方文档为准，下文出现的地址一律是占位示例。

先选接入形态，再谈优化#

• 前端直连：最快能跑通，但密钥暴露在浏览器，还要处理跨域（CORS）。只适合本身公开、无需密钥的接口。
• 服务端代理：密钥留在服务端，能加缓存、并发上限与降级逻辑，是生产环境的默认选择。
• 离线或构建期预取：把一批图片下到本地池，前端轮换。适合壁纸站首页这类高频、可接受轻微重复的场景，但要注意提供方的配额与公平使用条款。

随机性与缓存怎么共存#

随机接口每次返回不同资源，响应体本身不适合缓存。可缓存的是三样东西：候选图片 URL 池、已经下载到本地的图片文件、以及带业务参数的派生结果。

• 缓存键至少包含尺寸、分类、内容过滤等参数，否则不同页面会串图。
• 如果接口返回 302 跳转到静态资源地址，跟随后拿到的图片通常可以按较长时间缓存，具体取决于对方 CDN 的响应头，需实测确认。
• 给池子设上限并定期淘汰，避免长期运行后内存或磁盘无限增长。

体积：按展示位请求，而不是按最大分辨率#

壁纸类资源的体积随分辨率上升明显，同一张图在列表页和详情页需要的尺寸完全不同。可行做法是按容器宽度请求对应尺寸，列表用缩略图，进入详情再取大图。若接口支持 WebP 或 AVIF，优先使用；同时给 img 加上 loading="lazy" 与 decoding="async"，减少首屏阻塞。具体支持的格式与尺寸参数待核实。

失败路径比成功路径更需要设计#

1. 短超时：随机接口抖动时，宁可快速回退到本地占位图，也不要让页面长时间空白。
2. 校验内容类型：限流或故障时，对方可能返回 JSON 或 HTML 错误页，状态码 200 也不代表是图片。必须检查 Content-Type 是否以 image/ 开头。
3. 限制重试：代理层设并发上限和重试次数上限，前端不要无限重试，否则一次抖动会被放大成雪崩。
4. 可观测：至少记录状态码分布、内容类型异常次数与耗时，否则无法判断问题出在网络、对方服务还是自己的缓存层。

一个服务端代理的最小骨架#

下面代码未实际执行，仅示意结构，域名和密钥均为占位，请替换为官方文档给出的真实接口。

// Node.js 18+，未执行示例
const ALLOWED = /^image\//;

export async function handler(req, res) {
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), 3000);
  try {
    const upstream = await fetch(
      "https://api.example.com/random?size=thumb", // 占位地址
      { headers: { Authorization: "Bearer YOUR_KEY" }, signal: ctrl.signal }
    );
    const type = upstream.headers.get("content-type") || "";
    if (!upstream.ok || !ALLOWED.test(type)) {
      res.writeHead(502, { "content-type": "text/plain" });
      return res.end("upstream unavailable");
    }
    res.writeHead(200, { "content-type": type, "cache-control": "public, max-age=86400" });
    res.end(Buffer.from(await upstream.arrayBuffer()));
  } catch (e) {
    res.writeHead(504, { "content-type": "text/plain" });
    res.end("timeout");
  } finally {
    clearTimeout(timer);
  }
}

注意这里的 cache-control 只对本次拿到的这张图有意义，不能理解为随机接口本身可缓存。

版权与条款这一层不能省#

动漫壁纸多为第三方作品，是否允许商用、是否需要署名、是否允许热链，取决于提供方的条款与图片来源，本次材料未提供相关内容，待核实。可先假设不能直接商用，把署名位和替换机制留在设计里，比上线后再补救成本低得多。

结论很简单：先确定密钥在谁手里、图给多大、失败时显示什么，再去挑接口和调参数。