前言
哈喽，你们好，我是asong，这是个人第八篇原创文章。据说大家还不会jwt、swagger，因此我带来一个入门级别的小项目。实现用户登录、修改密码的操做。使用GIN（后台回复Golang梦工厂：gin，可获取2020GIN中文文档）做为web框架，使用jwt进行身份校验，使用swagger生成接口文档。代码已上传我的github：https://github.com/asong2020/Golang_Dream/tree/master/Gin/gin_jwt_swagger。有须要的自行下载，配有详细使用文档。html
1. jwt
1.1 简介
jwt全称 Json web token，是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准。JWT的声明通常被用来在身份提供者和服务提供者间传递被认证的用户身份信息，以便于从资源服务器获取资源，也能够增长一些额外的其余业务逻辑所必须的声明信息，该token也可直接被用于认证，也能够被加密。学习jwt，咱们能够从官网文档入手，jwt官网传送门。前端
1.2 json web 令牌结构
JSON Web令牌由三部分组成，这些部分由.分隔，分别是git
Header程序员
Payloadgithub
Signatureweb
一个JWT表示如示例：xxxxx.yyyyy.zzzzzredis
1.2.1 Header
Header一般由两部分组成：令牌的类型和所使用的签名算法，例如HMAC、SHA256或者RSA。算法
1{
2 "alg": "HS256",
3 "typ": "JWT"
4}
此json是由Base64Url编码造成JWT的第一部分。数据库
1.2.2 Payload
令牌的第二部分是有效载荷。用于声明，一般存储一些用户ID之类的索引数据，也能够放一些其余有用的信息，注意：不要存储机密数据。JWT标准定义了一些基本字段：json
iss：该JWT的签发者sub：该JWT所面向的用户aud：接收该JWT的一方exp（expires）：过时时间iat：签发时间
除了定义这几个标准字段外，咱们能够定义一些咱们在业务处理中须要用到的字段，能够有用户的id、名字等。来个例子看一看吧：
1{
2 "iss": "asong",
3 "iat": 6666666666,
4 "exp": 6666666666,
5 "aud": "user",
6 "sub": "all",
7 "user_id": "6666666666666666666",
8 "username": "asong"
9}
上面的user_id、username都是咱们定义的字段。对此负载进行Base64Url编码，造成JSON Web令牌的第二部分。
1.2.3 Signature
签名实际上是对JWT的Header和Payload整合的一个签名验证。咱们须要将Header和Payload连接起来，而后使用一个key用HMAC SHA256进行加密，建立一个签名，像下面这样。
1HMACSHA256(
2 base64UrlEncode(header) + "." +
3 base64UrlEncode(payload),
4 secret)
签名的做用用于验证消息在此过程当中没有更改，而且对于使用私钥进行签名的令牌，它还能够验证JWT的发件人是谁。
最终将这三部分放在一块儿，由.进行分隔，示例以下：
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中信息，示例定义以下：
1type UserClaims struct {
2 Username string
3 jwt.StandardClaims
4}
定义secret
1jwt:
2 signkey: 'asong'
定义过时时间
1redis:
2 addr: 127.0.0.1:6379
3 db: 1
4 password: ''
5 poolsize: 100
6 cache:
7 tokenexpired: 7200 # expired time 2*60*60
建立一个JWT对象
1type JWT struct {
2 SigningKey []byte
3}
4
5func NewJWT() *JWT {
6 return &JWT{
7 []byte(global.AsongServer.Jwt.Signkey),
8 }
9}
1.3.2 生成JWT
1func (j *JWT)GenerateToken(claims request.UserClaims) (string,error){
2 token := jwt.NewWithClaims(jwt.SigningMethodHS256,claims)
3 return token.SignedString(j.SigningKey)
4}
1.3.3 解析Token
1func (j *JWT)ParseToken(t string) (*request.UserClaims,error) {
2 token, err := jwt.ParseWithClaims(t,&request.UserClaims{}, func(token *jwt.Token) (interface{}, error) {
3 return j.SigningKey,nil
4 })
5 if err != nil{
6 if v, ok := err.(*jwt.ValidationError); ok {
7 if v.Errors&jwt.ValidationErrorMalformed != 0 {
8 return nil, errors.New("That's not even a token")
9 } else if v.Errors&jwt.ValidationErrorExpired != 0 {
10 // Token is expired
11 return nil, errors.New("Token is expired")
12 } else if v.Errors&jwt.ValidationErrorNotValidYet != 0 {
13 return nil, errors.New("Token not active yet")
14 } else {
15 return nil, errors.New("Couldn't handle this token:")
16 }
17 }
18 }
19 if token != nil {
20 if claims, ok := token.Claims.(*request.UserClaims); ok && token.Valid {
21 return claims, nil
22 }
23 return nil, errors.New("Couldn't handle this token:")
24
25 } else {
26 return nil, errors.New("Couldn't handle this token:")
27
28 }
29}
1.3.4 更新Token
1func (j *JWT) RefreshToken(t string) (string, error) {
2 jwt.TimeFunc = func() time.Time {
3 return time.Unix(0, 0)
4 }
5 token, err := jwt.ParseWithClaims(t, &request.UserClaims{}, func(token *jwt.Token) (interface{}, error) {
6 return j.SigningKey, nil
7 })
8 if err != nil {
9 return "", err
10 }
11 if claims, ok := token.Claims.(*request.UserClaims); ok && token.Valid {
12 jwt.TimeFunc = time.Now
13 claims.StandardClaims.ExpiresAt = time.Now().Add(1 * time.Hour).Unix()
14 return j.GenerateToken(*claims)
15 }
16 return "", errors.New("Couldn't handle this token:")
17}
1.3.5 编写中间件
1func Auth() gin.HandlerFunc{
2 return func(c *gin.Context) {
3 token := c.Request.Header.Get("token")
4 if token == ""{
5 response.Result(response.ERROR,gin.H{
6 "reload": true,
7 },"非法访问",c)
8 c.Abort()
9 return
10 }
11 j := NewJWT()
12 claims, err := j.ParseToken(token)
13 if err != nil{
14 response.Result(response.ERROR, gin.H{
15 "reload": true,
16 }, err.Error(), c)
17 c.Abort()
18 return
19 }
20 c.Set("claims",claims)
21 c.Next()
22 }
23}
1.3.6 在gin框架中使用
路由注册时，使用中间，做为用户登陆验证
1func RouteUserInit(Router *gin.RouterGroup) {
2 UserRouter := Router.Group("user").Use(middleware.Auth())
3 {
4 UserRouter.PUT("setPassword",setPassword)
5 }
6}
用户经过接口获取Token以后，后续就会携带着Token再来请求咱们的其余接口，这个时候就须要对这些请求的Token进行校验操做了
1func login(c *gin.Context) {
2 var req request.LoginRequest
3 _ = c.ShouldBindJSON(&req)
4 if req.Username == "" || req.Password == ""{
5 response.FailWithMessage("参数错误",c)
6 return
7 }
8 user := &model.User{
9 Username: req.Username,
10 Password: req.Password,
11 }
12 u ,err := service.Login(user)
13 if err != nil{
14 response.FailWithMessage(err.Error(),c)
15 return
16 }
17 service.GenerateTokenForUser(c,u)
18}
19//生成token
20func GenerateTokenForUser(c *gin.Context,u *model.User) {
21 j := &middleware.JWT{
22 SigningKey: []byte(global.AsongServer.Jwt.Signkey), // 惟一签名
23 }
24 claims := request.UserClaims{
25 Username: u.Username,
26 StandardClaims: jwt.StandardClaims{
27 NotBefore: time.Now().Unix() - 1000, // 签名生效时间
28 ExpiresAt: time.Now().Unix() + 60*60*2, // 过时时间 2h
29 Issuer: "asong", // 签名的发行者
30 },
31 }
32 token ,err := j.GenerateToken(claims)
33 if err != nil {
34 response.FailWithMessage("获取token失败", c)
35 return
36 }
37 res := resp.ResponseUser{Username: u.Username,Nickname: u.Nickname,Avatar: u.Avatar}
38 response.OkWithData(resp.LoginResponse{User: res,Token: token,ExpiresAt: claims.ExpiresAt *1000},c)
39 return
40}
好啦，代码部分完成了，接下来就能够测试了，在测试以前，我再来学一下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
1$ go get -u github.com/swaggo/swag/cmd/swag
这里有一点须要注意，生成的可执行文件会放到 $GOPATH/bin目录下，须要将这个路径放到环境变量中，验证是否安装成功：
1$ swag -v
2$ swag version v1.6.7
安装gin-swagger
1$ go get -u github.com/swaggo/gin-swagger
2$ go get -u github.com/swaggo/gin-swagger/swaggerFiles
安装好第三方库后，咱们进入到API接口中，在相应方法上编写swagger注释，注释参考go-gin-example
1// @Tags Base
2// @Summary 用户登陆
3// @Produce application/json
4// @Param data body request.LoginRequest true "用户登陆接口"
5// @Success 200 {string} string "{"success":true,"data": { "user": { "username": "asong", "nickname": "", "avatar": "" }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VybmFtZSI6ImFzb25nIiwiZXhwIjoxNTk2OTAyMzEyLCJpc3MiOiJhc29uZyIsIm5iZiI6MTU5Njg5NDExMn0.uUS1TreZusX-hL3nKOSNYZIeZ_0BGrxWjKI6xdpdO40", "expiresAt": 1596902312000 },,"msg":"操做成功"}"
6// @Router /base/login [post]
7func login(c *gin.Context) {}
8
9// @Tags User
10// @Summary 用户修改密码
11// @Security ApiKeyAuth
12// @Produce application/json
13// @Param data body request.ChangePassword true "用户修改密码"
14// @Success 200 {string} string "{"success":true,"data":{},"msg":"修改为功"}"
15// @Router /user/setPassword [PUT]
16func setPassword(c *gin.Context) {}
接下来生成swagger文档，进入项目根目录，执行如下命令
1$ swag init
完毕后会在你的项目根目录下生成docs目录：
1docs/
2├── docs.go
3├── swagger.json
4└── 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，便可获取。由笔者进行翻译，会按期进行维护。
到这里结束喽，咱们下期见。
本文分享自微信公众号 - Golang梦工厂（AsongDream）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。