|
|
# 期货股票数据统一平台 - API 文档
|
|
|
|
|
|
## 基础信息
|
|
|
|
|
|
- **Base URL**: `/api/v1`
|
|
|
- **认证方式**: JWT Bearer Token
|
|
|
- **数据格式**: JSON
|
|
|
|
|
|
## 认证
|
|
|
|
|
|
### 获取令牌
|
|
|
|
|
|
大多数 API 端点需要认证。首先通过登录接口获取访问令牌：
|
|
|
|
|
|
```bash
|
|
|
POST /api/v1/auth/login
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
|
|
username=admin&password=admin123
|
|
|
```
|
|
|
|
|
|
响应：
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "success",
|
|
|
"data": {
|
|
|
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
|
"token_type": "Bearer",
|
|
|
"expires_in": 3600
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 使用令牌
|
|
|
|
|
|
在请求头中添加 Authorization：
|
|
|
|
|
|
```bash
|
|
|
Authorization: Bearer <access_token>
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## API 端点
|
|
|
|
|
|
### 1. 认证模块 (Auth)
|
|
|
|
|
|
#### 1.1 用户登录
|
|
|
```http
|
|
|
POST /api/v1/auth/login
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
```
|
|
|
|
|
|
**请求参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| username | string | 是 | 用户名 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
|
|
|
**响应**:
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "success",
|
|
|
"data": {
|
|
|
"access_token": "string",
|
|
|
"refresh_token": "string",
|
|
|
"token_type": "Bearer",
|
|
|
"expires_in": 3600
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 1.2 刷新令牌
|
|
|
```http
|
|
|
POST /api/v1/auth/refresh
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"refresh_token": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 1.3 获取当前用户
|
|
|
```http
|
|
|
GET /api/v1/auth/me
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**响应**:
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "success",
|
|
|
"data": {
|
|
|
"id": 1,
|
|
|
"username": "admin",
|
|
|
"email": "admin@example.com",
|
|
|
"role": "admin"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 1.4 创建 API Key
|
|
|
```http
|
|
|
POST /api/v1/auth/api-key
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"name": "My API Key",
|
|
|
"expires_days": 30
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2. K 线数据模块 (Kline)
|
|
|
|
|
|
#### 2.1 获取 K 线数据
|
|
|
```http
|
|
|
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) |
|
|
|
|
|
|
**响应**:
|
|
|
```json
|
|
|
{
|
|
|
"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 线
|
|
|
```http
|
|
|
GET /api/v1/kline/latest
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**查询参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbol | string | 是 | 品种代码 |
|
|
|
| period | string | 是 | 周期 |
|
|
|
|
|
|
#### 2.3 获取品种列表
|
|
|
```http
|
|
|
GET /api/v1/kline/symbols
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**响应**:
|
|
|
```json
|
|
|
{
|
|
|
"code": 0,
|
|
|
"message": "success",
|
|
|
"data": ["IF2406", "IC2406", "IH2406", "SH0001"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 2.4 获取周期列表
|
|
|
```http
|
|
|
GET /api/v1/kline/periods
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**响应**:
|
|
|
```json
|
|
|
{
|
|
|
"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
|
|
|
```
|
|
|
|
|
|
**连接后发送订阅消息**:
|
|
|
```json
|
|
|
{
|
|
|
"action": "subscribe",
|
|
|
"symbols": ["IF2406", "IC2406"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**取消订阅**:
|
|
|
```json
|
|
|
{
|
|
|
"action": "unsubscribe",
|
|
|
"symbols": ["IF2406"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**接收行情数据**:
|
|
|
```json
|
|
|
{
|
|
|
"symbol": "IF2406",
|
|
|
"price": 4020.5,
|
|
|
"change": 0.5,
|
|
|
"change_percent": 0.012,
|
|
|
"volume": 1000,
|
|
|
"timestamp": "2024-01-01T10:00:00Z"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 3.2 获取实时行情
|
|
|
```http
|
|
|
GET /api/v1/realtime/quote
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**查询参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbol | string | 是 | 品种代码 |
|
|
|
|
|
|
#### 3.3 获取多个行情
|
|
|
```http
|
|
|
GET /api/v1/realtime/quotes
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**查询参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| symbols | string | 是 | 品种代码列表 (逗号分隔) |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4. 告警管理模块 (Alert)
|
|
|
|
|
|
#### 4.1 创建告警
|
|
|
```http
|
|
|
POST /api/v1/alert
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```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 获取告警列表
|
|
|
```http
|
|
|
GET /api/v1/alert
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
**查询参数**:
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| status | string | 否 | 状态 (active, triggered, disabled) |
|
|
|
| page | int | 否 | 页码 (默认 1) |
|
|
|
| page_size | int | 否 | 每页数量 (默认 10) |
|
|
|
|
|
|
#### 4.3 更新告警
|
|
|
```http
|
|
|
PUT /api/v1/alert/{alert_id}
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
#### 4.4 删除告警
|
|
|
```http
|
|
|
DELETE /api/v1/alert/{alert_id}
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
#### 4.5 禁用告警
|
|
|
```http
|
|
|
POST /api/v1/alert/{alert_id}/disable
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 5. 数据订阅模块 (Subscription)
|
|
|
|
|
|
#### 5.1 创建订阅
|
|
|
```http
|
|
|
POST /api/v1/subscription
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"symbol": "IF2406",
|
|
|
"period": "5m",
|
|
|
"subscription_type": "kline"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**subscription_type 可选值**:
|
|
|
- `kline`: K 线数据订阅
|
|
|
- `realtime`: 实时行情订阅
|
|
|
|
|
|
#### 5.2 获取订阅列表
|
|
|
```http
|
|
|
GET /api/v1/subscription
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
#### 5.3 取消订阅
|
|
|
```http
|
|
|
DELETE /api/v1/subscription/{subscription_id}
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 6. 用户管理模块 (User)
|
|
|
|
|
|
#### 6.1 创建用户
|
|
|
```http
|
|
|
POST /api/v1/user
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"username": "newuser",
|
|
|
"password": "password123",
|
|
|
"email": "user@example.com"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 6.2 获取用户列表 (仅管理员)
|
|
|
```http
|
|
|
GET /api/v1/user
|
|
|
Authorization: Bearer <token>
|
|
|
```
|
|
|
|
|
|
#### 6.3 更新用户信息
|
|
|
```http
|
|
|
PUT /api/v1/user/{user_id}
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
#### 6.4 修改密码
|
|
|
```http
|
|
|
POST /api/v1/user/{user_id}/password
|
|
|
Authorization: Bearer <token>
|
|
|
Content-Type: application/json
|
|
|
```
|
|
|
|
|
|
**请求体**:
|
|
|
```json
|
|
|
{
|
|
|
"old_password": "oldpass123",
|
|
|
"new_password": "newpass123"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 错误码说明
|
|
|
|
|
|
| 错误码 | 说明 |
|
|
|
|--------|------|
|
|
|
| 0 | 成功 |
|
|
|
| 400 | 请求参数错误 |
|
|
|
| 401 | 未授权/令牌过期 |
|
|
|
| 403 | 权限不足 |
|
|
|
| 404 | 资源不存在 |
|
|
|
| 500 | 服务器内部错误 |
|
|
|
|
|
|
## 限流说明
|
|
|
|
|
|
- 默认限流：60 次/分钟
|
|
|
- 健康检查端点不限流
|
|
|
- 认证端点单独限流
|
|
|
|
|
|
## 完整 API 文档
|
|
|
|
|
|
启动服务后访问：http://localhost:8000/docs
|
