[Golang梦工厂]一个小项目带你学会GIN框架、JWT鉴权、swagger生成接口文档，看这一篇就够了

前言

哈喽，大家好，我是asong，这是我的第八篇原创文章。听说你们还不会jwt、swagger，所以我带来一个入门级别的小项目。实现用户登陆、修改密码的操作。使用GIN（后台回复Golang梦工厂：gin，可获取2020GIN中文文档）作为web框架，使用jwt进行身份校验，使用swagger生成接口文档。代码已上传个人github：https://github.com/asong2020/Golang_Dream/tree/master/Gin/gin_jwt_swagger。有需要的自行下载，配有详细使用文档。

原文链接：原文传送门

1. jwt

1.1 简介

jwt全称 Json web token，是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准。JWT的声明一般被用来在身份提供者和服务提供者间传递被认证的用户身份信息，以便于从资源服务器获取资源，也可以增加一些额外的其他业务逻辑所必须的声明信息，该token也可直接被用于认证，也可以被加密。学习jwt，我们可以从官网文档入手，jwt官网传送门。

1.2 json web 令牌结构

JSON Web令牌由三部分组成，这些部分由.分隔，分别是

  • Header
  • Payload
  • Signature

一个JWT表示如示例：xxxxx.yyyyy.zzzzz

1.2.1 Header

Header通常由两部分组成：令牌的类型和所使用的签名算法，例如HMAC、SHA256或者RSA。

{
  "alg": "HS256",
  "typ": "JWT"
}

此json是由Base64Url编码形成JWT的第一部分。

1.2.2 Payload

令牌的第二部分是有效载荷。用于声明，通常存储一些用户ID之类的索引数据，也可以放一些其他有用的信息，注意：不要存储机密数据。JWT标准定义了一些基本字段：

  • iss：该JWT的签发者
  • sub：该JWT所面向的用户
  • aud：接收该JWT的一方
  • exp（expires）：过期时间
  • iat：签发时间

除了定义这几个标准字段外，我们可以定义一些我们在业务处理中需要用到的字段，可以有用户的id、名字等。来个例子看一看吧：

{
    "iss": "asong",
    "iat": 6666666666,
    "exp": 6666666666,
    "aud": "user",
    "sub": "all",
    "user_id": "6666666666666666666",
    "username": "asong"
}

上面的user_id、username都是我们定义的字段。对此负载进行Base64Url编码，形成JSON Web令牌的第二部分。

1.2.3 Signature

签名其实是对JWT的Header和Payload整合的一个签名验证。我们需要将Header和Payload链接起来，然后使用一个key用HMAC SHA256进行加密，创建一个签名，像下面这样。

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

签名的作用用于验证消息在此过程中没有更改，并且对于使用私钥进行签名的令牌，它还可以验证JWT的发件人是谁。

最终将这三部分放在一起，由.进行分隔，示例如下：

[图片上传失败...(image-b781ec-1596983242695)]

1.3 什么时候使用JWT

  • Authorization(授权)：用户请求的token中包含了该令牌允许的路由，服务和资源。单点登录就是其中广泛使用JWT的一个特性。
  • Information Exchange(信息交换)：对于安全的在各方之间传输信息而言，JSON Web Tokens无疑是一种很好的方式。因为JWTs可以被签名，例如，用公钥/私钥对，可以确定发送人身份。并且·签名是使用头和有效负载计算的，还可以验证内容有没有被篡改。

JWT工作可以用如下图表示：

在这里插入图片描述

根据上图所示，我们可以看到整个过程分为两个阶段，第一个阶段，客户端向服务器获取token，第二阶段，客户端带着该token去请求相关的资源。服务端通常根据指定的规则进行token的生成。在认证的时候，当用户用他们的凭证成功登录以后，一个JSON WebToken将会被返回。这是这个token就是用户凭证了，我们必须小心防止出现安全问题。一般我们保存令牌的时候不应该超过你所需要他的时间。无论何时用户想要访问受保护的路由或者资源的时候，用户代理（通常是浏览器）都应该带上JWT，典型的，通常放在Authorization header中，用Bearer schema: Authorization: Bearer <token>。服务器上的受保护的路由将会检查Authorization header中的JWT是否有效，如果有效，则用户可以访问受保护的资源。如果JWT包含足够多的必需的数据，那么就可以减少对某些操作的数据库查询的需要，尽管可能并不总是如此。如果token是在授权头（Authorization header）中发送的，那么跨源资源共享(CORS)将不会成为问题，因为它不使用cookie.

在这里插入图片描述
  • 客户端向授权接口请求授权
  • 服务端授权后返回一个access token给客户端
  • 客户端使用access token访问受保护的资源

好啦，JWT的基本原理介绍完毕，你学了嘛？没学会不要紧，我们还有代码呢。

1.3 代码实践

  • Web框架：Gin
  • 第三方库：github.com/dgrijalva/jwt-go

代码地址：https://github.com/asong2020/Golang_Dream/tree/master/Gin/gin_jwt_swagger

在这再推荐一个别人写好的JWT包，直接使用也可以：https://github.com/appleboy/gin-jwt

1.3.1 定义相关参数

  • 定义claims中信息，示例定义如下：
type UserClaims struct {
    Username string
    jwt.StandardClaims
}
  • 定义secret
jwt:
  signkey: 'asong'
  • 定义过期时间
redis:
  addr: 127.0.0.1:6379
  db: 1
  password: ''
  poolsize: 100
  cache:
    tokenexpired: 7200 # expired time 2*60*60
  • 创建一个JWT对象
type JWT struct {
    SigningKey []byte
}

func NewJWT() *JWT {
    return &JWT{
        []byte(global.AsongServer.Jwt.Signkey),
    }
}

1.3.2 生成JWT

func (j *JWT)GenerateToken(claims request.UserClaims)  (string,error){
    token := jwt.NewWithClaims(jwt.SigningMethodHS256,claims)
    return token.SignedString(j.SigningKey)
}

1.3.3 解析Token

func (j *JWT)ParseToken(t string) (*request.UserClaims,error) {
    token, err := jwt.ParseWithClaims(t,&request.UserClaims{}, func(token *jwt.Token) (interface{}, error) {
        return j.SigningKey,nil
    })
    if err != nil{
        if v, ok := err.(*jwt.ValidationError); ok {
            if v.Errors&jwt.ValidationErrorMalformed != 0 {
                return nil, errors.New("That's not even a token")
            } else if v.Errors&jwt.ValidationErrorExpired != 0 {
                // Token is expired
                return nil, errors.New("Token is expired")
            } else if v.Errors&jwt.ValidationErrorNotValidYet != 0 {
                return nil, errors.New("Token not active yet")
            } else {
                return nil, errors.New("Couldn't handle this token:")
            }
        }
    }
    if token != nil {
        if claims, ok := token.Claims.(*request.UserClaims); ok && token.Valid {
            return claims, nil
        }
        return nil, errors.New("Couldn't handle this token:")

    } else {
        return nil, errors.New("Couldn't handle this token:")

    }
}

1.3.4 更新Token

func (j *JWT) RefreshToken(t string) (string, error) {
    jwt.TimeFunc = func() time.Time {
        return time.Unix(0, 0)
    }
    token, err := jwt.ParseWithClaims(t, &request.UserClaims{}, func(token *jwt.Token) (interface{}, error) {
        return j.SigningKey, nil
    })
    if err != nil {
        return "", err
    }
    if claims, ok := token.Claims.(*request.UserClaims); ok && token.Valid {
        jwt.TimeFunc = time.Now
        claims.StandardClaims.ExpiresAt = time.Now().Add(1 * time.Hour).Unix()
        return j.GenerateToken(*claims)
    }
    return "", errors.New("Couldn't handle this token:")
}

1.3.5 编写中间件

func Auth()  gin.HandlerFunc{
    return func(c *gin.Context) {
        token := c.Request.Header.Get("token")
        if token == ""{
            response.Result(response.ERROR,gin.H{
                "reload": true,
            },"非法访问",c)
            c.Abort()
            return
        }
        j := NewJWT()
        claims, err := j.ParseToken(token)
        if err != nil{
            response.Result(response.ERROR, gin.H{
                "reload": true,
            }, err.Error(), c)
            c.Abort()
            return
        }
        c.Set("claims",claims)
        c.Next()
    }
}

1.3.6 在gin框架中使用

  • 路由注册时，使用中间，作为用户登录验证
func RouteUserInit(Router *gin.RouterGroup)  {
    UserRouter := Router.Group("user").Use(middleware.Auth())
    {
        UserRouter.PUT("setPassword",setPassword)
    }
}
  • 用户通过接口获取Token之后，后续就会携带着Token再来请求我们的其他接口，这个时候就需要对这些请求的Token进行校验操作了
func login(c *gin.Context)  {
     var req request.LoginRequest
     _ = c.ShouldBindJSON(&req)
     if req.Username == "" || req.Password == ""{
         response.FailWithMessage("参数错误",c)
         return
     }
     user := &model.User{
        Username: req.Username,
        Password: req.Password,
     }
     u ,err := service.Login(user)
     if err != nil{
         response.FailWithMessage(err.Error(),c)
         return
     }
     service.GenerateTokenForUser(c,u)
}
//生成token
func GenerateTokenForUser(c *gin.Context,u *model.User)  {
    j := &middleware.JWT{
        SigningKey: []byte(global.AsongServer.Jwt.Signkey), // 唯一签名
    }
    claims := request.UserClaims{
        Username: u.Username,
        StandardClaims: jwt.StandardClaims{
            NotBefore: time.Now().Unix() - 1000,       // 签名生效时间
            ExpiresAt: time.Now().Unix() + 60*60*2, // 过期时间 2h
            Issuer:    "asong",                       // 签名的发行者
        },
    }
    token ,err := j.GenerateToken(claims)
    if err != nil {
        response.FailWithMessage("获取token失败", c)
        return
    }
    res := resp.ResponseUser{Username: u.Username,Nickname: u.Nickname,Avatar: u.Avatar}
    response.OkWithData(resp.LoginResponse{User: res,Token: token,ExpiresAt: claims.ExpiresAt *1000},c)
    return
}

好啦，代码部分完成了，接下来就可以测试了，在测试之前，我再来学一下swagger，生成接口文档。

2. swagger

随着互联网的发展，现在的网站都是前后端分离了，前端渲染页面，后端提供API。前后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

swagger可以减少我们的工作量，直接生成API文档，减少了文档编写的工作。我们先来看一看swagger的生态使用图：

在这里插入图片描述

红色字是官方推荐的。

  • swagger-ui：一个渲染页面，可以用来显示API文档。不可以编辑。
  • swagger-editor：就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用
  • swagger-codegen：代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。
  • Swagger-validator：这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。

目前最流行的做法，就是在代码注释中写上swagger相关的注释，然后，利用小工具生成swagger.json或者swagger.yaml文件。

这里我们采用代码注释的方式实现。注释规范参考官网即可：https://goswagger.io/use/spec/params.html。这里只是一个简单实用，更多实用阅读官方文档学习。或者参考这篇文章：https://razeencheng.com/post/go-swagger

2.1 项目中使用swagger

  • 安装swag
$ go get -u github.com/swaggo/swag/cmd/swag

这里有一点需要注意，生成的可执行文件会放到 $GOPATH/bin目录下，需要将这个路径放到环境变量中，验证是否安装成功：

$ swag -v
$ swag version v1.6.7
  • 安装gin-swagger
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/gin-swagger/swaggerFiles
  • 安装好第三方库后，我们进入到API接口中，在相应方法上编写swagger注释，注释参考go-gin-example 
// @Tags Base
// @Summary 用户登录
// @Produce  application/json
// @Param data body request.LoginRequest true "用户登录接口"
// @Success 200 {string} string "{"success":true,"data": { "user": { "username": "asong", "nickname": "", "avatar": "" }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VybmFtZSI6ImFzb25nIiwiZXhwIjoxNTk2OTAyMzEyLCJpc3MiOiJhc29uZyIsIm5iZiI6MTU5Njg5NDExMn0.uUS1TreZusX-hL3nKOSNYZIeZ_0BGrxWjKI6xdpdO40", "expiresAt": 1596902312000 },,"msg":"操作成功"}"
// @Router /base/login [post]
func login(c *gin.Context)  {}

// @Tags User
// @Summary 用户修改密码
// @Security ApiKeyAuth
// @Produce  application/json
// @Param data body request.ChangePassword true "用户修改密码"
// @Success 200 {string} string "{"success":true,"data":{},"msg":"修改成功"}"
// @Router /user/setPassword [PUT]
func setPassword(c *gin.Context) {}
  • 接下来生成swagger文档，进入项目根目录，执行以下命令
$ swag init

完毕后会在你的项目根目录下生成docs目录：

docs/
├── docs.go
├── swagger.json
└── swagger.yaml

  • 还差最后一步，对swagger-ui进行路由注册，引入swagger生成的docs文件夹，图片中红色线是需要添加的


    在这里插入图片描述

至此，swagger也配置完成了。

3. 运行示例

运行代码，浏览器进入http://localhost:8888/swagger/index.html，可以看到页面如下：

在这里插入图片描述

在这里就可以进行接口测试了。

4. 总结

这篇文章，到此就结束了，第一次写这么长的文章，对自己也是一种提升。有些模糊的概念，又学习了一遍，此篇文章，全是自己总结的，有错误欢迎指出。如果欢迎三连：点赞、看一看、转发；感谢各位。

不会的小伙伴，赶快学起来吧，项目代码地址：https://github.com/asong2020/Golang_Dream/tree/master/Gin/gin_jwt_swagger

我是asong，一名普普通通的程序员，永远保持一颗热爱技术的心。欢迎关注个人公众号【Golang梦工厂】，第一时间观看优质文章，你想学的这里都有。

获取2020GIN官方中文文档，后台回复：gin，即可获取。由笔者进行翻译，会定期进行维护。

到这里结束喽，我们下期见。


qrcode_for_gh_efed4775ba73_258.jpg
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 202,529评论 5赞 475
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,015评论 2赞 379
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 149,409评论 0赞 335
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,385评论 1赞 273
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,387评论 5赞 364
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,466评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,880评论 3赞 395
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,528评论 0赞 256
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,727评论 1赞 295
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,528评论 2赞 319
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,602评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,302评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,873评论 3赞 306
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,890评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,132评论 1赞 259
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 42,777评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,310评论 2赞 342