Gin 框架响应格式与 HTML 模板渲染完整实战教程

🏷️ 标签：Gin Go语言 响应格式 模板渲染 HTML模板 FuncMap 后端开发 📝 简介：本文基于实训内容，全面讲解 Gin 框架JSON/XML/YAML 多种响应格式、HTML 模板渲染、自定义模板函数、模板嵌套布局，从零上手可直接实战开发，适合初学者、课程实训、CSDN 学习收藏。

一、前言

在 Gin 框架 Web 开发中，接口开发离不开多种数据响应格式 ，页面开发离不开HTML 模板渲染 。 Gin 基于Context上下文封装了丰富的响应方法，同时兼容 Go 原生html/template模板库，支持模板加载、数据传递、自定义模板函数、模板布局嵌套等功能。

本文完整覆盖以下知识点：

Gin 多种响应格式：JSON、XML、YAML、字符串响应
结构体、Map、数组三种方式返回 JSON
HTML 模板加载、渲染、向模板传递数据
自定义模板函数 FuncMap 注册与使用
模板嵌套、布局页面继承实现
常见思考题知识点解析

二、实训环境准备

开发环境

操作系统：Windows 10 / Windows 11
Go 版本：Go 1.23
编辑器：VS Code + Go 扩展插件
依赖：Gin 框架

安装 Gin 依赖

复制代码

go get github.com/gin-gonic/gin

三、Gin 多种响应格式实战

3.1 统一前置代码

复制代码

package main

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

func main() {
	r := gin.Default()

	// 下方所有路由写在这里

	r.Run(":8080")
}

3.2 JSON 响应（三种实现方式）

1）定义用户结构体

复制代码

type User struct {
	Name  string `json:"name"`
	Age   int    `json:"age"`
	Email string `json:"email"`
}

2）结构体方式返回 JSON

适合规范接口、结构化数据返回

复制代码

// 结构体返回JSON
r.GET("/json/struct", func(c *gin.Context) {
	c.JSON(200, User{
		Name:  "张三",
		Age:   25,
		Email: "zhangsan@example.com",
	})
})

3）Map 方式返回 JSON

适合临时构造不规则数据

复制代码

// Map方式返回JSON
r.GET("/json/map", func(c *gin.Context) {
	c.JSON(200, gin.H{
		"goodsName": "Gin教程",
		"price":     99,
		"stock":     100,
	})
})

4）数组 / 切片方式返回 JSON

适合返回列表、用户数组

复制代码

// 数组方式返回JSON
r.GET("/json/array", func(c *gin.Context) {
	userList := []User{
		{Name: "张三", Age: 25, Email: "zhangsan@example.com"},
		{Name: "李四", Age: 23, Email: "lisi@example.com"},
	}
	c.JSON(200, userList)
})

3.3 XML 响应格式

定义带 xml 标签的结构体：

复制代码

type UserXML struct {
	Name  string `xml:"name"`
	Age   int    `xml:"age"`
	Email string `xml:"email"`
}

编写路由：

复制代码

r.GET("/xml", func(c *gin.Context) {
	c.XML(200, UserXML{
		Name:  "张三",
		Age:   25,
		Email: "zhangsan@example.com",
	})
})

3.4 YAML 响应格式

复制代码

r.GET("/yaml", func(c *gin.Context) {
	c.YAML(200, gin.H{
		"appName": "Gin实训项目",
		"version": "v1.0",
		"author":  "admin",
	})
})

3.5 普通字符串响应

复制代码

r.GET("/string", func(c *gin.Context) {
	c.String(200, "Hello Gin 响应格式演示")
})

四、Gin HTML 模板渲染实战

4.1 项目目录结构

复制代码

project/
├── main.go
└── templates/
    ├── index.html
    ├── user.html
    └── layout.html

4.2 加载模板文件

使用LoadHTMLGlob加载 templates 下所有模板：

复制代码

func main() {
	r := gin.Default()
	// 加载templates目录下所有html模板
	r.LoadHTMLGlob("templates/*")

	// 模板路由...

	r.Run(":8080")
}

4.3 首页模板渲染

templates/index.html

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{{.title}}</title>
</head>
<body>
    <h1>{{.title}}</h1>
    <ul>
        {{range .users}}
        <li>姓名：{{.Name}}，年龄：{{.Age}}，邮箱：{{.Email}}</li>
        {{end}}
    </ul>
</body>
</html>

Go 路由代码：

复制代码

r.GET("/", func(c *gin.Context) {
	c.HTML(200, "index.html", gin.H{
		"title": "用户管理页面",
		"users": []User{
			{Name: "Zhang", Age: 25, Email: "z@test.com"},
			{Name: "Li", Age: 22, Email: "l@test.com"},
		},
	})
})

4.4 个人信息模板渲染

templates/user.html

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>用户详情</title>
</head>
<body>
    <h2>用户详情</h2>
    <p>姓名：{{.Name}}</p>
    <p>年龄：{{.Age}}</p>
    <p>邮箱：{{.Email}}</p>
</body>
</html>

路由：

复制代码

r.GET("/user", func(c *gin.Context) {
	c.HTML(200, "user.html", User{
		Name:  "王五",
		Age:   28,
		Email: "wangwu@test.com",
	})
})

五、自定义模板函数 FuncMap

5.1 注册自定义模板函数

支持时间格式化、字符串大写转换等自定义逻辑：

复制代码

import (
	"strings"
	"text/template"
	"time"
)

// 注册模板自定义函数
r.SetFuncMap(template.FuncMap{
	// 时间格式化
	"formatDate": func(t time.Time) string {
		return t.Format("2006-01-02")
	},
	// 转大写
	"upper": strings.ToUpper,
})

注意：必须在 LoadHTMLGlob 之前注册 FuncMap

5.2 模板中使用自定义函数

复制代码

<p>当前时间：{{formatDate .nowTime}}</p>
<p>姓名大写：{{upper .Name}}</p>

后端传值：

复制代码

r.GET("/func", func(c *gin.Context) {
	c.HTML(200, "user.html", gin.H{
		"Name":    "gin",
		"nowTime": time.Now(),
	})
})

六、模板嵌套与布局实现

6.1 布局模板 layout.html

定义公共头部和底部，预留内容插槽：

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>公共布局</title>
</head>
<body>
    <header>网站公共头部导航</header>

    {{template "content" .}}

    <footer>网站公共底部版权信息</footer>
</body>
</html>

6.2 子页面继承布局

在 index.html 中定义content区块：

复制代码

{{define "content"}}
<h1>首页主体内容</h1>
<p>继承公共布局页面</p>
{{end}}

访问路由即可自动嵌套公共布局，实现页面复用。

七、实训思考题答案

1. c.JSON ()、c.IndentedJSON ()、c.SecureJSON () 区别

c.JSON()：普通 JSON 响应，紧凑格式，生产常用
c.IndentedJSON()：格式化缩进 JSON，便于调试展示
c.SecureJSON()：安全 JSON，自动过滤特殊字符，防止 XSS 注入

2. 客户端自动适配 JSON/XML

通过获取请求头Accept，判断客户端支持的格式，动态调用c.JSON()或c.XML()返回对应数据。

3. 模板防止 XSS 攻击

Go html/template 默认自动转义 HTML 特殊字符，会自动过滤恶意脚本，无需手动处理；禁止使用template.JS、template.HTML直接渲染用户输入内容。

4. {{template}} 和 {{block}} 区别

{``{template}}：引入外部模板，固定渲染内容
{``{block}}：定义可重写区块，子模板可以覆盖默认内容，更适合布局继承

八、总结

Gin 支持 JSON、XML、YAML、String 多种响应格式，适配前后端交互各种场景。
JSON 可通过结构体、Map、数组三种方式返回，分别适合规范接口、临时数据、列表数据。
使用 LoadHTMLGlob 加载模板，c.HTML 实现页面渲染并传递变量。
通过 SetFuncMap 可以注册自定义模板函数，实现时间格式化、字符串处理等扩展功能。
利用 {``{template}} 可实现模板嵌套与公共布局复用，提升前端页面开发效率。
理解三种 JSON 方法区别、XSS 防护、模板布局语法，是 Gin 页面开发和接口开发的必备基础。

版权声明

本文为原创 Gin 框架响应格式与模板渲染实战教程，基于实训项目整理，知识点完整、代码可直接运行，适合 CSDN 发布、课程实训、期末作业学习，禁止未经授权转载、抄袭与搬运。