240 lines
4.9 KiB
Markdown
240 lines
4.9 KiB
Markdown
# 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)页面报告。 |