market-data-service/README.md

统一行情数据服务

提供股票和期货的标准化行情数据查询服务，支持多周期K线、复权计算、数据源热切换等功能。

🎉 重大更新: 现已支持 Go 和 Python 双实现，所有接口完全一致！

实现	推荐场景	目录
Go	生产环境、高并发	market-data-service/ (本目录)
Python	快速开发、原型验证	python_market_data_service/

---

特性

• 多周期K线支持：1m/5m/15m/30m/60m/1d/1w/1month
• 股票复权支持：前复权(qfq)/后复权(hfq)
• 数据源热切换：支持Wind、Tushare等多个数据源动态切换
• 双轨设计：股票和期货接口独立，数据存储隔离
• WebSocket实时订阅：支持实时行情推送
• 数据质量监控：自动检测数据缺失并告警
• 交易日历：支持查询股票和期货的交易日历
• 期货合约查询：根据品种获取可交易合约列表
• 双语言实现：Go高性能 + Python快速开发

---

技术栈

Go实现

• 语言: Go 1.21+
• Web框架: Gin
• WebSocket: Gorilla WebSocket
• 数据库: PostgreSQL 15+ (原生SQL)
• 数据源: Tushare

Python实现

• 语言: Python 3.10+
• Web框架: FastAPI
• WebSocket: FastAPI原生
• 数据库: PostgreSQL 15+ (SQLAlchemy ORM)
• 数据源: Tushare (原生支持)

---

项目结构

Go实现

market-data-service/
├── api/                    # API接口定义
│   ├── types.go           # 请求/响应类型定义
│   ├── router.go          # HTTP路由注册
│   ├── admin_types.go     # 管理后台类型定义
│   └── admin_router.go    # 管理后台路由
├── internal/              # 内部实现
│   ├── handler/           # HTTP Handler实现
│   ├── service/           # 业务逻辑层
│   ├── repository/        # 数据访问层
│   ├── websocket/         # WebSocket服务
│   └── monitor/           # 数据质量监控
├── adapter/               # 数据源适配器框架
│   ├── adapter.go         # 适配器接口定义
│   └── tushare/           # Tushare适配器实现
├── pkg/                   # 公共包
├── cmd/                   # 程序入口
├── config.example.json    # 配置文件示例
├── go.mod
├── Makefile
└── README.md

Python实现

python_market_data_service/
├── app/
│   ├── main.py            # FastAPI主应用
│   ├── api/               # API路由 (FastAPI)
│   ├── core/              # 核心模块 (配置、日志、错误)
│   ├── models/            # 数据模型 (Pydantic)
│   ├── repositories/      # 数据访问 (SQLAlchemy)
│   ├── services/          # 业务逻辑层
│   ├── adapters/          # 数据源适配器
│   ├── websocket/         # WebSocket服务
│   └── monitor/           # 数据质量监控
├── scripts/               # 数据同步工具
├── requirements.txt       # Python依赖
├── pyproject.toml        # 项目配置
├── config.json           # 配置文件 (与Go相同)
├── README.md             # Python项目说明
└── MIGRATION_GUIDE.md    # 迁移对照指南

---

快速开始

最快方式: 查看 QUICKSTART.md - 30秒启动指南

方式一：Go实现（推荐生产环境）

1. 环境准备

• Go 1.21+
• PostgreSQL 15+
• Tushare Token (从 Tushare官网 获取)

2. 配置环境变量

export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgres://user:password@localhost:5432/marketdata?sslmode=disable"
export PORT="8080"
export GIN_MODE="debug"

3. 初始化数据库

# 创建数据库
createdb marketdata

# 执行初始化脚本
psql $DATABASE_URL -f memory/2026-03-07-database-schema.sql

4. 下载依赖并启动

make deps
make run

方式二：Python实现（推荐开发环境）

1. 环境准备

• Python 3.10+
• PostgreSQL 15+
• Tushare Token

2. 安装依赖

cd python_market_data_service

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
pip install tushare

3. 配置环境变量

export TUSHARE_TOKEN="your_tushare_token"
export DATABASE_URL="postgresql://user:password@localhost:5432/marketdata"
export PORT="8080"

4. 初始化数据库并启动

# 初始化数据库（SQLAlchemy自动创建表）
python -c "from app.repositories.database import init_db; init_db()"

# 启动服务
python -m app.main
# 或使用 uvicorn
uvicorn app.main:app --reload --port 8080

服务将启动在 http://localhost:8080

---

API接口

注意: Go和Python实现的API接口完全一致！

股票接口

接口	方法	说明
/v1/stock/klines/:symbol	GET	查询K线数据
/v1/stock/symbols	GET	查询标的列表
/v1/stock/klines/batch	POST	批量查询K线
/v1/stock/trading-dates	GET	获取交易日历

查询K线示例:

curl "http://localhost:8080/v1/stock/klines/000001.SZ?start=20250301&end=20250307&freq=1d&adjust=qfq" \
  -H "X-API-Key: your_api_key"

期货接口

接口	方法	说明
/v1/futures/klines/:symbol	GET	查询K线数据
/v1/futures/symbols	GET	查询标的列表
/v1/futures/klines/batch	POST	批量查询K线
/v1/futures/continuous/:underlying	GET	查询主力连续合约（预留）
/v1/futures/trading-dates	GET	获取交易日历
/v1/futures/contracts	GET	获取品种合约列表

管理后台

服务启动后，访问 http://localhost:8080/admin 进入管理后台。

Python特有: 自动生成API文档

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

---

数据同步工具

Go实现

# 同步股票列表
go run ./cmd/sync -type stocks

# 同步期货列表
go run ./cmd/sync -type futures

# 同步交易日历
go run ./cmd/sync -type calendar -start 20240101 -end 20241231

# 同步K线数据
go run ./cmd/sync -type klines -symbol 000001.SZ -start 20240301 -end 20240307 -freq 1d

Python实现

# 同步股票列表
python scripts/sync_data.py --type stocks

# 同步期货列表
python scripts/sync_data.py --type futures

# 同步交易日历
python scripts/sync_data.py --type calendar --start 20240101 --end 20241231

# 同步K线数据
python scripts/sync_data.py --type klines --symbol 000001.SZ --start 20240301 --end 20240307 --freq 1d

---

部署

Docker部署

Go实现:

docker build -t market-data-service:go .
docker run -p 8080:8080 market-data-service:go

Python实现:

cd python_market_data_service
docker build -t market-data-service:python .
docker run -p 8080:8080 market-data-service:python

详细部署文档请参考 DEPLOY.md

---

实现方式对比

特性	Go	Python
性能	⭐⭐⭐ 高性能	⭐⭐ 良好
开发效率	⭐⭐ 中等	⭐⭐⭐ 高
数据源生态	⭐⭐ 需自行封装	⭐⭐⭐ Tushare原生支持
内存占用	⭐⭐⭐ 低 (~50MB)	⭐⭐ 中等 (~100MB)
启动速度	⭐⭐⭐ 快 (~100ms)	⭐⭐ 中等 (~2s)
类型安全	⭐⭐⭐ 编译期检查	⭐⭐ 运行时检查 (Pydantic)
部署复杂度	⭐⭐⭐ 单二进制	⭐⭐ 依赖较多
API文档	⭐⭐ 需手动维护	⭐⭐⭐ 自动生成

推荐:

• 生产环境: Go实现
• 开发测试: Python实现
• 数据源对接: Python实现（生态更好）

---

文档

🚀 启动部署

• QUICKSTART.md - 30秒快速启动指南（推荐先看）
• 启动指南 - 完整的启动教程
• 部署文档 - 详细部署指南（含Docker和Systemd）

📚 开发文档

• 开发指南 - 开发新功能指南
• 架构设计 - 系统架构文档
• API速查表 - API快速参考
• Python迁移指南 - Go到Python迁移对照

📋 项目信息

• 项目进度 - 开发进度和计划

---

常见问题

Q: 应该选择Go还是Python实现？

A:

• 如果需要生产环境高并发，选择Go
• 如果需要快速开发、原型验证，选择Python
• 如果需要频繁对接数据源，选择Python（生态更好）

Q: 两个实现的API是否兼容？

A: 完全兼容。所有接口、请求参数、响应格式完全一致，客户端可无缝切换。

Q: 数据库Schema是否相同？

A: 相同。两个实现使用相同的数据库Schema，可共享数据。

Q: 如何实现股票复权？

A: 查询时传入 adjust=qfq 或 adjust=hfq 参数，服务会自动应用复权系数。

Q: 期货主力连续合约何时支持？

A: 主力连续合约功能在预留表结构中，将在后续版本实现。

---

贡献

欢迎提交Issue和PR！

• Go实现相关: 提交到本仓库
• Python实现相关: 提交到 python_market_data_service/ 目录

---

License

MIT