GOLANG从浅入深必须学习的一些工具包
1.Viper:
Viper 是一个完整的 Go 应用程序配置解决方案,优势就在于开发项目中你不必去操心配置文件的格式而是让你腾出手来专注于项目的开发。其特性如下:
支持 JSON/TOML/YAML/HCL/envfile/Java properties 等多种格式的配置文件
可以设置监听配置文件的修改,修改时自动加载新的配置
从环境变量、命令行选项和io.Reader,远程K/V中读取配置
从远程配置系统中读取和监听修改,如 etcd/Consul
代码逻辑中显示设置键值
简单通俗的来说就是配置文件,比如数据库的连接参数(用户名,密码,端口号,数据名等等),这些都可以用viper包来实现存储
为什么使用viper包来存储固定参数:为的是方便管理,如果项目要移植或者修改参数,直接修改配置文件就可以了,保证代码的健壮
2. Mysql
操作数数据库包,基础用法可以参考博主的另外一篇我文章,此处就不再赘述了
引入包:
go get -u github.com/spf13/viper
怎么使用?实际上存储的数据是存储在一个yml格式的文件中(以数据库连接参数为例子)
1.创建一个文件夹:config
2.创建一个yml文件并写入数据:两种写法,可以自由选择(注意点:yml文件数据冒号后面一定要有空格,要不然没有效果)
//全量配置(不用写入yml文件)
mysql:
dsn: root:root@tcp(127.0.0.1:3306)/gochect?charset=utf8&parseTime=True&loc=Local
//非全量配置(不用写入yml文件)
mysql:
username: root
password: root
address: 127.0.0.1
port: 3306
dataname: gochect
3.引入包文件,开始读取包文件配置的数据:
SetConfigName : 设置yml文件配置名
AddConfigPath : 设置配置文件所在文件夹的名字
ReadInConfig : 获取文件是否存在(用于判断是否设置错误)
viper.Get : 获取单层文件(第一层)
viper.GetString : 获取多层文件(第二层乃至下级更多的层级)
实例代码:
package utils
import (
"fmt"
"github.com/spf13/viper"
"gorm.io/driver/mysql"
"gorm.io/gorm"
)
//定义变量
var DB *gorm.DB
func InitConfig () {
viper.SetConfigName("app")
viper.AddConfigPath("config")
err :=viper.ReadInConfig()
if err != nil{
fmt.Println("参数读取错误")
}
fmt.Println("数据库配置参数",viper.Get("mysql"))
fmt.Println("数据库配置参数1",viper.GetString("mysql.dsn"))
}
//此处特殊提醒一下:DB现在是提前定义的变量,该处切不使用 := 去初始化数据,这样就会一直实例化,导致会创建一个新的sqlDb变量,新的sqlDb会把全局变量sqlDb覆盖掉,最终会报错的
func IniMysql() {
DB, _ = gorm.Open(mysql.Open(viper.GetString("mysql.dsn")))
}
3.Swagger
相关的工具集会根据 OpenAPI 规范去生成各式各类的与接口相关联的内容,常见的流程是编写注解 =》调用生成库-》生成标准描述文件 =》生成/导入到对应的 Swagger 工具。
简单来说就是前后端调试的时候的API文档,该文档可以由Swag通过配置项直接生成
1.引包
GOLANG版本1.17以下:go get -u github.com/swaggo/swag/cmd/swag
GOLANG版本1.17以上:go install github.com/swaggo/swag/cmd/swag@latest
2.初始化
运行命令:swag init
结果(生成docs文件夹):
查看是否安装成功命令:swag -v
3.引入相关包
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
4.配置:
注意点:生成的docs包一定要引入(gochect是项目名称,在mod initi 初始化项目的时候设置的)
package route
import (
"github.com/gin-gonic/gin"
swaggerfiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
"gochect/docs"
"gochect/service"
)
func Route() *gin.Engine{
r := gin.Default()
//设置路径
docs.SwaggerInfo.BasePath =""
r.GET("/index",service.GetIndex)
//引入swag
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
return r
}
5.运行golang文件,查看是否成功
6.覆盖写入
入口文件配置示例:
// @title 测试用例
// @version 1.0
// @description 测试用例
方法文件配置:
// @Summary 首页
// @Tags 首页
// @Success 200 {string} Helloworld
// @Router /index [get]
到此为止Swag就已经成功了,那么应该有读者会问了,Swag的配置属性有哪些?下面就给介绍一下
通用API信息
注释 | 说明 | 示例 |
---|---|---|
title | 必填 应用程序的名称。 | // @title Swagger Example API |
version | 必填 提供应用程序API的版本。 | // @version 1.0 |
description | 应用程序的简短描述。 | // @description This is a sample server celler server. |
tag.name | 标签的名称。 | // @tag.name This is the name of the tag |
tag.description | 标签的描述。 | // @tag.description Cool Description |
tag.docs.url | 标签的外部文档的URL。 | // @tag.docs.url |
tag.docs.description | 标签的外部文档说明。 | // @tag.docs.description Best example documentation |
termsOfService | API的服务条款。 | // @termsOfService |
contact.name | 公开的API的联系信息。 | // @contact.name API Support |
contact.url | 联系信息的URL。 必须采用网址格式。 | // @contact.url |
contact.email | 联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。 | // @contact.email |
license.name | 必填 用于API的许可证名称。 | // @license.name Apache 2.0 |
license.url | 用于API的许可证的URL。 必须采用网址格式。 | // @license.url |
host | 运行API的主机(主机名或IP地址)。 | // @host localhost:8080 |
BasePath | 运行API的基本路径。 | // @BasePath /api/v1 |
accept | API 可以使用的 MIME 类型列表。 请注意,Accept 仅影响具有请求正文的操作,例如 POST、PUT 和 PATCH。 值必须如“”中所述。 | // @accept json |
produce | API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。 | // @produce json |
query.collection.format | 请求URI query里数组参数的默认格式:csv,multi,pipes,tsv,ssv。 如果未设置,则默认为csv。 | // @query.collection.format multi |
schemes | 用空格分隔的请求的传输协议。 | // @schemes http https |
externalDocs.description | Description of the external document. | // @externalDocs.description OpenAPI |
externalDocs.url | URL of the external document. | // @externalDocs.url |
x-name | 扩展的键必须以x-开头,并且只能使用json值 | // @x-example-key {"key": "value"} |
使用Markdown描述
如果文档中的短字符串不足以完整表达,或者需要展示图片,代码示例等类似的内容,则可能需要使用Markdown描述。要使用Markdown描述,请使用一下注释。
注释 | 说明 | 示例 |
---|---|---|
title | 必填 应用程序的名称。 | // @title Swagger Example API |
version | 必填 提供应用程序API的版本。 | // @version 1.0 |
description.markdown | 应用程序的简短描述。 从api.md 文件中解析。 这是@description 的替代用法。 | // @description.markdown No value needed, this parses the description from api.md |
tag.name | 标签的名称。 | // @tag.name This is the name of the tag |
tag.description.markdown | 标签说明,这是tag.description 的替代用法。 该描述将从名为tagname.md的 文件中读取。 | // @tag.description.markdown |
API操作
注释 | 描述 |
---|---|
description | 操作行为的详细说明。 |
description.markdown | 应用程序的简短描述。该描述将从名为endpointname.md 的文件中读取。 |
id | 用于标识操作的唯一字符串。在所有API操作中必须唯一。 |
tags | 每个API操作的标签列表,以逗号分隔。 |
summary | 该操作的简短摘要。 |
accept | API 可以使用的 MIME 类型列表。 请注意,Accept 仅影响具有请求正文的操作,例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。 |
produce | API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。 |
param | 用空格分隔的参数。param name ,param type ,data type ,is mandatory? ,comment attribute(optional) |
security | 每个API操作的安全性。 |
success | 以空格分隔的成功响应。return code ,{param type} ,data type ,comment |
failure | 以空格分隔的故障响应。return code ,{param type} ,data type ,comment |
response | 与success、failure作用相同 |
header | 以空格分隔的头字段。 return code ,{param type} ,data type ,comment |
router | 以空格分隔的路径定义。 path ,[httpMethod] |
x-name | 扩展字段必须以x- 开头,并且只能使用json值。 |
Mime类型
Alias | MIME Type |
---|---|
json | application/json |
xml | text/xml |
plain | text/plain |
html | text/html |
mpfd | multipart/form-data |
x-www-form-urlencoded | application/x-www-form-urlencoded |
json-api | application/vnd.api+json |
json-stream | application/x-json-stream |
octet-stream | application/octet-stream |
png | image/png |
jpeg | image/jpeg |
gif | image/gif |