# 管理后台架构设计文档 ## 重要说明 本文档适用于 **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实现**: ```go // 使用 sync.RWMutex 保证并发安全 type ConfigServiceImpl struct { config *config.Config mu sync.RWMutex callbacks map[api.ConfigType][]func() } ``` **Python实现**: ```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实现**: ```go type AdapterServiceImpl struct { factories map[string]AdapterFactory configs map[string]*adapterConfig activeAdapters map[string]adapter.DataSourceAdapter } ``` **Python实现**: ```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**: ```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**: ```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**: ```go // 1. 扩展配置结构 type Config struct { // ... 现有配置 Custom CustomConfig `json:"custom"` } // 2. 在 ConfigService 中添加处理逻辑 ``` **Python**: ```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 | --- **文档结束**