You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
31 KiB
31 KiB
管理后台架构设计文档
重要说明
本文档适用于 Go 和 Python 双实现。两者架构设计保持一致，仅技术栈不同：
- Go: Gin + 原生SQL + Goroutine
- Python: FastAPI + SQLAlchemy + asyncio
1. 系统架构图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Web Browser │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Dashboard │ │ Config │ │ Adapter │ │ Test │ │ │
│ │ │ Page │ │ Page │ │ Page │ │ Page │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ http://localhost:8080/admin │
└─────────────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 接入层 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Router (Gin/FastAPI) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │ API Router │ │ Admin Router │ │ WebSocket Handler │ │ │
│ │ │(api/router.go)│ │(api/admin_ │ │ (/v1/stream) │ │ │
│ │ │ (routes.py) │ │ router.go) │ │ │ │ │
│ │ │ │ │(admin_routes)│ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ │ │ │ │ │
│ └──────────┼────────────────┼─────────────────────────────────────────┘ │
│ │ │ │
└─────────────┼────────────────┼─────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 业务层 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
│ │ │ Stock/Futures │ │ AdminHandlerImpl │ │ │
│ │ │ Services │ │(admin.go / admin_routes.py) │ │ │
│ │ └─────────────────┘ └──────────────┬──────────────────┘ │ │
│ │ │ │ │
│ └──────────────────────────────────────────────┼──────────────────────┘ │
│ │ │
└─────────────────────────────────────────────────┼──────────────────────────┘
│
┌───────────────────────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 服务层 │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ ConfigService │ │AdapterService │ │ TestService │ │
│ │(config.go) │ │(adapter.go) │ │ (test.go) │ │
│ │(config_service)│ │(adapter_service)│ │(test_service) │ │
│ │ │ │ │ │ │ │
│ │ • 配置加载 │ │ • 适配器注册 │ │ • API测试 │ │
│ │ • 热加载 │ │ • 启用/禁用 │ │ • WS测试 │ │
│ │ • 状态监控 │ │ • 配置管理 │ │ • 历史记录 │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
└────────────────────────────────┼───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 数据层 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ config.json │ │ Database │ │ Adapter │ │ Memory │ │
│ │ (文件) │ │ (PostgreSQL)│ │ Factory │ │ Cache │ │
│ │ │ │ │ │ │ │ │ │
│ │ 持久化配置 │ │ 数据源配置 │ │ 适配器实例 │ │ 测试历史 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
技术栈对比
| 层级 | Go实现 | Python实现 |
|---|---|---|
| 接入层 | Gin Router | FastAPI Router |
| 业务层 | Go Interfaces | Python Protocols |
| 服务层 | Go Structs + Methods | Python Classes |
| 数据层 | database/sql | SQLAlchemy ORM |
| 配置 | JSON + 自定义解析 | Pydantic Settings |
2. 模块关系图
配置管理模块
┌─────────────────────────────────────────────────────────────────┐
│ 配置管理模块 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ConfigService │ │
│ │ (Go / Python) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│ │ │ Load Config │───►│ Store Config│◄───│UpdateConfig│ │ │
│ │ │ (JSON File) │ │ (Memory) │ │ (API) │ │ │
│ │ └─────────────┘ └──────┬──────┘ └────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Reload │ │ │
│ │ │ (Hot Swap) │ │ │
│ │ └──────┬──────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Callbacks │ │ │
│ │ │ (Notify All)│ │ │
│ │ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Go实现:
// 使用 sync.RWMutex 保证并发安全
type ConfigServiceImpl struct {
config *config.Config
mu sync.RWMutex
callbacks map[api.ConfigType][]func()
}
Python实现:
# 使用 threading.RLock 保证并发安全
class ConfigService:
def __init__(self):
self.config = get_config()
self.lock = threading.RLock()
self.callbacks: Dict[ConfigType, List[Callable]] = {}
适配器管理模块
┌─────────────────────────────────────────────────────────────────┐
│ 适配器管理模块 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ AdapterService │ │
│ │ (Go / Python) │ │
│ │ ┌──────────────┐ ┌─────────────────────┐ │ │
│ │ │ Register │────────►│ Factory Map │ │ │
│ │ │ (Add Factory)│ │ [name]factoryFunc │ │ │
│ │ └──────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌─────────────────────┐ │ │
│ │ │ Toggle │────────►│ Active Adapters │ │ │
│ │ │(Enable/Disable)│ │ [name]adapterInstance│ │ │
│ │ └──────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌─────────────────────┐ │ │
│ │ │Update Config │────────►│ Adapter Config │ │ │
│ │ └──────────────┘ │ [name]configMap │ │ │
│ │ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Go实现:
type AdapterServiceImpl struct {
factories map[string]AdapterFactory
configs map[string]*adapterConfig
activeAdapters map[string]adapter.DataSourceAdapter
}
Python实现:
class AdapterService:
def __init__(self):
self.factories: Dict[str, Callable] = {}
self.configs: Dict[str, dict] = {}
self.active_adapters: Dict[str, DataSourceAdapter] = {}
测试管理模块
┌─────────────────────────────────────────────────────────────────┐
│ 测试管理模块 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TestService │ │
│ │ (Go / Python) │ │
│ │ ┌────────────────┐ ┌──────────────────────┐ │ │
│ │ │ API Test │ │ Test Cases (JSON) │ │ │
│ │ │ • Build Request│◄───────│ • stock_klines │ │ │
│ │ │ • Execute HTTP │ │ • futures_klines │ │ │
│ │ │ • Parse Result │ │ • admin_health │ │ │
│ │ └───────┬────────┘ └──────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌────────────────┐ ┌──────────────────────┐ │ │
│ │ │ WS Test │ │ Test History │ │ │
│ │ │ • Dial WS │◄───────│ (In-Memory Cache) │ │ │
│ │ │ • Send Msg │ │ • api_tests [] │ │ │
│ │ │ • Recv Msg │ │ • ws_tests [] │ │ │
│ │ └────────────────┘ └──────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
3. 数据流图
3.1 配置热加载流程
User/Admin Admin API ConfigService File System
│ │ │ │
│ 1.修改 config.json │ │ │
│────────────────────────────►│ │ │
│ │ │ │
│ 2.点击"热加载" │ │ │
│────────────────────────────►│ │ │
│ │ 3.POST /system/reload │ │
│ │──────────────────────────►│ │
│ │ │ 4.读取 config.json │
│ │ │───────────────────────►│
│ │ │◄───────────────────────│
│ │ │ 5.解析并更新内存配置 │
│ │ │ │
│ │ │ 6.触发回调函数 │
│ │◄──────────────────────────│ │
│◄────────────────────────────│ 7.返回成功 │ │
│ │ │ │
3.2 适配器切换流程
User Admin API AdapterService Adapter Instance
│ │ │ │
│ 1.选择适配器并点击"启用" │ │ │
│──────────────────────────►│ │ │
│ │ 2.POST /adapters/toggle │ │
│ │─────────────────────────►│ │
│ │ │ 3.创建新实例 │
│ │ │─────────────────────►│
│ │ │◄─────────────────────│
│ │ │ 4.调用 Connect() │
│ │ │ │
│ │ │ 5.更新 activeAdapters│
│ │◄─────────────────────────│ │
│◄──────────────────────────│ 6.返回成功 │ │
4. 关键设计决策
4.1 配置存储
| 方案 | 优点 | 缺点 | Go选择 | Python选择 |
|---|---|---|---|---|
| JSON文件 | 简单、易编辑、无依赖 | 无事务支持 | ✅ | ✅ |
| 数据库存储 | 支持事务、历史版本 | 增加依赖 | ❌ | ❌ |
| etcd/consul | 分布式、高可用 | 引入新组件 | ❌ | ❌ |
Python增强: 使用 Pydantic 进行类型验证和自动解析
4.2 前端实现
| 方案 | 优点 | 缺点 | 选择 |
|---|---|---|---|
| 纯HTML/JS | 无依赖、部署简单 | 功能受限 | ✅ |
| Vue/React | 功能强大、生态丰富 | 需构建、体积大 | ❌ |
| 独立前端项目 | 前后端分离 | 部署复杂 | ❌ |
4.3 数据库访问
| 方案 | Go | Python | 说明 |
|---|---|---|---|
| 原生SQL | ✅ database/sql | ❌ | Go标准方式 |
| ORM | ❌ | ✅ SQLAlchemy | Python生态标准 |
| SQL Builder | ⏳ 可选 | ⏳ 可选 | 未来考虑 |
5. 扩展点设计
5.1 新增适配器
Go:
// 1. 实现适配器接口
type MyAdapter struct { ... }
func (a *MyAdapter) Connect(config map[string]string) error { ... }
func (a *MyAdapter) HealthCheck() error { ... }
// ... 实现其他方法
// 2. 注册到服务
func init() {
adapterService.RegisterAdapter("myadapter", func() adapter.DataSourceAdapter {
return &MyAdapter{}
})
}
Python:
# 1. 实现适配器接口
class MyAdapter(DataSourceAdapter):
async def connect(self, config: dict) -> None:
pass
async def health_check(self) -> bool:
return True
# ... 实现其他方法
# 2. 注册到服务
adapter_service.register_adapter("myadapter", lambda: MyAdapter())
5.2 新增配置类型
Go:
// 1. 扩展配置结构
type Config struct {
// ... 现有配置
Custom CustomConfig `json:"custom"`
}
// 2. 在 ConfigService 中添加处理逻辑
Python:
# 1. 扩展配置结构
class Config(BaseModel):
# ... 现有配置
custom: CustomConfig = Field(default_factory=CustomConfig)
# 2. Pydantic 自动处理验证和解析
6. 部署架构
┌─────────────────────────────────────────────────────────────┐
│ 生产环境部署 │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Nginx / LB │ │
│ │ (SSL终止、静态资源缓存) │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────┴──────────┐ │
│ │ │ │
│ ┌───────▼───────┐ ┌────────▼────────┐ │
│ │ Market Data │ │ Market Data │ │
│ │ Service 1 │ │ Service 2 │ │
│ │ │ │ │ │
│ │ • Go 或 │ │ • Go 或 │ │
│ │ Python │ │ Python │ │
│ │ • /v1/api │ │ • /v1/api │ │
│ │ • /admin │ │ • /admin │ │
│ │ • /v1/stream │ │ • /v1/stream │ │
│ └───────┬───────┘ └────────┬────────┘ │
│ │ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────────────▼──────────────────┐ │
│ │ PostgreSQL Cluster │ │
│ │ │ │
│ │ • data_source_config (数据源配置) │ │
│ │ • 其他业务表... │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
混合部署建议
┌─────────────────────────────────────────────────────────────┐
│ 推荐混合部署架构 │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Go 实现 │ │ Python 实现 │ │
│ │ (生产环境) │ │ (开发/测试) │ │
│ │ │ │ │ │
│ │ • 高并发API │ │ • 数据同步工具 │ │
│ │ • WebSocket │ │ • 管理后台 │ │
│ │ • 核心服务 │ │ • 快速原型 │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ PostgreSQL │ │
│ │ (共享数据库) │ │
│ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
7. 监控点
| 模块 | 监控项 | Go方式 | Python方式 |
|---|---|---|---|
| ConfigService | 配置加载耗时 | 日志 | 日志 |
| ConfigService | 配置热加载次数 | 日志 | 日志 |
| AdapterService | 适配器健康状态 | 接口/日志 | 接口/日志 |
| AdapterService | 适配器切换次数 | 日志 | 日志 |
| TestService | 测试执行次数 | 内存/日志 | 内存/日志 |
| TestService | 测试成功率 | 计算 | 计算 |
| WebSocket | 连接数 | metrics | metrics |
| Database | 查询耗时 | SQL日志 | SQLAlchemy事件 |
8. 实现差异汇总
| 方面 | Go | Python |
|---|---|---|
| 并发模型 | Goroutines | asyncio |
| 锁机制 | sync.Mutex | threading.Lock/asyncio.Lock |
| 数据库 | database/sql + pq | SQLAlchemy + psycopg2 |
| Web框架 | Gin | FastAPI |
| 类型系统 | Struct + Interface | Pydantic Model |
| 配置解析 | encoding/json | Pydantic Settings |
| 错误处理 | error interface | Exception |
| 日志 | log | logging |
文档结束