快速部署 Gin 应用

📋 目录导航

部署方式对比

前置条件

第一步:创建 Gin 应用

创建项目目录

mkdir cloudrun-gin
cd cloudrun-gin

初始化 Go 模块

go mod init cloudrun-gin
go get -u github.com/gin-gonic/gin

创建主应用文件

package main
import (
	"net/http"
	"os"
	"github.com/gin-gonic/gin"
)
func main() {
	// 设置 Gin 模式
	if os.Getenv("GIN_MODE") == "" {
		gin.SetMode(gin.ReleaseMode)
	}
	router := gin.Default()
	// 基础路由
	router.GET("/", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "欢迎使用 Gin CloudBase 应用!",
			"status": "running",
		})
	})
	// 健康检查
	router.GET("/health", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"status": "healthy",
			"framework": "Gin",
			"go_version": "1.19+",
			"gin_version": gin.Version,
		})
	})
	// 获取端口,支持环境变量
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	// 启动服务器
	router.Run(":" + port)
}

本地测试应用

go run main.go

第二步:添加 API 路由

创建用户模型

package models
type User struct {
	ID int `json:"id"`
	Name string `json:"name"`
	Email string `json:"email"`
}
type ApiResponse struct {
	Success bool `json:"success"`
	Message string `json:"message"`
	Data interface{} `json:"data,omitempty"`
}

创建用户控制器

package controllers
import (
	"net/http"
	"strconv"
	"sync"
	"cloudrun-gin/models"
	"github.com/gin-gonic/gin"
)
var (
	users []models.User
	usersMu sync.RWMutex
	nextID = 1
)
func init() {
	// 初始化测试数据
	users = []models.User{
		{ID: 1, Name: "张三", Email: "zhangsan@example.com"},
		{ID: 2, Name: "李四", Email: "lisi@example.com"},
		{ID: 3, Name: "王五", Email: "wangwu@example.com"},
	}
	nextID = 4
}
// GetUsers 获取用户列表
func GetUsers(c *gin.Context) {
	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "10"))
	usersMu.RLock()
	defer usersMu.RUnlock()
	startIndex := (page - 1) * limit
	endIndex := startIndex + limit
	if startIndex >= len(users) {
		c.JSON(http.StatusOK, models.ApiResponse{
			Success: true,
			Message: "获取成功",
			Data: []models.User{},
		})
		return
	}
	if endIndex > len(users) {
		endIndex = len(users)
	}
	paginatedUsers := users[startIndex:endIndex]
	c.JSON(http.StatusOK, models.ApiResponse{
		Success: true,
		Message: "获取成功",
		Data: gin.H{
			"total": len(users),
			"page": page,
			"limit": limit,
			"items": paginatedUsers,
		},
	})
}
// GetUser 根据ID获取用户
func GetUser(c *gin.Context) {
	id, err := strconv.Atoi(c.Param("id"))
	if err != nil {
		c.JSON(http.StatusBadRequest, models.ApiResponse{
			Success: false,
			Message: "无效的用户ID",
		})
		return
	}
	usersMu.RLock()
	defer usersMu.RUnlock()
	for _, user := range users {
		if user.ID == id {
			c.JSON(http.StatusOK, models.ApiResponse{
				Success: true,
				Message: "获取成功",
				Data: user,
			})
			return
		}
	}
	c.JSON(http.StatusNotFound, models.ApiResponse{
		Success: false,
		Message: "用户不存在",
	})
}
// CreateUser 创建用户
func CreateUser(c *gin.Context) {
	var newUser models.User
	if err := c.ShouldBindJSON(&newUser); err != nil {
		c.JSON(http.StatusBadRequest, models.ApiResponse{
			Success: false,
			Message: "请求参数错误: " + err.Error(),
		})
		return
	}
	if newUser.Name == "" || newUser.Email == "" {
		c.JSON(http.StatusBadRequest, models.ApiResponse{
			Success: false,
			Message: "姓名和邮箱不能为空",
		})
		return
	}
	usersMu.Lock()
	newUser.ID = nextID
	nextID++
	users = append(users, newUser)
	usersMu.Unlock()
	c.JSON(http.StatusCreated, models.ApiResponse{
		Success: true,
		Message: "创建成功",
		Data: newUser,
	})
}

更新主应用文件

package main
import (
	"fmt"
	"net/http"
	"os"
	"time"
	"cloudrun-gin/controllers"
	"github.com/gin-gonic/gin"
)
func main() {
	// 设置 Gin 模式
	if os.Getenv("GIN_MODE") == "" {
		gin.SetMode(gin.ReleaseMode)
	}
	router := gin.Default()
	// 添加 CORS 中间件
	router.Use(func(c *gin.Context) {
		c.Header("Access-Control-Allow-Origin", "*")
		c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
		c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
		if c.Request.Method == "OPTIONS" {
			c.AbortWithStatus(http.StatusNoContent)
			return
		}
		c.Next()
	})
	// 添加日志中间件
	router.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
		return fmt.Sprintf("%s - [%s] \"%s %s %s %d %s \"%s\" %s\"\n",
			param.ClientIP,
			param.TimeStamp.Format(time.RFC1123),
			param.Method,
			param.Path,
			param.Request.Proto,
			param.StatusCode,
			param.Latency,
			param.Request.UserAgent(),
			param.ErrorMessage,
		)
	}))
	// 基础路由
	router.GET("/", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "欢迎使用 Gin CloudBase 应用!",
			"status": "running",
		})
	})
	// 健康检查
	router.GET("/health", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"status": "healthy",
			"timestamp": time.Now().Format(time.RFC3339),
			"framework": "Gin",
			"go_version": "1.19+",
			"gin_version": gin.Version,
		})
	})
	// API 路由组
	api := router.Group("/api")
	{
		users := api.Group("/users")
		{
			users.GET("", controllers.GetUsers)
			users.GET("/:id", controllers.GetUser)
			users.POST("", controllers.CreateUser)
		}
	}
	// 获取端口,支持环境变量
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	// 启动服务器
	router.Run(":" + port)
}

第三步:本地测试

更新依赖

go mod tidy

启动应用

go run main.go

测试 API 接口

# 测试健康检查
curl http://localhost:8080/health
# 测试首页
curl http://localhost:8080/
# 测试用户列表
curl http://localhost:8080/api/users
# 测试分页
curl "http://localhost:8080/api/users?page=1&limit=2"
# 测试获取单个用户
curl http://localhost:8080/api/users/1
# 测试创建用户
curl -X POST http://localhost:8080/api/users \
 -H "Content-Type: application/json" \
 -d '{"name":"新用户","email":"newuser@example.com"}'

第四步:准备部署文件

📋 选择部署方式

第五步:项目结构

cloudrun-gin/
├── controllers/
│ └── user.go # 用户控制器
├── models/
│ └── user.go # 用户模型
├── main.go # 主应用文件
├── go.mod # Go 模块文件
├── go.sum # 依赖锁定文件
├── main # 编译后的二进制文件 (仅云函数需要)
├── scf_bootstrap # HTTP 云函数启动脚本 (仅云函数需要)
├── Dockerfile # 云托管容器配置 (仅云托管需要)
└── .dockerignore # Docker 忽略文件 (仅云托管需要)

第六步:部署应用

🚀 部署方式选择

第七步:访问您的应用

HTTP 云函数访问

云托管访问

测试接口

示例请求

# 健康检查
curl https://your-app-url/health
# 获取用户列表
curl https://your-app-url/api/users
# 分页查询
curl "https://your-app-url/api/users?page=1&limit=2"
# 创建新用户
curl -X POST https://your-app-url/api/users \
 -H "Content-Type: application/json" \
 -d '{"name":"测试用户","email":"test@example.com"}'

常见问题

❓ 问题分类

最佳实践

1. 环境变量管理

import "os"
func main() {
 // 端口配置
 port := os.Getenv("PORT")
 if port == "" {
 port = "8080"
 }
 
 // 数据库配置
 dbURL := os.Getenv("DATABASE_URL")
 
 // 应用模式
 if os.Getenv("GIN_MODE") == "" {
 gin.SetMode(gin.ReleaseMode)
 }
}

2. 端口配置策略

// 支持多环境端口配置(默认 8080,云函数环境通过 PORT=9000 控制)
port := os.Getenv("PORT")
if port == "" {
 port = "8080"
}
router.Run(":" + port)

3. 添加中间件

// 恢复中间件
router.Use(gin.Recovery())
// 自定义日志中间件
router.Use(gin.LoggerWithConfig(gin.LoggerConfig{
 Formatter: func(param gin.LogFormatterParams) string {
 return fmt.Sprintf("%s - %s \"%s %s\" %d %s\n",
 param.TimeStamp.Format("2006/01/02 - 15:04:05"),
 param.ClientIP,
 param.Method,
 param.Path,
 param.StatusCode,
 param.Latency,
 )
 },
}))
// 限流中间件
router.Use(ratelimit.RateLimiter(store, &ratelimit.Options{
 ErrorHandler: func(c *gin.Context, info ratelimit.Info) {
 c.String(429, "Too many requests. Try again in "+time.Until(info.ResetTime).String())
 },
}))

4. 错误处理

// 全局错误处理中间件
func ErrorHandler() gin.HandlerFunc {
 return func(c *gin.Context) {
 c.Next()
 
 if len(c.Errors) > 0 {
 err := c.Errors.Last()
 
 switch err.Type {
 case gin.ErrorTypeBind:
 c.JSON(http.StatusBadRequest, gin.H{
 "success": false,
 "message": "请求参数错误",
 "error": err.Error(),
 })
 default:
 c.JSON(http.StatusInternalServerError, gin.H{
 "success": false,
 "message": "服务器内部错误",
 })
 }
 }
 }
}

5. 结构化日志

import "github.com/sirupsen/logrus"
func init() {
 logrus.SetFormatter(&logrus.JSONFormatter{})
 logrus.SetLevel(logrus.InfoLevel)
}
func LoggerMiddleware() gin.HandlerFunc {
 return gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
 logrus.WithFields(logrus.Fields{
 "status_code": param.StatusCode,
 "latency": param.Latency,
 "client_ip": param.ClientIP,
 "method": param.Method,
 "path": param.Path,
 }).Info("HTTP Request")
 
 return ""
 })
}

6. 健康检查增强

func HealthCheck(c *gin.Context) {
 // 检查数据库连接
 dbStatus := "healthy"
 if err := db.Ping(); err != nil {
 dbStatus = "unhealthy"
 }
 
 // 检查外部服务
 externalStatus := "healthy"
 // ... 检查逻辑
 
 status := "healthy"
 if dbStatus != "healthy" || externalStatus != "healthy" {
 status = "unhealthy"
 c.Status(http.StatusServiceUnavailable)
 }
 
 c.JSON(c.Writer.Status(), gin.H{
 "status": status,
 "timestamp": time.Now().Format(time.RFC3339),
 "framework": "Gin",
 "go_version": runtime.Version(),
 "gin_version": gin.Version,
 "database": dbStatus,
 "external_service": externalStatus,
 })
}

进阶功能

数据库集成

go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql

import (
 "gorm.io/driver/mysql"
 "gorm.io/gorm"
)
func initDB() *gorm.DB {
 dsn := os.Getenv("DATABASE_URL")
 if dsn == "" {
 dsn = "user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
 }
 
 db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
 if err != nil {
 panic("failed to connect database")
 }
 
 return db
}

身份验证

go get -u github.com/golang-jwt/jwt/v4

API 文档

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

缓存支持

go get -u github.com/go-redis/redis/v8