go-sail

README

简体中文 | English

go-sail是什么？

go-sail是轻量的渐进式golang工程目录，它并不是一个框架，而是站在巨人的肩膀上，将所需的组件适当整理，有机结合， 在保证生产可用的前提下做到尽可能精简整洁的项目工程，更多的是一种想法。使用子命令的方式，实现功能模块/服务的拆分，通过配置中心完成服务注册与自动发现。从单体架构向微服务时代迈进。
go-sail user启动用户服务，go-sail order启动订单服务，……
正如它的名字一般，你可以把它视作自己在golang生态的一个开始。go-sail将助力你从轻出发，扬帆起航。

安装

go-sail cli

功能特点

Http接口

基于gin-gonic/ginhttp框架，具有轻量且高性能的特性，实现基本的路由注册、参数绑定、中间件挂载功能。

• 路由注册

r := gin.Default()
r.GET("/say-hello", handler.SayHello)

• 参数绑定

var (
    form request.SayHello
    resp response.SayHello
)
if err := c.ShouldBind(&form); err != nil {
    api.New(c).Assemble(constants.ErrRequestParamsInvalid, nil).Send()
    return
}

• 表单验证

var (
    form request.SayHello
    resp response.SayHello
)
if errorCode, err := form.Validator(); err != nil {
    api.New(c).Assemble(errorCode, nil, err.Error()).Send()
    return
}

• 统一返回

import "github.com/keepchen/go-sail/v2/pkg/common/http/api"

//根据业务错误码自动设置http状态码
api.New(c).Assemble(constants.ErrNone, anyResponseData).Send() // <- 200
api.New(c).Assemble(constants.ErrRequestParamsInvalid, nil).Send() // <- 400
api.New(c).Assemble(constants.ErrInternalSeverError, nil).Send() // <- 500

//指定http状态码
api.New(c).Assemble(constants.ErrInternalSeverError, nil).SendWithCode(400) // <- 400

//自定义返回消息提示
api.New(c).Assemble(constants.ErrInternalSeverError, nil, "Whoops!Looks like something went wrong.").SendWithCode(400) // <- 400

• 基于路由中间件的日志请求参数打印、允许跨域、Prometheus指标记录

//全局打印请求载荷、放行跨域请求、写入Prometheus exporter
r.Use(mdlw.PrintRequestPayload(), mdlw.WithCors(allowHeaders), mdlw.PrometheusExporter())

日志组件

go-sail基于uber/zap的日志类库和natefinch/lumberjack日志轮转类库，实现了按模块、分文件的日志记录功能，并支持配置文件启用基于redis list 的logstash导入方案。

//::初始化日志组件
logger.InitLoggerZap(config.GetGlobalConfig().Logger, "appName")

//::初始化日志组件（定义不同模块）
logger.InitLoggerZap(config.GetGlobalConfig().Logger, "appName", "api", "cron", "db")

//调用日志组件
logger.GetLogger().Info("hello~")

logger.GetLogger("api").Info("中间件:打印请求载荷", zap.Any("value", string(dump)))

logger.GetLogger("db").Error("数据库操作:CreateUserAndWallet:错误",
zap.Any("value", logger.MarshalInterfaceValue(userAndWallet)), zap.Errors("errors", []error{err}))

数据库组件

go-sail基于gorm.io/gorm的数据库类库，实现了读写分离功能。得益于gorm丰富的driver支持，go-sail支持mysql、sqlserver、postgresql、sqlite、clickhouse数据库操作。

import "github.com/keepchen/go-sail/v2/pkg/lib/db"

dbInstance := db.GetInstance()
dbR := dbInstance.R // <- 读实例
dbW := dbInstance.W // <- 写实例

err := dbR.Where(...).First(...).Error
err := dbW.Where(...).Updates(...).Error

缓存组件

go-sail基于go-redis/redis的redis类库，实现了对redis单实例和集群访问功能。

import "github.com/keepchen/go-sail/v2/pkg/lib/redis"

redisInstance := redis.GetInstance()
redisInstance.Set(context.Background(), key, string(value), expired).Result()

redisClusterInstacne := redis.GetClusterInstance()
redisClusterInstacne.Set(context.Background(), key, string(value), expired).Result()

配置中心

go-sail基于nacos-group/nacos-sdk-go的配置中心类库，集成了配置热更、服务注册与发现功能。

文档工具

go-sail基于swaggo/swag工具，实现了openapi文档生成功能。同时，go-sail提供了两种文档UI工具供你选择：
1.基于swaggo/gin-swagger类库的Swagger UI

2.基于Redocly/redoc工具的Redoc UI

持续集成

go-sail工程使用harness/droneCI/CD工具，实现对工程项目的自动化测试、集成与发布。参考.drone.yml文件配置。关于droneci工具的部署和使用，如果你感兴趣， 请移步至 GitLab+Drone使用体验。

构建与部署

go-sail提供了Dockerfiledocker镜像构建脚本，同时也提供了快速构建命令(shell命令)，帮助你快速方便的完成镜像构建。如需镜像仓库， 可以参考keepchen/docker-compose中关于harbor搭建的相关内容。 关于工程服务的快速启动，可以参考工程目录下的docker-compose.yml。

工程依赖

组件/类库

• spf13/cobra
• gin-gonic/gin
• swaggo/gin-swagger
• gorm.io/gorm
• go.uber.org/zap
• go-redis/redis
• jinzhu/configor
• stretchr/testify
• natefinch/lumberjack
• prometheus/client_golang
• nacos-group/nacos-sdk-go (可选)
• golang-jwt/jwt (可选)

命令行工具

• swag (version>=1.8.4)
• redoc-cli (version=latest)
• golangci-lint (version>=1.47.0)

如何使用？

golang版本

version >= 1.18

启动服务

在启动服务前，需要搭建必要依赖服务，如mysql数据库和redis缓存。为了帮助你快速的将服务运行起来，go-sail提供了基于docker-compose的基础服务启动脚本。 具体内容参考ecosystem目录下的相关内容。
配置文件中的ip地址是随机样例，实际值请修改成你自己的ip地址（请不要使用127.0.0.1）。

• mysql服务

cd ecosystem/docker-compose/mysql

docker-compose up -d

命令执行后，将启动mysql服务，监听33060端口，账号/密码为：root/root。

• redis服务

命令执行前，请将ecosystem/docker-compose/redis/docker-compose.yml中的192.168.224.114全局替换为你自己的ip地址。

cd ecosystem/docker-compose/redis

docker-compose up -d

命令执行后，将启动redis集群服务，集群以cluster模式运行，监听端口范围：6379~6384，认证密码为：changeme。

• nacos服务（可选）

cd ecosystem/docker-compose/nacos

docker-compose up -d

命令执行后，将启动mysql服务和nacos服务，这里的mysql服务是独立的服务，旨在仅对nacos提供存储服务；nacos以standalone模式运行，账号/密码为：nacos/nacos。 浏览器访问localhost:8848/nacos，输入账号密码即可进入控制台。
创建命名空间和配置文件：
1.进入命名空间，点击新增命名空间，在命名空间名的输入框中输入go-sail-user，描述输入框中输入go-sail user服务，点击确定保存。
2.进入配置管理>配置列表，在右侧选择go-sail-user命名空间，点击右侧的+号新增配置。在Data ID输入框中输入go-sail-user.yml，在group输入框中输入go-sail， 配置格式选择YAML，然后将config-user.sample.yml中的内容复制并粘贴到配置内容文本域中，点击发布。

记得将配置内容中的ip地址全局替换为你自己的ip地址。

3.回到命名空间列表，记录下go-sail-user的命名空间id。
4.设置环境变量并启动服务：

export nacosAddrs=<nacos服务的地址> # 如：192.168.224.114:8848
export nacosNamespaceID=<go-sail-user的命名空间id>

go mod tidy

go run main.go user

5.如果你不想使用nacos，也可以从本地配置文件启动。

如果不从nacos读取配置启动服务，go-sail不会将服务注册到nacos中。

go mod tidy

go run main.go user -c ./config-user.sample.yml

访问页面：

• Swagger ui(debug=true)
  http://localhost:8080/swagger/index.html
• Redoc ui(debug=true)
  http://localhost:8080/redoc/apidoc.html
• Prometheus metrics
  http://localhost:1910/metrics
• pprof(debug=true)
  http://localhost:8080/debug/pprof

命令脚手架

• 生成openapi

如果你的系统是Linux或MacOS，可直接使用make命令，更多指令请参考Makefile文件。

make gen-swag-user

• 构建镜像

docker build --tag go-sail:v1.0.0 .

• 本地构建

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./go-sail

其他插件

README.md

使用案例