让框架真的在生产环境里跑得稳。

项目介绍

ThinkGin 3.0 是一个基于 Gin 框架构建的现代化 Go 语言 Web 应用框架，面向中大型后端团队。

核心特性

快速开始

用几条命令把服务跑起来，是评估一个框架最直接的方式。

环境要求

• Go 版本：1.18 或更高版本，推荐 1.19+
• 操作系统：Windows 10+ / macOS 10.14+ / Linux（Ubuntu 18.04+, CentOS 7+）
• 内存：最低 512MB，推荐 1GB+
• 磁盘空间：最低 100MB

从源码运行

git clone https://gitee.com/cww0128/thinkgin.git
cd thinkgin

go mod tidy
go run main.go

# 验证运行
curl http://localhost:8000/

编译后运行

# 编译项目
go build -o thinkgin main.go

# Linux / macOS
./thinkgin

# Windows
thinkgin.exe

Docker 运行

docker build -t thinkgin:latest .
docker run -p 8000:8000 thinkgin:latest

环境配置

推荐：Go 1.18+ 现代化配置

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn

# 验证配置
go env | grep -E "(GO111MODULE|GOPROXY|GOSUMDB)"

macOS / Linux (Bash/Zsh)

export GO111MODULE=on
export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn

echo 'export GO111MODULE=on' >> ~/.bashrc
echo 'export GOPROXY=https://goproxy.cn,direct' >> ~/.bashrc
echo 'export GOSUMDB=sum.golang.google.cn' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

$env:GO111MODULE="on"
$env:GOPROXY="https://goproxy.cn,direct"
$env:GOSUMDB="sum.golang.google.cn"

[Environment]::SetEnvironmentVariable("GO111MODULE", "on", "User")
[Environment]::SetEnvironmentVariable("GOPROXY", "https://goproxy.cn,direct", "User")
[Environment]::SetEnvironmentVariable("GOSUMDB", "sum.golang.google.cn", "User")

架构设计

项目结构

thinkgin/                    # 项目根目录
├── app/                     # 应用层
│   ├── index/               # 模块示例
│   │   ├── controller/      # 控制器层
│   │   ├── model/           # 数据模型层
│   │   └── view/            # 视图层
│   └── config.go            # 配置管理入口
├── config/                  # 配置文件目录
│   ├── app.yaml             # 应用主配置
│   ├── server.yaml          # 服务器配置
│   ├── database.yaml        # 数据库配置
│   ├── log.yaml             # 日志配置
│   └── prometheus.yaml      # 监控配置
├── extend/                  # 扩展组件
│   └── middleware/          # 中间件
├── route/                   # 路由定义
├── public/                  # 静态资源
├── runtime/                 # 运行时文件
└── main.go                  # 程序入口

请求流程

HTTP Request → Router → Middleware → Controller
                                          ↓
                                        Model ↔ Database
                                          ↓
                             View / JSON → HTTP Response

服务启动示例

config := app.GetConfig()
logger := app.GetLogger()

appInstance, err := framework.New(
    framework.WithConfig(config),
    framework.WithLogger(logger),
    framework.WithShutdownTimeout(10*time.Second),
)
if err != nil {
    logger.Fatalf("应用初始化失败: %v", err)
}

if err := appInstance.Run(ctx); err != nil {
    logger.Fatalf("服务器运行失败: %v", err)
}

配置管理

ThinkGin 采用模块化配置架构，把不同功能的配置拆分到独立的 YAML 文件中。

配置文件矩阵

使用示例

// 获取配置实例
config := app.GetConfig()

// 访问不同模块配置
appName := config.App.Name
serverPort := config.Server.HTTP.Port
dbConfig := config.Database.Default

app.yaml

app:
  name: "ThinkGin"
  version: "3.0"
  debug: true
  timezone: "Asia/Shanghai"
  jwt:
    secret: "your-secret-key"
    expire: 7200

server.yaml

server:
  http:
    host: "0.0.0.0"
    port: 8000
    read_timeout: 60
    write_timeout: 60
  mode: "debug"

其他配置模块

日志系统

基于 Logrus 的高性能结构化日志系统，支持 JSON / Text 双格式，按时间或大小自动切割。

日志级别

使用方法

import "thinkgin/extend/middleware"

// 记录信息日志
middleware.BusinessLogger("info", "用户登录成功", map[string]interface{}{
    "user_id": 123,
    "username": "john",
    "ip": "192.168.1.1",
})

// 记录错误日志
middleware.BusinessLogger("error", "数据库连接失败", map[string]interface{}{
    "error": err.Error(),
    "database": "mysql",
})

直接使用 logrus 实例

import "thinkgin/app"

logger := app.GetLogger()
logger.WithFields(logrus.Fields{
    "user_id": 123,
    "action": "update_profile",
}).Info("用户更新资料")

日志文件

• 位置：runtime/log/
• 命名：system.YYYYMMDD.log
• 软链：system.log
• 自动清理：超过设定天数的旧日志会被删除

开发环境配置

log:
  default:
    level: "debug"
    format: "text"
  file:
    max_age: 3
    rotation_time: 6

生产环境配置

log:
  default:
    level: "info"
    format: "json"
  file:
    max_age: 30
    rotation_time: 24

监控体系

ThinkGin 3.0 集成 Prometheus 监控服务，提供完整的应用性能监控和业务指标采集能力。

监控特性

• HTTP 请求监控：自动记录请求数量、响应时间、请求体大小、响应体大小
• 系统资源监控：CPU 使用率、内存使用量、进程信息
• 业务指标：Counter / Histogram / Gauge 三种类型
• 配置化：所有监控参数均可配置调整
• 安全认证：支持基础认证保护监控端点
• 自定义标签：支持自定义标签与命名空间

快速启用

# config/app.yaml
app:
  monitoring:
    prometheus_enabled: true   # 总开关

go run main.go
curl http://localhost:8000/metrics

k8s 探针

• GET /livez
• GET /readyz

prometheus.yaml 核心配置

prometheus:
  enabled: true
  path: "/metrics"
  port: 0
  service_name: "thinkgin"
  namespace: "app"
  labels:
    environment: "development"
    version: "3.0"
  metrics:
    http:
      enabled: true
    system:
      enabled: true
    business:
      enabled: true
  scrape_interval: 15
  auth:
    enabled: false
    username: "prometheus"
    password: "secure_password"

业务埋点示例

import (
    "time"
    "thinkgin/extend/middleware"
    "github.com/gin-gonic/gin"
)

func YourHandler(c *gin.Context) {
    start := time.Now()

    if counter := middleware.BusinessCounter("api_calls", []string{"endpoint", "status"}); counter != nil {
        counter.WithLabelValues("/api/users", "success").Inc()
    }

    if histogram := middleware.BusinessHistogram("api_duration", []string{"endpoint"}, nil); histogram != nil {
        histogram.WithLabelValues("/api/users").Observe(time.Since(start).Seconds())
    }

    if gauge := middleware.BusinessGauge("online_users", []string{"type"}); gauge != nil {
        gauge.WithLabelValues("active").Set(123)
    }
}

常用 PromQL

# HTTP 请求总数
app_http_requests_total

# 平均响应时间
rate(app_http_request_duration_seconds_sum[5m]) / rate(app_http_request_duration_seconds_count[5m])

# 错误率（5xx）
rate(app_http_requests_total{status=~"5.."}[5m]) / rate(app_http_requests_total[5m])

# 内存使用量
app_system_memory_usage_bytes

开发指南

路由规范

// route/router.go
func SetupRoutes(r *gin.Engine) {
    api := r.Group("/api/v1")
    {
        api.GET("/users", controller.GetUsers)
        api.POST("/users", controller.CreateUser)
        api.PUT("/users/:id", controller.UpdateUser)
        api.DELETE("/users/:id", controller.DeleteUser)
    }
}

响应格式

{
  "code": 200,
  "data": {
    "Time": "2023-02-01T10:11:41.761Z",
    "data": "Hello ThinkGin!",
    "name": ""
  },
  "msg": "ok"
}

开发最佳实践

• 目录规范：按模块组织代码结构
• 配置驱动：环境差异全部交给配置文件
• 日志规范：使用结构化字段而不是拼接字符串
• 测试覆盖：单元测试 + 集成测试
• 监控埋点：在关键业务流程写入指标

部署指南

Docker 部署（推荐）

FROM golang:1.20-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod tidy && go build -o thinkgin

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/thinkgin .
COPY --from=builder /app/config ./config
CMD ["./thinkgin"]

docker build -t thinkgin:v3.0 .
docker run -p 8000:8000 thinkgin:v3.0

跨平台编译

# Linux
GOOS=linux GOARCH=amd64 go build -o thinkgin-linux

# Windows
GOOS=windows GOARCH=amd64 go build -o thinkgin.exe

# macOS
GOOS=darwin GOARCH=amd64 go build -o thinkgin-macos

Linux 后台运行

nohup ./thinkgin 1>info.log 2>&1 &

# 使用 systemd 管理
sudo systemctl enable thinkgin
sudo systemctl start thinkgin

常见问题

Go 版本过低

# 错误: go: thinkgin requires go >= 1.18
# macOS
brew install go
# 其他平台下载最新版: https://golang.org/dl/

端口占用

# Linux / macOS
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

网络连接问题

go env -w GOPROXY=https://goproxy.cn,direct

模块依赖问题

go clean -modcache
go mod download
go mod tidy

配置文件问题

ls -la config/

pip install yamllint
yamllint config/app.yaml

内存不足

# 调整 Go 垃圾回收
export GOGC=50
export GOMEMLIMIT=512MB  # Go 1.19+

故障排查命令

go version && go env
curl -I https://goproxy.cn
netstat -tlnp | grep :8000
tail -f runtime/log/system.log