基于gin的golang web开发:实现用户登录

前文分别介绍过了Restygin-jwt两个包,Resty是一个HTTP和REST客户端,gin-jwt是一个实现了JWT的Gin中间件。本文将使用这两个包来实现一个简单的用户登录功能。

环境准备

实现登录功能之前要提前准备一个用于查询用户是否存在的服务。访问服务http://127.0.0.1:18081/users?username=root时返回用户root的相关信息

1
2
3
4
5
6
7
8
9
10
11
12
{
"total": 1,
"data": [
{
"id": 1,
"username": "root",
"password": "CGUx1FN++xS+4wNDFeN6DA==",
"nickname": "超级管理员",
"mobile": "13323232323"
}
]
}

返回结果中password字段AES加密后的结果。当参数username传入其他字符串时返回null

1
2
3
4
{
"total": 0,
"data": null
}

好了准备工作到此结束,下面来看一下如何实现登录功能。

实现认证

首先实现调用查询用户服务的方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func FindUser(userName string) (user sysUser.SysUser, err error) {
client := resty.New().SetRetryCount(3)
resp, err := client.R().
SetQueryParams(map[string]string{
"username": userName,
}).
SetResult(&PagedUser{}).
Get("http://127.0.0.1:18081/users")
if err != nil {
log.Panicln("FindUser err: ", err.Error())
}
response := resp.Result().(*PagedUser)
if response.Total == 1 {
user = response.Data[0]
return
}
err = errors.New("用户不存在")
return
}

这里我们创建了一个Resty客户端,并设置了3次重试,依照服务的要求传入username参数,然后通过Total值判断用户是否存在,用户存在的话返回用户信息,否则返回错误。

接下来我们实现有关jwt验证的部分。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
var identityKey = "id"

type login struct {
Username string `form:"username" json:"username" binding:"required"`
Password string `form:"password" json:"password" binding:"required"`
}

type User struct {
Id int
UserName string
NickName string
}

func JwtMiddleware() (authMiddleware *jwt.GinJWTMiddleware, err error) {
authMiddleware, err = jwt.New(&jwt.GinJWTMiddleware{
Realm: "test zone",
Key: []byte("secret key"),
Timeout: time.Hour,
MaxRefresh: time.Hour,
IdentityKey: identityKey,
PayloadFunc: func(data interface{}) jwt.MapClaims {
if v, ok := data.(*User); ok {
return jwt.MapClaims{
identityKey: v.UserName,
}
}
return jwt.MapClaims{}
},
IdentityHandler: func(c *gin.Context) interface{} {
claims := jwt.ExtractClaims(c)
return &User{
UserName: claims[identityKey].(string),
}
},
Authenticator: func(c *gin.Context) (interface{}, error) {
var loginVals login
if err := c.ShouldBind(&loginVals); err != nil {
return "", jwt.ErrMissingLoginValues
}
userID := loginVals.Username
password := loginVals.Password

user, err := http_service.FindUser(userID)
if err != nil {
return nil, jwt.ErrFailedAuthentication
}

encrypt := utils.PasswordEncrypt(password, userID)
if encrypt != user.Password.String {
return nil, jwt.ErrFailedAuthentication
}

return &User{
Id: user.Id,
UserName: user.Username.String,
NickName: user.Nickname.String,
}, nil
},
Authorizator: func(data interface{}, c *gin.Context) bool {
if v, ok := data.(*User); ok && v.UserName == "admin" {
return true
}

return false
},
Unauthorized: func(c *gin.Context, code int, message string) {
c.JSON(code, gin.H{
"code": code,
"message": message,
})
},
TokenLookup: "header: Authorization, query: token, cookie: jwt_middleware",
TokenHeadName: "Bearer",
TimeFunc: time.Now,
})
return
}

以上代码在基于gin的golang web开发:认证利器jwt一文中有详细的解释,我们重点来看一下用户验证的部分:Authenticator

方法ShouldBind对参数进行模型绑定,不熟悉模型绑定的话可以查看前文基于gin的golang web开发:模型绑定。然后调用FindUser方法检查用户是否存在,如果用户存在的话还需要验证一下用户密码是否正确。全部验证通过返回User结构体,进入gin-jwt的后续流程。

最后一步在Gin中增加用户登录路由。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
func main() {
r := gin.Default()

authMiddleware, err := JwtMiddleware()
if err != nil {
log.Fatal("JWT Error:" + err.Error())
}

errInit := authMiddleware.MiddlewareInit()

if errInit != nil {
log.Fatal("authMiddleware.MiddlewareInit() Error:" + errInit.Error())
}

r.POST("/login", authMiddleware.LoginHandler)

r.Run(":8090")
}

大功告成,现在调用/login接口,并提供正确的用户名和密码,不出意外的话会得到一个成功的JSON,里面包含了验证通过的JWT。

基于gin的golang web开发:服务间调用

微服务开发中服务间调用的主流方式有两种HTTP、RPC,HTTP相对来说比较简单。本文将使用 Resty 包来实现基于HTTP的微服务调用。

Resty简介

是一个简单的HTTP和REST客户端工具包,简单是指使用上非常简单。Resty在使用简单的基础上提供了非常强大的功能,涉及到HTTP客户端的方方面面,可以满足我们日常开发使用的大部分需求。
1
2

go get安装

go get github.com/go-resty/resty/v2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

### 使用Resty提交HTTP请求
```golang
client := resty.New()

resp, err := client.R().
Get("https://httpbin.org/get")

resp, err := client.R().
SetQueryParams(map[string]string{
"page_no": "1",
"limit": "20",
"sort":"name",
"order": "asc",
"random":strconv.FormatInt(time.Now().Unix(), 10),
}).
SetHeader("Accept", "application/json").
SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
Get("/search_result")

resp, err := client.R().
SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more").
SetHeader("Accept", "application/json").
SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
Get("/show_product")

resp, err := client.R().
SetResult(AuthToken{}).
ForceContentType("application/json").
Get("v2/alpine/manifests/latest")

以上代码演示了HTTP GET请求,Resty提供SetQueryParams方法设置请求的查询字符串,使用SetQueryParams
方法我们可以动态的修改请求参数。SetQueryString也可以设置请求的查询字符串,如果参数中有变量的话,需要拼接字符串。SetHeader设置请求的HTTP头,以上代码设置了Accept属性。SetAuthToken设置授权信息,本质上还是设置HTTP头,以上例子中HTTP头会附加Authorization: Bearer BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F授权属性。SetResult设置返回值的类型,Resty自动解析json通过resp.Result().(*AuthToken)获取。

下面来看一下POST请求

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
client := resty.New()

resp, err := client.R().
SetBody(User{Username: "testuser", Password: "testpass"}).
SetResult(&AuthSuccess{}).
SetError(&AuthError{}).
Post("https://myapp.com/login")

resp, err := client.R().
SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
SetResult(&AuthSuccess{}).
SetError(&AuthError{}).
Post("https://myapp.com/login")

resp, err := client.R().
SetHeader("Content-Type", "application/json").
SetBody(`{"username":"testuser", "password":"testpass"}`).
SetResult(&AuthSuccess{}).
Post("https://myapp.com/login")

resp, err := client.R().
SetHeader("Content-Type", "application/json").
SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
SetResult(&AuthSuccess{}).
Post("https://myapp.com/login")

POST请求的代码和GET请求类似,只是最后调用了Post方法。POST请求可以附带BODY,代码中使用SetBody方法设置POST BODY。SetBody参数类型为结构体或map[string]interface{}时,Resty自动附加HTTP头Content-Type: application/json,当参数为string或[]byte类型时由于很难推断内容的类型,所以需要手动设置Content-Type请求头。SetBody还支持其他类型的参数,例如上传文件时可能会用到的io.Reader。SetError设置HTTP状态码为4XX或5XX等错误时返回的数据类型。

也提供了发起其他请求的方法,发起```PUT```请求和发起```POST```请求代码上只需要把最后的```Post```改成```Put```方法。其他没有差别,一样可以调用```SetBody```、```SetError```等方法。代码如下
1
2
3
4
5
6
7
8
9
10
11
12
13
```golang
client := resty.New()

resp, err := client.R().
SetBody(Article{
Title: "go-resty",
Content: "This is my article content, oh ya!",
Author: "Jeevanandam M",
Tags: []string{"article", "sample", "resty"},
}).
SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
SetError(&Error{}).
Put("https://myapp.com/article/1234")

PATCH,DELETE,HEAD,OPTIONS请求也是一样的,Resty为我们提供了一致的方式发起不同请求。

高级应用

代理

使用Resty作为HTTP客户端使用的话,添加代理似乎是一个常见的需求。Resty提供了SetProxy方法为请求添加代理,还可以调用RemoveProxy移除代理。代码如下:

1
2
3
4
5
client := resty.New()

client.SetProxy("http://proxyserver:8888")

client.RemoveProxy()

重试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
client := resty.New()

client.
SetRetryCount(3).
SetRetryWaitTime(5 * time.Second).
SetRetryMaxWaitTime(20 * time.Second).
SetRetryAfter(func(client *resty.Client, resp *resty.Response) (time.Duration, error) {
return 0, errors.New("quota exceeded")
})

client.AddRetryCondition(
func(r *resty.Response) (bool, error) {
return r.StatusCode() == http.StatusTooManyRequests
},
)

由于网络抖动带来的接口稳定性的问题Resty提供了重试功能来解决。以上代码我们可以看到SetRetryCount设置重试次数,SetRetryWaitTimeSetRetryMaxWaitTime设置等待时间。SetRetryAfter是一个重试后的回调方法。除此之外还可以调用AddRetryCondition设置重试的条件。

中间件

提供了和Gin类似的中间件特性。```OnBeforeRequest```和```OnAfterResponse```回调方法,可以在请求之前和响应之后加入自定义逻辑。参数包含了```resty.Client```和当前请求的```resty.Request```对象。成功时返回```nil```,失败时返回```error```对象。
1
2
3
4
5
6
7
8
9
10
11
12
13

```golang
client := resty.New()

client.OnBeforeRequest(func(c *resty.Client, req *resty.Request) error {

return nil
})

client.OnAfterResponse(func(c *resty.Client, resp *resty.Response) error {

return nil
})

基于gin的golang web开发:Gin技术拾遗

本文是对前几篇文章的一些补充,主要包含两部分:单元测试和实际项目中使用路由的小问题。

拾遗1:单元测试

Golang单元测试要求代码文件以_test结尾,单元测试方法以Test开头,参数为*testing.T类型。以下是一个计算hash值的工具包和对应的单元测试。

hashUtils.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package utils

import (
"crypto/md5"
"crypto/sha1"
"fmt"
)

func Md5(str string) string {
data := []byte(str)
has := md5.Sum(data)
return fmt.Sprintf("%X", has)
}

func SHA1(data []byte) []byte {
h := sha1.New()
h.Write(data)
return h.Sum(nil)
}

hashUtils_test.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package utils

import (
"fmt"
"testing"
)

func TestMd5(t *testing.T) {
content := "123456"
md5 := Md5(content)

if "E10ADC3949BA59ABBE56E057F20F883E" != md5 {
t.Errorf("md5 failed")
}
}

func TestSHA1(t *testing.T) {
content := "123456"
sha1 := fmt.Sprintf("%x", SHA1([]byte(content)))

if "7c4a8d09ca3762af61e59520943dc26494f8941b" != sha1 {
t.Errorf("sha1 failed")
}
}

除了测试这种逻辑代码我们还需要测试HTTP的请求响应。Gin推荐使用net/http/httptest测试HTTP相关的代码。

启动一个Gin服务器main.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
package main

func setupRouter() *gin.Engine {
r := gin.Default()
r.GET("/ping", func(c *gin.Context) {
c.String(200, "pong")
})
return r
}

func main() {
r := setupRouter()
r.Run(":8080")
}

单元测试main_test.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
package main

import (
"net/http"
"net/http/httptest"
"testing"

"github.com/stretchr/testify/assert"
)

func TestPingRoute(t *testing.T) {
router := setupRouter()

w := httptest.NewRecorder()
req, _ := http.NewRequest("GET", "/ping", nil)
router.ServeHTTP(w, req)

assert.Equal(t, 200, w.Code)
assert.Equal(t, "pong", w.Body.String())
}

拾遗2:路由

先看代码

1
2
3
4
userRouter := router.Group(`users`)
{
userRouter.GET(`/`, userHandler.UserList)
}

我们声明了路由/users/,这是一个Web Api,传入参数的url大概是这样的/users/?pageIndex=1&pageSize=10。用户访问/users?pageIndex=1&pageSize=10时也能正常返回数据,这是因为Gin帮我们做了一次301跳转,问题就出在这里。我们的路由是Web Api用户可能是JS前端,也可能是其他的业务系统。如果用户不支持301跳转呢?

其实我们只要在增加一个空路径路由就可以解决问题。

1
2
3
4
5
userRouter := router.Group(`users`)
{
userRouter.GET(``, userHandler.UserList)
userRouter.GET(`/`, userHandler.UserList)
}

现在不管用户访问/users/?pageIndex=1&pageSize=10还是访问/users?pageIndex=1&pageSize=10都会得到正确的结果。

基于gin的golang web开发:认证利器jwt

JSON Web Token(JWT)是一种很流行的跨域认证解决方案,JWT基于JSON可以在进行验证的同时附带身份信息,对于前后端分离项目很有帮助。

1
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

JWT由三部分组成,每个部分之间用点.隔开,分别称为HEADER、PAYLOAD和VERIFY SIGNATURE。HEADER和PAYLOAD经过base64解码后为JSON明文。

  1. HEADER包含两个字段,alg指明JWT的签名算法,typ固定为JWT
  2. PAYLOAD中包含JWT的声明信息,标准中定义了isssubaud等声明字段,如果标准声明不够用的话,我们还可以增加自定义声明。要注意两点,第一PAYLOAD只是经过base64编码,几乎就等于是明文,不要包含敏感信息。第二不要在PAYLOAD中放入过多的信息,因为验证通过以后每一个请求都要包含JWT,信息太多的话会造成一些没有必要的资源浪费。
  3. VERIFY SIGNATURE为使用HEADER中指定的算法生成的签名。例如alg:HS256签名算法HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),密钥)

了解完JWT的基本原理之后,我们来看一下在gin中是怎么使用JWT的。

引入gin-jwt中间件

在Gin中使用jwt有个开源项目gin-jwt,这项目几乎包含了我们要用到的一切。例如定义PAYLOAD中的声明、授权验证的方法、是否使用COOKIE等等。下面来看一下官网给出的例子。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
package main

import (
"log"
"net/http"
"os"
"time"

jwt "github.com/appleboy/gin-jwt/v2"
"github.com/gin-gonic/gin"
)

type login struct {
Username string `form:"username" json:"username" binding:"required"`
Password string `form:"password" json:"password" binding:"required"`
}

var identityKey = "id"

func helloHandler(c *gin.Context) {
claims := jwt.ExtractClaims(c)
user, _ := c.Get(identityKey)
c.JSON(200, gin.H{
"userID": claims[identityKey],
"userName": user.(*User).UserName,
"text": "Hello World.",
})
}

type User struct {
UserName string
FirstName string
LastName string
}

func main() {
port := os.Getenv("PORT")
r := gin.New()
r.Use(gin.Logger())
r.Use(gin.Recovery())

if port == "" {
port = "8000"
}

authMiddleware, err := jwt.New(&jwt.GinJWTMiddleware{
Realm: "test zone",
Key: []byte("secret key"),
Timeout: time.Hour,
MaxRefresh: time.Hour,
IdentityKey: identityKey,
PayloadFunc: func(data interface{}) jwt.MapClaims {
if v, ok := data.(*User); ok {
return jwt.MapClaims{
identityKey: v.UserName,
}
}
return jwt.MapClaims{}
},
IdentityHandler: func(c *gin.Context) interface{} {
claims := jwt.ExtractClaims(c)
return &User{
UserName: claims[identityKey].(string),
}
},
Authenticator: func(c *gin.Context) (interface{}, error) {
var loginVals login
if err := c.ShouldBind(&loginVals); err != nil {
return "", jwt.ErrMissingLoginValues
}
userID := loginVals.Username
password := loginVals.Password

if (userID == "admin" && password == "admin") || (userID == "test" && password == "test") {
return &User{
UserName: userID,
LastName: "Bo-Yi",
FirstName: "Wu",
}, nil
}

return nil, jwt.ErrFailedAuthentication
},
Authorizator: func(data interface{}, c *gin.Context) bool {
if v, ok := data.(*User); ok && v.UserName == "admin" {
return true
}

return false
},
Unauthorized: func(c *gin.Context, code int, message string) {
c.JSON(code, gin.H{
"code": code,
"message": message,
})
},

TokenLookup: "header: Authorization, query: token, cookie: jwt",
TokenHeadName: "Bearer",
TimeFunc: time.Now,
})

if err != nil {
log.Fatal("JWT Error:" + err.Error())
}

errInit := authMiddleware.MiddlewareInit()

if errInit != nil {
log.Fatal("authMiddleware.MiddlewareInit() Error:" + errInit.Error())
}

r.POST("/login", authMiddleware.LoginHandler)

r.NoRoute(authMiddleware.MiddlewareFunc(), func(c *gin.Context) {
claims := jwt.ExtractClaims(c)
log.Printf("NoRoute claims: %#v\n", claims)
c.JSON(404, gin.H{"code": "PAGE_NOT_FOUND", "message": "Page not found"})
})

auth := r.Group("/auth")
auth.GET("/refresh_token", authMiddleware.RefreshHandler)
auth.Use(authMiddleware.MiddlewareFunc())
{
auth.GET("/hello", helloHandler)
}

if err := http.ListenAndServe(":"+port, r); err != nil {
log.Fatal(err)
}
}

我们可以看到jwt.GinJWTMiddleware用于声明一个中间件。PayloadFunc方法中给默认的PAYLOAD增加了id字段,取值为UserName。Authenticator认证器,我们可以在这里验证用户身份,参数为*gin.Context,所以在这里我们可以像写Gin Handler那样获取到Http请求中的各种内容。Authorizator授权器可以判断判断当前JWT是否有权限继续访问。当然还可以设置像过期时间,密钥,是否设置COOKIE等其他选项。

登录Handler

以上例子中配置了路由r.POST("/login", authMiddleware.LoginHandler)下面我们来看一下登录过程是怎样的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
func (mw *GinJWTMiddleware) LoginHandler(c *gin.Context) {
if mw.Authenticator == nil {
mw.unauthorized(c, http.StatusInternalServerError, mw.HTTPStatusMessageFunc(ErrMissingAuthenticatorFunc, c))
return
}

data, err := mw.Authenticator(c)

if err != nil {
mw.unauthorized(c, http.StatusUnauthorized, mw.HTTPStatusMessageFunc(err, c))
return
}

// Create the token
token := jwt.New(jwt.GetSigningMethod(mw.SigningAlgorithm))
claims := token.Claims.(jwt.MapClaims)

if mw.PayloadFunc != nil {
for key, value := range mw.PayloadFunc(data) {
claims[key] = value
}
}

expire := mw.TimeFunc().Add(mw.Timeout)
claims["exp"] = expire.Unix()
claims["orig_iat"] = mw.TimeFunc().Unix()
tokenString, err := mw.signedString(token)

if err != nil {
mw.unauthorized(c, http.StatusUnauthorized, mw.HTTPStatusMessageFunc(ErrFailedTokenCreation, c))
return
}

// set cookie
if mw.SendCookie {
expireCookie := mw.TimeFunc().Add(mw.CookieMaxAge)
maxage := int(expireCookie.Unix() - mw.TimeFunc().Unix())

if mw.CookieSameSite != 0 {
c.SetSameSite(mw.CookieSameSite)
}

c.SetCookie(
mw.CookieName,
tokenString,
maxage,
"/",
mw.CookieDomain,
mw.SecureCookie,
mw.CookieHTTPOnly,
)
}

mw.LoginResponse(c, http.StatusOK, tokenString, expire)
}

LoginHandler整体逻辑还是比较简单的,检查并调用前面设置的Authenticator方法,验证成功的话生成一个新的JWT,调用PayloadFunc方法设置PAYLOAD的自定义字段,根据SendCookie判断是否需要在HTTP中设置COOKIE,最后调用LoginResponse方法设置返回值。

使用中间件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

```golang
func (mw *GinJWTMiddleware) MiddlewareFunc() gin.HandlerFunc {
return func(c *gin.Context) {
mw.middlewareImpl(c)
}
}

func (mw *GinJWTMiddleware) middlewareImpl(c *gin.Context) {
claims, err := mw.GetClaimsFromJWT(c)
if err != nil {
mw.unauthorized(c, http.StatusUnauthorized, mw.HTTPStatusMessageFunc(err, c))
return
}

if claims["exp"] == nil {
mw.unauthorized(c, http.StatusBadRequest, mw.HTTPStatusMessageFunc(ErrMissingExpField, c))
return
}

if _, ok := claims["exp"].(float64); !ok {
mw.unauthorized(c, http.StatusBadRequest, mw.HTTPStatusMessageFunc(ErrWrongFormatOfExp, c))
return
}

if int64(claims["exp"].(float64)) < mw.TimeFunc().Unix() {
mw.unauthorized(c, http.StatusUnauthorized, mw.HTTPStatusMessageFunc(ErrExpiredToken, c))
return
}

c.Set("JWT_PAYLOAD", claims)
identity := mw.IdentityHandler(c)

if identity != nil {
c.Set(mw.IdentityKey, identity)
}

if !mw.Authorizator(identity, c) {
mw.unauthorized(c, http.StatusForbidden, mw.HTTPStatusMessageFunc(ErrForbidden, c))
return
}

c.Next()
}

GetClaimsFromJWT方法在当前上下文中获取JWT,失败的话返回未授权。接着会判断JWT是否过期,最后前面设置的Authorizator方法验证是否有权限继续访问。

基于gin的golang web开发:docker

Golang天生适合运行在docker容器中,这得益于:Golang的静态编译,当在编译的时候关闭cgo的时候,可以完全不依赖系统环境。

一些基础

测试容器时我们经常需要进入容器查看运行情况,以下命令启动一个centos容器并进入bash交互环境。

1
docker run -it --rm centos bash

-it 组合参数-i: 以交互模式运行容器,-t: 为容器重新分配一个伪输入终端。

–rm 在容器退出时就能够自动清理容器。

alpine镜像中没有bash,启动容器并进入终端的命令为

1
docker run -it --rm alpine sh

启动一个golang编译环境并进入bash

1
docker run -it -p 8081:8081 -v ./project:/app --env --env GO111MODULE=on --env GOPROXY=https://goproxy.cn,direct --rm  --privileged golang:1.15 bash

-v ./project:/app 绑定本机项目的路径映射到容器中/app

–env 设置环境变量,由于我们网络环境的问题直接使用golang容器会很慢所以设置了GOPROXY=https://goproxy.cn,direct。

–privileged 容器内的root拥有真正的root权限,否则容器内root只是外部的一个普通用户。

-p 8081:8001 将本机的8081端口映射到容器的8001端口

docker打包项目

为了方便演示docker,我们准备一个简单Gin项目。要注意r.Run不能绑定127.0.0.1。

1
2
3
4
5
6
7
8
9
10
11
func main() {
r := gin.Default()

r.GET("/ping", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "pong",
})
})

r.Run("0.0.0.0:9999")
}

启动golang容器,在容器中尝试编译并运行程序。

1
docker run -it -p 9999:9999 -v ./project:/app --env --env GO111MODULE=on --env GOPROXY=https://goproxy.cn,direct --rm  --privileged golang:1.15 bash

Alpine和其他通用Linux发行版对于Golang编译出来的可执行文件要求有所不同,Alpine要求可执行文件必须是静态链接的可执行文件。所以在编译Golang时需要添加 -tags netgo ,来生成静态链接的可执行文件。

1
go build -tags netgo -o app .

把编译出来的二进制文件和所有依赖项拷贝到发布目录

1
2
mkdir publish && cp app publish && \
cp -r docs publish

golang镜像的1.15版本有839M,再加上下载依赖编译项目等各种文件的话最终镜像可能会超过1G,大部分文件是在运行时不需要的。我们编写Dockerfile的时候可以把编译和运行两个阶段分开。编译时使用golang镜像,运行时使用alpine镜像。alpine镜像初始大小只有5M左右,非常适合作为基础镜像。最终Dockerfile如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
FROM golang:1.15 as builder

ENV GO111MODULE=on \
GOPROXY=https://goproxy.cn,direct

WORKDIR /app
COPY . .
RUN GOOS=linux GOARCH=amd64 go build -tags netgo -o app .

RUN mkdir publish && cp app publish && \
cp -r docs publish


FROM alpine
WORKDIR /app
COPY --from=builder /app/publish .
ENV GIN_MODE=release \
PORT=8081

EXPOSE 8081
ENTRYPOINT ["./app"]

构建docker镜像,大功告成。

1
docker build -t test:0.1 .

基于gin的golang web开发:永远不要相信用户的输入

作为后端开发者我们要记住一句话:“永远不要相信用户的输入”,这里所说的用户可能是人,也可能是另一个应用程序。“永远不要相信用户的输入”是安全编码的准则,也就是说,任何输入的内容在验证无害之前都是有害的。很多应用程序的安全漏洞都和用户输入有关,比如SQL注入漏洞。

我们可以通过参数验证、sql语句过滤和参数化查询等方式对用户的输入进行处理来规避这种安全隐患。本文介绍第一种方法,并对基于gin的golang web开发:模型验证进行补充,了解更多的参数验证方法。

验证非必填的邮箱字段

需求是这样的:我们需要验证一个字段可以为空,同时字段的值为合法的电子邮箱。

1
2
3
type MailRequest struct {
Email string `json:"email" binding:"email"` // 邮箱地址
}

代码的执行结果和我们想的不太一样,我们没有为字段设置required标签,但是传入空字符串时会提示Email必须是一个有效的邮箱,解决方法是加入omitempty验证规则。omitempty允许条件验证,在没有为字段设置值的情况下,跳过后面的验证规则。注意omitempty要放在其他规则前面。下面是修改后的代码:

1
2
3
type MailRequest struct {
Email string `json:"email" binding:"omitempty,email"` // 邮箱地址
}

验证0值

先看代码

1
2
3
type AddRoleRequest struct {
Available int `json:"available" binding:"required"` // 是否可用 0 不可用 1 可用
}
字段为```int```类型,添加了```required```验证规则,0为一个有效的值。```Available```为0时不能通过Gin的参数验证。这里只需要把字段类型修改为```*int```即可。
1
2
3
4
```golang
type AddRoleRequest struct {
Available *int `json:"available" binding:"required"` // 是否可用 0 不可用 1 可用
}

自定义错误消息

前文基于gin的golang web开发:模型验证结尾部分,我们没有把参数验证的错误消息完全翻译成中文,字段名还是英文的。显然还有更优雅的做法,给用户提示一个更友好的错误信息。

1
2
3
{
"error": "Username为必填字段;"
}

返回值中的Username为字段名称,可以通过自定义标签的方式修改错误信息中的字段名。我们自定义一个display标签,然后使用标签的值替换掉验证器中的字段。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
func init() {
translator := zh.New()
uni = ut.New(translator, translator)
trans, _ = uni.GetTranslator("zh")
validate := binding.Validator.Engine().(*validator.Validate)
// 注意这里
validate.RegisterTagNameFunc(func(fld reflect.StructField) string {
return fld.Tag.Get("display")
})
_ = zh_translations.RegisterDefaultTranslations(validate, trans)
}

func Translate(err error) string {
var result string

errors := err.(validator.ValidationErrors)

for _, err := range errors {
errMessage := err.Translate(trans)
result += errMessage + ";"
}
return result[:len(result)-1] // <--
}

type AddUserRequest struct {
Username string `json:"username" binding:"required" display:"用户名"`
Password string `json:"password" binding:"required" display:"密码"` // 登录密码
Nickname string `json:"nickname" binding:"required" display:"昵称"` // 昵称
}

注意代码中validate.RegisterTagNameFunc方法注册display标签,Translate方法也有一些改进,去掉了结果中最后一个分号。

举个栗子

1
2
3
4
5
6
7
8
9
10
11
12
func checkUser(user string, password string) bool {
db := GetDbContext()
defer db.Close()

dataSql := `
select count(1) from sys_user
where username = '` + user + `' and password = '` + password + `'`
count := 0
log.Println(dataSql)
db.QueryRow(dataSql).Scan(&count)
return count > 0
}

这段代码用于判断账号密码是否正确,但是没有验证用户输入的user和password参数,恶意用户构造一个特殊的密码1' or '1'='1dataSql中拼接的sql语句变为

1
2
select count(1) from sys_user
where username = 'xxx' and password = '1' or '1'='1'

查询结果大于0,方法返回真。这就造成了sql注入。我们可以在password字段上增加规则alphanum验证字段内容只能为字母或数字。1' or '1'='1不能通过参数验证也就规避掉了SQL注入的问题。例子中拼接SQL语句是为了方便演示,正式项目中不推荐这种写法。完整代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
type UserAndPassword struct {
User string `json:"user" binding:"required,alphanum"`
Pwd string `json:"pwd" binding:"required,alphanum"`
}

func IsLoginIn(c *gin.Context) {
var req = UserAndPassword{}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}

c.String(http.StatusOK, strconv.FormatBool(checkUser(req.User, req.Pwd)))
}

func checkUser(user string, password string) bool {
db := GetDbContext()
defer db.Close()

dataSql := `
select count(1) from sys_user
where username = '` + user + `' and password = '` + password + `'`
count := 0
log.Println(dataSql)
db.QueryRow(dataSql).Scan(&count)
return count > 0
}

基于gin的golang web开发:集成swagger

在前后端分离的项目维护一份完整且及时更新的api文档会极大的提高我们的工作效率,传统项目中接口文档都是由后端开发手写的,这种文档很难保证及时性,久而久之便失去了参考意义。swagger给我们提供了一种新的维护文档的方式,在gin中只需要编写一些注释即可生成一份可交互的接口文档。

1
2
3
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

引入这些包之后就可以通过给方法写注释的方式生成接口文档。github.com/swaggo/swag/cmd/swag中包含一个用于生成接口文档的命令行工具swag,github.com/swaggo/gin-swagger是一个gin中间件,github.com/swaggo/files中包含了swagger UI的一些如css、js等必要的文件。

与gin集成

我们需要在代码中引入必要的包,并且在main方法上增加两个必填的通用API注释title和version,这两个注释分别表示应用程序的名称和应用程序API的版本,这些内容会显示在swagger ui中。代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package main

import (
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "proj/docs"
)

// @title 用户中心API
// @version 1.0
func main() {
engine := gin.Default()

url := ginSwagger.URL("/swagger/doc.json")
engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

_ = engine.Run(":8081")
}

我们在代码中定义doc.json的文件地址为/swagger/doc.json,swagger ui会解析这个地址渲染页面。紧接着定义路由规则/swagger/*any全部经由ginSwagger.WrapHandler中间件处理。

在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成docs/docs.go和swagger所需的文件,最后引用docs_ "proj/docs",proj是项目名。

现在访问http://localhost:8081/swagger/index.html就会看到熟悉的swagger ui页面。

编写接口注释信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
type SysRole struct {
Id int64 `json:"id"`
Name null.String `json:"name" swaggertype:"string"` // 角色名
Description null.String `json:"description" swaggertype:"string"`
Available null.Int `json:"available" swaggertype:"integer"`
CreateTime null.Time `json:"create_time" db:"create_time" swaggertype:"string"` // 添加时间
UpdateTime null.Time `json:"update_time" db:"update_time" swaggertype:"string"` // 更新时间
}

// 角色列表
// @Summary 角色列表
// @Description 角色列表
// @Tags 角色
// @Success 200 {array} SysRole
// @Router /roles [get]
func RoleList(c *gin.Context) {
list := sysRole.GetAllRole()

c.JSON(http.StatusOK, list)
}

我们分别在model和handler方法上增加一些必要的信息。

Name字段在SysRole结构体中的类型为null.String,但是swag init生成文档时因为不能自动解析null包产生如下错误信息:

1
ParseComment error in file xxxxxxx.go :cannot find package path of type: null.String

一种解决方案是命令改为执行swag init --parseDependency解析外部依赖,这个命令需要解析大量的外部依赖运行时间很长,而且似乎也并不能解决所有问题。更推荐使用以上代码中的swaggertype标签来解决问题。swaggertype标签指定swagger中使用的类型,如int类型字段设置标签为swaggertype:"integer"

handler方法上增加注释描述当前接口的信息。@Summary和@Description设置接口的概要和描述信息。@Tags设置接口的分组,例如有接口 /roles 和 /roles/[:id] 都返回角色相关的信息,那么这两个handler的注释可以统一设置为 @Tags 角色。@Success设置接口成功返回的内容,这里设置为SysRole数组,当然还有@Failure设置接口失败的返回结果。@Router设置接口的路由。

基于gin的golang web开发:中间件

gin中间件(middleware)提供了类似于面向切面编程或路由拦截器的功能,可以在请求前和请求之后添加一些自定义逻辑。实际开发中有很多场景会用到中间件,例如:权限验证,缓存,错误处理,日志,事务等。

使用中间件

gin的中间件分为三类:全局中间件、路由中间件、分组路由中间件。

全局中间件:注册全局中间件之后注册的路由才会生效,如果有一些不希望使用全局中间件的路由规则,注册路由代码要放在注册全局中间件之前。

路由中间件:在注册路由时传入的中间件,只对当前路由规则生效。

分组路由中间件:在分组路由中注册,对当前组下的全部路由生效。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
func main() {
r := gin.New()

r.Use(gin.Logger())

r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

authorized := r.Group("/")
authorized.Use(AuthRequired())
{
authorized.POST("/login", loginEndpoint)
testing := authorized.Group("testing")
testing.GET("/analytics", analyticsEndpoint)
}

r.Run(":8080")
}

以上代码展示了中间件的注册方式。r.Use(gin.Logger())为全局中间件,这里使用的是gin提供的Logger中间件。r.GET("/benchmark", MyBenchLogger(), benchEndpoint)使用了MyBenchLogger中间件,只有在访问/benchmark时生效。authorized.Use(AuthRequired())使用了AuthRequired中间件,在访问/login和/testing/analytics时生效,注意代码中的嵌套路由。

自定义中间件

自定义gin中间件有两种写法。第一种:定义一个方法接收一个*gin.Context类型的参数,和handler的写法是一样的。第二种:定义一个无参的方法,返回值为HandlerFunc类型。代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 第一种
func DemoMiddleware(c *gin.Context) {
fmt.Println("DemoMiddleware")

c.Next()

}

// 第二种
func Demo1Middleware() gin.HandlerFunc {

return func(c *gin.Context) {
fmt.Println("Demo1Middleware")
c.Next()
}
}

在代码中我们可以看到无论哪种方法定义的中间件都调用了c.Next()将请求传递给请求链中下一个处理方法。中间件中我们还可以调用c.Abort(code)提前结束请求,如下面认证中间件,token参数为空时将不在执行后续的处理方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func TokenAuthMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
token := c.Request.Header.Get("token")
if token == "" {
c.Abort()
return
}

c.Next()
}
}

func main() {
r := gin.Default()
r.GET("/auth", TokenAuthMiddleware(), func(c *gin.Context) {
c.JSON(200, gin.H{"message": "ok"})
})
r.Run(":9999")
}

基于gin的golang web开发:mysql增删改查

Go语言访问mysql数据库需要用到标准库database/sql和mysql的驱动。标准库的Api使用比较繁琐这里再引入另一个库github.com/jmoiron/sqlx

1
2
go get github.com/jmoiron/sqlx
go get github.com/go-sql-driver/mysql

连接数据库

1
2
3
4
db, err := sqlx.Connect("mysql", "...?parseTime=true")
if err != nil {
log.Panicln("db err: ", err.Error())
}

使用sqlx的Connect方法连接数据库,Connect自动确认是否连接成功,如果出错的话err返回错误信息。可以在需要连接数据库的函数中直接连接,也可以使用基于gin的golang web开发:访问mysql数据库中介绍的go语言init机制获取连接。

增删改

mysql的增删改使用db的Exec函数,传入sql语句和查询参数。sqlx也提供了MustExec函数,在sql语句执行出错的时候触发panic而不是返回error。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
db, err := sqlx.Connect("mysql", "...?parseTime=true")
if err != nil {
log.Panicln("db err: ", err.Error())
}
defer db.Close()

insertSql := `
INSERT INTO sys_user (
username,
PASSWORD
)
VALUES
(?, ?);
`
result, err := db.Db.Exec(insertSql, username, password)
if err != nil {
log.Panicln("add user err: ", err.Error())
}

updateSql := `
update sys_user
set username = ?
where id = ?;
`
result1, err1 := db.Db.Exec(updateSql, username, id)
if err1 != nil {
log.Panicln("update user by id err: ", err.Error())
}

deleteSql := `
delete from sys_user
where id = ?
`
result2, err2 := db.Db.Exec(deleteSql, id)
if err2 != nil {
log.Panicln("delete user by id err: ", err.Error())
}

Exec函数的结果result接口包含两个函数LastInsertId,RowsAffected,可以判断RowsAffected > 0来验证sql语句的执行结果。注意RowsAffected不是所有数据库和驱动都支持,如果你用的不是mysql的话需要检查你的环境是否支持RowsAffected。

sqlx支持可以方便把数据库查询结果转换成go结构体,Get和Select分别用来获取单个结果和多个结果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
type SysUser struct {
Id int `json:"id"`
Username null.String `json:"username"`
Password null.String `json:"password"` // 登录密码
}

func GetAllUser(request GetAllUserRequest) (list []SysUser) {
strSql := `
select id,
username,
password
from sys_user
`
err = db.Db.Select(&list, strSql)
if err != nil {
log.Panicln("select sys_user err: ", err.Error())
}

return
}

func GetById(id int) (user SysUser) {
sysUser := SysUser{}
dataSql := `
select id,
username,
password
from sys_user
where id = ?
`
err := db.Db.Get(&sysUser, dataSql, id)
if err != nil {
log.Panicln("get user by id err: ", err.Error())
}
return sysUser
}

Select方法获取所有结果放入内存,并转换为目标结构体,如果结果中包含大量数据的话可以分页返回,也可以使用Query/StructScan迭代方法。

基于gin的golang web开发:使用数据库事务

在前文介绍访问数据库时介绍了github.com/jmoiron/sqlx包,本文基于这个包使用数据库事务。

defer

在使用数据库事务之前,首先需要了解go语言的defer关键字。defer是go语言的延迟执行语句,defer后面的语句会被go进行延迟处理,在函数即将结束的时候,defer后面的语句将逆序执行。也就是说,先defer的语句最后执行。defer很像java或者C#中的finally语句。下面通过一个例子看一下defer。

1
2
3
4
5
6
7
8
9
10
11
12
package main

import "fmt"

func main() {
fmt.Println("defer 开始")
defer fmt.Println(1)
defer fmt.Println(2)
defer fmt.Println(3)
panic("测试 panic")
fmt.Println("defer 结束")
}

代码运行结果:

1
2
3
4
5
6
7
8
9
10
11
defer 开始
3
2
1
panic: 测试 panic

goroutine 1 [running]:
main.main()
/tests/gookokok/main.go:10 +0x1b8

Process finished with exit code 2

通过运行结果可以看到defer的逆序输出。在之后又手动触发了一个panic,影响了最后一行的输出defer 结束,go在触发panic时优先执行了defer,足以证明defer是非常安全的,所以defer也常常被用来互斥解锁、关闭文件或数据库事务的处理。

事务

sqlx使用事务和database/sql相比扩展出了MustBegin()、MustExec()等方法,这样就不需要在代码中手动处理很多错误。MustBegin会在出现错误的时候触发panic而不是返回错误,这样就可以在代码的更上一层统一处理错误。

1
2
3
4
5
6
7
tx, err := db.Begin()
err = tx.Exec(...)
err = tx.Commit()

tx := db.MustBegin()
tx.MustExec(...)
err = tx.Commit()

sqlx支持以上两种开启事务的方法。MustBegin返回sqlx.Tx,sqlx.Tx也提供了Select,Get之类的API,执行数据库操作和使用sqlx.DB是一样的。

以上代码执行tx.MustExec(...)如果报错的话,代码将没有机会运行到tx.Commit(),这样数据库连接会等到go进行垃圾回收的时候才能关闭,而且很高并发的话,可能会占满数据库连接数,造成站点无法访问的情况。

1
2
3
4
tx := db.MustBegin()
defer tx.Rollback()
tx.MustExec(...)
err = tx.Commit()

代码中加入defer tx.Rollback()就可以解决问题。通过前面的介绍已知defer是在方法即将结束时执行,哪怕是代码出现异常也不会影响数据库连接。