刘华勇
c19ca2aa4c
- 基于 axum + sqlx + tokio 的 Rust 后端服务 - 实现多数据源管理（东方财富/新浪/腾讯）含 failover 容错 - 数据源健康检查、请求日志记录与重放诊断 - 股票公司列表、历史K线、实时行情数据获取 - 配置 .gitignore：忽略 target 构建产物、.env 密钥、data 数据库
242 lines
4.9 KiB
Markdown
242 lines
4.9 KiB
Markdown
# Trading Backend 🦀
|
||
|
||
基于 Rust 的交易数据后端服务，提供A股公司信息、历史行情、实时数据查询接口，支持多数据库和Redis缓存。
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 技术栈
|
||
- **Web框架**: Axum 0.7
|
||
- **数据库**: SQLite（可切换到 PostgreSQL/MySQL）
|
||
- **缓存**: Redis（Key = md5(url + 参数)）
|
||
- **ORM**: SQLx + SeaORM（多数据库兼容）
|
||
- **异步运行时**: Tokio
|
||
|
||
### 目录结构
|
||
```
|
||
backend/
|
||
├── migrations/ # 数据库迁移文件
|
||
├── src/
|
||
│ ├── main.rs # 入口文件
|
||
│ ├── db/ # 数据库抽象层（支持多数据库）
|
||
│ ├── cache/ # Redis 缓存层
|
||
│ ├── models/ # 数据模型
|
||
│ ├── services/ # 数据服务（可扩展多数据源）
|
||
│ ├── routes/ # API 路由
|
||
│ └── utils/ # 工具函数
|
||
├── data/ # SQLite 数据文件（运行时创建）
|
||
├── Cargo.toml
|
||
├── .env # 环境变量
|
||
└── .env.example # 环境变量模板
|
||
```
|
||
|
||
### 核心特性
|
||
|
||
1. **多数据库兼容**
|
||
- 当前使用 SQLite（无配置开箱即用）
|
||
- 通过修改环境变量 `DB_TYPE` 可切换到 PostgreSQL/MySQL
|
||
- 使用 trait 抽象数据库接口，未来可平滑迁移
|
||
|
||
2. **Redis 缓存**
|
||
- 缓存 Key 格式：`td:cache:{md5(url+参数)}`
|
||
- 默认 TTL: 5 分钟
|
||
- 支持缓存查询结果，减少外部 API 调用
|
||
|
||
3. **数据源可扩展**
|
||
- 实现 `DataService` trait
|
||
- 当前提供 MockService（测试）和 TushareService（生产）
|
||
- 可轻松接入其他数据源（东方财富、同花顺等）
|
||
|
||
## 📊 数据库设计
|
||
|
||
### 表结构
|
||
|
||
**companies** - 公司基本信息
|
||
```
|
||
- id: 主键
|
||
- code: 股票代码
|
||
- name: 公司名称
|
||
- market: 市场（SH/SZ/BJ）
|
||
- industry: 行业
|
||
- list_date: 上市日期
|
||
- ...
|
||
```
|
||
|
||
**stock_daily** - 日线行情
|
||
```
|
||
- id: 主键
|
||
- stock_id: 关联公司ID
|
||
- trade_date: 交易日期
|
||
- open/high/low/close: OHLC
|
||
- volume/amount: 成交量/额
|
||
- adj_close: 前复权价
|
||
- ...
|
||
```
|
||
|
||
**dividends** - 分红送转
|
||
```
|
||
- id: 主键
|
||
- stock_id: 关联公司ID
|
||
- div_date: 除权日
|
||
- dividend_cash: 每股现金分红
|
||
- ...
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
- Rust 1.70+
|
||
- Redis（可选，用于缓存）
|
||
- SQLite（已内置）
|
||
|
||
### 安装运行
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 安装依赖
|
||
cargo build
|
||
|
||
# 复制配置文件
|
||
cp .env.example .env
|
||
|
||
# 启动服务
|
||
./start.sh
|
||
# 或直接运行
|
||
cargo run
|
||
```
|
||
|
||
服务默认运行在 `http://localhost:8080`
|
||
|
||
### 环境变量配置
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```env
|
||
# 服务器配置
|
||
RUST_LOG=info
|
||
SERVER_HOST=0.0.0.0
|
||
SERVER_PORT=8080
|
||
|
||
# 数据库配置
|
||
DB_TYPE=sqlite
|
||
SQLITE_PATH=./data/trading.db
|
||
|
||
# Redis 配置（可选）
|
||
REDIS_URL=redis://127.0.0.1:6379
|
||
REDIS_CACHE_TTL=300
|
||
|
||
# Tushare Token（如需使用真实数据源）
|
||
TUSHARE_TOKEN=your_token_here
|
||
```
|
||
|
||
## 📡 API 接口
|
||
|
||
### 公开 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/health` | 健康检查 |
|
||
| GET | `/api/companies` | 获取公司列表（分页） |
|
||
| GET | `/api/companies/:code` | 获取公司详情 |
|
||
| GET | `/api/companies/search` | 搜索公司 |
|
||
| GET | `/api/stocks/daily` | 获取日线行情 |
|
||
| GET | `/api/stocks/latest` | 获取最新行情 |
|
||
|
||
### 示例请求
|
||
|
||
```bash
|
||
# 获取公司列表
|
||
curl http://localhost:8080/api/companies?page=1&page_size=20
|
||
|
||
# 获取公司详情
|
||
curl http://localhost:8080/api/companies/000100
|
||
|
||
# 搜索公司
|
||
curl "http://localhost:8080/api/companies/search?keyword=科技"
|
||
|
||
# 获取日线行情
|
||
curl "http://localhost:8080/api/stocks/daily?code=000100&start=2024-01-01&end=2024-12-31"
|
||
|
||
# 获取最新行情
|
||
curl "http://localhost:8080/api/stocks/latest?codes=000100,600036"
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
## 🔐 内部 API（管理后台）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/internal/sync/companies` | 同步公司列表 |
|
||
| POST | `/api/internal/sync/daily` | 同步历史行情 |
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行特定测试
|
||
cargo test test_generate_key
|
||
```
|
||
|
||
## 📦 构建生产版本
|
||
|
||
```bash
|
||
# 构建 Release
|
||
cargo build --release
|
||
|
||
# 运行
|
||
./target/release/trading-backend
|
||
```
|
||
|
||
## 🔄 切换数据库
|
||
|
||
### 切换到 PostgreSQL
|
||
|
||
```env
|
||
DB_TYPE=postgres
|
||
POSTGRES_URL=postgresql://user:password@localhost/trading
|
||
```
|
||
|
||
### 切换到 MySQL
|
||
|
||
```env
|
||
DB_TYPE=mysql
|
||
MYSQL_URL=mysql://user:password@localhost/trading
|
||
```
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 添加新的数据源
|
||
|
||
1. 实现 `DataService` trait
|
||
2. 在 `main.rs` 中注册服务
|
||
3. 重启服务
|
||
|
||
### 添加新的 API
|
||
|
||
1. 在 `routes/` 中创建处理器
|
||
2. 在 `main.rs` 中注册路由
|
||
3. 添加单元测试
|
||
|
||
## 📝 待办事项
|
||
|
||
- [ ] 完善数据库同步逻辑
|
||
- [ ] 实现前复权价格计算
|
||
- [ ] 添加更多技术指标（MA/MACD/KDJ）
|
||
- [ ] 实现实时行情推送（WebSocket）
|
||
- [ ] 添加认证和授权
|
||
- [ ] 性能优化和监控
|
||
|
||
## 📄 License
|
||
|
||
MIT |