fin_data_unify_plat/API.md

期货股票数据统一平台 - API 文档

基础信息

• Base URL: /api/v1
• 认证方式: JWT Bearer Token
• 数据格式: JSON

认证

获取令牌

大多数 API 端点需要认证。首先通过登录接口获取访问令牌：

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin123

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

使用令牌

在请求头中添加 Authorization：

Authorization: Bearer <access_token>

---

API 端点

1. 认证模块 (Auth)

1.1 用户登录

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

请求参数:

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码

响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

1.2 刷新令牌

POST /api/v1/auth/refresh
Content-Type: application/json

请求体:

{
  "refresh_token": "string"
}

1.3 获取当前用户

GET /api/v1/auth/me
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin"
  }
}

1.4 创建 API Key

POST /api/v1/auth/api-key
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "name": "My API Key",
  "expires_days": 30
}

---

2. K 线数据模块 (Kline)

2.1 获取 K 线数据

GET /api/v1/kline/data
Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
symbol	string	是	品种代码 (如 IF2406)
period	string	是	周期 (1m, 5m, 1h, 1d)
start	datetime	是	开始时间 (ISO 8601)
end	datetime	是	结束时间 (ISO 8601)

响应:

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "time": "2024-01-01T10:00:00Z",
      "open": 4000.0,
      "high": 4050.0,
      "low": 3980.0,
      "close": 4020.0,
      "volume": 1000,
      "amount": 4000000.0,
      "open_interest": 500
    }
  ]
}

2.2 获取最新 K 线

GET /api/v1/kline/latest
Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
symbol	string	是	品种代码
period	string	是	周期

2.3 获取品种列表

GET /api/v1/kline/symbols
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "message": "success",
  "data": ["IF2406", "IC2406", "IH2406", "SH0001"]
}

2.4 获取周期列表

GET /api/v1/kline/periods
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "message": "success",
  "data": ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]
}

---

3. 实时行情模块 (Realtime)

3.1 WebSocket 连接

ws://localhost:8000/api/v1/realtime/ws

连接后发送订阅消息:

{
  "action": "subscribe",
  "symbols": ["IF2406", "IC2406"]
}

取消订阅:

{
  "action": "unsubscribe",
  "symbols": ["IF2406"]
}

接收行情数据:

{
  "symbol": "IF2406",
  "price": 4020.5,
  "change": 0.5,
  "change_percent": 0.012,
  "volume": 1000,
  "timestamp": "2024-01-01T10:00:00Z"
}

3.2 获取实时行情

GET /api/v1/realtime/quote
Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
symbol	string	是	品种代码

3.3 获取多个行情

GET /api/v1/realtime/quotes
Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
symbols	string	是	品种代码列表 (逗号分隔)

---

4. 告警管理模块 (Alert)

4.1 创建告警

POST /api/v1/alert
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "symbol": "IF2406",
  "condition_type": "greater_than",
  "condition_value": 4000.0,
  "alert_type": "price"
}

condition_type 可选值:

• greater_than: 大于
• less_than: 小于
• equals: 等于

alert_type 可选值:

• price: 价格告警
• percent_change: 涨跌幅告警

4.2 获取告警列表

GET /api/v1/alert
Authorization: Bearer <token>

查询参数:

参数	类型	必填	说明
status	string	否	状态 (active, triggered, disabled)
page	int	否	页码 (默认 1)
page_size	int	否	每页数量 (默认 10)

4.3 更新告警

PUT /api/v1/alert/{alert_id}
Authorization: Bearer <token>
Content-Type: application/json

4.4 删除告警

DELETE /api/v1/alert/{alert_id}
Authorization: Bearer <token>

4.5 禁用告警

POST /api/v1/alert/{alert_id}/disable
Authorization: Bearer <token>

---

5. 数据订阅模块 (Subscription)

5.1 创建订阅

POST /api/v1/subscription
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "symbol": "IF2406",
  "period": "5m",
  "subscription_type": "kline"
}

subscription_type 可选值:

• kline: K 线数据订阅
• realtime: 实时行情订阅

5.2 获取订阅列表

GET /api/v1/subscription
Authorization: Bearer <token>

5.3 取消订阅

DELETE /api/v1/subscription/{subscription_id}
Authorization: Bearer <token>

---

6. 用户管理模块 (User)

6.1 创建用户

POST /api/v1/user
Content-Type: application/json

请求体:

{
  "username": "newuser",
  "password": "password123",
  "email": "user@example.com"
}

6.2 获取用户列表 (仅管理员)

GET /api/v1/user
Authorization: Bearer <token>

6.3 更新用户信息

PUT /api/v1/user/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

6.4 修改密码

POST /api/v1/user/{user_id}/password
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "old_password": "oldpass123",
  "new_password": "newpass123"
}

---

错误码说明

错误码	说明
0	成功
400	请求参数错误
401	未授权/令牌过期
403	权限不足
404	资源不存在
500	服务器内部错误

限流说明

• 默认限流：60 次/分钟
• 健康检查端点不限流
• 认证端点单独限流

完整 API 文档

启动服务后访问：http://localhost:8000/docs