Gin框架介绍及使用
Gin框架介绍
Gin是一个用Go语言编写的web框架。它是一个类似于martini但拥有更好性能的API框架, 由于使用了httprouter，速度提高了近40倍。 如果你是性能和高效的追求者, 你会爱上Gin。
Go世界里最流行的Web框架，Github上有32K+star。 基于httprouter开发的Web框架。 中文文档齐全，简单易用的轻量级框架。
Gin框架安装与使用
安装
下载并安装Gin:
go get -u github.com/gin-gonic/gin
如果运行过后报错：
go:build comment without // +build comment
可能是go 的版本 是低于1.17版本 导致出现的问题，go 引入的依赖库包中 1.17版本后 引入了新的构建标记语法导致的兼容问题
第一个Gin示例：
package main
import (
"github.com/gin-gonic/gin"
)
func main() {
// 创建一个默认的路由引擎
r := gin.Default()
// GET：请求方式；/hello：请求的路径
// 当客户端以GET方法请求/hello路径时，会执行后面的匿名函数
r.GET("/hello", func(c *gin.Context) {
// c.JSON：返回JSON格式的数据
c.JSON(200, gin.H{
"message": "Hello world!",
})
})
// 启动HTTP服务，默认在0.0.0.0:8080启动服务
r.Run()
}
将上面的代码保存并编译执行，然后使用浏览器打开127.0.0.1:8080/hello就能看到一串JSON字符串。
如果修改默认端口号为9080：
r.Run(":9080")
RESTful API
REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表征状态转移”或“表现层状态转化”。
推荐阅读阮一峰 理解RESTful架构
简单来说，REST的含义就是客户端与Web服务器之间进行交互的时候，使用HTTP协议中的4个请求方法代表不同的动作。
GET用来获取资源POST用来新建资源PUT用来更新资源DELETE用来删除资源。
只要API程序遵循了REST风格，那就可以称其为RESTful API。目前在前后端分离的架构中，前后端基本都是通过RESTful API来进行交互。
例如，我们现在要编写一个管理书籍的系统，我们可以查询对一本书进行查询、创建、更新和删除等操作，我们在编写程序的时候就要设计客户端浏览器与我们Web服务端交互的方式和路径。按照经验我们通常会设计成如下模式：
| 请求方法 | URL | 含义 |
|---|---|---|
| GET | /book | 查询书籍信息 |
| POST | /create_book | 创建书籍记录 |
| POST | /update_book | 更新书籍信息 |
| POST | /delete_book | 删除书籍信息 |
同样的需求我们按照RESTful API设计如下：
| 请求方法 | URL | 含义 |
|---|---|---|
| GET | /book | 查询书籍信息 |
| POST | /book | 创建书籍记录 |
| PUT | /book | 更新书籍信息 |
| DELETE | /book | 删除书籍信息 |
Gin框架支持开发RESTful API的开发。
func main() {
r := gin.Default()
r.GET("/book", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "GET",
})
})
r.POST("/book", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "POST",
})
})
r.PUT("/book", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "PUT",
})
})
r.DELETE("/book", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "DELETE",
})
})
}
开发RESTful API的时候我们通常使用Postman来作为客户端的测试工具。
定义模板和解析模板
Go语言标准库之http/template
html/template包实现了数据驱动的模板，用于生成可防止代码注入的安全的HTML内容。它提供了和text/template包相同的接口，Go语言中输出HTML的场景都应使用html/template这个包。
模板与渲染
在一些前后端不分离的Web架构中，我们通常需要在后端将一些数据渲染到HTML文档中，从而实现动态的网页（网页的布局和样式大致一样，但展示的内容并不一样）效果。
我们这里说的模板可以理解为事先定义好的HTML文档文件，模板渲染的作用机制可以简单理解为文本替换操作–使用相应的数据去替换HTML文档中事先准备好的标记。
很多编程语言的Web框架中都使用各种模板引擎，比如Python语言中Flask框架中使用的jinja2模板引擎。
Go语言的模板引擎
Go语言内置了文本模板引擎text/template和用于HTML文档的html/template。它们的作用机制可以简单归纳如下：
- 模板文件通常定义为
.tmpl和.tpl为后缀（也可以使用其他的后缀），必须使用UTF8编码。 - 模板文件中使用
{{和}}包裹和标识需要传入的数据。 - 传给模板这样的数据就可以通过点号（
.）来访问，如果数据是复杂类型的数据，可以通过{ { .FieldName }}来访问它的字段。 - 除
{{和}}包裹的内容外，其他内容均不做修改原样输出。
模板引擎的使用
Go语言模板引擎的使用可以分为三部分：定义模板文件、解析模板文件和模板渲染.
定义模板文件
其中，定义模板文件时需要我们按照相关语法规则去编写，后文会详细介绍。
解析模板文件
上面定义好了模板文件之后，可以使用下面的常用方法去解析模板文件，得到模板对象：
//解析字符串形式的模板
func (t *Template) Parse(src string) (*Template, error)
//解析文件形式的模板，参数为地址
func ParseFiles(filenames ...string) (*Template, error)
//解析多个文件形式的地址，参数是多个地址
func ParseGlob(pattern string) (*Template, error)
当然，你也可以使用func New(name string) *Template函数创建一个名为name的模板，然后对其调用上面的方法去解析模板字符串或模板文件。
模板渲染
渲染模板简单来说就是使用数据去填充模板，当然实际上可能会复杂很多。
//渲染一个模板
func (t *Template) Execute(wr io.Writer, data interface{}) error
//当含有解析了多个模板文件时，指定渲染的模板文件进行渲染
func (t *Template) ExecuteTemplate(wr io.Writer, name string, data interface{}) error
基本示例
定义模板文件
我们按照Go模板语法定义一个hello.tmpl的模板文件，内容如下：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
<p>Hello {{.}}</p>
</body>
</html>
解析和渲染模板文件
然后我们创建一个main.go文件，在其中写下HTTP server端代码如下：
func sayHello(w http.ResponseWriter, r *http.Request) {
// 解析指定文件生成模板对象
tmpl, err := template.ParseFiles("./hello.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
// 利用给定数据渲染模板，并将结果写入w
tmpl.Execute(w, "沙河小王子")
}
func main() {
http.HandleFunc("/", sayHello)
err := http.ListenAndServe(":9090", nil)
if err != nil {
fmt.Println("HTTP server failed,err:", err)
return
}
}
将上面的main.go文件编译执行，然后使用浏览器访问http://127.0.0.1:9090就能看到页面上显示了“Hello 沙河小王子”。 这就是一个最简单的模板渲染的示例，Go语言模板引擎详细用法请往下阅读。
模板语法
{{.}}
模板语法都包含在{{和}}中间，其中{{.}}中的点表示当前对象。
当我们传入一个结构体对象时，我们可以根据.来访问结构体的对应字段。例如：
// main.go
type UserInfo struct {
Name string
Gender string
Age int
}
func sayHello(w http.ResponseWriter, r *http.Request) {
// 解析指定文件生成模板对象
tmpl, err := template.ParseFiles("./hello.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
// 利用给定数据渲染模板，并将结果写入w
user := UserInfo{
Name: "小王子",
Gender: "男",
Age: 18,
}
tmpl.Execute(w, user)
}
模板文件hello.tmpl内容如下：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
<p>Hello {{.Name}}</p>
<p>性别：{{.Gender}}</p>
<p>年龄：{{.Age}}</p>
</body>
</html>
同理，当我们传入的变量是map时，也可以在模板文件中通过.根据key来取值。
main.go
func sayHello(w http.ResponseWriter, r *http.Request) {
// 解析指定文件生成模板对象
tmpl, err := template.ParseFiles("./hello.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
// 利用给定数据渲染模板，并将结果写入w
m1 := map[string]interface{}{
"name": "小王子",
"age": 20,
"gender": "boy",
}
tmpl.Execute(w, m1)
}
hello.tmpl
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
<p>Hello {{.name}}</p>
<p>性别：{{.gender}}</p>
<p>年龄：{{.age}}</p>
</body>
</html>
main.go
package main
import (
"fmt"
"html/template"
"net/http"
)
type UserInfo struct {
Name string
Gender string
Age int
}
func sayHello(w http.ResponseWriter, r *http.Request) {
// 解析指定文件生成模板对象
tmpl, err := template.ParseFiles("./hello.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
// 利用给定数据渲染模板，并将结果写入w
m1 := map[string]interface{}{
"name": "小王子",
"age": 20,
"gender": "boy",
}
user := UserInfo{
Name: "小王子",
Gender: "男",
Age: 18,
}
tmpl.Execute(w, map[string]interface{}{
"user":user,
"m1":m1,
})
}
hello.tmpl
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
<p>m1</p>
<p>Hello {{.m1.name}}</p>
<p>性别：{{.gender}}</p>
<p>年龄：{{.age}}</p>
<p>user</p>
<p>Hello {{.user.Name}}</p>
<p>性别：{{.user.Gender}}</p>
<p>年龄：{{.user.Age}}</p>
</body>
</html>
注释
{{/* a comment */}}
注释，执行时会忽略。可以多行。注释不能嵌套，并且必须紧贴分界符始止。
pipeline
pipeline是指产生数据的操作。比如{{.}}、{{.Name}}等。Go的模板语法中支持使用管道符号|链接多个命令，用法和unix下的管道类似：|前面的命令会将运算结果(或返回值)传递给后一个命令的最后一个位置。
注意： 并不是只有使用了|才是pipeline。Go的模板语法中，pipeline的概念是传递数据，只要能产生数据的，都是pipeline。
变量
我们还可以在模板中声明变量，用来保存传入模板的数据或其他语句生成的结果。具体语法如下：
$obj := {{.}}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{ $v1 :=100 }}
{{ $age :=.m1.age }}
</body>
</html>
其中$obj是变量的名字，在后续的代码中就可以使用该变量了。
移除空格
有时候我们在使用模板语法的时候会不可避免的引入一下空格或者换行符，这样模板最终渲染出来的内容可能就和我们想的不一样，这个时候可以使用{{-语法去除模板内容左侧的所有空白符号， 使用-}}去除模板内容右侧的所有空白符号。
例如：
{{- .Name -}}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{- .user.Name -}}
</body>
</html>
注意： -要紧挨{{和}}，同时与模板值之间需要使用空格分隔。
条件判断
Go模板语法中的条件判断有以下几种:
{{if pipeline}} T1 {{end}}
{{if pipeline}} T1 {{else}} T0 {{end}}
{{if pipeline}} T1 {{else if pipeline}} T0 {{end}}
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{ $v1:=100 }}
{{ if $v1 }}
{{ $v1 }}
{{else}}
啥都没有
{{end}}
</body>
</html>
range
Go的模板语法中使用range关键字进行遍历，有以下两种写法，其中pipeline的值必须是数组、切片、字典或者通道。
{{range pipeline}} T1 {{end}}
如果pipeline的值其长度为0，不会有任何输出
{{range pipeline}} T1 {{else}} T0 {{end}}
如果pipeline的值其长度为0，则会执行T0。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{ range $id,$hobby := .m1}}
<p>{{$idx}} - {{$hobby}}</p>
{{end}}
</body>
</html>
with
{{with pipeline}} T1 {{end}}
如果pipeline为empty不产生输出，否则将dot设为pipeline的值并执行T1。不修改外面的dot。
{{with pipeline}} T1 {{else}} T0 {{end}}
如果pipeline为empty，不改变dot并执行T0，否则dot设为pipeline的值并执行T1。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{ with .m1}}
<p>{{.name}}</p>
<p>{{.age}}</p>
<p>{{.gender}}</p>
</body>
</html>
预定义函数
执行模板时，函数从两个函数字典中查找：首先是模板函数字典，然后是全局函数字典。一般不在模板内定义函数，而是使用Funcs方法添加函数到模板里。
预定义的全局函数如下：
and
函数返回它的第一个empty参数或者最后一个参数；
就是说"and x y"等价于"if x then y else x"；所有参数都会执行；
or
返回第一个非empty参数或者最后一个参数；
亦即"or x y"等价于"if x then x else y"；所有参数都会执行；
not
返回它的单个参数的布尔值的否定
len
返回它的参数的整数类型长度
index
执行结果为第一个参数以剩下的参数为索引/键指向的值；
如"index x 1 2 3"返回x[1][2][3]的值；每个被索引的主体必须是数组、切片或者字典。
print
即fmt.Sprint
printf
即fmt.Sprintf
println
即fmt.Sprintln
html
返回与其参数的文本表示形式等效的转义HTML。
这个函数在html/template中不可用。
urlquery
以适合嵌入到网址查询中的形式返回其参数的文本表示的转义值。
这个函数在html/template中不可用。
js
返回与其参数的文本表示形式等效的转义JavaScript。
call
执行结果是调用第一个参数的返回值，该参数必须是函数类型，其余参数作为调用该函数的参数；
如"call .X.Y 1 2"等价于go语言里的dot.X.Y(1, 2)；
其中Y是函数类型的字段或者字典的值，或者其他类似情况；
call的第一个参数的执行结果必须是函数类型的值（和预定义函数如print明显不同）；
该函数类型值必须有1到2个返回值，如果有2个则后一个必须是error接口类型；
如果有2个返回值的方法返回的error非nil，模板执行会中断并返回给调用模板执行者该错误；
比较函数
布尔函数会将任何类型的零值视为假，其余视为真。
下面是定义为函数的二元比较运算的集合：
eq 如果arg1 == arg2则返回真
ne 如果arg1 != arg2则返回真
lt 如果arg1 < arg2则返回真
le 如果arg1 <= arg2则返回真
gt 如果arg1 > arg2则返回真
ge 如果arg1 >= arg2则返回真
为了简化多参数相等检测，eq（只有eq）可以接受2个或更多个参数，它会将第一个参数和其余参数依次比较，返回下式的结果：
{{eq arg1 arg2 arg3}}
比较函数只适用于基本类型（或重定义的基本类型，如”type Celsius float32”）。但是，整数和浮点数不能互相比较。
自定义函数
Go的模板支持自定义函数。
func sayHello(w http.ResponseWriter, r *http.Request) {
htmlByte, err := ioutil.ReadFile("./hello.tmpl")
if err != nil {
fmt.Println("read html failed, err:", err)
return
}
// 自定义一个夸人的模板函数
kua := func(arg string) (string, error) {
return arg + "真帅", nil
}
// 采用链式操作在Parse之前调用Funcs添加自定义的kua函数
tmpl, err := template.New("hello").Funcs(template.FuncMap{"kua": kua}).Parse(string(htmlByte))
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
user := UserInfo{
Name: "小王子",
Gender: "男",
Age: 18,
}
// 使用user渲染模板，并将结果写入w
tmpl.Execute(w, user)
}
我们可以在模板文件hello.tmpl中按照如下方式使用我们自定义的kua函数了。
{{kua .Name}}
分来写不用链式结构
package main
import (
"fmt"
"html/template"
"io/ioutil"
"net/http"
)
type UserInfo struct {
Name string
Gender string
Age int
}
func sayHello(w http.ResponseWriter, r *http.Request) {
_, err := ioutil.ReadFile("./hello.tmpl")
if err != nil {
fmt.Println("read html failed, err:", err)
return
}
// 自定义一个夸人的模板函数
kua := func(arg string) (string, error) {
return arg + "真帅", nil
}
tmpl := template.New("f.tmpl") //创建一个名字为f的模板对象
//告诉模板我现在多了一个自定义函数kua
tmpl.Funcs(template.FuncMap{
"kua": kua,
})
//解析模板
_,err1 := tmpl.ParseFiles("./f.tmpl")
if err1 != nil {
fmt.Println("create template failed, err:", err)
return
}
user := UserInfo{
Name: "小王子",
Gender: "男",
Age: 18,
}
// 使用user渲染模板，并将结果写入w
tmpl.Execute(w, user)
}
嵌套template
我们可以在template中嵌套其他的template。这个template可以是单独的文件，也可以是通过define定义的template。
举个例子： t.tmpl文件内容如下：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>tmpl test</title>
</head>
<body>
<h1>测试嵌套template语法</h1>
<hr>
{{template "ul.tmpl"}}
<hr>
{{template "ol.tmpl"}}
</body>
</html>
{{ define "ol.tmpl"}}
<ol>
<li>吃饭</li>
<li>睡觉</li>
<li>打豆豆</li>
</ol>
{{end}}
ul.tmpl文件内容如下：
<ul>
<li>注释</li>
<li>日志</li>
<li>测试</li>
</ul>
我们注册一个templDemo路由处理函数.
http.HandleFunc("/tmpl", tmplDemo)
tmplDemo函数的具体内容如下：
func tmplDemo(w http.ResponseWriter, r *http.Request) {
tmpl, err := template.ParseFiles("./t.tmpl", "./ul.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
user := UserInfo{
Name: "小王子",
Gender: "男",
Age: 18,
}
tmpl.Execute(w, user)
}
注意：在解析模板时，被嵌套的模板一定要在后面解析，例如上面的示例中t.tmpl模板中嵌套了ul.tmpl，所以ul.tmpl要在t.tmpl后进行解析。
block
{{block "name" pipeline}} T1 {{end}}
block是定义模板{{define "name"}} T1 {{end}}和执行{{template "name" pipeline}}缩写，典型的用法是定义一组根模板，然后通过在其中重新定义块模板进行自定义。
定义一个根模板templates/base.tmpl，内容如下：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<title>Go Templates</title>
</head>
<body>
<div class="container-fluid">
{{block "content" . }}{{end}}
</div>
</body>
</html>
然后定义一个templates/index.tmpl，”继承”base.tmpl：
{{template "base.tmpl"}}
{{define "content"}}
<div>Hello world!</div>
{{end}}
然后使用template.ParseGlob按照正则匹配规则解析模板文件，然后通过ExecuteTemplate渲染指定的模板：
func index(w http.ResponseWriter, r *http.Request){
tmpl, err := template.ParseGlob("templates/*.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
err = tmpl.ExecuteTemplate(w, "index.tmpl", nil)
if err != nil {
fmt.Println("render template failed, err:", err)
return
}
}
如果我们的模板名称冲突了，例如不同业务线下都定义了一个index.tmpl模板，我们可以通过下面两种方法来解决。
- 在模板文件开头使用
{{define 模板名}}语句显式的为模板命名。 - 可以把模板文件存放在
templates文件夹下面的不同目录中，然后使用template.ParseGlob("templates/**/*.tmpl")解析模板。
修改默认的标识符
Go标准库的模板引擎使用的花括号{{和}}作为标识，而许多前端框架（如Vue和 AngularJS）也使用{{和}}作为标识符，所以当我们同时使用Go语言模板引擎和以上前端框架时就会出现冲突，这个时候我们需要修改标识符，修改前端的或者修改Go语言的。这里演示如何修改Go语言模板引擎默认的标识符：
template.New("test").Delims("{[", "]}").ParseFiles("./t.tmpl")
text/template与html/tempalte的区别
html/template针对的是需要返回HTML内容的场景，在模板渲染过程中会对一些有风险的内容进行转义，以此来防范跨站脚本攻击。
例如，我定义下面的模板文件：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Hello</title>
</head>
<body>
{{.}}
</body>
</html>
这个时候传入一段JS代码并使用html/template去渲染该文件，会在页面上显示出转义后的JS内容。 <script>alert('嘿嘿嘿')</script> 这就是html/template为我们做的事。
但是在某些场景下，我们如果相信用户输入的内容，不想转义的话，可以自行编写一个safe函数，手动返回一个template.HTML类型的内容。示例如下：
func xss(w http.ResponseWriter, r *http.Request){
tmpl,err := template.New("xss.tmpl").Funcs(template.FuncMap{
"safe": func(s string)template.HTML {
return template.HTML(s)
},
}).ParseFiles("./xss.tmpl")
if err != nil {
fmt.Println("create template failed, err:", err)
return
}
jsStr := `<script>alert('嘿嘿嘿')</script>`
err = tmpl.Execute(w, jsStr)
if err != nil {
fmt.Println(err)
}
}
这样我们只需要在模板文件不需要转义的内容后面使用我们定义好的safe函数就可以了。
{{ . | safe }}
