HKbitEX 开发文档

🌙 主题

Exchange Quoter2 Backend 开发文档

项目概述 ​

Exchange Quoter2 Backend 是一个基于 Go 语言开发的加密货币和法币价格报价服务后端系统。该系统提供实时价格数据获取、存储和查询功能，支持 gRPC 和 HTTP API 两种接口形式。

主要功能 ​

  • 价格数据获取: 从 CoinMarketCap 获取加密货币价格，从汇率 API 获取法币汇率
  • 数据存储: 将价格数据持久化存储到数据库中
  • 价格查询: 提供实时和历史价格查询服务
  • 定时更新: 自动定时更新价格数据

技术栈 ​

核心技术 ​

  • 语言: Go 1.22.2
  • RPC框架: gRPC
  • 数据库ORM: GORM
  • 日志: Zerolog
  • 配置管理: Viper
  • 任务调度: gocron

数据库支持 ​

  • MySQL

外部服务 ​

  • CoinMarketCap API (加密货币价格)
  • Exchange Rate API (法币汇率)

项目结构 ​

/dev/null/project-structure.txt#L1-20
exchange-quoter2-backend/
├── consts/          # 常量定义
├── core/            # 核心应用逻辑
│   └── modules/     # 各功能模块
├── g/               # 全局变量
├── grpc/            # gRPC服务实现
├── types/           # 类型定义
│   ├── dbmodels/    # 数据库模型
│   ├── http_server/ # HTTP服务相关
│   ├── quoter/      # 价格服务相关
│   └── validator/   # 数据验证
├── utils/           # 工具函数
├── config.toml      # 配置文件
├── private.toml     # 私有配置文件
├── main.go          # 程序入口
├── Dockerfile       # Docker构建文件
└── Makefile         # 构建脚本

核心模块架构 ​

1. 应用核心 (Core) ​

应用采用模块化架构，主要模块包括：

exchange-quoter2-backend/core/app.go#L8-24
type Application struct {
	modules     map[string]types.Module
	moduleNames []string
	cfg         *types.Configuration
}

模块列表 ​

  • Cacher模块: 内存缓存管理
  • Database模块: 数据库连接和管理
  • gRPC模块: gRPC服务器
  • Cron模块: 定时任务调度
  • Quoter模块: 价格报价核心服务

2. 价格服务 (QuoterService) ​

exchange-quoter2-backend/types/quoter/quoter.go#L16-20
type QuoterService struct {
	// db             *gorm.DB
	CmcClient      *CoinMarketCap
	ExchangeClient *ExchangeRateClient
}

主要功能 ​

  • AddTokenPrices(): 添加加密货币价格数据
  • AddFiatPrices(): 添加法币汇率数据
  • GetLatestRate(): 获取最新汇率
  • GetPriceHistory(): 获取价格历史记录

3. 数据模型 ​

exchange-quoter2-backend/types/dbmodels/quoter.go#L25-31
// QuoterPriceRecord 价格记录模型
type QuoterPriceRecord struct {
	BaseType string          `gorm:"type:varchar(10);not null;index;"`
	Base     string          `gorm:"type:varchar(20);not null;index:idx_base_quote"`
	Quote    string          `gorm:"type:varchar(20);not null;index:idx_base_quote"`
	Price    decimal.Decimal `gorm:"type:decimal(24,8);not null"`

	gorm.Model
}

数据库表结构 ​

  • quoter_symbol_mappings: 符号到ID的映射关系
  • quoter_fiat_currencies: 支持的法币列表
  • quoter_price_records: 价格记录表

配置说明 ​

配置文件结构 ​

exchange-quoter2-backend/config.toml#L1-15
[common]
# production为true时设置zerolog的output为os.Stderr,否则为ConsoleWriter
is_production = true

[log]
level = "info"

[cacher]
default_expiration = "1h"
cleanup_interval = "10m"

[db_main]
enable = true
log_level = "info"
driver = "mysql"
dsn = ""

[grpc]
enable = true
host = "0.0.0.0"
port = 9000
with_health = true

[cron]
enable = true

[cmc_config]
# 如果是多个key，使用逗号分隔
api_keys = ""

[exchange_rate_config]
# 如果是多个key，使用逗号分隔
api_keys = ""

[quoter_config]
token_interval = "30m"
fiat_interval = "10h"
load_config_interval = "10m"
token_lifetime = "0h"

主要配置项 ​

数据库配置 ​

  • driver: 数据库驱动 (mysql/postgres/sqlite)
  • dsn: 数据库连接字符串
  • read_write_separate: 是否启用读写分离

服务配置 ​

  • grpc.port: gRPC服务端口 (默认: 9000)
  • http_server.port: HTTP服务端口 (默认: 8080)

API配置 ​

  • cmc_config.api_keys: CoinMarketCap API密钥
  • exchange_rate_config.api_keys: 汇率API密钥

定时任务配置 ​

  • token_interval: 代币价格更新间隔 (默认: 30分钟)
  • fiat_interval: 法币汇率更新间隔 (默认: 10小时)

部署和运行 ​

开发环境 ​

/dev/null/commands.sh#L1-10
# 运行开发环境
make run

# 构建Linux版本
make build-linux

# 构建Mac版本
make build-mac

Docker部署 ​

exchange-quoter2-backend/Dockerfile#L1-10
# Builder
FROM golang:1.22-bullseye AS builder

RUN useradd -m builder

WORKDIR /src
RUN go env -w GOPRIVATE=gitlab.atom8.io/hkbitex/*

ARG ACCESS_TOKEN_USR="nothing"
ARG ACCESS_TOKEN_PWD="nothing"

数据库初始化 ​

在使用前需要初始化数据库表和基础数据：

exchange-quoter2-backend/README.md#L2-15
INSERT INTO quoter_symbol_mappings (symbol, symbol_id, created_at, updated_at, deleted_at) VALUES
('BTC', 1, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('ETH', 1027, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('USDT', 825, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('USDC', 3408, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('XRP', 52, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('BNB', 1839, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('SOL', 5426, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('DOGE', 74, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('ADA', 2010, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('TRX', 1958, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('LINK', 1975, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('XLM', 512, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null),
('AVAX', 5805, '2025-02-15 16:59:02.000', '2025-02-15 16:59:04.000', null);

API接口 ​

gRPC接口 ​

该服务提供 gRPC 接口，使用 Protocol Buffers 定义服务契约。主要包括：

  • 价格查询接口
  • 汇率查询接口
  • 健康检查接口

开发指南 ​

环境要求 ​

  • Go 1.22.2 或更高版本
  • 数据库 (MySQL/PostgreSQL/SQLite)
  • Docker (可选)

依赖管理 ​

# 更新依赖
make tidy

# 清理并更新exchange-protos
make clean-protos

添加新模块 ​

  1. 在 types/ 目录下定义模块接口
  2. 在 core/modules/ 目录下实现模块
  3. 在 core/app_init.go 中注册模块

日志和调试 ​

项目使用 Zerolog 进行日志记录，支持结构化日志：

  • 开发环境: 控制台输出，带颜色格式化
  • 生产环境: JSON格式输出到stderr

监控和维护 ​

健康检查 ​

  • gRPC健康检查: 内置健康检查服务

日志监控 ​

  • 日志级别可配置 (debug/info/warn/error)
  • 支持结构化日志输出
  • 生产环境建议使用 info 级别

🚀 构建现代化数字资产交易平台

Copyright © 2025 HKbitEX Development Team