概述缓存基础缓存头 ETag缓存缓存控制指令 CDN集成客户端缓存缓存清除监控缓存最佳实践

API文档

响应缓存与CDN集成指南

通过智能缓存策略优化Smart Money API性能。学习HTTP缓存头、ETag验证、CDN集成和客户端缓存模式，以减少延迟和带宽成本。

发布于2026年3月21日 • 16分钟阅读 • 性能

缓存概述

Smart Money API端点提供不同频率变化的加密货币市场数据。一些数据（鲸鱼地址、资金费率）每隔几秒更新一次，而其他数据（历史分析、教育内容）则保持静态数小时。智能缓存显著提高了性能并降低了成本。

Smart Money API实现了三层缓存策略：

CDN边缘缓存 — 全球内容交付，自动缓存失效
HTTP浏览器缓存 — 使用标准HTTP头的客户端缓存
应用缓存 — 内存缓存，用于频繁访问的数据集

性能洞察： 缓存响应比新鲜API请求快50-100倍，并显著节省带宽。正确缓存的集成可以减少70-85%的数据传输。

每个Smart Money API响应都包含缓存指令，告诉客户端和CDN数据保持有效的时间。理解这些指令并正确实施它们对于优化性能至关重要。

缓存基础

HTTP缓存基于响应头操作，指示内容是否可以缓存以及缓存多长时间。

Cache-Control头

控制缓存行为的主要机制。每个Smart Money API响应都包含一个Cache-Control头，指定：

max-age — 响应保持有效的秒数
public/private — 中间缓存是否可以存储它
must-revalidate — 在提供服务前是否检查新鲜度
no-store — 不缓存敏感数据

示例缓存头

不同的端点有不同的缓存要求：

响应头
// 鲸鱼地址数据（每5分钟更新一次）
Cache-Control: public, max-age=300
ETag: "abc123def456"
// 实时资金费率（每秒更新一次）
Cache-Control: public, max-age=1
ETag: "xyz789abc123"
// 历史数据（不变）
Cache-Control: public, max-age=86400, immutable
ETag: "static-content-v1"

按端点类型缓存时长

数据类型	缓存时长	使用案例
实时资金	1-5秒	实时交易，仓位调整
鲸鱼动向	5分钟	信号确认，警报
每日OHLCV	1小时	技术分析，图表
历史分析	24小时	回测，研究
静态内容	7天	API文档，指南，配置

30秒内获取您的API密钥

准备好构建了吗？获取免费API密钥（每天100次调用，无需信用卡）并开始提取实时鲸鱼、资金和链上数据。

获取您的API密钥 →

HTTP缓存头

Smart Money API响应包含多个缓存相关的头，协同工作以在保持数据新鲜度的同时最大化性能。

Cache-Control：主要头

控制浏览器和中间缓存的缓存行为：

Cache-Control指令
// 公共数据，缓存5分钟
Cache-Control: public, max-age=300
// 私有数据，仅在浏览器中缓存
Cache-Control: private, max-age=3600
// 不可变内容，永久缓存
Cache-Control: public, max-age=31536000, immutable
// 在提供服务前始终重新验证
Cache-Control: public, max-age=0, must-revalidate
// 不缓存敏感数据
Cache-Control: private, no-store, no-cache

Expires头（旧版）

对于旧版客户端，Smart Money还提供Expires头（HTTP/1.0）：

Expires头
// 绝对过期时间
Expires: Wed, 22 Mar 2026 14:30:00 GMT
// Cache-Control max-age在HTTP/1.1中优先

Last-Modified头

指示内容上次更新的时间，启用条件请求：

Last-Modified用法
// 响应包含Last-Modified
Last-Modified: Wed, 21 Mar 2026 10:15:30 GMT
// 客户端使用If-Modified-Since重新验证
If-Modified-Since: Wed, 21 Mar 2026 10:15:30 GMT
// 如果未更改，服务器响应304 Not Modified
HTTP/1.1 304 Not Modified

Vary头

告诉缓存哪些请求头影响响应（认证、参数）：

Vary头
// 响应因认证和符号而异
Vary: Authorization, X-Symbols
// 缓存为不同的值存储单独的版本

ETag和条件请求

ETags（实体标签）提供了一种有效的方法来验证缓存内容，而无需下载完整的响应体。

ETag工作原理

初始请求 — 客户端请求数据，服务器响应ETag
缓存存储 — 客户端缓存带有ETag的响应
后续请求 — 客户端发送带有缓存ETag的If-None-Match请求头
验证 — 若数据未更改，服务器返回304 Not Modified
节省带宽 — 不发送响应体，大幅节省带宽

ETag实现

初始请求与响应
// 首次请求
GET /v1/whales/btc HTTP/1.1
// 响应包含ETag
HTTP/1.1 200 OK
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
Content-Type: application/json
{...响应体...}

条件验证
// 缓存过期后发送If-None-Match
GET /v1/whales/btc HTTP/1.1
If-None-Match: "8a3b9c2d"
// 若未修改，服务器返回304
HTTP/1.1 304 Not Modified
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
// 不发送响应体！节省带宽

ETag强度

ETag可分为强验证与弱验证：

类型	格式	使用场景
强ETag	"8a3b9c2d"	字节级完全一致，用于严格验证
弱ETag	W/"8a3b9c2d"	语义等效，适用于内容展示变更

缓存控制指令

理解Cache-Control指令可帮助您为应用构建最优缓存策略。

指令参考

指令	含义	示例
max-age	响应保持新鲜的秒数	max-age=300
public	可被任何缓存存储和共享	public
private	仅限接收方缓存	private
must-revalidate	过期后必须重新验证	must-revalidate
no-cache	使用前必须验证	no-cache
no-store	禁止缓存	no-store
immutable	永不改变，永久缓存	immutable
s-maxage	CDN缓存时长	s-maxage=3600

实用缓存控制模式

常见模式
// 模式1：浏览器缓存300秒，CDN缓存1小时
Cache-Control: public, max-age=300, s-maxage=3600
// 模式2：用户私有数据，禁止代理缓存
Cache-Control: private, max-age=1800
// 模式3：始终验证新鲜度
Cache-Control: public, no-cache, must-revalidate
// 模式4：版本化静态资源永久缓存
Cache-Control: public, max-age=31536000, immutable

CDN集成

Smart Money API通过Cloudflare全球CDN网络交付响应，自动在边缘节点缓存以实现最低延迟。

Smart Money CDN工作原理

用户请求 — 请求到达最近的Cloudflare边缘节点
缓存检查 — 边缘节点检查是否存在新鲜缓存
缓存命中 — 若命中缓存，10毫秒内立即响应
缓存未命中 — 若无缓存，回源服务器获取
存储并响应 — 缓存响应并返回用户

缓存键配置

Cloudflare使用缓存键唯一标识响应。默认规则：

包含请求路径和查询参数
忽略大多数请求头（最大化缓存命中率）
不包含Authorization头（防止账户信息泄露）
可通过Vary头添加自定义头

CDN缓存清除

Smart Money在数据更新时自动清除CDN缓存：

手动清除缓存
// 从CDN清除特定URL
curl -X POST "https://api.smartmoneyapi.com/v1/cache/purge" \
  -H "Authorization: Bearer token" \
  -d '{
 "urls": [
 "https://api.smartmoneyapi.com/v1/whales/btc"
    ]
  }'

测量CDN性能

检查响应头判断是否命中缓存：

响应头示例
// CDN边缘节点命中缓存
CF-Cache-Status: HIT
CF-RAY: 8a9b7c6d5e4f3g2h
Age: 45  // 缓存存储时长（秒）
// 未命中缓存，回源获取
CF-Cache-Status: MISS
Age: 0

客户端缓存

在应用中实现缓存可进一步减少API调用并提升响应速度。

浏览器缓存实现

JavaScript缓存方案
// 创建缓存存储
const cache = new Map();
async function fetchWithCache(url) {
  // 首先检查缓存
  const cached = cache.get(url);
  if (cached && !isCacheExpired(cached)) {
    return cached.data;
  }
  // 从API获取数据
  const response = await fetch(url);
  const data = await response.json();
  // 从响应头解析缓存时长
  const cacheControl = response.headers
    .get('cache-control');
  const maxAge = parseMaxAge(cacheControl);
  // 存入缓存
  cache.set(url, {
    data,
    expiry: Date.now() + (maxAge * 1000)
  });
  return data;
}

Service Worker缓存

如需离线支持和高级缓存策略，请使用Service Workers：

Service Worker
// 使用Service Worker缓存API响应
self.addEventListener('fetch', (event) => {
  if (event.request.url.includes('api.smartmoneyapi.com')) {
    // 网络优先，回退到缓存
    event.respondWith(
      fetch(event.request)
        .then(response => {
          // 用最新响应更新缓存
          caches.open('api-cache')
            .then(cache => cache.put(
              event.request, response.clone()));
          return response;
        })
        .catch(() => 
          caches.match(event.request))
    );
  }
});

缓存刷新策略

有时需要强制客户端获取最新数据，可采用以下方法：

版本参数

添加版本参数以便数据更新时使缓存失效：

版本化URL
// 包含数据版本或时间戳
https://api.smartmoneyapi.com/v1/whales/btc?v=1709980800
// 数据更新时递增版本号
https://api.smartmoneyapi.com/v1/whales/btc?v=1709981000
// 新URL即新缓存条目

强制重新验证

需要最新数据时，用Cache-Control: no-cache覆盖缓存：

强制获取新数据
// JavaScript: 强制发起新请求
fetch(url, {
  cache: 'no-cache',  // 总是重新验证
  headers: {
    'Cache-Control': 'max-age=0'
  }
});

监控缓存性能

追踪缓存命中率和性能提升，以验证缓存策略有效性。

需监控的缓存指标

命中率 — 从缓存响应的请求占比（目标：>70%）
响应时间 — 平均延迟（缓存：<50ms，未缓存：100-300ms）
节省带宽 — 减少的数据传输量
源站负载 — 源服务器请求减少量

分析缓存头

缓存分析脚本
// 分析响应缓存头
async function analyzeCache(url) {
  const response = await fetch(url);
  return {
    cacheControl: response.headers
      .get('cache-control'),
    etag: response.headers.get('etag'),
    age: response.headers.get('age'),
    cfStatus: response.headers
      .get('cf-cache-status'),
    contentLength: 
      response.headers.get('content-length')
  };
}

缓存最佳实践

1. 遵循响应头指示

始终遵循Smart Money API的Cache-Control头。不要缓存标记为no-store或no-cache的内容。

2. 实现条件请求

重新验证缓存内容时发送If-None-Match（ETag）和If-Modified-Since头。通过304响应节省带宽。

3. 按数据类型合理缓存

实时数据（资金费率）：最多缓存1-5秒
实时信号（巨鲸动向）：缓存5-30秒
小时数据（OHLCV）：缓存1小时
历史数据：缓存24小时
静态内容：缓存7天

4. 监控缓存效果

追踪命中率和延迟改善。根据数据新鲜度需求和缓存性能调整TTL。

5. 谨慎使用Vary头

Vary头会因创建独立缓存条目而降低命中率。仅在不同认证级别或参数必需时使用。

6. 多层缓存策略

在CDN、浏览器和应用层实施缓存。每层都能在请求到达源站前拦截。

优化API性能

Smart Money API的缓存基础设施确保全球响应速度低于100毫秒。实施智能缓存策略以最大化性能并降低成本。

方案对比

所有方案均包含完整CDN缓存。更高阶版本提供缓存控制和清除API。