文章目录
- 导言
- 一、加载配置
- 二、初始化日志
- 三、初始化MySQL连接
- 四、初始化Redis连接
- 五、初始化gin框架内置的校验器使用的翻译器
- 六、注册路由
- 七、 启动服务
- 八、测试运行
- 九：注意事项
代码地址：https://gitee.com/lymgoforIT/bluebell
导言
有了前述知识的基础后，我们便可以开始搭建基本脚手架了。
脚手架应该包含如下信息：
- 较好的代码管理、即清晰的目录结构，层次分明。
- 配置文件管理和加载。
- 日志组件初始化和加载。
Redis初始化和加载。MySQL初始化和加载。- 路由拆分管理。
- 中间件使用。
- 服务启动。
有了脚手架之后，后续的CRUD就比较简单啦。
本文完成后总体目录结构如下
注意：我们主要关注的是后端逻辑，所以涉及前端的static和templates两个目录没有过多介绍，可以直接从代码仓库获取即可。
最关键的是main文件，毕竟它是整个程序的入口，我们的main文件应该足够清晰，让人一眼就能看出做了哪些事情，大致结构如下：
package main
func main() {
// 1. 加载配置
// 2. 初始化日志
// 3. 初始化MySQL连接
// 4. 初始化Redis连接
// 5. 初始化gin框架内置的校验器使用的翻译器
// 6. 注册路由
// 7. 启动服务（优雅关机和重启）
}
一、加载配置
首先我们应该定义一个config.yaml配置文件，将相关配置写到里面
config/config.yaml
name: "bluebell"
mode: "release"
port: 8084
version: "v0.0.1"
log:
level: "info"
filename: "web_app.log"
max_size: 200
max_age: 30
max_backups: 7
mysql:
host: "127.0.0.1"
port: 3306
user: "root"
password: "root"
dbname: "bluebell"
max_open_conns: 200
max_idle_conns: 50
redis:
host: "127.0.0.1"
port: 6379
password: ""
db: 0
pool_size: 100
由于我们后续是要将配置加载到一个全局结构体对象中，然后各个地方使用这个全局变量读取配置的，所以很自然的想到，我们应该定义对应的配置结构体，并提供一个全局变量以及相应的初始化函数。
setting/setting.go
package setting
import (
"fmt"
"github.com/fsnotify/fsnotify"
"github.com/spf13/viper"
)
var Conf = new(AppConfig)
type AppConfig struct {
Name string `mapstructure:"name"`
Mode string `mapstructure:"mode"`
Version string `mapstructure:"version"`
Port int `mapstructure:"port"`
*LogConfig `mapstructure:"log"`
*MySQLConfig `mapstructure:"mysql"`
*RedisConfig `mapstructure:"redis"`
}
type LogConfig struct {
Level string `mapstructure:"level"`
Filename string `mapstructure:"filename"`
MaxSize int `mapstructure:"max_size"`
MaxAge int `mapstructure:"max_age"`
MaxBackups int `mapstructure:"max_backups"`
}
type MySQLConfig struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
User string `mapstructure:"user"`
Password string `mapstructure:"password"`
DB string `mapstructure:"dbname"`
MaxOpenConns int `mapstructure:"max_open_conns"`
MaxIdleConns int `mapstructure:"max_idle_conns"`
}
type RedisConfig struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
Password string `mapstructure:"password"`
DB int `mapstructure:"db"`
PoolSize int `mapstructure:"pool_size"`
MinIdleConns int `mapstructure:"min_idle_conns"`
}
func Init(filePath string) (err error) {
// 方式1：直接指定配置文件路径（相对路径或者绝对路径）
// 相对路径：相对执行的可执行文件的相对路径
//viper.SetConfigFile("./conf/config.yaml")
// 绝对路径：系统中实际的文件路径
//viper.SetConfigFile("/Users/liwenzhou/Desktop/bluebell/conf/config.yaml")
// 方式2：指定配置文件名和配置文件的位置，viper自行查找可用的配置文件
// 配置文件名不需要带后缀
// 配置文件位置可配置多个
//viper.SetConfigName("config") // 指定配置文件名（不带后缀）
//viper.AddConfigPath(".") // 指定查找配置文件的路径（这里使用相对路径）
//viper.AddConfigPath("./conf") // 指定查找配置文件的路径（这里使用相对路径）
// 基本上是配合远程配置中心使用的，告诉viper当前的数据使用什么格式去解析
//viper.SetConfigType("json")
viper.SetConfigFile(filePath)
err = viper.ReadInConfig() // 读取配置信息到viper中
if err != nil {
fmt.Printf("viper.ReadInconfig failed,err:%v\n", err)
return
}
// 把读取到的配置信息反序列化到 Conf 全局变量中
if err := viper.Unmarshal(Conf); err != nil {
fmt.Printf("viper.Unmarshal failed,err:%v\n", err)
}
viper.WatchConfig()
viper.OnConfigChange(func(in fsnotify.Event) {
fmt.Println("配置文件修改了")
if err := viper.Unmarshal(Conf); err != nil {
fmt.Printf("viper.Unmarshal failed,err:%v\n", err)
}
})
return
}
二、初始化日志
我们该项目使用之前介绍的Zap作为日志组件，并会仿照Gin中的Logger和Recovery中间件，写自己的中间件替换掉Gin自带的。如下
logger/logger.go
package logger
import (
"bluebell/setting"
"net"
"net/http"
"net/http/httputil"
"os"
"runtime/debug"
"strings"
"time"
"github.com/gin-gonic/gin"
"github.com/natefinch/lumberjack"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)
var lg *zap.Logger
// Init 初始化lg
func Init(cfg *setting.LogConfig, mode string) (err error) {
writeSyncer := getLogWriter(cfg.Filename, cfg.MaxSize, cfg.MaxBackups, cfg.MaxAge)
encoder := getEncoder()
var l = new(zapcore.Level)
err = l.UnmarshalText([]byte(cfg.Level))
if err != nil {
return
}
var core zapcore.Core
if mode == "dev" {
// 进入开发模式，日志输出到终端
consoleEncoder := zapcore.NewConsoleEncoder(zap.NewDevelopmentEncoderConfig())
core = zapcore.NewTee(
zapcore.NewCore(encoder, writeSyncer, l),
zapcore.NewCore(consoleEncoder, zapcore.Lock(os.Stdout), zapcore.DebugLevel),
)
} else {
core = zapcore.NewCore(encoder, writeSyncer, l)
}
lg = zap.New(core, zap.AddCaller())
// 使用 lg 替换zap中的全局L，从而外部可以直接使用zap.L().Info记录日志，而不是logger.lg.Info
zap.ReplaceGlobals(lg)
zap.L().Info("init logger success")
return
}
func getEncoder() zapcore.Encoder {
encoderConfig := zap.NewProductionEncoderConfig()
encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
encoderConfig.TimeKey = "time"
encoderConfig.EncodeLevel = zapcore.CapitalLevelEncoder
encoderConfig.EncodeDuration = zapcore.SecondsDurationEncoder
encoderConfig.EncodeCaller = zapcore.ShortCallerEncoder
return zapcore.NewJSONEncoder(encoderConfig)
}
func getLogWriter(filename string, maxSize, maxBackup, maxAge int) zapcore.WriteSyncer {
lumberJackLogger := &lumberjack.Logger{
Filename: filename,
MaxSize: maxSize,
MaxBackups: maxBackup,
MaxAge: maxAge,
}
return zapcore.AddSync(lumberJackLogger)
}
// GinLogger 接收gin框架默认的日志
func GinLogger() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
path := c.Request.URL.Path
query := c.Request.URL.RawQuery
c.Next()
cost := time.Since(start)
lg.Info(path,
zap.Int("status", c.Writer.Status()),
zap.String("method", c.Request.Method),
zap.String("path", path),
zap.String("query", query),
zap.String("ip", c.ClientIP()),
zap.String("user-agent", c.Request.UserAgent()),
zap.String("errors", c.Errors.ByType(gin.ErrorTypePrivate).String()),
zap.Duration("cost", cost),
)
}
}
// GinRecovery recover掉项目可能出现的panic，并使用zap记录相关日志
func GinRecovery(stack bool) gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != any(nil) {
// Check for a broken connection, as it is not really a
// condition that warrants a panic stack trace.
var brokenPipe bool
if ne, ok := any(err).(*net.OpError); ok {
if se, ok := ne.Err.(*os.SyscallError); ok {
if strings.Contains(strings.ToLower(se.Error()), "broken pipe") || strings.Contains(strings.ToLower(se.Error()), "connection reset by peer") {
brokenPipe = true
}
}
}
httpRequest, _ := httputil.DumpRequest(c.Request, false)
if brokenPipe {
lg.Error(c.Request.URL.Path,
zap.Any("error", err),
zap.String("request", string(httpRequest)),
)
// If the connection is dead, we can't write a status to it.
c.Error(any(err).(error)) // nolint: errcheck
c.Abort()
return
}
if stack {
lg.Error("[Recovery from panic]",
zap.Any("error", err),
zap.String("request", string(httpRequest)),
zap.String("stack", string(debug.Stack())),
)
} else {
lg.Error("[Recovery from panic]",
zap.Any("error", err),
zap.String("request", string(httpRequest)),
)
}
c.AbortWithStatus(http.StatusInternalServerError)
}
}()
c.Next()
}
}
三、初始化MySQL连接
使用Gorm，初始化代码如下
dao/mysql/mysql.go
package mysql
import (
"bluebell/setting"
"fmt"
"gorm.io/driver/mysql"
"gorm.io/gorm"
)
var db *gorm.DB
func Init(cfg *setting.MySQLConfig) (err error) {
dsn := fmt.Sprintf("%s:%s@(%s:%d)/%s?charset=utf8mb4&parseTime=true&loc=Local", cfg.User, cfg.Password, cfg.Host, cfg.Port, cfg.DB)
db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
panic(any("failed to connect to db"))
}
sqlDB, err := db.DB()
if err != nil {
panic(any("create table err"))
}
// SetMaxIdleConns sets the maximum number of connections in the idle connection pool.
sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
// SetMaxOpenConns sets the maximum number of open connections to the database.
sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
return nil
}
四、初始化Redis连接
与初始化MySQL非常类似
dao/redis/redis.go
package redis
import (
"bluebell/setting"
"fmt"
"github.com/go-redis/redis"
)
var (
client * redis.Client
Nil = redis.Nil
)
func Init(cfg *setting.RedisConfig) (err error) {
client = redis.NewClient(&redis.Options{
Addr: fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
Password: cfg.Password, // no password set
DB: cfg.DB, // use default DB
PoolSize: cfg.PoolSize,
MinIdleConns: cfg.MinIdleConns,
})
// 注：使用Val()不会返回错误，出错时返回零值，使用Result则可以根据返回的error判断是否出错了
_, err = client.Ping().Result()
if err != nil {
fmt.Println("init redis failed")
return err
}
return nil
}
五、初始化gin框架内置的校验器使用的翻译器
由于我们会使用validator组件进行gin的参数校验，所以为了错误提示信息更为友好，需要初始化翻译器。
controller/validator.go
package controller
import (
"bluebell/models"
"fmt"
"reflect"
"strings"
"github.com/gin-gonic/gin/binding"
"github.com/go-playground/locales/en"
"github.com/go-playground/locales/zh"
ut "github.com/go-playground/universal-translator"
"github.com/go-playground/validator/v10"
enTranslations "github.com/go-playground/validator/v10/translations/en"
zhTranslations "github.com/go-playground/validator/v10/translations/zh"
)
// 定义一个全局翻译器T
var trans ut.Translator
// InitTrans 初始化翻译器
func InitTrans(locale string) (err error) {
// 修改gin框架中的Validator引擎属性，实现自定制
if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
// 注册一个获取json tag的自定义方法
v.RegisterTagNameFunc(func(fld reflect.StructField) string {
name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
if name == "-" {
return ""
}
return name
})
// 为SignUpParam注册自定义校验方法
v.RegisterStructValidation(SignUpParamStructLevelValidation, models.ParamSignUp{})
zhT := zh.New() // 中文翻译器
enT := en.New() // 英文翻译器
// 第一个参数是备用（fallback）的语言环境
// 后面的参数是应该支持的语言环境（支持多个）
// uni := ut.New(zhT, zhT) 也是可以的
uni := ut.New(enT, zhT, enT)
// locale 通常取决于 http 请求头的 'Accept-Language'
var ok bool
// 也可以使用 uni.FindTranslator(...) 传入多个locale进行查找
trans, ok = uni.GetTranslator(locale)
if !ok {
return fmt.Errorf("uni.GetTranslator(%s) failed", locale)
}
// 注册翻译器
switch locale {
case "en":
err = enTranslations.RegisterDefaultTranslations(v, trans)
case "zh":
err = zhTranslations.RegisterDefaultTranslations(v, trans)
default:
err = enTranslations.RegisterDefaultTranslations(v, trans)
}
return
}
return
}
// removeTopStruct 去除提示信息中的结构体名称
func removeTopStruct(fields map[string]string) map[string]string {
res := map[string]string{}
for field, err := range fields {
res[field[strings.Index(field, ".")+1:]] = err
}
return res
}
// SignUpParamStructLevelValidation 自定义SignUpParam结构体校验函数
func SignUpParamStructLevelValidation(sl validator.StructLevel) {
su := sl.Current().Interface().(models.ParamSignUp)
if su.Password != su.RePassword {
// 输出错误提示信息，最后一个参数就是传递的param
sl.ReportError(su.RePassword, "re_password", "RePassword", "eqfield", "password")
}
}
其中我们为注册参数ParamSignUp校验做了自定义校验，用到了注册参数，所以这里也把model定义一下。
models/params.go
package models
// ParamSignUp 注册请求参数
type ParamSignUp struct {
Username string `json:"username" binding:"required"`
Password string `json:"password" binding:"required"`
RePassword string `json:"re_password" binding:"required,eqfield=Password"`
}
六、注册路由
注册路由用到了我们之前介绍的路由拆分和管理技巧。
package router
import (
"bluebell/logger"
"net/http"
"github.com/gin-gonic/gin"
)
func SetupRouter(mode string) *gin.Engine {
if mode == gin.ReleaseMode {
gin.SetMode(gin.ReleaseMode) // gin 设置成发布模式
}
r := gin.New()
// 使用我们自定义的两个中间件
r.Use(logger.GinLogger(), logger.GinRecovery(true))
// 加载首页html文件
r.LoadHTMLFiles("./templates/index.html")
// 加载静态文件
r.Static("/static", "./static")
r.GET("/ping", func(c *gin.Context) {
c.String(http.StatusOK, "pong")
})
r.GET("/", func(c *gin.Context) {
c.HTML(http.StatusOK, "index.html", nil)
})
r.NoRoute(func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
"msg": "404",
})
})
return r
}
七、 启动服务
main.go
package main
import (
"bluebell/controller"
"bluebell/dao/mysql"
"bluebell/dao/redis"
"bluebell/logger"
"bluebell/router"
"bluebell/setting"
"fmt"
"os"
)
func main() {
if len(os.Args) < 2 {
fmt.Println("need config file. eg:bluebell config.yaml")
return
}
// 1. 加载配置
if err := setting.Init(os.Args[1]); err != nil {
fmt.Printf("load config failed,err:%v\n", err)
return
}
// 2. 初始化日志
if err := logger.Init(setting.Conf.LogConfig, setting.Conf.Mode); err != nil {
fmt.Printf("init logger failed,err:%v\n", err)
return
}
// 3. 初始化MySQL连接
if err := mysql.Init(setting.Conf.MySQLConfig); err != nil {
fmt.Printf("init mysql failed,err:%v\n", err)
}
// 4. 初始化Redis连接
if err := redis.Init(setting.Conf.RedisConfig); err != nil {
fmt.Printf("init redis failed,err:%v\n", err)
}
// 5. 初始化gin框架内置的校验器使用的翻译器
if err := controller.InitTrans("zh"); err != nil {
fmt.Printf("init validator trans failed, err:%v\n", err)
return
}
// 6. 注册路由
r := router.SetupRouter(setting.Conf.Mode)
// 7. 启动服务（优雅关机和重启）
err := r.Run(fmt.Sprintf(":%d", setting.Conf.Port))
if err != nil {
fmt.Printf("run server failed, err:%v\n", err)
return
}
}
八、测试运行
运行前需要先保证MySQL中已经建立了对应的bluebell库，然后Redis服务端时开启的。
首先我们需要使用go build编译项目，在项目路径下执行go build即可，编译成功会出现一个可执行文件，如下
随后我们传入配置文件路径执行，可以看到启动后，没有报错且光标一直在闪烁，便是项目启动成功且在8084端口监听了（可通过Ctrl+C退出程序）。此外，我们也能看到产生了日志文件web_app.log
通过浏览器访问也成功了
还可以访问一下首页看看，访问成功！只是目前还没有业务数据，所以是一个非常简单的空页面而已。
九：注意事项
项目中我们使用了os.Args接收参数，实际也可以使用flag。那么为什么要运行时传配置文件路径，而不是直接在代码中用相对路径写死呢？
原因是项目运行时的基准目录，是以执行运行程序所在目录为准的，也就是说，编译后产生了.exe文件，我们如何放到了其他目录下去执行，代码中写死配置文件读取目录的话可能就读不到了，因为路径不对了。但是让用户自己指定目录，在执行时保证指定路径下配置文件存在，就可以正常执行。
