# 🔥 Air 热加载开发指南

本指南详细介绍如何在 TaskTrack 项目中使用 Air 工具进行 Go 后端热加载开发，大幅提升开发效率。

## 📋 目录

1. [快速开始](#快速开始)
2. [配置详解](#配置详解)
3. [使用方法](#使用方法)
4. [常见问题](#常见问题)
5. [VS Code 集成](#vs-code-集成)
6. [性能优化](#性能优化)

## 🚀 快速开始

### 方法一：使用一键脚本（推荐）

1. **启动热加载开发环境**
   ```bash
   # Windows
   .\dev.bat
   
   # Linux/macOS
   ./dev.sh
   ```

2. **仅启动后端热加载**
   ```bash
   # Windows
   .\hot-reload.bat
   
   # Linux/macOS  
   cd backend && air
   ```

3. **使用 start.bat 选择模式**
   ```bash
   .\start.bat
   # 选择 "3) 开发模式（热加载）"
   ```

### 方法二：手动操作

1. **进入后端目录**
   ```bash
   cd backend
   ```

2. **启动 Air**
   ```bash
   air
   ```

## ⚙️ 配置详解

### .air.toml 配置文件

项目已在 `backend/.air.toml` 中进行了优化配置：

```toml
# Air 热加载配置 - 仅监控后端 Go 代码
root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  args_bin = []
  bin = "./tmp/task-track-backend.exe"
  cmd = "go build -o ./tmp/task-track-backend.exe ."
  delay = 1000
  # 排除不需要监控的目录 - 确保不监控前端和其他非后端目录
  exclude_dir = ["tmp", "vendor", "testdata", "uploads", "database", ".git", "node_modules", "../frontend", "../todo", "../database"]
  exclude_file = []
  exclude_regex = ["_test.go", ".*\\.md$", ".*\\.bat$", ".*\\.sh$", ".*\\.http$"]
  exclude_unchanged = false
  follow_symlink = false
  full_bin = ""
  # 明确指定只监控后端相关目录
  include_dir = [".", "internal", "model", "pkg"]
  # 只监控 Go 代码和配置文件
  include_ext = ["go", "yaml", "yml"]
  include_file = []
  kill_delay = "2s"
  log = "tmp/build-errors.log"
  poll = false
  poll_interval = 0
  post_cmd = []
  pre_cmd = []
  rerun = false
  rerun_delay = 500
  send_interrupt = false
  stop_on_error = true
```

### 关键配置说明

- **`include_dir`**: 明确指定只监控 backend 下的相关目录
- **`exclude_dir`**: 排除前端、数据库、临时文件等目录
- **`exclude_regex`**: 排除测试文件、文档、脚本等
- **`include_ext`**: 只监控 Go 代码和配置文件
- **`delay`**: 1000ms 防抖，避免频繁重构建

## 🎯 使用方法

### 基本使用

1. **启动热加载**
   ```bash
   cd backend
   air
   ```

2. **查看监控状态**
   - Air 启动时会显示正在监控的目录
   - 文件变更时会自动显示构建和重启信息

3. **停止热加载**
   - 按 `Ctrl+C` 停止 Air 进程

### 开发流程

1. **启动服务**
   ```bash
   # 进入项目根目录
   cd e:\apps\python\task_track
   
   # 启动热加载开发
   .\dev.bat
   ```

2. **开始编码**
   - 修改 `backend/` 下的任意 Go 文件
   - 保存文件后 Air 会自动检测变更
   - 自动重新编译并重启后端服务

3. **实时查看**
   - 终端会显示编译状态和服务日志
   - 前端可立即访问更新后的 API

### 监控范围

Air 配置为**仅监控**以下目录：
- `backend/` (根目录)
- `backend/internal/` (业务逻辑)
- `backend/model/` (数据模型)
- `backend/pkg/` (工具包)

**不会监控**：
- `frontend/` (前端代码)
- `todo/` (任务文件)
- `database/` (数据库文件)
- `tmp/` (临时文件)
- 测试文件 (`*_test.go`)
- 文档文件 (`.md`)
- 脚本文件 (`.bat`, `.sh`)

## 🔧 常见问题

### Q1: Air 无法启动
```bash
# 检查 Air 是否安装
air --version

# 重新安装 Air
go install github.com/air-verse/air@latest
```

### Q2: 端口冲突
```bash
# 检查端口占用
netstat -ano | findstr :8080

# 杀死占用进程
taskkill /PID [进程ID] /F

# 或使用项目脚本自动清理
.\dev.bat  # 脚本会自动处理端口冲突
```

### Q3: 前端文件被误监控
配置已优化，确保只监控 backend 目录。如仍有问题：
```bash
# 检查 .air.toml 配置
cat backend/.air.toml

# 重新生成配置
cd backend
air init
# 然后用项目提供的配置替换
```

### Q4: 编译错误
```bash
# 查看详细错误
cd backend
go build -o ./tmp/task-track-backend.exe .

# 检查 Go 模块
go mod tidy
```

### Q5: 热加载不生效
```bash
# 检查文件扩展名
# Air 只监控 .go, .yaml, .yml 文件

# 手动触发重载
# 保存任意 .go 文件即可

# 检查延迟设置
# 当前设为 1000ms，修改后需等待 1 秒
```
- **快速重启**: 2秒内完成服务器重启
- **错误停止**: 编译错误时停止执行
- **日志记录**: 构建错误日志保存到 `tmp/build-errors.log`

## 开发体验优化

### 自动功能
1. **依赖安装**: 自动检查并安装 Air 工具
2. **进程清理**: 启动前自动清理已有后端进程
3. **端口检测**: 自动检测并清理端口占用
4. **前端集成**: 可选同时启动前端开发服务器

### 开发优势
- ⚡ **快速重启**: 代码保存后 1-2 秒内重启完成
- 🔍 **实时反馈**: 编译错误即时显示
- 🛠️ **无配置**: 开箱即用，无需额外配置
- 🔄 **智能监听**: 只监听相关文件，避免不必要的重启

## Air 命令参考

### 基本命令
```bash
# 启动热加载
air

# 使用指定配置文件
air -c .air.toml

# 显示版本
air --version

# 生成配置文件
air init
```

### 配置文件位置
- 默认配置: `backend/.air.toml`
- 构建日志: `backend/tmp/build-errors.log`
- 临时文件: `backend/tmp/`

## 故障排除

### Air 未安装
```bash
go install github.com/air-verse/air@latest
```

### 端口被占用
```bash
# Windows
netstat -ano | findstr :8080
taskkill /f /pid [PID]

# Linux/macOS
lsof -i :8080
kill -9 [PID]
```

### 配置文件丢失
```bash
cd backend
air init
```

### 热加载不工作
1. 检查文件是否在监听目录中
2. 检查文件扩展名是否被包含
3. 查看 `tmp/build-errors.log` 错误日志
4. 确认没有语法错误

## 性能优化建议

1. **排除不必要的目录**: 在 `.air.toml` 中排除 `uploads`、`logs` 等目录
2. **精确文件类型**: 只监听需要的文件扩展名
3. **适当延迟**: 设置合理的 `delay` 避免频繁重启
4. **清理临时文件**: 定期清理 `tmp/` 目录

## 与其他工具集成

### VS Code 集成
可以在 VS Code 中使用终端运行 `air`，或者配置 tasks.json:

```json
{
    "label": "启动热加载开发服务器",
    "type": "shell",
    "command": "air",
    "group": "build",
    "options": {
        "cwd": "${workspaceFolder}/backend"
    },
    "isBackground": true
}
```

### Git 忽略
确保 `.gitignore` 包含以下内容：
```
backend/tmp/
backend/*.log
```

## 最佳实践

1. **代码质量**: 保持代码编译通过，避免频繁的编译错误
2. **文件组织**: 将配置文件放在合理位置，便于版本控制
3. **环境隔离**: 使用不同配置文件区分开发和生产环境
4. **资源清理**: 开发结束后及时停止热加载进程

## 相关链接

- [Air GitHub 仓库](https://github.com/air-verse/air)
- [Go 热加载最佳实践](https://github.com/air-verse/air#readme)
- [项目故障排除指南](TROUBLESHOOTING.md)