Golang_demo/README.md

# Golang Demo Project

一个基于 Gin 框架的 Go Web 应用示例项目，集成了完整的 CI/CD 流水线。

## 🎯 项目特性

- ✅ **现代 Go 开发**: 使用 Go 1.21+和 Gin 框架
- ✅ **完整 CI/CD**: Jenkins Pipeline 自动化构建、测试和部署
- ✅ **代码质量保障**: SonarQube 集成，覆盖率报告，静态分析
- ✅ **容器化部署**: Docker 镜像构建和多环境部署
- ✅ **健康检查**: 内置应用健康监控端点
- ✅ **高度可复用**: 提供 Jenkins 模板，可快速应用到其他 Go 项目

## 🚀 快速开始

### 本地开发

```bash
# 克隆项目
git clone <repository-url>
cd Golang_demo

# 安装依赖
go mod tidy

# 运行项目
go run main.go

# 访问应用
# http://localhost:8080
```

### 运行测试

```bash
# 运行单元测试
go test ./...

# 生成覆盖率报告
go test -cover ./...

# 详细覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
```

## 🏗️ CI/CD 流水线

本项目包含完整的 Jenkins Pipeline 配置，支持：

### 流水线阶段

1. **🔄 初始化**: 代码检出、环境检查
2. **📦 依赖管理**: Go 模块下载和验证
3. **🔍 代码质量**: 静态检查、格式验证、代码规范
4. **🧪 测试**: 单元测试、性能测试、覆盖率报告
5. **📊 代码扫描**: SonarQube 质量扫描
6. **🔨 构建**: Go 应用编译、Docker 镜像构建
7. **🧪 镜像测试**: 容器启动和健康检查验证
8. **🚀 部署**: 多环境自动化部署
9. **🏥 健康检查**: 部署后应用状态验证

### 环境映射

```yaml
分支策略:
  main/master → 生产环境 (端口: 15021)
  staging/release → 预发布环境 (端口: 15022)
  feature/* → 开发环境 (端口: 15023)
```

### 性能优化成果

- **总构建时间**: 从 10 分钟优化到 3 分 16 秒 (67%提升)
- **SonarQube 扫描**: 从 7 分 25 秒优化到 11.3 秒 (94%提升)
- **Docker 镜像**: 优化到 34.8MB Alpine 基础镜像

## 🔧 配置说明

### Jenkins 要求

1. **必需插件**: Pipeline, Git, SSH Agent, SonarQube Scanner, HTML Publisher
2. **工具配置**: Go 语言工具 (名称: go), SonarQube Scanner (名称: sonarQube)
3. **凭据配置**: SSH Key, SonarQube Token

### 项目配置

在`Jenkinsfile`中修改以下配置：

```groovy
PROJECT_NAME = 'golang-demo'                    // 项目名称
DEPLOY_SERVER = '116.62.163.84'                 // 部署服务器
SSH_CREDENTIAL_ID = 'deploy-server-ssh-key'     // SSH凭据ID
SONAR_HOST_URL = 'http://116.62.163.84:15010'   // SonarQube地址
```

## 🐳 Docker 部署

### 本地构建

```bash
# 构建镜像
docker build -t golang-demo .

# 运行容器
docker run -d \
  --name golang-demo \
  -p 8080:8080 \
  --restart unless-stopped \
  golang-demo
```

### 健康检查

应用提供多个健康检查端点：

```bash
# 基本健康检查
curl http://localhost:8080/health

# 简单ping检查
curl http://localhost:8080/ping

# 根路径
curl http://localhost:8080/
```

## 📊 代码质量

### 覆盖率目标

- **最低覆盖率**: 50% (警告阈值)
- **推荐覆盖率**: 70%+ (良好实践)
- **当前覆盖率**: 44.4% (需要改进)

### 静态检查

项目集成了多种 Go 代码质量检查：

```bash
# 语法检查
go vet ./...

# 格式检查
go fmt ./...

# 导入顺序检查 (可选)
goimports -l .

# 代码复杂度检查 (可选)
gocyclo -over 15 .
```

## 🌐 部署环境

### 生产环境

- **访问地址**: http://116.62.163.84:15021
- **部署分支**: main/master
- **容器名称**: golang-demo-production

### 预发布环境

- **访问地址**: http://116.62.163.84:15022
- **部署分支**: staging/release
- **容器名称**: golang-demo-staging

### 开发环境

- **访问地址**: http://116.62.163.84:15023
- **部署分支**: feature/\*
- **容器名称**: golang-demo-development

## 📈 监控和报告

### SonarQube 代码质量

- **访问地址**: http://116.62.163.84:15010/dashboard?id=golang-demo
- **代码覆盖率**: 集成 Go 测试覆盖率数据
- **质量门禁**: 生产环境必须通过质量检查

### Jenkins 报告

- **测试报告**: JUnit 格式测试结果
- **覆盖率报告**: HTML 格式覆盖率详情
- **构建产物**: 二进制文件和 Docker 镜像

## 🔄 使用 Jenkins 模板

### 应用到新项目

1. **复制模板文件**:

   ```bash
   cp Jenkinsfile.go-template ./Jenkinsfile
   ```

2. **修改项目配置**:

   ```groovy
   PROJECT_NAME = 'your-project-name'
   DEPLOY_SERVER = 'your.server.ip'
   // ... 其他配置
   ```

3. **验证项目结构**:

   ```bash
   # 确保是Go模块项目
   go mod init your-project-name
   go mod tidy

   # 添加健康检查端点 (推荐)
   # /health, /ping 或 /
   ```

4. **推送并构建**:
   ```bash
   git add Jenkinsfile
   git commit -m "Add Jenkins CI/CD pipeline"
   git push origin main
   ```

### 模板特性

- ✅ **参数化构建**: 支持环境选择、跳过测试等选项
- ✅ **并行执行**: 多阶段并行执行，提高构建效率
- ✅ **错误处理**: 完善的错误处理和回滚机制
- ✅ **通知集成**: 支持 Slack、邮件、钉钉通知
- ✅ **安全扫描**: 依赖漏洞检查和代码安全分析

详细使用说明请参考：[Go 项目 Jenkins CI/CD 模板使用指南](docs/go-project-template-guide.md)

## 📚 技术栈

- **语言**: Go 1.21+
- **框架**: Gin Web Framework
- **容器**: Docker + Alpine Linux
- **CI/CD**: Jenkins Pipeline
- **代码质量**: SonarQube
- **部署**: SSH + Docker Compose

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交改动 (`git commit -m 'Add some amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 许可证

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

## 📞 联系方式

如果有任何问题或建议，请：

1. 创建 Issue
2. 发送 Pull Request
3. 联系项目维护者

---

**🏗️ 项目状态**: 生产就绪  
**🔄 最后更新**: 2024 年 12 月  
**📊 构建状态**: [![Build Status](http://116.62.163.84:15008/buildStatus/icon?job=golang-demo)](http://116.62.163.84:15008/job/golang-demo/)  
**📈 代码质量**: [![Quality Gate Status](http://116.62.163.84:15010/api/project_badges/measure?project=golang-demo&metric=alert_status)](http://116.62.163.84:15010/dashboard?id=golang-demo)