go语言Gin框架教程

本文作者：陈进坚
个人博客：https://jian1098.github.io
CSDN博客：https://blog.csdn.net/c_jian
简书：https://www.jianshu.com/u/8ba9ac5706b6
联系方式：[email protected]

下载使用

$ go get -u github.com/gin-gonic/gin

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

HTTP服务

func main() {
    
    
	router := gin.Default()
	//路由
	router.GET("/", func(c *gin.Context) {
    
    
		c.JSON(200, gin.H{
    
    
			"message": "hello gin",
		})
	})
	router.Run(":8080")
}

路由绑定

router.GET("/", index)表示用GET方式接收路由，如果路由是根目录，那么直接执行index控制器方法，index控制器必须含有gin.Context参数，也可以向上面一样将index控制器的内容写成匿名函数。

router.GET("/", index)

func index(c *gin.Context) {
    
    
	c.JSON(200, gin.H{
    
    
		"msg": "hello gin",
	})
}

路由分离

为了更好的管理路由，最好将路由和控制器分开不同的文件

在根目录下新建router.go

package gin

import (
	"github.com/gin-gonic/gin"
	"os"
	"path/filepath"
)

func initRouter() *gin.Engine {
    
    
	//路由
	router := gin.Default()
	router.GET("/", index)
	return router
}

在main方法中进行初始化

func main() {
    
    
	router := initRouter()
	router.Run(":8080")
}

此时目录结构如下

--src
	--gin
		--gin.go	 #用于存放控制器
		--router.go	 #用于存放路由
	--main.go

路由组

一些情况下，我们会有统一前缀的 url 的需求，典型的如 Api 接口版本号 /v1/something。Gin 可以使用 Group 方法统一归类到路由组中

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

  	// /v1/login 就会匹配到这个组
	v1 := router.Group("/v1")
	{
    
    
		v1.POST("/login", loginEndpoint)
		v1.POST("/submit", submitEndpoint)
		v1.POST("/read", readEndpoint)
	}
	
  	// 不用花括号包起来也是可以的。上面那种只是看起来会统一一点。看你个人喜好
	v2 := router.Group("/v2")
	v2.POST("/login", loginEndpoint)
	v2.POST("/submit", submitEndpoint)
	v2.POST("/read", readEndpoint)

	router.Run(":8080")
}

异步处理

goroutine 机制可以方便地实现异步处理

func main() {
    
    
	r := gin.Default()
	//1. 异步
	r.GET("/long_async", func(c *gin.Context) {
    
    
		// goroutine 中只能使用只读的上下文 c.Copy()
		cCp := c.Copy()
		go func() {
    
    
			time.Sleep(5 * time.Second)

			// 注意使用只读上下文
			log.Println("Done! in path " + cCp.Request.URL.Path)
		}()
	})
	//2. 同步
	r.GET("/long_sync", func(c *gin.Context) {
    
    
		time.Sleep(5 * time.Second)

		// 注意可以使用原始上下文
		log.Println("Done! in path " + c.Request.URL.Path)
	})

	// Listen and serve on 0.0.0.0:8080
	r.Run(":8080")
}

接收参数

接收GET参数

访问链接： http://localhost:8080/user?firstname=jian&lastname=chen

路由

router.GET("/user", hello)

控制器 (这里用的接收方法是Query)

func hello(c *gin.Context) {
    
    
	firstname := c.DefaultQuery("firstname", "Guest") //设置默认参数值
	lastname := c.Query("lastname")                   //获取参数值,c.Request.URL.Query().Get("lastname")的缩写
	c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
}

或者

访问链接：http://localhost:8080/user/jian/eat

路由 （参数名用:号标记）

router.GET("/user/:name/:action", user)

或者

router.GET("/user/:name/*action", user)

上面这个写法将会匹配/user/:name/开头的所有路由

控制器 (这里的接收方法是Param)

func user(c *gin.Context) {
    
    
	name := c.Param("name")
	action := c.Param("action")
	message := name + " is " + action
	c.String(http.StatusOK, message)
}

接收POST参数

访问链接：http://localhost:8080/post

路由

router.POST("/post", post)

控制器

func post(c *gin.Context) {
    
    
	name := c.PostForm("name")
	age := c.PostForm("age")
	fmt.Printf("name: %s, age: %s;", name, age)
}

文件上传

单文件上传

路由

router.POST("/upload", upload)

控制器

func upload(c *gin.Context) {
    
    
	file, _ := c.FormFile("file") //表单的文件name="file"
	//文件上传路径和文件名
	c.SaveUploadedFile(file, "./upload/"+file.Filename)
	c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename))
}

多文件上传

注意多文件上传表单<form>标签需要注明属性enctype="multipart/form-data" method="post"，<input>标签的name属性值必须相同，例如全部为name="file"

路由

router.POST("/multiupload", multiupload)

控制器

func multiupload(c *gin.Context) {
    
    
	// 文件上传大小限制 8 MB,在路由注册时设定
	//router.MaxMultipartMemory = 8 << 20
	formdata := c.Request.MultipartForm
	files := formdata.File["file"] //表单的文件name="file"
	for i, _ := range files {
    
    
		file, err := files[i].Open()
		defer file.Close()
		if err != nil {
    
    
			c.String(http.StatusBadRequest, fmt.Sprintf("get file err: %s", err.Error()))
			return
		}
		//文件上传路径和文件名
		out, err := os.Create("./upload/" + files[i].Filename)
		defer out.Close()
		if err != nil {
    
    
			c.String(http.StatusBadRequest, fmt.Sprintf("upload err: %s", err.Error()))
			return
		}
		_, err = io.Copy(out, file)
		if err != nil {
    
    
			c.String(http.StatusBadRequest, fmt.Sprintf("save file err: %s", err.Error()))
			return
		}
		c.String(http.StatusOK, "upload successful")
	}
}

视图模板

• 目录结构

  在根目录下新建templates文件夹用于存放html页面，为了便于管理在templates目录下再创建一个index文件夹存放与index控制器相关的页面，在index目录下新建index.html文件

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
    <h1>
        {
   
   {.title}}
    </h1>
</body>
</html>

此时目录结构如下

- src
	--gin
		--main.go
		--router.go
		--templates
			--index
				--index.html

加载视图

在初始化路由的位置加载所有视图模板，其中**表示各个控制器或路由组对应的视图目录，*表示该目录下所有文件

router := gin.Default()
//加载模板
router.LoadHTMLGlob(filepath.Join(os.Getenv("GOPATH"), "./src/gin/templates/**/*"))
router.GET("/", index)

控制器绑定视图

func index(c *gin.Context) {
    
    
	c.HTML(http.StatusOK, "index.html", gin.H{
    
    
		"title": "Main website",
	})
}

静态文件

网页开发离不开css和图片等静态资源文件，我们必须设置好路径才能正确访问，例如我的目录结构为(缩进表示二级目录)

--src
	--gin
		--static
			--css
				--index.css
		--templates
			--index
				--index.html
		--router.go
		--main.go

如果index.html文件需要引入index.css文件，则在路由申请的地方声明

//加载模板
router.LoadHTMLGlob(filepath.Join(os.Getenv("GOPATH"), "./src/gin/templates/**/*"))
//加载静态文件
router.Static("/static", filepath.Join(os.Getenv("GOPATH"), "./src/gin/static"))

然后index.css文件中这样调用就可以了，其他静态资源用法类似

<link rel="stylesheet" href="/static/css/index.css">

参数传递

在控制器传递参数

c.HTML(http.StatusOK, "index.html", gin.H{
    
    
	"title": "Main website",
})

在视图渲染参数

<h1>
	{
   
   {.title}}
</h1>

重定向

r.GET("/redirect", func(c *gin.Context) {
    
    
	//支持内部和外部的重定向
    c.Redirect(http.StatusMovedPermanently, "http://www.baidu.com/")
})

中间件

使用中间件

router := gin.Default()
router.Use(middleware.IPLimit()) //使用自定义中间件：IP验证

中间件实现

package middleware

import (
	"core"
	"github.com/gin-gonic/gin"
	"net/http"
	"strings"
)

//访问ip限制
func IPLimit() gin.HandlerFunc {
    
    
	return func(c *gin.Context) {
    
    
		ip := c.ClientIP()
		ipList := strings.Split(core.Config["allow_ip"], "|")
		flag := false
		for i := 0; i < len(ipList); i++ {
    
    
			if ip == ipList[i] {
    
    
				flag = true
				break
			}
		}

		if !flag {
    
    
			c.Abort()
			c.JSON(http.StatusUnauthorized, gin.H{
    
    
				"code": 0,
				"msg":  "IP " + ip + " 没有访问权限",
				"data": nil})
			return // return也是可以省略的，执行了abort操作，会内置在中间件defer前，return，写出来也只是解答为什么Abort()之后，还能执行返回JSON数据
		} 
	}
}

数据绑定和验证

使用 c.ShouldBind方法，可以将参数自动绑定到 struct，该方法是会检查 Url 查询字符串和 POST 的数据，而且会根据 content-type类型，优先匹配JSON或者 XML,之后才是 Form。数据绑定可以用来做数据验证，例如

路由

router.POST("/binding", binding)

控制器

//数据结构体，username为表单字段，required表示必须参数，可选的话binding留空即可
type Login struct {
    
    
	Username string `form:"username" binding:"required"`
	Password string `form:"password" binding:"required"`
}

//控制器
func binding(c *gin.Context) {
    
    
	var form Login
	// 验证数据并绑定
	if err := c.ShouldBind(&form); err == nil {
    
    
		if form.Username == "manu" && form.Password == "123" {
    
    
			c.JSON(http.StatusOK, gin.H{
    
    "msg": "Login successfully"})
		} else {
    
    
			c.JSON(http.StatusUnauthorized, gin.H{
    
    "msg": "username or password error"})
		}
	} else {
    
    
		c.JSON(http.StatusBadRequest, gin.H{
    
    "error": err.Error()})
	}
}

• 当没有接收到参数时返回

  {
        
        
      "error": "Key: 'Login.Username' Error:Field validation for 'Username' failed on the 'required' tag"
  }
  

• 当参数错误时返回

  {
        
        
      "msg": "username or password error"
  }
  

• 当接收到参数且正确时放回

  {
        
        
      "msg": "Login successfully"
  }
  

  不用在接收参数时用if逐个进行验证，除了binding:"required"属性外还有更多的校验规则，可以参考 https://godoc.org/gopkg.in/go-playground/validator.v8#hdr-Baked_In_Validators_and_Tags

日志

自带日志

Gin日志默认只在控制台显示，如果要写入文件需要在main方法中声明

gin.DisableConsoleColor()	//关掉控制台颜色,可省略
f, _ := os.Create("gin.log")	//日志文件
//gin.DefaultWriter = io.MultiWriter(f)	//将日志写入文件
gin.DefaultWriter = io.MultiWriter(f, os.Stdout) //将日志写入文件同时在控制台输出

Logrus 日志库

Gin自带的日志系统只支持简单的功能，需要更强大的功能还需要用到第三方日志库，这里选择github上面star最多的Logrus。

下载

go get github.com/sirupsen/logrus

使用

package main

import (
	log "github.com/Sirupsen/logrus"
)

func main() {
    
    
	log.Trace("Something very low level.")
    log.Debug("Useful debugging information.")
    log.Info("Something noteworthy happened!")
    log.Warn("You should probably take a look at this.")
    log.Error("Something failed but I'm not quitting.")
    // Calls os.Exit(1) after logging
    log.Fatal("Bye.")
    // Calls panic() after logging
    log.Panic("I'm bailing.")
}

数据库

Gin框架没有自带的数据库封装，导入的数据库驱动由开发使用的数据库类型决定,例如开发使用mysql就直接import _ "github.com/go-sql-driver/mysql"；但是访问数据库都是直接用写 sql，取出结果然后自己拼成对象，使用上面不是很方便，可读性也不好。这里使用目前github上star数量最多的https://github.com/jinzhu/gorm

gorm的详细教程参考http://gorm.book.jasperxu.com/models.html#md

下载

go get -u github.com/jinzhu/gorm

连接mysql

package gin

import (
	"github.com/jinzhu/gorm"
)

func Index() {
    
    
	db, err := gorm.Open("mysql", "root:root@(127.0.0.1:3306)/test?charset=utf8&parseTime=True&loc=Local")
	if err != nil {
    
    
		panic(err)
	}
	defer db.Close()
}

数据表

import (
	"github.com/jinzhu/gorm"
	_ "github.com/jinzhu/gorm/dialects/mysql"
	"time"
)

//定义数据表模型
type User struct {
    
    
	Id      uint      `gorm:"primary_key;AUTO_INCREMENT"` // 自增主键
	Name    string    `gorm:"size:255"`                   // string默认长度为255, 使用这种tag重设。
	Address string    `gorm:"not null;unique"`            // 设置字段为非空并唯一
	Addtime time.Time `gorm:"default:'2019-03-11 13:19:40'"` //默认值
}

func Index() {
    
    
	//连接数据库
	db, err := gorm.Open("mysql", "root:root@(127.0.0.1:3306)/test?charset=utf8&parseTime=True&loc=Local")
	if err != nil {
    
    
		panic(err)
	}
	//关闭数据库
	defer db.Close()

	//设置默认表名前缀
	gorm.DefaultTableNameHandler = func(db *gorm.DB, defaultTableName string) string {
    
    
		return "test_" + defaultTableName
	}

	//创建表
	if !db.HasTable(&User{
    
    }) {
    
     //检查表是否存在
		if err := db.Set("gorm:table_options", "ENGINE=InnoDB DEFAULT CHARSET=utf8").CreateTable(&User{
    
    }).Error; err != nil {
    
    
			panic(err)
		}
	}

	// 删除表users
	db.DropTable("test_users")
		
	// 修改模型`User`的"addtime"列类型
    db.Model(&User{
    
    }).ModifyColumn("addtime", "text")

    // 删除模型`User`的addtime列
    db.Model(&User{
    
    }).DropColumn("addtime")
    
    // 为`name`列添加索引`idx_user_name`
	db.Model(&User{
    
    }).AddIndex("idx_user_name", "name")
	
	// 删除索引
	db.Model(&User{
    
    }).RemoveIndex("idx_user_name")
}

添加记录

//添加记录
user := User{
    
    Name: "jian", Address: "1234", Addtime: time.Now()}
if err := db.Create(&user).Error; err != nil {
    
    
panic(err)
}

查询数据

无条件查询

// 获取第一条记录，按主键排序
db.First(&user)
// SELECT * FROM users ORDER BY id LIMIT 1;

// 获取最后一条记录，按主键排序
db.Last(&user)
// SELECT * FROM users ORDER BY id DESC LIMIT 1;

// 获取所有记录
db.Find(&users)
// SELECT * FROM users;

// 使用主键获取记录
db.First(&user, 10)
// SELECT * FROM users WHERE id = 10;

Where查询条件

user := User{
    
    }

// 获取第一个匹配记录
db.Where("name = ?", "jinzhu").First(&user)
fmt.Println(user.Name)	//读取数据
// SELECT * FROM users WHERE name = 'jinzhu' limit 1;

// 获取最后一条记录，按主键排序
db.Last(&user)
// SELECT * FROM users ORDER BY id DESC LIMIT 1;

// 获取所有匹配记录
db.Where("name = ?", "jinzhu").Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu';

db.Where("name <> ?", "jinzhu").Find(&users)

// IN
db.Where("name in (?)", []string{
    
    "jinzhu", "jinzhu 2"}).Find(&users)

// LIKE
db.Where("name LIKE ?", "%jin%").Find(&users)

// AND
db.Where("name = ? AND age >= ?", "jinzhu", "22").Find(&users)

// Time
db.Where("updated_at > ?", lastWeek).Find(&users)

db.Where("created_at BETWEEN ? AND ?", lastWeek, today).Find(&users)

// Struct
db.Where(&User{
    
    Name: "jinzhu", Age: 20}).First(&user)
 SELECT * FROM users WHERE name = "jinzhu" AND age = 20 LIMIT 1;

// Map
db.Where(map[string]interface{
    
    }{
    
    "name": "jinzhu", "age": 20}).Find(&users)
// SELECT * FROM users WHERE name = "jinzhu" AND age = 20;

// 主键的Slice
db.Where([]int64{
    
    20, 21, 22}).Find(&users)
// SELECT * FROM users WHERE id IN (20, 21, 22);

Not条件查询

db.Not("name", "jinzhu").First(&user)
// SELECT * FROM users WHERE name <> "jinzhu" LIMIT 1;

// Not In
db.Not("name", []string{
    
    "jinzhu", "jinzhu 2"}).Find(&users)
// SELECT * FROM users WHERE name NOT IN ("jinzhu", "jinzhu 2");

// Not In slice of primary keys
db.Not([]int64{
    
    1,2,3}).First(&user)
// SELECT * FROM users WHERE id NOT IN (1,2,3);

db.Not([]int64{
    
    }).First(&user)
// SELECT * FROM users;

// Plain SQL
db.Not("name = ?", "jinzhu").First(&user)
// SELECT * FROM users WHERE NOT(name = "jinzhu");

// Struct
db.Not(User{
    
    Name: "jinzhu"}).First(&user)
// SELECT * FROM users WHERE name <> "jinzhu";

Or条件查询

db.Where("role = ?", "admin").Or("role = ?", "super_admin").Find(&users)
// SELECT * FROM users WHERE role = 'admin' OR role = 'super_admin';

// Struct
db.Where("name = 'jinzhu'").Or(User{
    
    Name: "jinzhu 2"}).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' OR name = 'jinzhu 2';

// Map
db.Where("name = 'jinzhu'").Or(map[string]interface{
    
    }{
    
    "name": "jinzhu 2"}).Find(&users)

指定字段和表

db.Select("name, age").Find(&users)
// SELECT name, age FROM users;
db.Table("users").Select("COALESCE(age,?)", 42).Rows()
// SELECT COALESCE(age,'42') FROM users;

Order条件查询

db.Order("age desc, name").Find(&users)
// SELECT * FROM users ORDER BY age desc, name;

Limit条件查询

db.Limit(3).Find(&users)
// SELECT * FROM users LIMIT 3;

Offset条件查询

指定在开始返回记录之前要跳过的记录数

db.Offset(3).Find(&users)
// SELECT * FROM users OFFSET 3;

Count条件查询

db.Where("name = ?", "jinzhu").Or("name = ?", "jinzhu 2").Find(&users).Count(&count)
// SELECT * from USERS WHERE name = 'jinzhu' OR name = 'jinzhu 2'; (users)

多条件查询

db.Where("role = ?", "admin").Or("role = ?", "super_admin").Not("name = ?", "jinzhu").Find(&users)
db.Where("name <> ?","jinzhu").Where("age >= ? and role <> ?",20,"admin").Find(&users)

更新数据

 // 使用组合条件更新单个属性
db.Model(&user).Where("active = ?", true).Update("name", "hello")
// UPDATE users SET name='hello', updated_at='2013-11-17 21:34:10' WHERE id=111 AND active=true;

// 使用`map`更新多个属性，只会更新这些更改的字段
db.Model(&user).Updates(map[string]interface{
    
    }{
    
    "name": "hello", "age": 18, "actived": false})

// 使用`struct`更新多个属性，只会更新这些更改的和非空白字段
db.Model(&user).Updates(User{
    
    Name: "hello", Age: 18})

删除数据

db.Where("email LIKE ?", "%jinzhu%").Delete(Email{
    
    })
// DELETE from emails where email LIKE "%jinhu%";

db.Delete(Email{
    
    }, "email LIKE ?", "%jinzhu%")
// DELETE from emails where email LIKE "%jinhu%";

执行原生SQL语句

Scan()是将结果扫描到另一个结构中。

db.Exec("DROP TABLE users;")
db.Exec("UPDATE orders SET shipped_at=? WHERE id IN (?)", time.Now, []int64{
    
    11,22,33})

db.Raw("SELECT name, age FROM users WHERE name = ?", 3).Scan(&result)
row := db.Table("users").Where("name = ?", "jinzhu").Select("name, age").Row() // (*sql.Row)
row.Scan(&name, &age)

rows, err := db.Model(&User{
    
    }).Where("name = ?", "jinzhu").Select("name, age, email").Rows() // (*sql.Rows, error)
defer rows.Close()
for rows.Next() {
    
    
    ...
    rows.Scan(&name, &age, &email)
    ...
}

连接池

db.DB().SetMaxIdleConns(10)
db.DB().SetMaxOpenConns(100)

锁行

注意：加行锁的表必须是InnoDB并且要加索引，否则无效；语句必须在事务里面，必须提交或回滚

// 为Select语句添加扩展SQL选项
db.Set("gorm:query_option", "FOR UPDATE").First(&user, 10)
// SELECT * FROM users WHERE id = 10 FOR UPDATE;

锁表

db.Exec("LOCK TABLES real_table WRITE, insert_table WRITE;")  //锁定real_table和insert_table表
UNLOCK TABLES;	//解锁

日志

// 启用Logger，显示详细日志
db.LogMode(true)

// 禁用日志记录器，不显示任何日志
db.LogMode(false)

// 调试单个操作，显示此操作的详细日志
db.Debug().Where("name = ?", "jinzhu").First(&User{
    
    })

//自定义日志
db.SetLogger(gorm.Logger{
    
    revel.TRACE})
db.SetLogger(log.New(os.Stdout, "\r\n", 0))

事务

// 开始事务
tx := db.Begin()
// 注意，一旦你在一个事务中，使用tx作为数据库句柄，而不再是上面的db
// 在事务中做一些数据库操作（从这一点使用'tx'，而不是'db'）
tx.Create(...)

// ...

// 发生错误时回滚事务
tx.Rollback()

// 提交事务
tx.Commit()