【Golang】Gin：静态服务与模板

T0uken2025-09-25 10:54

本教程将带你从零开始，在 Ubuntu 环境下安装 Go，初始化 Gin 项目，依次实现 静态资源服务 和 模板渲染。

推荐阅读官方文档：

一、安装 Go 语言

1.1 检查是否已安装

bash 复制代码 
go version

若提示 command not found 或版本低于 1.20，需要重新安装。

1.2 使用 APT 安装

更新软件包索引：

bash 复制代码 
sudo apt update

安装 Go：

bash 复制代码 
sudo apt install golang -y

1.3 验证安装

bash 复制代码 
go version

输出类似：

复制代码 
go version go1.22.2 linux/amd64

1.4 配置代理（国内环境推荐）

bash 复制代码 
go env -w GOPROXY=https://goproxy.cn,direct

这能加速依赖下载。

二、初始化 Demo

2.1 创建项目目录

bash 复制代码 
mkdir -p ~/workspace/gin-tutorial
cd ~/workspace/gin-tutorial

2.2 初始化 Go 模块

bash 复制代码 
go mod init gin-tutorial

生成的 go.mod 文件类似：

go 复制代码 
module gin-tutorial

go 1.22.2

2.3 安装 Gin 框架

bash 复制代码 
go get github.com/gin-gonic/gin

go.mod 会出现依赖：

go 复制代码 
require github.com/gin-gonic/gin v1.10.0

2.4 编写第一个 Gin 程序

main.go：

go 复制代码 
// 声明这个文件属于 main 包，每个 Go 程序都必须有一个 main 包，它是程序的入口
package main

// 导入程序需要用到的其他代码包（库）
// "fmt" 是 Go 语言内置的标准包，用来打印文字、格式化输出等
// "github.com/gin-gonic/gin" 是一个第三方 Web 框架，用来快速创建网站和 API
// 我们可以通过别名 gin 来使用它提供的功能
import (
	"fmt"
	"github.com/gin-gonic/gin"
)

// main 函数是程序的起点，当你运行这个程序时，会从这里开始执行
func main() {
	// 使用 fmt 包中的 Println 函数，在终端（命令行）输出一句话
	// 这句话只是测试，表示程序已经开始运行了
	fmt.Println("Hello, Go!")

	// 使用 Gin 框架的 Default() 函数创建一个 Web 服务器（也叫路由引擎）
	// r 是我们给这个服务器起的名字，后面可以通过它来设置各种网页路径
	// Default() 会自动加上一些常用的功能，比如记录请求日志、防止程序崩溃等
	r := gin.Default()

	// 设置一个网页路径：当有人用浏览器访问 http://你的电脑地址:8080/hello 时
	// 执行后面的函数，向用户返回一段 JSON 数据
	// r.GET 表示只处理 "GET" 类型的请求（最常见的网页访问方式）
	// "/hello" 是路径，就像网站的子页面，比如 www.example.com/hello
	// func(c *gin.Context) { ... } 是一个"匿名函数"，用来处理这个请求
	// c 是上下文（Context），你可以把它看作是一个工具箱，包含了请求信息和返回响应的方法
	r.GET("/hello", func(c *gin.Context) {
		// 使用 c.JSON 方法向用户返回一个 JSON 格式的数据
		// 200 是 HTTP 状态码，表示"成功"（就像打电话接通了）
		// gin.H 是 Gin 提供的一个快捷方式，用来创建一个 map（字典）
		// 这里返回的内容是：{"message": "Hello, Gin!"}
		c.JSON(200, gin.H{"message": "Hello, Gin!"})
	})

	// 启动服务器，让它在电脑的 8080 端口等待别人访问
	// 你可以想象成打开了一扇门，门牌号是 8080
	// 启动后，程序会一直运行，直到你手动停止（比如按 Ctrl+C）
	// 之后你就可以在浏览器输入 http://localhost:8080/hello 来看到返回的结果
	r.Run(":8080")
}

运行：

bash 复制代码 
go run main.go

测试：

bash 复制代码 
curl http://localhost:8080/hello

输出：

json 复制代码 
{"message":"Hello, Gin!"}

三、静态 HTML 服务器

很多时候我们需要把前端页面一并打包进 Go 二进制。Gin 支持结合 Go 的 embed 包 实现这一功能。

3.1 创建静态资源目录

bash 复制代码 
mkdir static

在 static/index.html 写入：

html 复制代码 
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Gin Static Demo</title>
</head>
<body>
    <h1>Hello, Gin Static!</h1>
</body>
</html>

3.2 编写 main.go

go 复制代码 
// 声明这是一个主程序包，每个 Go 程序都必须有一个 main 包，它是程序的起点
package main

// 导入所需的代码包
// "embed" 用于将模板文件直接打包进最终的可执行程序，无需外部依赖
// "net/http" 提供 HTTP 协议支持，如状态码 http.StatusOK（200）
// "time" 用于获取和格式化当前时间
// "github.com/gin-gonic/gin" 是一个轻量高效的 Web 框架，用于构建 Web 服务
import (
	"embed"
	"net/http"
	"time"

	"github.com/gin-gonic/gin"
)

// 编译指令：将 templates 文件夹中的所有文件（如 index.html）嵌入到程序中
// 运行时这些文件就像已经内置在程序内部，不需要额外部署
// embeddedTemplates 是一个 embed.FS 类型的变量，代表这个嵌入的文件系统
//
//go:embed templates/*
var embeddedTemplates embed.FS

// 程序入口函数，当执行程序时，从这里开始运行
func main() {
	// 创建一个默认的 Gin 路由引擎，自带日志和错误恢复功能
	r := gin.Default()

	// 告诉 Gin 从嵌入的文件系统中加载 HTML 模板
	// http.FS(embeddedTemplates) 将 embed.FS 转换为 HTTP 可识别的文件系统
	// "templates/*" 表示匹配 templates 目录下的所有文件
	// 这样 Gin 就能使用这些模板来生成动态网页
	r.LoadHTMLFS(http.FS(embeddedTemplates), "templates/*")

	// 定义一个路由：当用户访问根路径 "/" 时（如 http://localhost:8080），执行后面的函数
	r.GET("/", func(c *gin.Context) {
		// 使用 c.HTML 返回一个渲染后的 HTML 页面
		// http.StatusOK 表示 HTTP 状态码 200（请求成功）
		// "index.html" 是要渲染的模板文件名（必须位于 templates 目录下）
		// gin.H{} 是一个快捷方式，用来创建一个包含动态数据的字典
		// 这些数据会被传递到模板中：
		//   title: 设置网页标题
		//   message: 显示欢迎文字
		//   time: 显示当前时间，格式化为 "年-月-日 时:分:秒"
		//   items: 一个字符串列表，可在模板中循环展示
		// 在模板中可通过 {{ .title }}、{{ .message }} 等方式使用这些值
		c.HTML(http.StatusOK, "index.html", gin.H{
			"title":   "Gin 模板渲染示例 --- 第四章",
			"message": "欢迎使用 Gin 模板渲染！",
			"time":    time.Now().Format("2006-01-02 15:04:05"),
			"items":   []string{"项目 A", "项目 B", "项目 C"},
		})
	})

	// 启动 Web 服务器，监听本地的 8080 端口
	// 程序会持续运行，接收并处理来自浏览器的请求
	// 你可以通过访问 http://localhost:8080 来查看页面效果
	r.Run(":8080")
}

3.3 运行与测试

bash 复制代码 
go run main.go

在浏览器中测试：

四、模板渲染

Gin 内置对 Go 的 html/template 模板的支持，可以在后端渲染动态页面。

4.1 创建模板目录

bash 复制代码 
mkdir templates

templates/index.html 示例：

html 复制代码 
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{ .title }}</title>
</head>
<body>
    <h1>{{ .message }}</h1>
    <p>当前时间：{{ .time }}</p>

    {{ if .items }}
    <h2>项目列表：</h2>
    <ul>
    {{ range .items }}
        <li>{{ . }}</li>
    {{ end }}
    </ul>
    {{ else }}
    <p>没有项目。</p>
    {{ end }}
</body>
</html>

4.2 编写 main.go

go 复制代码 
// 声明这个文件属于 main 包，每个 Go 程序都必须有一个 main 包，它是程序的入口
package main

// 导入程序需要用到的代码包（库）
// "net/http" 是 Go 内置的网络包，提供 HTTP 相关功能，比如状态码 http.StatusOK（表示成功）
// "time" 是 Go 内置的时间包，用来获取当前时间、格式化时间等
// "github.com/gin-gonic/gin" 是一个流行的 Web 框架，用于快速构建 Web 服务和 API
import (
	"net/http"
	"time"
	"github.com/gin-gonic/gin"
)

// main 函数是程序的起点，当你运行这个程序时，会从这里开始执行
func main() {
	// 使用 Gin 框架的 Default() 函数创建一个 Web 服务器（也叫路由引擎）
	// r 是我们给这个服务器起的名字，后面可以通过它来设置各种网页路径
	// Default() 会自动加上一些常用的功能，比如记录请求日志、防止程序崩溃等
	r := gin.Default()

	// 告诉 Gin 从 templates 目录下加载所有 HTML 模板文件
	// "templates/*" 表示 templates 文件夹中的所有文件（比如 index.html、about.html 等）
	// 这样 Gin 才能知道有哪些模板可以用来生成网页内容
	r.LoadHTMLGlob("templates/*")

	// 定义一个路由：当用户访问根路径 "/"（即 http://localhost:8080/）时触发
	// r.GET 表示只处理 "GET" 请求（最常见的网页访问方式）
	// func(c *gin.Context) { ... } 是一个匿名函数，用来处理这个请求
	// c 是 *gin.Context 类型，代表当前请求的上下文，可以用来返回响应
	r.GET("/", func(c *gin.Context) {
		// 使用 c.HTML 方法渲染一个 HTML 模板并返回给用户
		// 第一个参数 http.StatusOK 表示 HTTP 状态码 200，即"成功"
		// 第二个参数 "index.html" 是要渲染的模板文件名（必须在 templates 目录下）
		// 第三个参数是一个数据对象（gin.H 是 map 的快捷方式），包含要传递给模板的数据
		// 这些数据包括：
		//   - title: 网页标题
		//   - message: 欢迎信息
		//   - time: 当前时间，使用 time.Now() 获取，并用 Format 格式化为 "年-月-日 时:分:秒"
		//   - items: 一个字符串切片（列表），可以在模板中循环显示
		// 模板文件中可以通过 {{ .title }}、{{ .message }} 等方式使用这些数据
		c.HTML(http.StatusOK, "index.html", gin.H{
			"title":   "Gin 模板渲染示例 --- 第四章",
			"message": "欢迎使用 Gin 模板渲染！",
			"time":    time.Now().Format("2006-01-02 15:04:05"),
			"items":   []string{"项目 A", "项目 B", "项目 C"},
		})
	})

	// 启动 Web 服务器，监听本地 8080 端口
	// 程序会一直运行，等待并处理来自浏览器的请求
	// 你可以通过 http://localhost:8080/ 访问这个页面
	r.Run(":8080")
}

4.3 运行与测试

bash 复制代码 
go run main.go

浏览器打开：
http://127.0.0.1:8080/

你会看到渲染后的 HTML 页面。

可选：用 curl 查看 HTML：

bash 复制代码 
curl -i http://127.0.0.1:8080/

4.4 常用模板语法

  • 变量输出 ：{``{ .Var }}

  • 条件语句：

    go 复制代码 
    {{ if .Cond }}内容{{ else }}备用内容{{ end }}

  • 循环语句：

    go 复制代码 
    {{ range .List }}<li>{{ . }}</li>{{ end }}

  • 子模板/继承 ：

    可用 {``{ define "name" }} 与 {``{ template "name" . }} 组合（参考 Go 文档 html/template）

五、总结

通过本文你学会了安装 Go 并配置环境，完成了 Gin 项目初始化与第一个 API，用 embed 打包静态资源避免依赖外部文件，并学习了模板渲染以结合后端数据动态生成 HTML。

相关推荐
CAir23 小时前
go引入自定义mod
开发语言·golang
Humbunklung3 小时前
C# 获取docx文档页数的古怪方法
开发语言·microsoft·c#
gxea4 小时前
PHP 分布式验证码登录解决方案
开发语言·分布式·php
翻斗花园刘大胆4 小时前
JavaWeb之HttpServletRequest与HttpServletResponse详解及快递管理系统实践
java·开发语言·数据库·mysql·servlet·架构·mvc
张童瑶4 小时前
Linux Cent OS7离线安装Go环境（最新版本）
linux·运维·golang
张璐月4 小时前
go 持续集成、持续部署之gitlab流水线+docker-compose踩坑之旅
ci/cd·golang·gitlab
椎名澄嵐4 小时前
★ Linux ★ 信号
linux·运维·服务器·开发语言·c++
赵谨言5 小时前
基于Python的二手房价格数据分析预测系统
开发语言·经验分享·python
普通网友5 小时前
C++构建缓存加速
开发语言·c++·算法
热门推荐
01UV 工具安装与国内镜像源配置指南02GitHub 镜像站点03Spec-Kit 使用指南04UV安装并设置国内源052025年华为杯研赛数学建模竞赛C题完整参考论文 （含模型、MATLAB和Python代码）0646个Nano-banana 精选提示词，持续更新中07保姆级教程：手把手教你用Dify实现完美多轮对话（附Chatflow和提示词）08KGG转MP3工具|非KGM文件|解密音频09Linux下V2Ray安装配置指南10解决 WSL Ubuntu 中 /etc/resolv.conf 自动重置问题