HKbitEX 开发文档

🌙 主题

Exchange Funding Backend 开发文档 ​

1. 项目概述 ​

exchange-funding-backend 是一个用Go语言开发的资产管理后端服务，主要负责交易所的用户资产管理、资金流水记录、余额锁定/解锁等核心功能。 本项目部署了两个实例，一个用于管理交易所的资金（funding），另一个用于管理OTC业务的资金（otc-funding）。

1.1 技术栈 ​

  • 编程语言: Go 1.21.1
  • 数据库: 支持MySQL、PostgreSQL、SQLite (使用GORM)
  • 通信协议: gRPC
  • 容器化: Docker

1.2 主要功能 ​

  • 用户资产余额管理
  • 资产转入/转出操作
  • 资产锁定/解锁机制
  • 资金流水记录
  • 定时快照备份
  • gRPC API服务

2. 项目结构 ​

exchange-funding-backend#L1-15
exchange-funding-backend/
├── app/                    # 应用程序主入口和初始化
├── clients/               # 外部客户端连接
├── config/                # 配置管理
├── consts/                # 常量定义
├── cutoff/                # 日切快照功能
├── docs/                  # 文档目录
├── grpc/                  # gRPC服务实现
├── jobworkers/            # 后台任务处理
├── logger/                # 日志组件
├── model/                 # 数据模型定义
├── modules/               # 功能模块
├── service/               # 业务逻辑层
├── types/                 # 类型定义
├── utils/                 # 工具函数
└── main.go               # 程序入口

3. 核心模块 ​

3.1 数据模型 (model/dbmodel) ​

项目定义了以下核心数据模型：

UserFunding - 用户资产表 ​

exchange-funding-backend/model/dbmodel/user_funding.go#L10-25
// 用户资产表
type UserFunding struct {
	UserId    string `gorm:"size:50;uniqueIndex:uniq_u_a;"`
	AssetName string `gorm:"size:50;uniqueIndex:uniq_u_a;"`

	Balance       decimal.Decimal `gorm:"type:decimal(65,18);"` // 总资产
	LockedBalance decimal.Decimal `gorm:"type:decimal(65,18);"` // 锁定资产
	LastTradeDate time.Time       `gorm:"index"`                // 最后交易日期

	CutOffBalance       decimal.Decimal `gorm:"type:decimal(65,18);"` // 日切总余额
	CutOffLockedBalance decimal.Decimal `gorm:"type:decimal(65,18);"` // 日切锁定余额
	CutOffDate          sql.NullTime    `gorm:"index"`                //  日切日期

	UserKind string `gorm:"size:50;"` // 用户类型

	gorm.Model
}

UserFundingFlow - 用户资产流水表 ​

exchange-funding-backend/model/dbmodel/user_funding.go#L28-52
// 用户资产流水表
type UserFundingFlow struct {
	Type string `gorm:"size:50;uniqueIndex:uniq_t_r;"` // TRANSFER_IN TRANSFER_OUT DEPOSIT WITHDRAW
	AssetName string          `gorm:"size:50;"`
	Amount    decimal.Decimal `gorm:"type:decimal(65,18);"`
	RequestId string          `gorm:"size:50;uniqueIndex:uniq_t_r;"`

	From         string `gorm:"size:50;"` // 内部转账(TRANSFER_IN)时的转出方
	FromKind     string `gorm:"size:50;"` // 内部转账(TRANSFER_IN)时的转出方类型
	FromCategory string `gorm:"size:50;"` // 内部转账(TRANSFER_IN)时的转出方所属系统

	To         string `gorm:"size:50;"` // 内部转账(TRANSFER_OUT)时的转入方
	ToKind     string `gorm:"size:50;"` // 内部转账(TRANSFER_OUT)时的转入方类型
	ToCategory string `gorm:"size:50;"` // 内部转账(TRANSFER_OUT)时的转入方所属系统

	BusinessType string `gorm:"size:50;"` // 业务类型
	OrderId      string `gorm:"size:50;"` // 订单ID

	gorm.Model
}

UserFundingLock - 锁定资产表 ​

exchange-funding-backend/model/dbmodel/user_funding.go#L67-81
// 锁定资产表
type UserFundingLock struct {
	UserId    string          `gorm:"size:50;"`
	UserKind  string          `gorm:"size:50;"` // 用户类型
	AssetName string          `gorm:"size:50;"`
	Balance   decimal.Decimal `gorm:"type:decimal(65,18);"`
	Reason    string          `gorm:"size:50;"`                      // WITHDRAW WITHDRAW_FEE
	Action    string          `gorm:"size:50;uniqueIndex:uniq_a_r;"` // LOCK UNLOCK
	RequestId string          `gorm:"size:50;uniqueIndex:uniq_a_r;"` // 外部ID: ledger-manager: requestId

	BusinessType string `gorm:"size:50;"` // 业务类型
	OrderId      string `gorm:"size:50;"` // 订单ID

	gorm.Model
}

3.2 业务服务层 (service) ​

主要的业务逻辑包含在 service/user_funding.go 中，提供以下核心功能：

  • GetUserFundings: 获取用户资产信息
  • Move: 资产转移操作
  • In: 资产转入操作
  • Out: 资产转出操作
  • Lock: 资产锁定操作
  • Unlock: 资产解锁操作
  • ExecuteTransaction: 执行单个交易
  • ExecuteTransactions: 批量执行交易

3.3 gRPC服务 (grpc) ​

项目提供gRPC API服务，主要接口包括：

  • GetUserAssets: 获取用户资产信息
  • ExecuteTransactions: 执行资产交易

4. 配置文件 ​

4.1 主配置文件 (config.toml) ​

exchange-funding-backend/config.toml#L1-29
[log]
level = "debug"
# json console
format = "console"

[db]
enable = true
log = true
driver = "mysql"
dsn = ""

[snapshot]
# 快照cron表达式
cronStmt = "0 0,8,16 * * *"

[grpc]
enable = true
host = "0.0.0.0"
port = 9088

配置说明 ​

  • log: 日志配置，支持debug/info/warn/error级别
  • db: 数据库配置，支持MySQL/PostgreSQL/SQLite
  • snapshot: 快照任务配置，默认每天0点、8点、16点执行
  • grpc: gRPC服务器配置

5. 部署和运行 ​

5.1 本地开发环境 ​

  1. 环境要求

    • Go 1.21.1+
    • MySQL/PostgreSQL数据库

  2. 运行步骤

    bash
    # 安装依赖
go mod tidy

# 配置数据库连接
# 编辑 config.toml 文件，设置正确的数据库DSN

# 运行应用
make run

5.2 Docker部署 ​

  1. 构建镜像

    bash
    docker build -t exchange-funding-backend .

  2. 运行容器

    bash
    docker-compose up -d

5.3 生产环境部署 ​

使用Makefile提供的部署命令：

bash
# 部署到funding服务
make funding

# 部署到otc-funding服务
make otc-funding

6. API使用说明 ​

6.1 获取用户资产 ​

接口: GetUserAssets

请求参数:

  • UserId: 用户ID
  • AssetNames: 资产名称列表（可选）

返回数据:

  • Assets: 资产列表
    • UserId: 用户ID
    • AssetName: 资产名称
    • Balance: 可用余额
    • Locked: 锁定金额

6.2 执行交易 ​

接口: ExecuteTransactions

请求参数:

  • Transactions: 交易列表

支持的交易类型：

  • TRANSFER_IN: 转入
  • TRANSFER_OUT: 转出
  • LOCK: 锁定
  • UNLOCK: 解锁

7. 开发指南 ​

7.1 代码结构规范 ​

  • model: 数据模型定义
  • service: 业务逻辑实现
  • grpc: API接口实现
  • types: 通用类型定义
  • utils: 工具函数

7.2 数据库操作 ​

项目使用GORM作为ORM框架，支持：

  • 自动迁移
  • 事务处理
  • 连接池管理
  • 多数据库支持

7.3 错误处理 ​

  • 使用结构化日志记录
  • 统一错误响应格式
  • 数据库事务回滚机制

7.4 测试 ​

运行测试：

bash
go test ./...

8. 监控和日志 ​

8.1 日志配置 ​

  • 支持控制台和JSON格式输出
  • 可配置日志级别
  • 结构化日志记录

8.2 健康检查 ​

  • gRPC服务健康检查
  • 数据库连接状态监控

9. 常见问题 ​

9.1 数据库连接问题 ​

确保配置文件中的DSN格式正确：

  • MySQL: user:password@tcp(host:port)/dbname?charset=utf8mb4&parseTime=True&loc=Local
  • PostgreSQL: host=localhost user=user password=password dbname=dbname port=5432 sslmode=disable

9.2 gRPC服务启动失败 ​

检查端口是否被占用，确保防火墙设置正确。

9.3 定时任务配置 ​

快照任务使用Cron表达式，格式为：秒 分 时 日 月 周

10. 联系和支持 ​

如有技术问题或需要支持，请联系开发团队或查阅项目文档。

这份文档涵盖了项目的主要功能、架构设计、部署方式和开发指南。建议根据实际项目需求和团队规范进行调整和补充。

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

Copyright © 2025 HKbitEX Development Team