# Golang Demo - 现代化Web API项目

这是一个基于Gin框架的现代化Go web项目，专为Jenkins CI/CD部署流程设计。

## 🚀 特性

- **现代Go技术栈**: 使用Go 1.21+和最新的依赖包
- **Gin Web框架**: 高性能的HTTP web框架
- **结构化日志**: 使用Zap进行高性能日志记录
- **优雅关闭**: 支持优雅的服务器关闭
- **健康检查**: 内置健康检查端点，适合容器化部署
- **Docker支持**: 多阶段构建，优化镜像大小
- **CI/CD就绪**: 包含完整的Jenkins Pipeline配置

## 📋 API端点

### 基础端点
- `GET /` - 欢迎页面
- `GET /ping` - 简单的ping测试
- `GET /health` - 健康检查（适合负载均衡器）
- `GET /version` - 版本信息

### API端点 (v1)
- `GET /api/v1/status` - API状态信息
- `GET /api/v1/time` - 当前时间信息
- `POST /api/v1/echo` - 回显请求body

## 🛠️ 技术栈

- **语言**: Go 1.21+
- **Web框架**: Gin v1.9.1
- **日志**: Zap v1.26.0
- **配置**: godotenv v1.5.1
- **容器**: Docker & Docker Compose
- **CI/CD**: Jenkins Pipeline

## 🚀 快速开始

### 本地开发

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd golang_demo
   ```

2. **安装依赖**
   ```bash
   make deps
   ```

3. **运行测试**
   ```bash
   make test
   ```

4. **开发模式运行**
   ```bash
   make dev
   ```

5. **访问应用**
   ```
   http://localhost:8080
   ```

### 使用Docker

1. **构建并运行**
   ```bash
   make docker-run
   ```

2. **查看日志**
   ```bash
   make logs
   ```

3. **停止容器**
   ```bash
   make docker-stop
   ```

### 使用Docker Compose

```bash
docker-compose up -d
```

## 🔧 配置

项目使用环境变量进行配置，可以通过`.env`文件设置：

```env
PORT=8080
GIN_MODE=debug
```

### 环境变量说明

- `PORT`: 服务端口（默认：8080）
- `GIN_MODE`: Gin运行模式（debug/release/test）

## 📦 构建

### 本地构建

```bash
make build
```

### Docker构建

```bash
make docker-build
```

构建时会注入以下信息：
- 构建时间
- Git提交哈希
- 版本信息

## 🚀 部署

### Jenkins Pipeline

项目包含完整的`Jenkinsfile`，支持：

- **代码检出** - 自动获取Git提交信息和构建时间
- **环境检查** - 验证Go、Docker等构建环境
- **依赖管理** - 自动下载和验证Go模块依赖
- **代码检查** - 运行`go vet`和`go fmt`检查
- **单元测试** - 执行测试并生成覆盖率报告
- **代码质量扫描** - SonarQube代码质量分析（可选）
- **编译构建** - 交叉编译Linux二进制文件
- **Docker镜像构建** - 多阶段构建优化镜像
- **镜像测试** - 验证Docker镜像功能正常
- **自动部署** - 支持多环境部署（生产/测试）
- **健康检查** - 验证部署后应用状态
- **构建产物清理** - 自动清理临时文件和镜像

**分支策略：**
- `main`/`master`分支部署到生产环境（端口15020）
- `develop`/`feature/*`分支部署到测试环境（端口15021）

### 手动部署

1. **构建镜像**
   ```bash
   docker build -t golang-demo:latest .
   ```

2. **运行容器**
   ```bash
   docker run -d \
     --name golang-demo \
     -p 8080:8080 \
     -e GIN_MODE=release \
     golang-demo:latest
   ```

3. **健康检查**
   ```bash
   curl http://localhost:8080/health
   ```

## 🧪 测试

### 运行所有测试

```bash
make test
```

### 健康检查测试

```bash
make health
```

### API测试示例

```bash
# 基础测试
curl http://localhost:8080/ping

# 健康检查
curl http://localhost:8080/health

# API测试
curl http://localhost:8080/api/v1/time

# POST请求测试
curl -X POST http://localhost:8080/api/v1/echo \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello World"}'
```

## 📖 开发指南

### 项目结构

```
golang_demo/
├── main.go              # 主程序文件
├── go.mod               # Go模块文件
├── go.sum               # 依赖锁定文件
├── .env                 # 环境变量配置
├── Dockerfile           # Docker构建文件
├── docker-compose.yml   # Docker Compose配置
├── Jenkinsfile          # Jenkins Pipeline配置
├── Makefile             # 构建脚本
└── README.md            # 项目说明
```

### 添加新的API端点

1. 在`setupRouter()`函数中添加路由
2. 实现对应的处理函数
3. 更新API文档

### 自定义配置

修改`.env`文件或设置环境变量来自定义配置。

## 🤝 贡献

1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 📝 许可证

本项目采用MIT许可证 - 查看[LICENSE](LICENSE)文件了解详情。

## 🐛 问题报告

如果发现bug或有功能建议，请在[Issues](../../issues)页面报告。