# gin-starter

**Repository Path**: ynsluhan/gin-starter

## Basic Information

- **Project Name**: gin-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-02
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gin Starter - 功能完整的Gin Web启动器

一个功能完整、开箱即用的 Gin Web 框架启动器，提供统一的配置管理、中间件、数据库连接、Redis、JWT认证等功能。

## 🚀 特性

- **Web框架**: 基于Gin的高性能HTTP框架
- **配置管理**: 支持YAML配置文件，统一管理应用配置
- **数据库支持**: 集成GORM，支持MySQL、PostgreSQL等数据库
- **Redis支持**: 集成Redis客户端，支持缓存和会话管理
- **JWT认证**: 内置JWT认证中间件（支持RSA和HMAC算法）
- **中间件**: 提供安全、日志、恢复等常用中间件
- **统一响应**: 提供统一的API响应格式
- **优雅关闭**: 支持优雅关闭服务器
- **健康检查**: 内置健康检查接口
- **消息队列**: 支持RabbitMQ消息队列

## 📦 安装

```bash
go get gitee.com/ynsluhan/gin-starter
```

## 🚀 快速开始

### 1. 基本使用

```go
package main

import (
    "log"
    "gitee.com/ynsluhan/gin-starter/pkg/starter"
    "github.com/gin-gonic/gin"
)

func main() {
    // 加载配置并初始化
    if err := starter.LoadAndInit("config/config.yaml"); err != nil {
        log.Fatal(err)
    }

    // 创建Gin引擎
    gin.SetMode(gin.DebugMode)
    engine := gin.New()

    // 注册路由
    engine.GET("/health", func(c *gin.Context) {
        R.Data(c, gin.H{
            "status": "ok",
            "message": "服务运行正常",
        })
    })

    // 启动服务器
    engine.Run(":8080")
}
```

### 2. 使用启动器一键启动

```go
package main

import (
    "log"
    "gitee.com/ynsluhan/gin-starter/pkg/starter"
)

func main() {
    // 一键启动，包含配置加载、中间件注册、优雅关闭等
    if err := starter.Run("config/config.yaml"); err != nil {
        log.Fatal(err)
    }
}
```

## 📝 统一响应格式

### 使用方式

```go
import "gitee.com/ynsluhan/gin-starter/pkg/starter"

// 成功响应（带数据）
R.Data(c, user)

// 成功响应（无数据）
R.Ok(c, "操作成功")

// 错误响应
R.Error(c, http.StatusBadRequest, 40001, "参数错误")
R.BadRequest(c, "请求参数无效")
R.Unauthorized(c, "未授权访问")
R.Forbidden(c, "禁止访问")
R.NotFound(c, "资源不存在")
R.ServerError(c, "服务器内部错误")
```

### 响应格式

```json
{
    "code": 0,
    "message": "ok",
    "data": {
        "id": 1,
        "name": "用户名称"
    }
}
```

## ⚙️ 配置示例

### 快速开始

复制示例配置文件：
```bash
cp config/config.example.yaml config/config.yaml
```

然后根据需要修改配置。

### 完整配置示例

创建 `config/config.yaml` 文件：

```yaml
app:
  name: "gin-starter"
  mode: "debug"  # debug, release, test
  port: 8080
  read_timeout: 30
  write_timeout: 30
  max_header_bytes: 1048576

log:
  level: "info"
  format: "json"
  output: "stdout"
  file:
    enabled: true
    path: "./logs/app.log"
    max_size: 100
    max_age: 30
    max_backups: 10
    compress: true

database:
  enabled: true
  driver: "mysql"
  host: "localhost"
  port: 3306
  username: "root"
  password: "password"
  database: "gin_starter"
  charset: "utf8mb4"
  max_idle_conns: 10
  max_open_conns: 100
  conn_max_lifetime: 3600

redis:
  enabled: true
  host: "localhost"
  port: 6379
  password: ""
  database: 0
  pool_size: 10
  min_idle_conns: 5

jwt:
  enabled: true
  algorithm: "rs256"  # 支持 rs256, hs256
  secret: "your-secret-key"
  expire_hours: 24
```

## 🛠️ 中间件

### 安全中间件

```go
import "gitee.com/ynsluhan/gin-starter/internal/middleware"

security := middleware.NewSecurityMiddleware(cfg)
engine.Use(
    security.Recovery(),      // 恢复中间件
    security.Logger(),        // 日志中间件
    security.RequestID(),     // 请求ID中间件
    security.SecurityHeaders(), // 安全头中间件
    security.CORS(),          // 跨域中间件
    security.XSS(),           // XSS防护中间件
    security.RateLimit(),     // 限流中间件
)
```

### 认证中间件

```go
// 创建认证中间件
authMw := middleware.NewAuthMiddleware(jwtManager, cfg)

// 保护路由组
protected := engine.Group("/api/v1")
protected.Use(authMw.Auth())
{
    protected.GET("/profile", func(c *gin.Context) {
        // 获取当前用户信息
        user := c.MustGet("user")
        R.Data(c, user)
    })
}
```

### JWT 算法支持

项目支持以下 JWT 算法：

- **RS256**: 使用 RSA 私钥签名，公钥验证（推荐用于生产环境）
- **HS256**: 使用共享密钥签名和验证（适合开发环境）

配置示例：
```yaml
jwt:
  enabled: true
  algorithm: "rs256"  # 或 "hs256"
  secret: "your-secret-key"  # HS256 使用，RS256 可忽略
  expire_hours: 24
```

## 🗄️ 数据库操作

```go
import "gitee.com/ynsluhan/gin-starter/internal/database"

// 获取数据库连接
db := database.GetDB()

// 使用GORM进行数据库操作
var users []User
db.Find(&users)
```

## 🔴 Redis操作

```go
import "gitee.com/ynsluhan/gin-starter/pkg/starter"

// 使用Redis
err := starter.Redis.Set(ctx, "key", "value", time.Hour)
val, err := starter.Redis.Get(ctx, "key")
```

## 📨 消息队列

```go
import "gitee.com/ynsluhan/gin-starter/pkg/starter"

// 使用RabbitMQ
err := starter.MQ.Publish("exchange", "routing-key", []byte("message"))
```

## 📚 更多示例

查看 `examples/` 目录下的完整示例：

- `examples/simple/` - 简单使用示例

## 📝 日志配置

gin-starter 提供了强大的日志配置功能，支持多种输出格式和自定义参数。

### 快速配置

```yaml
log:
  level: "info"           # 日志级别: trace, debug, info, warn, error, fatal, panic
  format: "json"          # 日志格式: text, json
  output: "both"          # 输出方式: stdout, file, both
  file:
    enabled: true
    path: "./logs/app.log"
    max_size: 100         # 单个文件最大大小(MB)
    max_age: 30           # 文件保留天数
    max_backups: 10       # 最大备份文件数
    compress: true        # 是否压缩备份文件
  console:
    enabled: true
    force_colors: true    # 强制显示颜色
  json:
    pretty_print: false   # 是否美化输出
    timestamp_format: "2006-01-02 15:04:05"
  text:
    full_timestamp: true  # 显示完整时间戳
    force_colors: true    # 强制显示颜色
  caller:
    enabled: true         # 是否显示调用者信息
    skip: 0              # 跳过调用栈层数
  timestamp:
    format: "2006-01-02 15:04:05"  # 全局时间戳格式
    utc: false           # 是否使用UTC时间
```

### 详细配置说明

查看 [日志配置详解](docs/LOG_CONFIG.md) 获取完整的配置参数说明和示例。

### 使用示例

```go
import "gitee.com/ynsluhan/gin-starter/pkg/logger"

// 基础日志
logger.Info("应用启动成功")
logger.Debug("调试信息")
logger.Error("发生错误")

// 带字段的日志
logger.WithField("user_id", 123).Info("用户登录")
logger.WithFields(logrus.Fields{
    "user_id": 123,
    "action": "login",
}).Info("用户操作")
```

## 🔧 故障排除

### 常见问题

#### 1. 除零错误 (integer divide by zero)
```
panic: runtime error: integer divide by zero
```

**原因**: 限流配置中的 `requests_per_minute` 为 0 或未配置。

**解决方案**: 在配置文件中设置正确的限流值：
```yaml
security:
  rate_limit:
    enabled: true
    requests_per_minute: 1000  # 设置为大于0的值
```

#### 2. 数据库连接失败
```
dial tcp 127.0.0.1:3306: connect: connection refused
```

**原因**: MySQL 服务未启动或配置错误。

**解决方案**: 
- 启动 MySQL 服务
- 检查数据库配置
- 或禁用数据库功能：`database.enabled: false`

#### 3. Redis 连接失败
```
dial tcp 127.0.0.1:6379: connect: connection refused
```

**原因**: Redis 服务未启动。

**解决方案**:
- 启动 Redis 服务
- 或禁用 Redis 功能：`redis.enabled: false`

#### 4. 配置文件不存在
```
读取配置文件失败: open config/config.yaml: no such file or directory
```

**解决方案**: 复制示例配置文件：
```bash
cp config/config.example.yaml config/config.yaml
```

### 调试模式

启用调试模式获取更详细的日志：
```yaml
app:
  mode: "debug"

log:
  level: "debug"
```

## 📝 变更日志

### v1.1.0 (2024-09-04)

#### ✨ 新增功能
- 简化了响应API调用：`starter.R.Data(user)` → `R.Data(user)`
- 优化了项目结构，移除了不必要的依赖

#### 🔧 技术改进
- 移除了 SM2 加密支持，专注于 RSA 和 HMAC 算法
- 清理了未使用的依赖包
- 修复了 Go 版本兼容性问题
- 优化了 JWT 认证实现

#### 🗑️ 移除功能
- 移除了 Swagger 文档生成（可单独集成）
- 移除了 Excel 文件处理功能（可单独集成）
- 移除了阿里云 OSS 和 MinIO 支持（可单独集成）
- 移除了 SM2 国密算法支持

#### 📦 依赖更新
- 更新了核心依赖包版本
- 移除了有问题的第三方包
- 优化了模块依赖关系

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License