Golang-01 windows 环境 gin + swagger

0x00 前言

• 面向读者:
  第一次在Windows环境构建go开发环境.
• 本文目的
  学习使用gin进行接口开发, 并为此接口服务添加 swagger 接口文档功能
• 注意:
  请自带梯子

0x01 环境

本文开发环境为Windows 7, 所以这里以 win 7 为例进行介绍.

• 下载安装包
  首先在官网https://golang.org/dl/, 选择msi安装包.

安装包下载

• 安装
  大力双击下载到的安装文件, 我们这里把它安装到D:\go 目录
  

  

  安装

• 创建工作目录
  手动创建目录 D:\go_base , 这个目录就是将来go的依赖库下载目录 ,
  同时,也是我们添加新项目所在的目录.

这里和java的工作机制不太一样.
不过感觉这种设定也挺好的,不用"满地图"到处找代码 :-)

• 环境变量设定
  GO开头的环境变量如下:

GOARCH=amd64
GOBIN=D:\go\bin
GOOS=windows
GOPATH=D:\go_base
GOROOT=D:\go

设置环境变量

配置完成后, 打开一个新的命令行窗口, 能正常执行 go env表示安装配置成功.

go env

• 配置 GoLand
  打开Goland的设置画面, 点选并设置 GO下面的两个选项:
  
  

  GOROOT
  
  
  

  GOPATH

到这里, 开发环境已经基本配置完成 .

0x02 创建第一个Go版本的api项目

Go语言版本的RestApi框架有很多, 这里我们以https://github.com/gin-gonic/gin 作为学习对象.

• 手动下载gin依赖项
  打开命令行窗口, 执行命令:

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

执行正常结束后, 会在 %GOPATH%\src\github.com\gin-gonic\gin目录下多出一大票代码.
如你所想, 这个命令, 就是把 github上的代码下载到本地了.

• one more thing
Go编译成功后, 只有一个执行文件(便于发布?).
  因此, 就不难理解 , 为什么下载依赖, 其实就是把依赖的源码给拉下来了.

• 创建项目
  创建一个新的Go工程, 注意选择路径为 %GOPATH%\src\项目名称
  

  

  image.png
  
  设置好目录后, 下一步, 就直接到了开发主界面了.
  好简洁呀,一个文件都没有 O_O
  
  

  主界面

• 编写代码
  好吧, 我们还是进入正题, 参考gin官网示例程序,导入测试代码.
  我们在项目中手动创建一个main.go文件,内容如下

package main

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

func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })
    r.Run() // listen and serve on 0.0.0.0:8080
}

• 运行
  一般的, 我们写一个go文件, 如果package main 下面, 再有一个 func main()的话, 那么这个main()就是程序 的入口了.

我们可以直接在IDE上 轻戳边上的小三角, 启动程序.

运行

• 验证
  程序启动后, 我们就可以 访问 http://localhost:8080/ping此接口, 查看效果:

接口成功

哇, 这代码量, 比SpringBoot 少了不是一点半点啊, 点赞

到这里呢, 框架开发的流程已经走完了, 接下来开发的部分, 参考文档慢慢学习.

0x03 导入 SwaggerUI

作为一个不爱写文档, 又恨别人不写文档的的程序员, 我们当然选择Swagger来做为接口说明输出啦.
这个神器可是Spring项目的标配了, go开发的接口当然也不能放松要求.

我们使用https://github.com/swaggo/gin-swagger作为 swagger接入方案.

跟上面的流程一样, 我们先下载依赖

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/alecthomas/template

• 开始导入
  在项目根目录(main.go所在目录 ) , 执行命令行: swag init,会在项目目录下生成一堆文件.
  

  

  swag init

• 修改代码
  要增加的代码太零散, 直接上完成代码

其中

• DOC主体注释写法参考
  https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

• API上面的注释写法请参考
  https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html

package main

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

// @title 国服最坑开发
// @version 1.0.1
// @description 神奇的API.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))


    r.GET("/ping", pong)

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

// Ping Pong
// @Summary Ping Pong
// @Description get string by ID
// @Tags 健康检测
// @Produce  json
// @Success 200
// @Router /ping [get]
func pong(ctx * gin.Context)  {
    ctx.JSON(200, gin.H{
        "message": "pong",
    })
}

注意
每次修改注释后, 都要执行 swag init , 然后再启动服务进行验证

• 验证
  启动服务后,打开网页 http://localhost:8080/swagger/index.html, 查看效果:

swagger

0x04 后记

为什么要搞 golang?

最近线上发现在用java作计算密集型的操作时, 时间消耗有点大.
就想着是否要另外一种语言来作替代实现.
生命不息, 折腾不止, go起来

体验:

这一篇只是刚刚开始, 关于swagger 熟练使用, 还有很长路要走.
对比 java版的swagger, 感觉java的好像更简单一点?
不不不, 只是自己还没熟练吧, 哈哈