API.PLUS 动漫壁纸随机图 API 的失败边界：超时、重复图与空响应怎么处理

处理顺序可以概括为：请求有超时，重复图不直接展示，空响应和连续失败落到占位图；图片源本身要能替换。这样即使 API.PLUS 的具体端点或额度调整，页面也不必重写。本文材料没有提供 API.PLUS 的端点、鉴权、配额、价格和图片授权信息，这些均待核实；以下只讨论调用侧设计，不声称已调用或实测。

先定“随机”的含义#

随机图片 API 的“随机”至少有三个待确认点：是否允许短时间重复、是否支持分类/尺寸/清晰度参数、重试后是否仍返回同一张。接入前应在契约中写清。

• 去重键优先用响应中的稳定图片 ID；没有 ID 时可用图片 URL 的哈希，但要知道 URL 可能带临时参数。
• 去重集合要有容量上限，例如只保留最近若干条；否则长时间运行的进程或页面会持续增长。
• 重复图不是错误响应，但可以触发一次有限重试；重试仍重复就展示当前图或降级，不要循环拉取。

响应字段与错误语义#

建议至少确认响应是否提供图片 URL、稳定 ID、宽高、MIME 类型、字节大小、过期时间和署名信息。字段缺失时要有保守分支：没有 size 就不要假设图片很小；没有 expires 就不要长期缓存。

错误要分开处理：网络超时、HTTP 4xx、HTTP 5xx、响应不是 JSON、字段缺失、图片体积超限。4xx 通常不应原样重试，5xx 和超时可以有限重试；具体状态码含义以实际文档为准。

体积预算与缓存#

体积预算应按场景设定：列表缩略图、详情大图、移动网络和桌面端可以不同。预算比较的是图片字节，不是 API JSON 的大小；如果响应没有 size 字段，是否额外发 HEAD 请求要权衡，因为那会增加一次网络往返。

缓存键应包含分类、尺寸、清晰度和语言等筛选条件。随机参数是否进缓存键，取决于产品是“每次都要新图”还是“同条件下可复用”。HTTP 缓存头以实际响应为准。

超时、重试与占位图#

超时应该覆盖整个请求，而不只是建立连接。重试次数要有限，并加退避；不要把重试放在用户快速滑动的每一张图上。最终失败应返回本地占位图，同时记录脱敏后的错误类型，便于区分 API 故障和字段变更。

边界条件：如果业务要求“绝不重复”，必须在调用侧维护有上限的去重状态，并接受可能因状态淘汰而再次出现同一张图。

未执行的调用骨架#

下面示例只示意字段校验、去重和体积检查，未执行，也不提供预期输出。端点、字段名均为占位，需按实际文档替换；AbortSignal.timeout 的运行时兼容性也需自行核对。示例中的体积上限是演示值，不是推荐值。

// 未执行示例：端点与字段均为占位，请勿直接用于生产
const ENDPOINT = "https://api.example.com/v1/anime/wallpaper?key=YOUR_KEY";
const seen = new Set();
const MAX_BYTES = 350 * 1024; // 演示值，不是推荐值

async function pickWallpaper() {
  const res = await fetch(ENDPOINT, { signal: AbortSignal.timeout(3000) });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const item = await res.json();
  if (!item || !item.url || !item.id) throw new Error("响应字段不完整");
  if (seen.has(item.id)) throw new Error("重复图片");
  if (typeof item.size === "number" && item.size > MAX_BYTES) {
    throw new Error("超出体积预算");
  }
  seen.add(item.id); // 生产代码应改为有上限的去重结构
  return item.url;
}

这个骨架没有处理重试、占位图和状态淘汰，不能直接当生产代码。它的价值是把失败点显式化。

上线前核对#

• API.PLUS 的实际端点、鉴权方式、配额与计费规则：待核实。
• 图片版权、来源署名和再分发条件：待核实，按服务条款执行。
• 响应缓存头、图片尺寸参数和错误码语义：以实际文档与响应为准。
• 日志不要记录完整密钥或带签名的图片 URL；示例中的 YOUR_KEY 只是占位符。

把图片源做成可替换端口后，页面只依赖“取一张可用图片”的接口，去重、体积预算和降级留在调用侧；更换服务或调整参数时，改动范围才可控。