Gin

Gin 是一个用 Go 语言编写的 HTTP Web 框架。它具有类似 Martini 的 API，但性能比 Martini 快 40 倍。Gin 使用了自定义版本的 HttpRouter，因此它不仅提供了极快的路由，还提供了中间件支持。

本指南介绍如何在 CloudBase HTTP 云函数上部署 Gin 应用程序。

示例源码请参考: cloudrun-gin

前置条件

在开始之前，请确保您已经：

安装了 Go 1.23 或更高版本
拥有腾讯云账号并开通了 CloudBase 服务
了解基本的 Go 语言和 Gin 框架开发知识

第一步：创建 Gin 应用

💡 提示：如果您已经有一个 Gin 应用，可以跳过此步骤。

创建项目目录

mkdir cloudrun-gin
cd cloudrun-gin

初始化 Go 模块

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

创建主应用文件

在 cloudrun-gin 目录下创建 main.go 文件：

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

打开浏览器访问 http://localhost:8080，您应该能看到 JSON 响应。

第二步：添加 API 路由

让我们创建一个 RESTful API 来演示 Gin 的功能。

创建用户模型

在项目根目录创建 models 目录，并创建 user.go 文件：

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"`
}

创建用户控制器

在项目根目录创建 controllers 目录，并创建 user.go 文件：

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,
	})
}

更新主应用文件

更新 main.go 文件，添加路由和中间件：

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"}'

第四步：准备部署文件

1. 创建启动脚本

💡 注意：

在 windows 下创建 scf_bootstrap 文件时，优先使用 nano scf_bootstrap 或者 vim scf_bootstrap 创建

在 windows 下使用 vscode 创建 scf_bootstrap 文件时，部署到 HTTP 云函数可能会报错: scf_bootstrap 文件不存在

这个错误是因为脚本文件包含了 Windows 格式的回车符（^M），导致 Linux 无法正确识别解释器路径。这是 WSL 中常见的问题

创建 scf_bootstrap 文件（无扩展名）：

#!/bin/bash
export PORT=9000
export GIN_MODE=release
./main

为启动脚本添加执行权限：

chmod +x scf_bootstrap

2. 编译应用

编译 Go 应用为 Linux 二进制文件：

# 交叉编译为 Linux 64位
GOOS=linux GOARCH=amd64 go build -o main .

3. 项目结构

cloudrun-gin/
├── controllers/
│   └── user.go
├── models/
│   └── user.go
├── main.go
├── go.mod
├── go.sum
├── main                   # 编译后的二进制文件
└── scf_bootstrap         # 🔑 云函数启动脚本

💡 说明：

scf_bootstrap 是 CloudBase 云函数的启动脚本

需要将 Go 应用编译为 Linux 二进制文件

设置 PORT=9000 环境变量确保应用监听正确端口

设置 GIN_MODE=release 优化性能

第五步：部署到 CloudBase

通过控制台部署

登录 CloudBase 控制台
选择您的环境，进入「云函数」页面
点击「新建云函数」
选择「HTTP 云函数」
填写函数名称（如：gin-app）
选择运行时：Go 1.x（或其他支持的版本）
提交方法选择：本地上传代码包
上传编译后的二进制文件和 scf_bootstrap 文件
自动安装依赖：关闭（Go 应用无需此选项）
点击「创建」按钮等待部署完成

打包部署

如果需要手动打包：

# 编译应用
GOOS=linux GOARCH=amd64 go build -o main .

# 创建部署包
zip -j gin-app.zip main scf_bootstrap

第六步: 访问您的应用

部署成功后，您可以参考通过 HTTP 访问云函数设置自定义域名访问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"}'

常见问题

Q: 为什么 HTTP 云函数必须使用 9000 端口？

A: CloudBase HTTP 云函数要求应用监听 9000 端口，这是平台的标准配置。应用通过环境变量 PORT=9000 来控制端口，本地开发时默认使用 8080 端口。

Q: Go 应用如何进行交叉编译？

A: 使用以下命令进行交叉编译：

GOOS=linux GOARCH=amd64 go build -o main .

Q: 如何优化 Go 应用的冷启动时间？

减少依赖包数量
使用 gin.ReleaseMode 模式
避免在启动时进行重复的初始化操作
合理设置内存配置

Q: scf_bootstrap 文件有什么作用？

A: scf_bootstrap 是云函数的启动脚本，用于设置环境变量和启动编译后的二进制文件。

下一步

了解更多 HTTP 云函数配置选项
学习如何连接 CloudBase 数据库

前置条件​

第一步：创建 Gin 应用​

创建项目目录​

初始化 Go 模块​

创建主应用文件​

本地测试应用​

第二步：添加 API 路由​

创建用户模型​

创建用户控制器​

更新主应用文件​

第三步：本地测试​

更新依赖​

启动应用​

测试 API 接口​

第四步：准备部署文件​

1. 创建启动脚本​

2. 编译应用​

3. 项目结构​

第五步： 部署到 CloudBase​

通过控制台部署​

打包部署​

第六步: 访问您的应用​

示例请求​

常见问题​

Q: 为什么 HTTP 云函数必须使用 9000 端口？​

Q: Go 应用如何进行交叉编译？​

Q: 如何优化 Go 应用的冷启动时间？​

Q: scf_bootstrap 文件有什么作用？​

下一步​