18 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

管理后台开发文档

版本: v1.0
日期: 2026-03-07
作者: AI Assistant

一、功能概述

管理后台为行情数据服务提供统一的可视化管理界面，支持配置热加载、数据源适配器管理、接口测试等功能。

1.1 功能模块

模块	功能描述	状态
系统概览	实时监控系统状态、内存使用、运行时长	✅ 已完成
配置管理	在线修改配置、热加载、配置持久化	✅ 已完成
数据源适配	适配器管理、启用/禁用、配置更新	✅ 已完成
接口测试	API测试、WebSocket测试、历史记录	✅ 已完成

1.2 技术特性

热加载: 配置修改后无需重启服务即可生效
实时状态: 系统运行状态定时刷新（5秒间隔）
单页应用: 纯前端实现，无页面刷新
响应式设计: 适配桌面端浏览器

二、架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                         前端层                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │  系统概览    │ │  配置管理    │ │  数据源适配  │  接口测试   │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
│                         │                                   │
│                    内嵌HTML/JS                               │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP API
┌─────────────────────────┼───────────────────────────────────┐
│                         ▼                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   AdminRouter                         │  │
│  │  (api/admin_router.go)                               │  │
│  └──────────────────────────────────────────────────────┘  │
│                         │                                   │
│                         ▼                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                AdminHandlerImpl                       │  │
│  │  (internal/handler/admin.go)                         │  │
│  └──────────────────────────────────────────────────────┘  │
│                         │                                   │
│       ┌─────────────────┼─────────────────┐                 │
│       ▼                 ▼                 ▼                 │
│  ┌─────────┐      ┌─────────┐      ┌─────────┐             │
│  │Config   │      │Adapter  │      │Test     │             │
│  │Service  │      │Service  │      │Service  │             │
│  └─────────┘      └─────────┘      └─────────┘             │
│                                                         服务层│
└─────────────────────────────────────────────────────────────┘

2.2 目录结构

market-data-service/
├── api/
│   ├── admin_types.go          # 管理后台类型定义 (270行)
│   └── admin_router.go         # 管理后台路由 + HTML页面 (680行)
├── internal/
│   ├── handler/
│   │   └── admin.go            # 管理后台Handler (180行)
│   └── service/
│       ├── config.go           # 配置管理服务 (330行)
│       ├── adapter.go          # 适配器管理服务 (220行)
│       └── test.go             # 测试服务 (350行)
├── pkg/
│   └── config/
│       └── config.go           # 配置结构定义
├── cmd/server/
│   └── main.go                 # 服务入口（集成管理后台）
└── docs/
    └── admin-dashboard-development.md  # 本文档

三、核心模块

3.1 配置管理服务 (ConfigService)

文件: internal/service/config.go

功能

配置加载与保存（JSON格式）
热加载配置（支持按类型选择性加载）
配置变更回调机制
系统状态监控

核心接口

type ConfigService interface {
    GetConfigList(ctx context.Context, req *api.ConfigListRequest) (*api.ConfigListData, error)
    UpdateConfig(ctx context.Context, req *api.ConfigUpdateRequest) (*api.ConfigUpdateData, error)
    ReloadConfig(ctx context.Context, req *api.ReloadRequest) (*api.ConfigUpdateData, error)
    GetSystemStatus(ctx context.Context) (*api.SystemStatusData, error)
    GetCurrentConfig() *config.Config
}

配置类型

配置类型	说明	热加载支持
server	服务器端口、运行模式、API Key	部分需重启
database	数据库连接配置	需重启
redis	Redis连接配置	需重启
source	数据源适配器配置	✅ 支持

使用示例

// 创建配置服务
configService, err := service.NewConfigService("./config.json")

// 获取配置列表
data, err := configService.GetConfigList(ctx, &api.ConfigListRequest{Type: "server"})

// 更新配置
result, err := configService.UpdateConfig(ctx, &api.ConfigUpdateRequest{
    Type: "server",
    Items: map[string]interface{}{
        "port": 8080,
        "mode": "release",
    },
})

// 热加载配置
result, err := configService.ReloadConfig(ctx, &api.ReloadRequest{ConfigType: "source"})

3.2 适配器管理服务 (AdapterService)

文件: internal/service/adapter.go

功能

适配器工厂注册
适配器启用/禁用
适配器配置管理
适配器实例管理

适配器状态

状态	说明
active	已激活，正在使用
standby	待命，可用但未激活
disabled	已禁用
error	发生错误

核心接口

type AdapterService interface {
    GetAdapterList(ctx context.Context) (*api.AdapterListData, error)
    ToggleAdapter(ctx context.Context, req *api.AdapterToggleRequest) error
    UpdateAdapterConfig(ctx context.Context, req *api.AdapterConfigUpdateRequest) error
    GetActiveAdapter(assetClass string) (adapter.DataSourceAdapter, error)
    RegisterAdapter(name string, factory AdapterFactory)
}

内置适配器

适配器	类型	状态	说明
tushare	HTTP	已实现	Tushare Pro 数据接口
wind	WebSocket	预留	Wind 金融终端（待实现）

3.3 测试服务 (TestService)

文件: internal/service/test.go

功能

API接口测试用例管理
WebSocket连接测试
测试历史记录
实时测试执行

测试分类

API测试:

股票接口：K线查询、标的列表、批量查询、交易日历
期货接口：K线查询、标的列表、批量查询、合约查询
管理接口：健康检查、数据源状态

WebSocket测试:

订阅股票行情
订阅期货行情
批量订阅
取消订阅

核心接口

type TestService interface {
    GetAPITestList(ctx context.Context) (*api.APITestListData, error)
    RunAPITest(ctx context.Context, baseURL string, req *api.APITestRequest) (*api.APITestResult, error)
    GetWSTestList(ctx context.Context) (*api.WSTestListData, error)
    RunWSTest(ctx context.Context, wsURL string, req *api.WSTestRequest) (*api.WSTestResult, error)
    GetTestHistory(ctx context.Context, req *api.TestHistoryRequest) (*api.TestHistoryData, error)
}

四、API接口文档

4.1 系统管理接口

获取系统状态

GET /v1/admin/system/status

响应示例:

{
  "code": 0,
  "data": {
    "status": "running",
    "version": "1.0.0",
    "start_time": "2026-03-07T13:00:00Z",
    "uptime": "1小时30分钟",
    "go_version": "go1.21.0",
    "memory": {
      "alloc": 10485760,
      "total_alloc": 52428800,
      "sys": 33554432,
      "num_gc": 5
    },
    "goroutines": 15
  }
}

热加载配置

POST /v1/admin/system/reload
Content-Type: application/json

{
  "config_type": "source"  // 可选：server/database/redis/source
}

响应示例:

{
  "code": 0,
  "data": {
    "success": true,
    "message": "配置热加载成功"
  }
}

重启服务

POST /v1/admin/system/restart
Content-Type: application/json

{
  "force": false
}

4.2 配置管理接口

获取配置列表

GET /v1/admin/config?type=server

响应示例:

{
  "code": 0,
  "data": {
    "sections": [
      {
        "name": "服务器配置",
        "type": "server",
        "description": "HTTP服务器相关配置",
        "items": [
          {
            "key": "port",
            "value": 8080,
            "type": "int",
            "description": "服务端口",
            "editable": true,
            "required": true
          }
        ]
      }
    ],
    "version": "1.0.0",
    "updated": "2026-03-07T13:00:00Z"
  }
}

更新配置

PUT /v1/admin/config
Content-Type: application/json

{
  "type": "server",
  "items": {
    "port": 8080,
    "mode": "release",
    "api_key": "new-key"
  }
}

响应示例:

{
  "code": 0,
  "data": {
    "success": true,
    "need_restart": false,
    "message": "配置更新成功"
  }
}

4.3 适配器管理接口

获取适配器列表

GET /v1/admin/adapters

响应示例:

{
  "code": 0,
  "data": {
    "adapters": [
      {
        "name": "tushare",
        "type": "http",
        "version": "1.0.0",
        "description": "Tushare Pro 金融数据接口",
        "status": "active",
        "config": {
          "token": "***",
          "base_url": "https://api.tushare.pro"
        },
        "updated_at": "2026-03-07T13:00:00Z"
      }
    ]
  }
}

启用/禁用适配器

POST /v1/admin/adapters/toggle
Content-Type: application/json

{
  "name": "tushare",
  "enable": true
}

更新适配器配置

PUT /v1/admin/adapters/config
Content-Type: application/json

{
  "name": "tushare",
  "config": {
    "token": "new-token",
    "base_url": "https://api.tushare.pro"
  }
}

4.4 接口测试管理

获取API测试列表

GET /v1/admin/tests/api

响应示例:

{
  "code": 0,
  "data": {
    "categories": [
      {
        "name": "股票接口",
        "items": [
          {
            "id": "stock_klines",
            "name": "查询股票K线",
            "method": "GET",
            "path": "/v1/stock/klines/{symbol}",
            "description": "查询指定股票的K线数据",
            "params": {
              "symbol": "000001.SZ",
              "start": "20260201",
              "end": "20260307",
              "freq": "1d"
            }
          }
        ]
      }
    ],
    "base_url": "http://localhost:8080"
  }
}

执行API测试

POST /v1/admin/tests/api/run
Content-Type: application/json

{
  "id": "stock_klines",
  "params": {
    "symbol": "000001.SZ"
  }
}

响应示例:

{
  "code": 0,
  "data": {
    "id": 1234567890,
    "case_id": "stock_klines",
    "name": "查询股票K线",
    "success": true,
    "status_code": 200,
    "latency": 45,
    "request": {
      "method": "GET",
      "url": "http://localhost:8080/v1/stock/klines/000001.SZ?start=20260201&end=20260307&freq=1d"
    },
    "response": {
      "code": 0,
      "data": {...}
    },
    "timestamp": "2026-03-07T13:00:00Z"
  }
}

获取WebSocket测试列表

GET /v1/admin/tests/ws

执行WebSocket测试

POST /v1/admin/tests/ws/run
Content-Type: application/json

{
  "id": "ws_subscribe_stock",
  "symbols": ["000001.SZ", "000002.SZ"]
}

获取测试历史

GET /v1/admin/tests/history?type=api&limit=20

五、前端实现

5.1 技术方案

纯HTML/CSS/JS: 无前端框架依赖
单页应用: 前端路由切换，无页面刷新
嵌入式部署: HTML代码内嵌在Go文件中

5.2 页面结构

/admin
├── 系统概览 (dashboard)
│   ├── 状态卡片（运行状态、运行时长、版本、Goroutines）
│   ├── 内存使用详情
│   └── 操作按钮（热加载、重启）
│
├── 配置管理 (config)
│   ├── 服务器配置
│   ├── 数据库配置
│   ├── Redis配置
│   └── 数据源配置
│
├── 数据源适配 (adapters)
│   └── 适配器列表表格
│
└── 接口测试 (tests)
    ├── API测试页签
    ├── WebSocket测试页签
    └── 测试历史页签

5.3 前端API封装

// API请求封装
async function apiRequest(method, path, data = null) {
    const options = {
        method,
        headers: {
            'Content-Type': 'application/json',
            'X-Admin-Token': localStorage.getItem('adminToken') || ''
        }
    };
    
    if (data) {
        options.body = JSON.stringify(data);
    }
    
    const response = await fetch(state.baseURL + path, options);
    return response.json();
}

六、使用指南

6.1 启动服务

# 设置配置文件路径
export CONFIG_PATH="./config.json"

# 启动服务
go run ./cmd/server

# 或使用Makefile
make run

6.2 访问管理后台

浏览器访问：http://localhost:8080/admin

6.3 配置热加载示例

# 1. 修改 config.json 文件

# 2. 调用热加载API
curl -X POST "http://localhost:8080/v1/admin/system/reload" \
  -H "Content-Type: application/json" \
  -d '{"config_type": "source"}'

# 3. 或在管理后台点击"热加载配置"按钮

6.4 适配器管理流程

1. 进入"数据源适配"页面
2. 查看已注册的适配器列表
3. 点击"启用"/"禁用"按钮切换状态
4. 点击适配器名称可编辑配置

七、待完善事项

7.1 功能增强

优先级	功能	说明
P1	用户认证	实现基于Token的管理员认证机制
P1	操作日志	记录所有配置变更和管理操作
P2	配置版本	支持配置历史版本回滚
P2	批量操作	支持批量启用/禁用适配器
P3	数据可视化	添加数据源调用统计图表
P3	告警管理	集成钉钉/邮件告警配置

7.2 安全加固

优先级	功能	说明
P1	访问控制	基于IP白名单的访问限制
P1	HTTPS支持	管理后台强制HTTPS访问
P2	密码加密	配置文件中的敏感信息加密存储
P2	审计日志	详细的操作审计日志

7.3 性能优化

优先级	功能	说明
P2	配置缓存	热点配置缓存，减少磁盘IO
P3	前端优化	静态资源CDN、代码分割
P3	WebSocket推送	系统状态通过WebSocket实时推送

7.4 已知问题

重启服务: 当前仅返回成功响应，实际重启需外部脚本配合
并发安全: 配置热加载时可能存在短暂的数据竞争
测试隔离: API测试直接调用生产接口，需增加测试模式

7.5 扩展建议

插件系统: 支持第三方适配器动态加载
多租户: 支持多用户、多权限级别的管理
移动端: 开发响应式移动端管理界面
国际化: 支持中英文切换

附录

A. 配置文件示例

{
  "server": {
    "port": 8080,
    "mode": "debug",
    "api_key": "your-api-key"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "password",
    "database": "marketdata"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 0
  },
  "sources": {
    "stock": {
      "active": "tushare"
    },
    "futures": {
      "active": "tushare"
    }
  }
}

B. 相关文件清单

文件	说明	行数
`api/admin_types.go`	类型定义	~270
`api/admin_router.go`	路由 + HTML	~680
`internal/handler/admin.go`	Handler实现	~180
`internal/service/config.go`	配置服务	~330
`internal/service/adapter.go`	适配器服务	~220
`internal/service/test.go`	测试服务	~350
`pkg/config/config.go`	配置结构	~60

文档结束

18 KiB Raw Blame History Unescape Escape

管理后台开发文档

目录

一、功能概述

1.1 功能模块

1.2 技术特性

二、架构设计

2.1 整体架构

2.2 目录结构

三、核心模块

3.1 配置管理服务 (ConfigService)

功能

核心接口

配置类型

使用示例

3.2 适配器管理服务 (AdapterService)

功能

适配器状态

核心接口

内置适配器

3.3 测试服务 (TestService)

功能

测试分类

核心接口

四、API接口文档

4.1 系统管理接口

获取系统状态

热加载配置

重启服务

4.2 配置管理接口

获取配置列表

更新配置

4.3 适配器管理接口

获取适配器列表

启用/禁用适配器

更新适配器配置

4.4 接口测试管理

获取API测试列表

执行API测试

获取WebSocket测试列表

执行WebSocket测试

获取测试历史

五、前端实现

5.1 技术方案

5.2 页面结构

5.3 前端API封装

六、使用指南

6.1 启动服务

6.2 访问管理后台

6.3 配置热加载示例

6.4 适配器管理流程

七、待完善事项

7.1 功能增强

7.2 安全加固

7.3 性能优化

7.4 已知问题

7.5 扩展建议

附录

A. 配置文件示例

B. 相关文件清单

18 KiB

Raw Blame History Unescape Escape