# go-eagle

**Repository Path**: wangxuancheng/go-eagle

## Basic Information

- **Project Name**: go-eagle
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-20
- **Last Updated**: 2025-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Eagle Project Template

基于 [go-eagle/eagle](https://github.com/go-eagle/eagle) 框架的项目模板

## 📋 目录

- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [Eagle CLI 工具](#eagle-cli-工具)
- [开发环境配置 (Windows)](#开发环境配置-windows)
- [生产环境部署 (Linux)](#生产环境部署-linux)
- [项目结构](#项目结构)
- [常用命令](#常用命令)
- [配置说明](#配置说明)

## 🛠 环境要求

### Windows 开发环境

1. **Go 环境**
   - Go 1.19+ (推荐 1.21+)
   - 设置 GOPATH 和 GOROOT
   - 配置 Go 代理: `go env -w GOPROXY=https://goproxy.cn,direct`

2. **数据库**
   - MySQL 5.7+ 或 8.0+ (推荐使用 Docker)
   - Redis 6.0+ (推荐使用 Docker)

3. **开发工具**
   - Git
   - IDE (推荐 GoLand 或 VS Code)
   - Make (可选，Windows 可使用 [chocolatey](https://chocolatey.org/) 安装)

4. **Docker (推荐)**
   - Docker Desktop for Windows
   - Docker Compose

### Linux 生产环境

1. **系统要求**
   - Ubuntu 20.04+ / CentOS 8+ / RHEL 8+
   - 内存: 4GB+ (推荐 8GB+)
   - 磁盘: 20GB+ 可用空间

2. **必需软件**
   - Docker 20.10+
   - Docker Compose 2.0+
   - Git

## 🚀 快速开始

### Windows 开发环境

#### 1. 一键环境配置
```bash
# 以管理员身份运行
scripts\setup-windows.bat
```

#### 2. 一键启动开发环境
```bash
# 启动开发服务器
scripts\start-dev.bat
```

### Linux 生产环境

#### 1. 构建应用
```bash
# 在 Windows 开发环境构建
scripts\deploy-prod.ps1 -BuildOnly
```

#### 2. 部署到 Linux 服务器
```bash
# 上传文件到 Linux 服务器
scp -r bin/ config/ deploy/ scripts/ user@server:/path/to/project/

# 在 Linux 服务器上运行部署脚本
chmod +x scripts/deploy-linux.sh
./scripts/deploy-linux.sh
```

## 🛠 Eagle CLI 工具

Eagle 框架提供了强大的命令行工具，用于快速生成项目代码。

### 安装 Eagle CLI

```bash
# 安装 Eagle CLI 工具
go install github.com/go-eagle/eagle/cmd/eagle@latest

# 验证安装
eagle -v
```

### 命令详解

#### 1. `eagle new` - 创建新项目
```bash
# 创建新项目
eagle new my-project

# 指定项目路径
eagle new my-project --path /path/to/project

# 使用特定模板
eagle new my-project --template web
```

**选项说明:**
- `--path`: 指定项目创建路径
- `--template`: 选择项目模板 (web, api, grpc)
- `--force`: 强制覆盖已存在的目录

#### 2. `eagle run` - 运行项目
```bash
# 运行当前项目
eagle run

# 指定配置文件
eagle run -c config/config.local.yaml

# 指定端口
eagle run --port 8080
```

**选项说明:**
- `-c, --config`: 指定配置文件路径
- `--port`: 指定服务端口
- `--env`: 指定运行环境 (dev, test, prod)

#### 3. `eagle model` - 生成模型文件
```bash
# 生成用户模型
eagle model user

# 生成带字段的模型
eagle model user --fields "id:int,name:string,email:string,created_at:time.Time"

# 生成带标签的模型
eagle model user --tags "json,db"
```

**选项说明:**
- `--fields`: 指定模型字段 (格式: field:type)
- `--tags`: 指定结构体标签
- `--table`: 指定数据库表名

**字段类型支持:**
- 基础类型: `int`, `int64`, `string`, `bool`, `float64`
- 时间类型: `time.Time`
- 自定义类型: `uuid.UUID`, `decimal.Decimal`

#### 4. `eagle repo` - 生成仓储层
```bash
# 生成用户仓储
eagle repo user

# 生成带接口的仓储
eagle repo user --interface

# 生成带缓存的仓储
eagle repo user --cache
```

**选项说明:**
- `--interface`: 生成接口定义
- `--cache`: 添加缓存支持
- `--mock`: 生成 Mock 文件

#### 5. `eagle svc` - 生成服务层
```bash
# 生成用户服务
eagle svc user

# 生成带接口的服务
eagle svc user --interface

# 生成带验证的服务
eagle svc user --validate
```

**选项说明:**
- `--interface`: 生成接口定义
- `--validate`: 添加参数验证
- `--mock`: 生成 Mock 文件

#### 6. `eagle handler` - 生成处理器
```bash
# 生成用户处理器
eagle handler user

# 生成 RESTful 处理器
eagle handler user --rest

# 生成带中间件的处理器
eagle handler user --middleware "auth,cors"
```

**选项说明:**
- `--rest`: 生成 RESTful API
- `--middleware`: 指定中间件
- `--group`: 指定路由组

#### 7. `eagle proto` - 生成 Proto 文件
```bash
# 生成用户 Proto
eagle proto user

# 生成带服务的 Proto
eagle proto user --service

# 生成带验证的 Proto
eagle proto user --validate
```

**选项说明:**
- `--service`: 生成 gRPC 服务定义
- `--validate`: 添加字段验证
- `--go_out`: 指定 Go 输出路径

#### 8. `eagle cache` - 生成缓存文件
```bash
# 生成缓存配置
eagle cache

# 生成 Redis 缓存
eagle cache --redis

# 生成内存缓存
eagle cache --memory
```

**选项说明:**
- `--redis`: 生成 Redis 缓存
- `--memory`: 生成内存缓存
- `--config`: 指定配置文件

#### 9. `eagle task` - 生成任务文件
```bash
# 生成定时任务
eagle task cron

# 生成队列任务
eagle task queue

# 生成带参数的任务
eagle task email --params "to,subject,body"
```

**选项说明:**
- `--params`: 指定任务参数
- `--schedule`: 指定执行计划
- `--retry`: 指定重试次数

#### 10. `eagle upgrade` - 升级工具
```bash
# 升级 Eagle CLI 工具
eagle upgrade

# 检查更新
eagle upgrade --check
```

### 使用示例

#### 创建完整的用户模块
```bash
# 1. 生成用户模型
eagle model user --fields "id:int64,name:string,email:string,password:string,created_at:time.Time,updated_at:time.Time" --tags "json,db"

# 2. 生成用户仓储
eagle repo user --interface --cache

# 3. 生成用户服务
eagle svc user --interface --validate

# 4. 生成用户处理器
eagle handler user --rest --middleware "auth"

# 5. 生成用户 Proto (如果需要 gRPC)
eagle proto user --service --validate
```

#### 创建商品模块
```bash
# 生成商品相关文件
eagle model product --fields "id:int64,name:string,price:decimal.Decimal,stock:int,status:int,created_at:time.Time"
eagle repo product --interface
eagle svc product --interface
eagle handler product --rest --group "api/v1"
```

### 配置文件

Eagle CLI 支持配置文件来简化命令：

**eagle.yaml**
```yaml
# Eagle CLI 配置文件
project:
  name: my-project
  module: github.com/username/my-project

templates:
  model:
    fields:
      - id:int64
      - created_at:time.Time
      - updated_at:time.Time
    tags:
      - json
      - db

  handler:
    middleware:
      - cors
      - logger
    group: api/v1

  repo:
    cache: true
    interface: true

  svc:
    interface: true
    validate: true
```

### 自定义模板

您可以创建自定义模板来满足特定需求：

```bash
# 创建自定义模板目录
mkdir -p ~/.eagle/templates/custom

# 创建模板文件
# ~/.eagle/templates/custom/model.tmpl
```

### 最佳实践

1. **命名规范**
   - 模型名使用单数形式: `user`, `product`
   - 字段名使用小驼峰: `userName`, `createdAt`
   - 表名使用复数形式: `users`, `products`

2. **文件组织**
   - 按模块组织代码
   - 保持目录结构清晰
   - 使用统一的命名规范

3. **代码生成**
   - 先生成模型，再生成其他文件
   - 使用配置文件简化重复操作
   - 生成后检查并调整代码

4. **版本控制**
   - 将生成的代码纳入版本控制
   - 保留生成脚本和配置
   - 记录自定义修改

## 🏗 开发环境配置 (Windows)

### 使用 Docker Compose (推荐)

1. **启动依赖服务**
```bash
cd deploy/docker-compose
docker-compose up -d db redis
```

2. **等待服务启动完成**
```bash
# 检查 MySQL 状态
docker-compose ps db

# 检查 Redis 状态  
docker-compose ps redis
```

3. **运行应用**
```bash
# 回到项目根目录
cd ../..
go run cmd/server/main.go cmd/server/wire_gen.go -c config/config.local.yaml
```

### 手动安装依赖

#### MySQL 安装配置
1. 下载并安装 [MySQL Community Server](https://dev.mysql.com/downloads/mysql/)
2. 创建数据库和用户：
```sql
CREATE DATABASE eagle CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'eagle_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON eagle.* TO 'eagle_user'@'localhost';
FLUSH PRIVILEGES;
```

#### Redis 安装配置
1. 下载 [Redis for Windows](https://github.com/microsoftarchive/redis/releases)
2. 或使用 [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) 安装 Redis

### 开发工具配置

#### VS Code 配置
安装以下扩展：
- Go
- Go Test Explorer
- Docker
- YAML

#### GoLand 配置
1. 配置 Go SDK
2. 设置 GOPATH
3. 配置数据库连接
4. 配置 Docker 连接

## 🚀 生产环境部署 (Linux)

### 1. 在 Windows 开发环境构建

#### 构建应用
```bash
# 构建 Linux 版本
scripts\deploy-prod.ps1 -BuildOnly
```

#### 构建 Docker 镜像
```bash
# 构建镜像
docker build -t eagle-service:latest -f deploy/docker/Dockerfile .

# 保存镜像
docker save eagle-service:latest | gzip > eagle-service.tar.gz
```

### 2. 部署到 Linux 服务器

#### 方式一: 使用部署脚本 (推荐)
```bash
# 1. 上传项目文件
scp -r . user@server:/opt/eagle/

# 2. 在服务器上运行部署脚本
ssh user@server
cd /opt/eagle
chmod +x scripts/deploy-linux.sh
./scripts/deploy-linux.sh
```

#### 方式二: 手动部署
```bash
# 1. 上传文件
scp bin/eagle-service user@server:/opt/eagle/
scp config/config.prod.yaml user@server:/opt/eagle/config/
scp deploy/docker-compose/docker-compose.prod.yaml user@server:/opt/eagle/

# 2. 创建服务文件
sudo nano /etc/systemd/system/eagle.service
```

systemd 服务配置示例：
```ini
[Unit]
Description=Eagle Service
After=network.target

[Service]
Type=simple
User=eagle
WorkingDirectory=/opt/eagle
ExecStart=/opt/eagle/eagle-service -c /opt/eagle/config/config.prod.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# 3. 启动服务
sudo systemctl daemon-reload
sudo systemctl enable eagle
sudo systemctl start eagle
sudo systemctl status eagle
```

#### 方式三: Docker 部署
```bash
# 1. 上传 Docker 镜像
scp eagle-service.tar.gz user@server:/opt/eagle/

# 2. 在服务器上加载镜像
ssh user@server
cd /opt/eagle
docker load < eagle-service.tar.gz

# 3. 启动服务
docker-compose -f deploy/docker-compose/docker-compose.prod.yaml up -d
```

### 3. 生产环境配置

#### 环境变量配置
```bash
# 创建环境变量文件
cat > /opt/eagle/.env << EOF
MYSQL_ROOT_PASSWORD=your_secure_mysql_root_password
MYSQL_PASSWORD=your_secure_mysql_password
REDIS_PASSWORD=your_secure_redis_password
JWT_SECRET=your_jwt_secret_key
EOF
```

#### 防火墙配置
```bash
# Ubuntu/Debian
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8080/tcp

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
```

## 📁 项目结构

```
app/
├── api/                    # API 定义
├── cmd/                    # 应用程序入口
│   ├── server/            # HTTP 服务器
│   └── consumer/          # 消息消费者
├── config/                # 配置文件
├── internal/              # 内部包
│   ├── model/            # 数据模型
│   ├── repository/       # 数据访问层
│   ├── service/          # 业务逻辑层
│   ├── handler/          # HTTP 处理器
│   └── middleware/       # 中间件
├── deploy/                # 部署相关
│   ├── docker/           # Docker 配置
│   ├── docker-compose/   # Docker Compose 配置
│   └── k8s/              # Kubernetes 配置
├── scripts/               # 脚本文件
│   ├── setup-windows.bat # Windows 环境配置
│   ├── start-dev.bat     # Windows 开发启动
│   ├── deploy-prod.ps1   # Windows 生产构建
│   └── deploy-linux.sh   # Linux 生产部署
└── third_party/          # 第三方依赖
```

## 🔧 常用命令

### Windows 开发命令
```bash
# 运行应用
go run cmd/server/main.go cmd/server/wire_gen.go

# 运行消费者
go run cmd/consumer/main.go cmd/consumer/wire_gen.go

# 代码格式化
go fmt ./...

# 代码检查
golangci-lint run

# 运行测试
go test ./...

# 生成 Wire 代码
cd cmd/server && wire
cd cmd/consumer && wire
```

### Eagle CLI 命令
```bash
# 生成用户模块
eagle model user --fields "id:int64,name:string,email:string"
eagle repo user --interface
eagle svc user --interface
eagle handler user --rest

# 生成商品模块
eagle model product --fields "id:int64,name:string,price:decimal.Decimal"
eagle repo product --interface
eagle svc product --interface
eagle handler product --rest --group "api/v1"

# 运行项目
eagle run -c config/config.local.yaml
```

### 构建命令
```bash
# 构建应用 (Windows)
go build -o bin/eagle-service.exe cmd/server/main.go cmd/server/wire_gen.go

# 构建 Linux 版本 (Windows)
set GOOS=linux
set GOARCH=amd64
go build -o bin/eagle-service cmd/server/main.go cmd/server/wire_gen.go
```

### Docker 命令
```bash
# 启动开发环境
cd deploy/docker-compose
docker-compose up -d

# 查看日志
docker-compose logs -f app

# 停止服务
docker-compose down
```

### Linux 生产环境命令
```bash
# 查看服务状态
docker-compose -f /opt/eagle/docker-compose.prod.yaml ps

# 查看日志
docker-compose -f /opt/eagle/docker-compose.prod.yaml logs -f

# 重启服务
docker-compose -f /opt/eagle/docker-compose.prod.yaml restart

# 更新服务
docker-compose -f /opt/eagle/docker-compose.prod.yaml pull
docker-compose -f /opt/eagle/docker-compose.prod.yaml up -d
```

## ⚙️ 配置说明

### 环境配置
- `config/config.local.yaml` - Windows 本地开发环境
- `config/config.dev.yaml` - 开发环境
- `config/config.test.yaml` - 测试环境
- `config/config.prod.yaml` - Linux 生产环境

### 主要配置项
- **app**: 应用基本信息
- **Http**: HTTP 服务器配置
- **Grpc**: gRPC 服务器配置
- **mysql**: MySQL 数据库配置
- **redis**: Redis 缓存配置
- **logger**: 日志配置

### 环境变量
可以通过环境变量覆盖配置：
```bash
# Windows
set APP_ENV=prod
set MYSQL_DSN="user:pass@tcp(localhost:3306)/db"
set REDIS_ADDR="localhost:6379"

# Linux
export APP_ENV=prod
export MYSQL_DSN="user:pass@tcp(localhost:3306)/db"
export REDIS_ADDR="localhost:6379"
```

## 🔍 故障排除

### Windows 开发环境问题

1. **端口被占用**
```bash
# 查看端口占用
netstat -ano | findstr :8080
# 结束进程
taskkill /PID <进程ID> /F
```

2. **数据库连接失败**
- 检查 MySQL 服务是否启动
- 验证连接字符串和权限
- 检查防火墙设置

3. **Redis 连接失败**
- 检查 Redis 服务是否启动
- 验证地址和端口
- 检查密码配置

4. **Wire 生成失败**
```bash
# 重新安装 Wire
go install github.com/google/wire/cmd/wire@latest
# 清理并重新生成
cd cmd/server && wire
```

5. **Eagle CLI 命令失败**
```bash
# 重新安装 Eagle CLI
go install github.com/go-eagle/eagle/cmd/eagle@latest

# 检查版本
eagle -v

# 升级到最新版本
eagle upgrade
```

### Linux 生产环境问题

1. **Docker 服务未启动**
```bash
sudo systemctl start docker
sudo systemctl enable docker
```

2. **权限问题**
```bash
# 添加用户到 docker 组
sudo usermod -aG docker $USER
# 重新登录或重启
```

3. **磁盘空间不足**
```bash
# 清理 Docker 资源
docker system prune -a
docker volume prune
```

4. **服务无法访问**
```bash
# 检查防火墙
sudo ufw status
# 检查端口监听
netstat -tlnp | grep :8080
```

## 📞 技术支持

- 项目文档: [Eagle Framework](https://github.com/go-eagle/eagle)
- CLI 文档: [Eagle CLI](https://github.com/go-eagle/eagle/tree/main/cmd/eagle)
- 问题反馈: [Issues](https://github.com/go-eagle/eagle/issues)
- 社区讨论: [Discussions](https://github.com/go-eagle/eagle/discussions)