# 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`