|
|
# API 接口文档 - 数据缓存模块
|
|
|
|
|
|
## 基础信息
|
|
|
|
|
|
- **Base URL**: `http://localhost:3007/api`
|
|
|
- **Content-Type**: `application/json`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 数据缓存接口
|
|
|
|
|
|
### 1. 批量缓存所有合约
|
|
|
|
|
|
批量获取所有合约的详情和K线数据，并持久化存储到数据库。
|
|
|
|
|
|
```http
|
|
|
POST /market/cache-all
|
|
|
```
|
|
|
|
|
|
**请求参数**: 无
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"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. 缓存指定合约
|
|
|
|
|
|
针对单个合约进行强制刷新缓存。
|
|
|
|
|
|
```http
|
|
|
POST /market/cache/:symbol
|
|
|
```
|
|
|
|
|
|
**路径参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbol | string | 是 | 合约代码，如 AU、CU、RB |
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"periods": ["1H", "4H", "1D"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求体参数**:
|
|
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
|
|------|------|------|--------|------|
|
|
|
| periods | string[] | 否 | ["1H", "4H", "1D"] | 要缓存的K线周期 |
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"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. 获取缓存统计
|
|
|
|
|
|
获取数据库中的缓存统计信息。
|
|
|
|
|
|
```http
|
|
|
GET /market/cache-stats
|
|
|
```
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"success": true,
|
|
|
"data": {
|
|
|
"total": 150,
|
|
|
"byType": {
|
|
|
"detail": 50,
|
|
|
"kline:1H": 30,
|
|
|
"kline:1D": 30,
|
|
|
"kline:4H": 20,
|
|
|
"overview": 1,
|
|
|
"alerts": 1
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4. 获取市场概览
|
|
|
|
|
|
获取所有期货合约的市场概览数据。
|
|
|
|
|
|
```http
|
|
|
GET /market/overview
|
|
|
```
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"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. 获取品种详情
|
|
|
|
|
|
获取指定合约的详细信息。
|
|
|
|
|
|
```http
|
|
|
GET /market/detail/:symbol
|
|
|
```
|
|
|
|
|
|
**路径参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbol | string | 是 | 合约代码 |
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"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线数据。
|
|
|
|
|
|
```http
|
|
|
GET /market/klines/:symbol?period=1D
|
|
|
```
|
|
|
|
|
|
**路径参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbol | string | 是 | 合约代码 |
|
|
|
|
|
|
**查询参数**:
|
|
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
|
|------|------|------|--------|------|
|
|
|
| period | string | 否 | "1H" | K线周期: 1M, 5M, 15M, 30M, 1H, 4H, 1D, 1W |
|
|
|
|
|
|
**响应示例**:
|
|
|
```json
|
|
|
{
|
|
|
"success": true,
|
|
|
"data": [
|
|
|
{
|
|
|
"timestamp": 1704067200,
|
|
|
"open": 480.5,
|
|
|
"high": 485.2,
|
|
|
"low": 479.8,
|
|
|
"close": 485.0,
|
|
|
"volume": 15234
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**缓存策略**:
|
|
|
- Redis: 10分钟
|
|
|
- MySQL: 永久
|
|
|
|
|
|
---
|
|
|
|
|
|
## 错误处理
|
|
|
|
|
|
### 错误响应格式
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"success": false,
|
|
|
"message": "错误描述信息"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 常见错误码
|
|
|
|
|
|
| HTTP 状态码 | 说明 | 场景 |
|
|
|
|------------|------|------|
|
|
|
| 200 | 成功 | 请求处理成功 |
|
|
|
| 500 | 服务器内部错误 | 数据源连接失败、数据库错误 |
|
|
|
| 404 | 未找到 | 合约不存在 |
|
|
|
|
|
|
### 常见错误消息
|
|
|
|
|
|
| 错误消息 | 说明 | 解决方案 |
|
|
|
|---------|------|---------|
|
|
|
| 无可用数据源 | 未配置或启用数据源 | 在 AdminConfig 中启用至少一个数据源 |
|
|
|
| 合约不存在 | 指定的合约代码无效 | 检查合约代码是否正确 |
|
|
|
| 获取市场概览失败 | 数据源连接问题 | 检查数据源配置和网络连接 |
|
|
|
| 批量缓存失败 | 批量处理过程中出错 | 查看服务器日志获取详细错误 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 调用示例
|
|
|
|
|
|
### JavaScript/Fetch
|
|
|
|
|
|
```javascript
|
|
|
// 批量缓存所有合约
|
|
|
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
|
|
|
|
|
|
```typescript
|
|
|
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
|
|
|
|
|
|
```typescript
|
|
|
interface KlineData {
|
|
|
timestamp: number; // 时间戳（秒）
|
|
|
open: number; // 开盘价
|
|
|
high: number; // 最高价
|
|
|
low: number; // 最低价
|
|
|
close: number; // 收盘价
|
|
|
volume: number; // 成交量
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### CacheStats
|
|
|
|
|
|
```typescript
|
|
|
interface CacheStats {
|
|
|
total: number; // 缓存总数
|
|
|
byType: Record<string, number>; // 按类型统计
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
**文档版本**: 1.0
|
|
|
**最后更新**: 2026-03-02
|
