python_market_data_service/IMPROVEMENTS.md

系统完善报告

概述

本次系统完善共完成了6个主要功能的开发和改进。

已完成的功能

1. 股票复权计算功能 ✅

文件修改:

• app/repositories/models.py - 添加 StockAdjustFactor 复权系数表
• app/repositories/stock_repository.py - 添加复权系数查询和保存方法
• app/services/stock_service.py - 实现复权计算逻辑

功能说明:

• 支持前复权(qfq)和后复权(hfq)计算
• 复权系数自动从数据源获取并缓存到数据库
• 支持价格、成交量的复权调整
• 保留原始复权系数在K线数据中

技术实现:

• 前复权：以最新价格为基准，历史价格按比例缩小
• 后复权：以历史最早价格为基准，后续价格按比例放大

---

2. Prometheus指标暴露端点 ✅

新增文件:

• app/core/metrics.py - 指标收集模块

文件修改:

• app/main.py - 添加指标中间件和端点
• requirements.txt - 添加 prometheus-client 依赖

功能说明:

• HTTP请求计数和持续时间监控
• 活跃请求数跟踪
• 数据库操作性能监控
• 数据源健康状态监控
• WebSocket连接数监控
• 缓存命中率监控

暴露端点:

GET /metrics - Prometheus格式的指标数据

指标列表:

指标名	类型	说明
http_requests_total	Counter	HTTP请求总数
http_request_duration_seconds	Histogram	HTTP请求持续时间
http_requests_active	Gauge	活跃请求数
api_calls_total	Counter	API调用总数
db_operation_duration_seconds	Histogram	数据库操作持续时间
data_source_status	Gauge	数据源健康状态
websocket_connections	Gauge	WebSocket连接数
websocket_messages_total	Counter	WebSocket消息总数

---

3. 应用层限流功能 ✅

新增文件:

• app/core/rate_limiter.py - 限流模块

文件修改:

• app/main.py - 添加限流中间件

功能说明:

• 支持三种限流算法：固定窗口、滑动窗口、令牌桶
• 基于客户端IP + 路径的限流key
• 可配置的请求速率和突发容量
• 自动清理过期数据

默认配置:

RateLimitConfig(
    requests_per_minute=120,  # 每分钟120请求
    burst_size=20,           # 突发20请求
    strategy="sliding_window" # 滑动窗口算法
)

响应头:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1700000000
Retry-After: 60  # 限流时返回

---

4. 监控告警通道 ✅

新增文件:

• app/monitor/alert_channels.py - 告警通道模块

文件修改:

• app/monitor/__init__.py - 导出告警类
• app/monitor/monitor.py - 集成新的告警管理器

支持的告警通道:

通道	类型	说明
LogAlertChannel	日志	默认日志输出
DingTalkAlertChannel	钉钉	钉钉机器人webhook
EmailAlertChannel	邮件	SMTP邮件发送
WebhookAlertChannel	Webhook	自定义HTTP回调

功能特性:

• 支持消息路由（按告警级别）
• 支持批量发送
• Markdown格式的钉钉消息
• HTML格式的邮件内容
• 可扩展的架构

使用示例:

from app.monitor import get_alert_manager

# 发送告警
await get_alert_manager().send_simple(
    title="数据缺失告警",
    content="股票000001.SZ数据缺失",
    level="warning"
)

---

5. 修复已知问题 ✅

修复内容:

1. 添加缺失的 Response 导入到 rate_limiter.py
2. 修复 app/monitor/__init__.py 中已删除类的引用
3. 更新 requirements.txt 添加 prometheus-client
4. 安装缺失的依赖包

---

6. 服务重启功能 ✅

文件修改:

• app/api/admin_routes.py - 实现重启逻辑

功能说明:

• 延迟2秒后重启，确保当前响应返回
• 支持Windows和Linux/Mac系统
• 在后台线程中执行，不阻塞API响应

使用方式:

POST /v1/admin/system/restart

注意: 生产环境建议使用Docker或systemd管理服务生命周期

---

配置文件更新建议

添加告警配置到 config.json:

{
  "alert": {
    "log": {
      "enabled": true
    },
    "dingtalk": {
      "enabled": false,
      "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
      "secret": "your-secret",
      "at_mobiles": ["13800138000"],
      "at_all": false
    },
    "email": {
      "enabled": false,
      "smtp_host": "smtp.example.com",
      "smtp_port": 587,
      "username": "alert@example.com",
      "password": "your-password",
      "from_addr": "alert@example.com",
      "to_addrs": ["admin@example.com"],
      "use_tls": true
    },
    "routing": {
      "info": ["log"],
      "warning": ["log", "dingtalk"],
      "error": ["log", "dingtalk", "email"],
      "critical": ["log", "dingtalk", "email"]
    }
  }
}

---

API端点更新

新增端点:

端点	方法	说明
/metrics	GET	Prometheus指标数据
/admin/system/restart	POST	重启服务

限流保护端点:

所有 /v1/* 端点（除 /health, /metrics, /docs 等外）都受到限流保护。

---

系统架构图

┌─────────────────────────────────────────────────────────┐
│                    FastAPI Application                  │
├─────────────────────────────────────────────────────────┤
│  CORS Middleware                                        │
│  Metrics Middleware (Prometheus)                        │
│  Rate Limit Middleware (120 req/min)                    │
├─────────────────────────────────────────────────────────┤
│  Routes:                                                │
│    /v1/stock/*     - 股票接口                           │
│    /v1/futures/*   - 期货接口                           │
│    /v1/admin/*     - 管理接口                           │
│    /v1/stream      - WebSocket                          │
│    /metrics        - 指标端点                           │
│    /admin          - 管理后台UI                         │
├─────────────────────────────────────────────────────────┤
│  Services:                                              │
│    StockService        - 复权计算 ✅                    │
│    FuturesService      - 期货业务                       │
│    AdminService        - 管理功能                       │
│    AdapterService      - 数据源适配                     │
│    AlertManager        - 告警管理 ✅                    │
├─────────────────────────────────────────────────────────┤
│  Repositories:                                          │
│    StockRepository     - 复权系数表 ✅                  │
│    FuturesRepository   - 期货数据                       │
├─────────────────────────────────────────────────────────┤
│  Data Sources:                                          │
│    AmazingDataAdapter  - 星耀数智                       │
└─────────────────────────────────────────────────────────┘

---

后续建议

1. Prometheus集成

   • 部署Prometheus服务器抓取 /metrics 端点
   • 配置Grafana仪表板展示指标

2. 告警规则配置

   • 配置告警路由规则
   • 设置钉钉/邮件通道参数

3. 性能优化

   • 添加Redis缓存层
   • 实现数据库连接池监控

4. 安全性增强

   • 实现API Key验证逻辑
   • 添加请求签名验证

---

完成时间

2026-03-14