# gin-framework

**Repository Path**: zhenyangze/gin-framework

## Basic Information

- **Project Name**: gin-framework
- **Description**: 基于Go标准布局的现代化Gin Web框架，支持依赖注入、结构化日志、健康检查等企业级特性。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-10-12
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gin Framework v2.0

> 基于Go标准布局的现代化Gin Web框架，支持依赖注入、结构化日志、健康检查等企业级特性。

## 🚀 快速开始

### 安装依赖
```bash
go mod tidy
```

### 启动方式
```bash
# Web服务 (默认)
go run cmd/main.go -t web

# 定时任务服务
go run cmd/main.go -t cron

# RPC服务
go run cmd/main.go -t rpc

# 所有服务
go run cmd/main.go -t all

# 自定义端口和调试模式
go run cmd/main.go -t web -p :8080 -d
```

### 开发环境热重载
```bash
# 启动Air热重载 (推荐开发使用)
air

# 服务将运行在 http://localhost:8081
```

## 🏗️ 项目架构

### 目录结构 (Go标准布局)

```
gin-framework/
├── cmd/                    # 应用程序入口
│   └── main.go
├── internal/               # 内部实现 (不可导入)
│   ├── app/               # 应用层
│   │   ├── bases/         # 基础控制器
│   │   ├── handlers/      # HTTP处理器
│   │   ├── middleware/    # 中间件
│   │   ├── models/        # 数据模型
│   │   ├── providers/     # 向后兼容适配层
│   │   ├── security/      # 安全相关
│   │   └── services/      # 业务服务
│   ├── handlers/          # 内部处理器 (健康检查等)
│   └── pkg/              # 内部包
│       ├── bootstrap/     # 应用启动
│       ├── config/        # 配置管理
│       ├── container/     # 依赖注入容器
│       ├── errors/        # 错误处理
│       └── logger/        # 日志系统
├── pkg/                   # 公共库 (可被外部导入)
│   └── helpers/          # 工具函数
├── configs/               # 配置文件
├── resources/             # 资源文件
│   └── views/            # 模板文件
├── routes/               # 路由定义
├── scripts/              # 脚本文件
├── docs/                 # 文档
└── runtime/              # 运行时文件
    └── logs/             # 日志文件
```

### 架构特性

- ✅ **Go标准项目布局** - 遵循Go社区最佳实践
- ✅ **依赖注入容器** - 现代化服务管理
- ✅ **结构化日志** - 基于logrus的企业级日志
- ✅ **健康检查** - 完整的监控和诊断端点
- ✅ **优雅关闭** - 安全的服务停止机制
- ✅ **向后兼容** - 保持所有原有API功能
- ✅ **热重载开发** - Air支持的高效开发体验

## 📡 API 端点

### 基础服务端点

```bash
# 基础信息
GET  /                     # 框架信息
GET  /test                 # 接口测试
GET  /json                 # JSON性能测试

# 工具函数
GET  /md5/:str            # MD5加密
GET  /view                # 模板渲染
POST /valid               # 表单验证

# 服务检查
GET  /redis               # Redis连接测试
GET  /db                  # 数据库连接测试
```

### 健康检查端点

```bash
GET  /health              # 综合健康检查
GET  /health/ready        # 就绪状态检查
GET  /health/live         # 存活状态检查
GET  /metrics             # 系统指标
```

### WebSocket支持

```bash
# WebSocket连接 (ping-pong测试)
WS   /ws                  # WebSocket端点
```

### 服务状态端点

```bash
GET  /cron/status         # 定时任务状态
GET  /rpc/status          # RPC服务状态
```

## 🔧 配置管理

### 配置文件

项目使用TOML格式配置文件，位于 `configs/` 目录：

- `app.toml` - 主配置文件
- `db.go` - 数据库配置
- `redis.go` - Redis配置
- `log.go` - 日志配置
- `mail.go` - 邮件配置

### 环境变量

可通过环境变量覆盖配置：

```bash
export GIN_MODE=release
export DB_HOST=localhost
export REDIS_HOST=localhost
```

## 🔐 JWT 认证

### 登录获取Token

```bash
# 使用HTTPie
http --json POST localhost:8080/login username=admin password=admin

# 使用curl
curl -X POST http://localhost:8080/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
```

响应示例：
```json
{
  "code": 200,
  "expire": "2024-01-21T15:36:46+08:00",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 使用Token访问受保护端点

```bash
# 使用Bearer Token
http GET localhost:8080/auth/hello \
  "Authorization:Bearer YOUR_TOKEN_HERE"
```

## 📊 监控和诊断

### 健康检查

```bash
# 综合健康检查
curl http://localhost:8080/health

# 就绪检查 (用于K8s readiness probe)
curl http://localhost:8080/health/ready

# 存活检查 (用于K8s liveness probe)  
curl http://localhost:8080/health/live

# 系统指标
curl http://localhost:8080/metrics
```

### 日志系统

- **结构化日志** - JSON格式输出
- **日志轮转** - 按时间和大小自动轮转
- **上下文感知** - 请求ID和用户ID跟踪
- **多级别支持** - Debug/Info/Warn/Error/Fatal

## 🛠️ 开发工具

### Air 热重载

配置文件：`.air.toml`

```bash
# 启动开发服务器
air

# 自动监控文件变化并重新编译
# 支持Go、模板、配置文件变化检测
```

### 脚本工具

```bash
# JWT密钥生成
./scripts/generate-jwt-key.sh

# 其他工具脚本...
```

## 🔌 功能组件

### 核心功能
- ✅ **HTTP Web服务** - 基于Gin的高性能Web框架
- ✅ **依赖注入** - 现代化的服务容器管理
- ✅ **配置管理** - 支持多环境和热重载
- ✅ **结构化日志** - 企业级日志记录和分析

### 数据层
- ✅ **MySQL/GORM** - 数据库ORM支持
- ✅ **Redis缓存** - 高性能缓存系统
- ✅ **事件总线** - 解耦的事件通信机制

### 中间件系统
- ✅ **JWT认证** - 基于Token的身份验证
- ✅ **请求ID追踪** - 分布式请求跟踪
- ✅ **访问日志** - 详细的请求日志记录
- ✅ **限流控制** - API访问频率限制
- ✅ **页面缓存** - HTTP响应缓存
- ✅ **CORS支持** - 跨域资源共享
- ✅ **请求验证** - 输入数据验证

### 服务支持
- ✅ **定时任务(Cron)** - 后台任务调度
- ✅ **RPC服务** - 远程过程调用支持
- ✅ **WebSocket** - 实时双向通信
- ✅ **邮件服务** - SMTP邮件发送
- ✅ **健康检查** - 服务状态监控

### 工具函数库
- ✅ **加密解密** - MD5/AES/RSA/Base64等
- ✅ **字符串处理** - 随机字符串、格式化等
- ✅ **时间处理** - 时间转换和格式化
- ✅ **数组操作** - 数组处理工具函数
- ✅ **HTTP工具** - HTTP请求和响应处理
- ✅ **JSON处理** - JSON序列化和解析
- ✅ **文件操作** - 文件读写和处理
- ✅ **验证器** - 数据验证工具

## 📝 版本历史

- **v2.0.0** - 重大架构升级，Go标准布局，依赖注入，现代化特性
- **v1.1.0** - 重构前稳定版本，传统app目录结构
- **v1.0.0** - 初始发布版本

## 🤝 贡献指南

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

## 📄 许可证

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

## 🆘 支持

如果您在使用过程中遇到问题，请：

1. 查看 [文档](docs/)
2. 搜索 [Issues](../../issues)
3. 创建新的 [Issue](../../issues/new)

---

**Gin Framework v2.0** - 企业级Go Web开发框架 🚀