AlphaFuturesPro/docs/api-reference.md

API 接口文档 - 数据缓存模块

基础信息

• Base URL: http://localhost:3007/api
• Content-Type: application/json

---

数据缓存接口

1. 批量缓存所有合约

批量获取所有合约的详情和K线数据，并持久化存储到数据库。

POST /market/cache-all

请求参数: 无

响应示例:

{
  "success": true,
  "message": "批量缓存完成，成功: 25/30",
  "data": {
    "total": 30,
    "success": 25,
    "failed": 5,
    "details": [
      { "code": "AU", "status": "success" },
      { "code": "CU", "status": "success" },
      { "code": "XX", "status": "error", "error": "合约不存在" }
    ],
    "klineCached": 50
  }
}

说明:

• 自动获取市场概览中的所有合约
• 逐个缓存合约详情到 MySQL 和 Redis
• 缓存前10个热门合约的1H和1D周期K线数据
• 每10个合约延迟100ms避免请求过快

---

2. 缓存指定合约

针对单个合约进行强制刷新缓存。

POST /market/cache/:symbol

路径参数:

参数	类型	必填	说明
symbol	string	是	合约代码，如 AU、CU、RB

请求体:

{
  "periods": ["1H", "4H", "1D"]
}

请求体参数:

参数	类型	必填	默认值	说明
periods	string[]	否	["1H", "4H", "1D"]	要缓存的K线周期

响应示例:

{
  "success": true,
  "message": "合约 AU 缓存成功",
  "data": {
    "symbol": "AU",
    "detail": true,
    "klines": [
      { "period": "1H", "success": true },
      { "period": "4H", "success": true },
      { "period": "1D", "success": false, "error": "数据获取失败" }
    ]
  }
}

说明:

• 会先清除该合约的现有缓存（强制刷新）
• 缓存合约详情和指定周期的K线数据
• 各周期K线缓存相互独立，单个失败不影响其他

---

3. 获取缓存统计

获取数据库中的缓存统计信息。

GET /market/cache-stats

响应示例:

{
  "success": true,
  "data": {
    "total": 150,
    "byType": {
      "detail": 50,
      "kline:1H": 30,
      "kline:1D": 30,
      "kline:4H": 20,
      "overview": 1,
      "alerts": 1
    }
  }
}

---

4. 获取市场概览

获取所有期货合约的市场概览数据。

GET /market/overview

响应示例:

{
  "success": true,
  "data": [
    {
      "code": "AU",
      "name": "黄金",
      "currentPrice": 485.32,
      "changePercent": 1.25,
      "winRate": 65,
      "atr": 2.34,
      "adx": 35,
      "trends": {
        "5MIN": { "direction": "看多", "status": "多头趋势", "rsi": 58 },
        "1DAY": { "direction": "看多", "status": "多头趋势", "rsi": 62 }
      }
    }
  ]
}

缓存策略:

• Redis: 5分钟
• MySQL: 永久

---

5. 获取品种详情

获取指定合约的详细信息。

GET /market/detail/:symbol

路径参数:

参数	类型	必填	说明
symbol	string	是	合约代码

响应示例:

{
  "success": true,
  "data": {
    "code": "AU",
    "name": "黄金",
    "currentPrice": 485.32,
    "changePercent": 1.25,
    "winRate": 65,
    "indicators": {
      "macd": "金叉向上",
      "rsi": "58(中性)"
    },
    "tradingAdvice": {
      "entry": 485.0,
      "stopLoss": 475.0,
      "target": 500.0
    }
  }
}

缓存策略:

• Redis: 5分钟
• MySQL: 永久

---

6. 获取K线数据

获取指定合约的K线数据。

GET /market/klines/:symbol?period=1D

路径参数:

参数	类型	必填	说明
symbol	string	是	合约代码

查询参数:

参数	类型	必填	默认值	说明
period	string	否	"1H"	K线周期: 1M, 5M, 15M, 30M, 1H, 4H, 1D, 1W

响应示例:

{
  "success": true,
  "data": [
    {
      "timestamp": 1704067200,
      "open": 480.5,
      "high": 485.2,
      "low": 479.8,
      "close": 485.0,
      "volume": 15234
    }
  ]
}

缓存策略:

• Redis: 10分钟
• MySQL: 永久

---

错误处理

错误响应格式

{
  "success": false,
  "message": "错误描述信息"
}

常见错误码

HTTP 状态码	说明	场景
200	成功	请求处理成功
500	服务器内部错误	数据源连接失败、数据库错误
404	未找到	合约不存在

常见错误消息

错误消息	说明	解决方案
无可用数据源	未配置或启用数据源	在 AdminConfig 中启用至少一个数据源
合约不存在	指定的合约代码无效	检查合约代码是否正确
获取市场概览失败	数据源连接问题	检查数据源配置和网络连接
批量缓存失败	批量处理过程中出错	查看服务器日志获取详细错误

---

调用示例

JavaScript/Fetch

// 批量缓存所有合约
const cacheAllContracts = async () => {
  const response = await fetch('http://localhost:3007/api/market/cache-all', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    }
  });
  return await response.json();
};

// 缓存指定合约
const cacheSymbol = async (symbol) => {
  const response = await fetch(`http://localhost:3007/api/market/cache/${symbol}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      periods: ['1H', '4H', '1D']
    })
  });
  return await response.json();
};

// 获取缓存统计
const getCacheStats = async () => {
  const response = await fetch('http://localhost:3007/api/market/cache-stats');
  return await response.json();
};

---

数据类型定义

ContractDetail

interface ContractDetail {
  code: string;                    // 合约代码
  name: string;                    // 合约名称
  currentPrice: number;            // 当前价格
  changePercent: number;           // 涨跌幅百分比
  winRate: number;                 // 胜率
  atr: number;                     // 平均真实波幅
  adx: number;                     // ADX指标值
  trends: {                        // 各周期趋势
    [period: string]: {
      direction: string;           // 方向：看多/看空/观望
      status: string;              // 状态：多头趋势/空头趋势/震荡
      rsi: number;                 // RSI值
    }
  };
  indicators: {                    // 技术指标
    macd: string;
    rsi: string;
    bollinger: string;
    kdj: string;
  };
  tradingAdvice: {                 // 交易建议
    entry: number;                 // 入场价
    stopLoss: number;              // 止损价
    target: number;                // 目标价
    resistance: number;            // 阻力位
    support: number;               // 支撑位
  };
}

KlineData

interface KlineData {
  timestamp: number;   // 时间戳（秒）
  open: number;        // 开盘价
  high: number;        // 最高价
  low: number;         // 最低价
  close: number;       // 收盘价
  volume: number;      // 成交量
}

CacheStats

interface CacheStats {
  total: number;                    // 缓存总数
  byType: Record<string, number>;   // 按类型统计
}

---

文档版本: 1.0
最后更新: 2026-03-02