最佳实践

让轮询频率与套餐匹配

每个套餐都以固定的更新间隔提供价格：Free 为每日，Lite 为 30 分钟，Standard 为 10 分钟，Advanced 和 Pro 为 60 秒，Ultra 和 Business 为 15 秒，Enterprise 为 5 秒。比这更频繁地请求 /latest 只会返回相同的价格，白白消耗配额。

一般来说，/latest 的缓存时间应与套餐的更新间隔一致，而过去日期的数据可以永久缓存。

一次请求多个品种

一次请求可以返回任意数量的品种，消耗与只请求一个品种相同。请在一次调用中请求所需的全部数据：

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XAU,XAG,XPT,XPD,EUR,GBP

每 10 分钟轮询一次每月约需 4,500 次请求，每分钟轮询一次约需 45,000 次。请据此选择套餐。

在您这边做缓存

在 API 前加一层小型缓存，可以让应用保持快速，并让用量可预测。如果请求失败，还可以继续提供最后一次成功获取的价格：

const TTL = 10 * 60 * 1000; // Standard 套餐：每 10 分钟更新
let cache = { at: 0, data: null };

export async function getPrices() {
  if (cache.data && Date.now() - cache.at < TTL) return cache.data;

  const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG,XPT,XPD", {
    headers: { "X-API-Key": process.env.METALAPI_KEY },
  });
  const data = await res.json();

  if (!data.success) {
    if (cache.data) return cache.data; // 返回最后一次成功获取的价格
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

用实时流代替轮询

对于需要获取每次更新的看板和交易工具，请在 Pro 及以上套餐中使用 /stream。一个长期保持的 Server-Sent Events 连接会在新价格到达时立即推送，无需反复调整轮询循环。

对于“金价突破 4,000 美元时通知我”之类的阈值逻辑，请使用价格提醒和 Webhook，完全无需轮询。

妥善处理错误

• 检查每个响应的 success，并根据 error.code 进行分支处理。
• 对 104、500 和 503 使用退避策略重试，不要重试校验错误。
• 如果无法访问 API，请继续显示最后一次成功获取的价格及其时间戳。
• 关注 X-RateLimit-Remaining 响应头和系统状态页面。

详细说明和代码请参见错误处理。

保障集成安全

• 将密钥存储在环境变量或密钥管理服务中，切勿放入 Git 或客户端代码包。
• 从浏览器发起的任何调用都应使用域名限制密钥。
• 每个应用和环境使用一个密钥，并在有人离职或密钥可能泄露时轮换密钥。
• 验证每个 Webhook 的 X-MetalAPI-Signature 请求头，并拒绝过期的时间戳。

性能优化建议

• 复用同一个 HTTP 客户端，使连接在请求之间保持活动状态。
• 接受压缩响应（gzip 或 br）。大多数 HTTP 客户端默认支持。
• 设置约 10 秒的请求超时，避免网络缓慢时阻塞应用。
• 在启动时加载一次 /symbols，并据此校验用户输入，而不是让错误的品种代码导致请求失败。
• 在监控系统中调用 /usage，以便在配额用尽之前收到警告。该端点是免费的。