2a8b8413af
- 新增 20_Go迭代系统/README.md：模块索引与实际试运行记录 - 新增 Go量化知识迭代系统完整架构.md：完整目录结构、核心模块详解、API设计、数据流架构图 - 新增 Air热重载配置与迭代工作流程.md：安装步骤、.air.toml配置、日常迭代流程 - 新增 数据源接入完整指南.md：12个数据源（Binance/OKX/Bybit/Deribit/Glassnode/CoinGlass/DeFiLlama/TheGraph/CMC/FRED等） - 新增 部署运维指南.md：本地开发、生产部署、Docker Compose、监控告警 已验证：Go 1.23.5 + Air v1.64.5 热重载 < 1秒，API接口全部正常
231 行
6.9 KiB
Markdown
231 行
6.9 KiB
Markdown
# Air 热重载配置与迭代工作流程
|
||
|
||
> 返回：[Go 迭代系统主文档](./Go量化知识迭代系统完整架构.md) | [Wiki 主索引](../wiki/README.md)
|
||
>
|
||
> **已验证**：2026-03-06 实际测试，Air v1.64.5 + Go 1.23.5，热重载响应时间 **< 1 秒**。
|
||
|
||
---
|
||
|
||
## 一、Air 简介
|
||
|
||
**Air** 是 Go 语言最流行的热重载工具（GitHub Stars 23.1k+），核心功能是监听文件变化，自动重新编译并重启服务，彻底解决 Go 开发中"改一行代码就要手动 `go build && ./server`"的痛点。
|
||
|
||
**与其他语言热重载对比**：
|
||
|
||
| 语言 | 热重载工具 | 重启速度 | 备注 |
|
||
|------|----------|---------|------|
|
||
| Go + Air | Air v1.64.5 | **< 1 秒** | 编译型，速度极快 |
|
||
| Node.js | nodemon | < 0.5 秒 | 解释型，无需编译 |
|
||
| Python | uvicorn --reload | < 0.5 秒 | 解释型，无需编译 |
|
||
| Java | Spring DevTools | 3-10 秒 | JVM 启动慢 |
|
||
|
||
---
|
||
|
||
## 二、安装步骤
|
||
|
||
### 2.1 安装 Go
|
||
|
||
```bash
|
||
# 下载 Go 1.23.5（Linux amd64）
|
||
wget https://go.dev/dl/go1.23.5.linux-amd64.tar.gz -O /tmp/go.tar.gz
|
||
|
||
# 解压到 /usr/local
|
||
sudo tar -C /usr/local -xzf /tmp/go.tar.gz
|
||
|
||
# 配置环境变量（写入 ~/.bashrc）
|
||
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
|
||
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
|
||
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
|
||
# 验证
|
||
go version
|
||
# 输出：go version go1.23.5 linux/amd64
|
||
```
|
||
|
||
### 2.2 安装 Air
|
||
|
||
```bash
|
||
# 方式一：go install（推荐）
|
||
go install github.com/air-verse/air@latest
|
||
|
||
# 方式二：curl 脚本
|
||
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
|
||
|
||
# 验证
|
||
air -v
|
||
# 输出：v1.64.5, built with Go go1.25.8
|
||
```
|
||
|
||
---
|
||
|
||
## 三、.air.toml 完整配置说明
|
||
|
||
```toml
|
||
# Air v1.64.5 热重载配置
|
||
# 量化知识迭代系统 - QuantSystem
|
||
|
||
root = "."
|
||
tmp_dir = "tmp"
|
||
|
||
[build]
|
||
# 编译命令（每次文件变化后执行）
|
||
cmd = "go build -o ./tmp/quant-system ./cmd/server/main.go"
|
||
|
||
# 编译输出的二进制文件路径
|
||
bin = "tmp/quant-system"
|
||
|
||
# 启动命令（支持注入环境变量）
|
||
full_bin = "PORT=9090 ./tmp/quant-system"
|
||
|
||
# 监听的文件扩展名（包含 .md 以便知识库更新时触发）
|
||
include_ext = ["go", "tpl", "tmpl", "html", "toml", "yaml", "yml", "json", "md"]
|
||
|
||
# 排除的目录（不监听变化，避免无限循环）
|
||
exclude_dir = ["tmp", "vendor", "testdata", "node_modules", ".git"]
|
||
|
||
# 排除测试文件（测试文件变化不触发重启）
|
||
exclude_regex = ["_test\\.go"]
|
||
|
||
# 文件变化后等待 1 秒再重编译（防止连续保存触发多次）
|
||
delay = 1000
|
||
|
||
# 构建失败时不停止旧进程（保持服务可用）
|
||
stop_on_error = false
|
||
|
||
# 构建错误日志路径
|
||
log = "tmp/build-errors.log"
|
||
|
||
[log]
|
||
# 显示时间戳
|
||
time = true
|
||
|
||
# 显示所有日志（包括 watcher 日志）
|
||
main_only = false
|
||
|
||
[color]
|
||
# 各类日志颜色（ANSI 颜色）
|
||
main = "magenta"
|
||
watcher = "cyan"
|
||
build = "yellow"
|
||
runner = "green"
|
||
|
||
[misc]
|
||
# 退出时清理 tmp 目录
|
||
clean_on_exit = true
|
||
```
|
||
|
||
### 关键配置项说明
|
||
|
||
| 配置项 | 说明 | 量化系统推荐值 |
|
||
|--------|------|--------------|
|
||
| `delay` | 文件变化后等待时间（ms）| 1000（防止连续保存）|
|
||
| `exclude_dir` | 排除目录 | 必须排除 `tmp`，否则死循环 |
|
||
| `include_ext` | 监听扩展名 | 加入 `md` 以便文档更新触发 |
|
||
| `stop_on_error` | 编译失败时保留旧进程 | `false`（保持服务可用）|
|
||
| `full_bin` | 启动命令 | 注入 `PORT` 等环境变量 |
|
||
|
||
---
|
||
|
||
## 四、日常迭代工作流程
|
||
|
||
### 4.1 标准开发流程
|
||
|
||
```
|
||
1. 启动 Air
|
||
$ cd quant-system && air
|
||
|
||
2. 修改 .go 文件（例如新增指标计算逻辑）
|
||
→ Air 自动检测到文件变化
|
||
→ 自动执行 go build
|
||
→ 编译成功后自动重启服务
|
||
→ 整个过程 < 1 秒
|
||
|
||
3. 验证功能
|
||
$ curl http://localhost:9090/api/v1/indicators/calculate \
|
||
-d '{"symbol":"BTCUSDT","timeframe":"10m","indicators":["EWO"]}'
|
||
|
||
4. 功能正常 → 提交
|
||
$ git add -A && git commit -m "feat: 新增 EWO 相对阈值计算" && git push
|
||
```
|
||
|
||
### 4.2 知识库 MD 文档迭代流程
|
||
|
||
```
|
||
触发方式（三种）：
|
||
A. 定时触发（cron，每 10 分钟）
|
||
B. API 触发：POST /api/v1/knowledge/update
|
||
C. 手动脚本：./scripts/update_knowledge.sh
|
||
|
||
执行流程：
|
||
1. updater/knowledge_updater.go 调度
|
||
2. 从数据源拉取最新数据
|
||
3. 格式化为 Markdown 表格
|
||
4. 定位 quantKonwledge 仓库对应文档
|
||
5. 更新文档中 <!-- AUTO_UPDATE_START --> 到 <!-- AUTO_UPDATE_END --> 之间的内容
|
||
6. git add + commit + push 到 quantKonwledge 仓库
|
||
7. 飞书通知：「知识库已更新」
|
||
|
||
MD 文档中的自动更新标记示例：
|
||
<!-- AUTO_UPDATE_START: btc_ewo_status -->
|
||
| 更新时间 | EWO 值 | 方向 | 信号评分 |
|
||
|---------|-------|------|---------|
|
||
| 2026-03-06 10:10 | +33.32 | 绿(多头) | +6 |
|
||
<!-- AUTO_UPDATE_END: btc_ewo_status -->
|
||
```
|
||
|
||
### 4.3 新增数据源迭代流程
|
||
|
||
```
|
||
1. 在 internal/datasource/ 新建目录（如 internal/datasource/coinbase/）
|
||
2. 实现 DataSource 接口（interface.go 中定义）
|
||
3. 在 datasource/manager.go 注册新数据源
|
||
4. Air 自动检测到文件变化，重编译重启
|
||
5. 验证：GET /api/v1/datasources 查看新数据源状态
|
||
6. 编写对应 MD 文档：20_Go迭代系统/数据源接入完整指南.md
|
||
7. 提交到两个仓库：quant-system + quantKonwledge
|
||
```
|
||
|
||
---
|
||
|
||
## 五、常见问题与解决方案
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|------|------|---------|
|
||
| Air 启动后无输出 | PATH 未配置 | `export PATH=$PATH:$HOME/go/bin` |
|
||
| 端口被占用 | 旧进程未退出 | `pkill -f quant-system` |
|
||
| 编译后立即退出 | 代码有 panic | 查看 `tmp/build-errors.log` |
|
||
| 文件变化未触发重载 | 扩展名不在 `include_ext` | 检查 `.air.toml` 配置 |
|
||
| 无限循环重编译 | `tmp/` 未排除 | 确认 `exclude_dir` 包含 `"tmp"` |
|
||
| 热重载后 API 返回旧数据 | Redis 缓存未清除 | 重启时自动清除，或手动 `redis-cli FLUSHDB` |
|
||
|
||
---
|
||
|
||
## 六、与 tradehk 的协同关系
|
||
|
||
本系统与 `tradehk` 仓库的协同方式：
|
||
|
||
```
|
||
tradehk（TypeScript 前端）
|
||
↓ 参考指标逻辑
|
||
quant-system（Go 后端）
|
||
↓ 计算结果写入
|
||
quantKonwledge（MD 知识库）
|
||
↓ 文档反哺
|
||
tradehk 开发优化
|
||
```
|
||
|
||
**具体协同点**：
|
||
- `tradehk/client/src/lib/indicators.ts` → `quant-system/internal/indicators/` 的 Go 实现参考
|
||
- `tradehk/server/_core/marketEngine.ts` → `quant-system/internal/signals/ewo_detector.go` 的逻辑参考
|
||
- `tradehk` 发出的飞书通知格式 → `quant-system/internal/notifier/formatter.go` 保持一致
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
- [1] Air 官方文档：https://github.com/air-verse/air
|
||
- [2] Go 官方下载：https://go.dev/dl/
|
||
- [3] Go 迭代系统完整架构：`./Go量化知识迭代系统完整架构.md`
|
||
- [4] tradehk 部署运维指南：`../wiki/tradehk/部署运维指南.md`
|