quantKonwledge/20_Go迭代系统/Air热重载配置与迭代工作流程.md

Air 热重载配置与迭代工作流程

返回：Go 迭代系统主文档 | Wiki 主索引

已验证：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

# 下载 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

# 方式一：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 完整配置说明

# 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