Go Gin 系列二：初始化项目及公共库

2020年6月13日 319点热度 0人点赞 0条评论

思考

首先，在一个初始项目开始前，大家都要思考一下

程序的文本配置写在代码中，好吗？
API 的错误码硬编码在程序中，合适吗？
db 句柄谁都去Open，没有统一管理，好吗？
获取分页等公共参数，谁都自己写一套逻辑，好吗？

显然在较正规的项目中，这些问题的答案都是不可以，为了解决这些问题，我们挑选一款读写配置文件的库，目前比较火的有 viper，有兴趣你未来可以简单了解一下，没兴趣的话等以后接触到再说。

但是本系列选用 go-ini/ini ，它的中文文档。大家是必须需要要简单阅读它的文档，再接着完成后面的内容。

本文目标

编写一个简单的 API 错误码包。
完成一个 Demo 示例。
讲解 Demo 所涉及的知识点。

介绍和初始化项目

初始化项目目录

在前一章节中，我们初始化了一个 go-gin-example 项目，接下来我们需要继续新增如下目录结构：

go-gin-example/├── conf├── middleware├── models├── pkg├── routers└── runtime

conf：用于存储配置文件
middleware：应用中间件
models：应用数据库模型
pkg：第三方包
routers 路由逻辑处理
runtime：应用运行时数据

添加 Go Modules Replace

打开 go.mod 文件，新增 replace 配置项，如下：

module github.com/EDDYCJY/go-gin-example
go 1.13
require (...)
replace (		github.com/EDDYCJY/go-gin-example/pkg/setting => ~/go-application/go-gin-example/pkg/setting		github.com/EDDYCJY/go-gin-example/conf    	  => ~/go-application/go-gin-example/pkg/conf		github.com/EDDYCJY/go-gin-example/middleware  => ~/go-application/go-gin-example/middleware		github.com/EDDYCJY/go-gin-example/models 	  => ~/go-application/go-gin-example/models		github.com/EDDYCJY/go-gin-example/routers 	  => ~/go-application/go-gin-example/routers)

可能你会不理解为什么要特意跑来加 replace 配置项，首先你要看到我们使用的是完整的外部模块引用路径（github.com/EDDYCJY/go-gin-example/xxx），而这个模块还没推送到远程，是没有办法下载下来的，因此需要用 replace 将其指定读取本地的模块路径，这样子就可以解决本地模块读取的问题。

注：后续每新增一个本地应用目录，你都需要主动去 go.mod 文件里新增一条 replace（我不会提醒你），如果你漏了，那么编译时会出现报错，找不到那个模块。

初始项目数据库

新建 blog 数据库，编码为utf8_general_ci，在 blog 数据库下，新建以下表

1、标签表

CREATE TABLE `blog_tag` (  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,  `name` varchar(100) DEFAULT '' COMMENT '标签名称',  `created_on` int(10) unsigned DEFAULT '0' COMMENT '创建时间',  `created_by` varchar(100) DEFAULT '' COMMENT '创建人',  `modified_on` int(10) unsigned DEFAULT '0' COMMENT '修改时间',  `modified_by` varchar(100) DEFAULT '' COMMENT '修改人',  `deleted_on` int(10) unsigned DEFAULT '0',  `state` tinyint(3) unsigned DEFAULT '1' COMMENT '状态 0为禁用、1为启用',  PRIMARY KEY (`id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='文章标签管理';

2、文章表

CREATE TABLE `blog_article` (  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,  `tag_id` int(10) unsigned DEFAULT '0' COMMENT '标签ID',  `title` varchar(100) DEFAULT '' COMMENT '文章标题',  `desc` varchar(255) DEFAULT '' COMMENT '简述',  `content` text,  `created_on` int(11) DEFAULT NULL,  `created_by` varchar(100) DEFAULT '' COMMENT '创建人',  `modified_on` int(10) unsigned DEFAULT '0' COMMENT '修改时间',  `modified_by` varchar(255) DEFAULT '' COMMENT '修改人',  `deleted_on` int(10) unsigned DEFAULT '0',  `state` tinyint(3) unsigned DEFAULT '1' COMMENT '状态 0为禁用1为启用',  PRIMARY KEY (`id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='文章管理';

3、认证表

CREATE TABLE `blog_auth` (  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,  `username` varchar(50) DEFAULT '' COMMENT '账号',  `password` varchar(50) DEFAULT '' COMMENT '密码',  PRIMARY KEY (`id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8;
INSERT INTO `blog`.`blog_auth` (`id`, `username`, `password`) VALUES (null, 'test', 'test123456');

编写项目配置包

在 go-gin-example 应用目录下，拉取 go-ini/ini 的依赖包，如下：

$ go get -u github.com/go-ini/inigo: finding github.com/go-ini/ini v1.48.0go: downloading github.com/go-ini/ini v1.48.0go: extracting github.com/go-ini/ini v1.48.0

接下来我们需要编写基础的应用配置文件，在 go-gin-example 的conf目录下新建app.ini文件，写入内容：

#debug or releaseRUN_MODE = debug
[app]PAGE_SIZE = 10JWT_SECRET = 23347$040412
[server]HTTP_PORT = 8000READ_TIMEOUT = 60WRITE_TIMEOUT = 60
[database]TYPE = mysqlUSER = 数据库账号PASSWORD = 数据库密码#127.0.0.1:3306HOST = 数据库IP:数据库端口号NAME = blogTABLE_PREFIX = blog_

建立调用配置的setting模块，在go-gin-example的pkg目录下新建setting目录（注意新增 replace 配置），新建 setting.go 文件，写入内容：

package setting
import (	"log"	"time"
	"github.com/go-ini/ini")
var (	Cfg *ini.File
	RunMode string
	HTTPPort int	ReadTimeout time.Duration	WriteTimeout time.Duration
	PageSize int	JwtSecret string)
func init() {	var err error	Cfg, err = ini.Load("conf/app.ini")	if err != nil {		log.Fatalf("Fail to parse 'conf/app.ini': %v", err)	}
	LoadBase()	LoadServer()	LoadApp()}
func LoadBase() {	RunMode = Cfg.Section("").Key("RUN_MODE").MustString("debug")}
func LoadServer() {	sec, err := Cfg.GetSection("server")	if err != nil {		log.Fatalf("Fail to get section 'server': %v", err)	}
	HTTPPort = sec.Key("HTTP_PORT").MustInt(8000)	ReadTimeout = time.Duration(sec.Key("READ_TIMEOUT").MustInt(60)) * time.Second	WriteTimeout =  time.Duration(sec.Key("WRITE_TIMEOUT").MustInt(60)) * time.Second}
func LoadApp() {	sec, err := Cfg.GetSection("app")	if err != nil {		log.Fatalf("Fail to get section 'app': %v", err)	}
	JwtSecret = sec.Key("JWT_SECRET").MustString("!@)*#)!@U#@*!@!)")	PageSize = sec.Key("PAGE_SIZE").MustInt(10)}

当前的目录结构：

go-gin-example├── conf│   └── app.ini├── go.mod├── go.sum├── middleware├── models├── pkg│   └── setting.go├── routers└── runtime

编写 API 错误码包

建立错误码的e模块，在go-gin-example的pkg目录下新建e目录（注意新增 replace 配置），新建code.go和msg.go文件，写入内容：

1、 code.go：

package e
const (	SUCCESS = 200	ERROR = 500	INVALID_PARAMS = 400
	ERROR_EXIST_TAG = 10001	ERROR_NOT_EXIST_TAG = 10002	ERROR_NOT_EXIST_ARTICLE = 10003
	ERROR_AUTH_CHECK_TOKEN_FAIL = 20001	ERROR_AUTH_CHECK_TOKEN_TIMEOUT = 20002	ERROR_AUTH_TOKEN = 20003	ERROR_AUTH = 20004)

2、 msg.go：

package e
var MsgFlags = map[int]string {	SUCCESS : "ok",	ERROR : "fail",	INVALID_PARAMS : "请求参数错误",	ERROR_EXIST_TAG : "已存在该标签名称",	ERROR_NOT_EXIST_TAG : "该标签不存在",	ERROR_NOT_EXIST_ARTICLE : "该文章不存在",	ERROR_AUTH_CHECK_TOKEN_FAIL : "Token鉴权失败",	ERROR_AUTH_CHECK_TOKEN_TIMEOUT : "Token已超时",	ERROR_AUTH_TOKEN : "Token生成失败",	ERROR_AUTH : "Token错误",}
func GetMsg(code int) string {	msg, ok := MsgFlags[code]	if ok {		return msg	}
	return MsgFlags[ERROR]}

编写工具包

在go-gin-example的pkg目录下新建util目录（注意新增 replace 配置），并拉取com的依赖包，如下：

$ go get -u github.com/unknwon/com

编写分页页码的获取方法

在util目录下新建pagination.go，写入内容：

package util
import (	"github.com/gin-gonic/gin"	"github.com/unknwon/com"
	"github.com/EDDYCJY/go-gin-example/pkg/setting")
func GetPage(c *gin.Context) int {	result := 0	page, _ := com.StrTo(c.Query("page")).Int()    if page > 0 {        result = (page - 1) * setting.PageSize    }
    return result}

编写 models init

拉取gorm的依赖包，如下：

$ go get -u github.com/jinzhu/gorm

拉取mysql驱动的依赖包，如下：

$ go get -u github.com/go-sql-driver/mysql

完成后，在go-gin-example的models目录下新建models.go，用于models的初始化使用

package models
import (	"log"	"fmt"
	"github.com/jinzhu/gorm"	_ "github.com/jinzhu/gorm/dialects/mysql"
	"github.com/EDDYCJY/go-gin-example/pkg/setting")
var db *gorm.DB
type Model struct {	ID int `gorm:"primary_key" json:"id"`	CreatedOn int `json:"created_on"`	ModifiedOn int `json:"modified_on"`}
func init() {	var (		err error		dbType, dbName, user, password, host, tablePrefix string	)
	sec, err := setting.Cfg.GetSection("database")	if err != nil {		log.Fatal(2, "Fail to get section 'database': %v", err)	}
	dbType = sec.Key("TYPE").String()	dbName = sec.Key("NAME").String()	user = sec.Key("USER").String()	password = sec.Key("PASSWORD").String()	host = sec.Key("HOST").String()	tablePrefix = sec.Key("TABLE_PREFIX").String()
	db, err = gorm.Open(dbType, fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8&parseTime=True&loc=Local",		user,		password,		host,		dbName))
	if err != nil {		log.Println(err)	}
	gorm.DefaultTableNameHandler = func (db *gorm.DB, defaultTableName string) string  {	    return tablePrefix + defaultTableName;	}
	db.SingularTable(true)	db.LogMode(true)	db.DB().SetMaxIdleConns(10)	db.DB().SetMaxOpenConns(100)}
func CloseDB() {	defer db.Close()}

编写项目启动、路由文件

最基础的准备工作完成啦，让我们开始编写 Demo 吧！

编写 Demo

在go-gin-example下建立main.go作为启动文件（也就是main包），我们先写个Demo，帮助大家理解，写入文件内容：

package main
import (    "fmt"    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/EDDYCJY/go-gin-example/pkg/setting")
func main() {    router := gin.Default()    router.GET("/test", func(c *gin.Context) {		c.JSON(200, gin.H{			"message": "test",		})	})
	s := &http.Server{		Addr:           fmt.Sprintf(":%d", setting.HTTPPort),		Handler:        router,		ReadTimeout:    setting.ReadTimeout,		WriteTimeout:   setting.WriteTimeout,		MaxHeaderBytes: 1 << 20,	}
	s.ListenAndServe()}

执行go run main.go，查看命令行是否显示

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. - using env:	export GIN_MODE=release - using code:	gin.SetMode(gin.ReleaseMode)
[GIN-debug] GET    /test                     --> main.main.func1 (3 handlers)

在本机执行curl 127.0.0.1:8000/test，检查是否返回{"message":"test"}。

知识点

那么，我们来延伸一下 Demo 所涉及的知识点！

标准库

fmt：实现了类似 C 语言 printf 和 scanf 的格式化 I/O。格式化动作（'verb'）源自 C 语言但更简单
net/http：提供了 HTTP 客户端和服务端的实现

Gin

gin.Default()：返回 Gin 的type Engine struct{...}，里面包含RouterGroup，相当于创建一个路由Handlers，可以后期绑定各类的路由规则和函数、中间件等
router.GET(...){...}：创建不同的 HTTP 方法绑定到Handlers中，也支持 POST、PUT、DELETE、PATCH、OPTIONS、HEAD 等常用的 Restful 方法
gin.H{...}：就是一个map[string]interface{}
gin.Context：Context是gin中的上下文，它允许我们在中间件之间传递变量、管理流、验证 JSON 请求、响应 JSON 请求等，在gin中包含大量Context的方法，例如我们常用的DefaultQuery、Query、DefaultPostForm、PostForm等等

&http.Server 和 ListenAndServe？

1、http.Server：

type Server struct {    Addr    string    Handler Handler    TLSConfig *tls.Config    ReadTimeout time.Duration    ReadHeaderTimeout time.Duration    WriteTimeout time.Duration    IdleTimeout time.Duration    MaxHeaderBytes int    ConnState func(net.Conn, ConnState)    ErrorLog *log.Logger}

Addr：监听的 TCP 地址，格式为:8000
Handler：http 句柄，实质为ServeHTTP，用于处理程序响应 HTTP 请求
TLSConfig：安全传输层协议（TLS）的配置
ReadTimeout：允许读取的最大时间
ReadHeaderTimeout：允许读取请求头的最大时间
WriteTimeout：允许写入的最大时间
IdleTimeout：等待的最大时间
MaxHeaderBytes：请求头的最大字节数
ConnState：指定一个可选的回调函数，当客户端连接发生变化时调用
ErrorLog：指定一个可选的日志记录器，用于接收程序的意外行为和底层系统错误；如果未设置或为nil则默认以日志包的标准日志记录器完成（也就是在控制台输出）

2、 ListenAndServe：

func (srv *Server) ListenAndServe() error {    addr := srv.Addr    if addr == "" {        addr = ":http"    }    ln, err := net.Listen("tcp", addr)    if err != nil {        return err    }    return srv.Serve(tcpKeepAliveListener{ln.(*net.TCPListener)})}

开始监听服务，监听 TCP 网络地址，Addr 和调用应用程序处理连接上的请求。

我们在源码中看到Addr是调用我们在&http.Server中设置的参数，因此我们在设置时要用&，我们要改变参数的值，因为我们ListenAndServe和其他一些方法需要用到&http.Server中的参数，他们是相互影响的。

3、 http.ListenAndServe和连载一的r.Run()有区别吗？

我们看看r.Run的实现：

func (engine *Engine) Run(addr ...string) (err error) {    defer func() { debugPrintError(err) }()
    address := resolveAddress(addr)    debugPrint("Listening and serving HTTP on %s\n", address)    err = http.ListenAndServe(address, engine)    return}

通过分析源码，得知本质上没有区别，同时也得知了启动gin时的监听 debug 信息在这里输出。

4、为什么 Demo 里会有WARNING？

首先我们可以看下Default()的实现

// Default returns an Engine instance with the Logger and Recovery middleware already attached.func Default() *Engine {	debugPrintWARNINGDefault()	engine := New()	engine.Use(Logger(), Recovery())	return engine}

大家可以看到默认情况下，已经附加了日志、恢复中间件的引擎实例。并且在开头调用了debugPrintWARNINGDefault()，而它的实现就是输出该行日志

func debugPrintWARNINGDefault() {	debugPrint(`[WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.`)}

而另外一个Running in "debug" mode. Switch to "release" mode in production.，是运行模式原因，并不难理解，已在配置文件的管控下 :-)，运维人员随时就可以修改它的配置。

5、 Demo 的router.GET等路由规则可以不写在main包中吗？

我们发现router.GET等路由规则，在 Demo 中被编写在了main包中，感觉很奇怪，我们去抽离这部分逻辑！

在go-gin-example下routers目录新建router.go文件，写入内容：

package routers
import (    "github.com/gin-gonic/gin"
    "github.com/EDDYCJY/go-gin-example/pkg/setting")
func InitRouter() *gin.Engine {    r := gin.New()
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    gin.SetMode(setting.RunMode)
    r.GET("/test", func(c *gin.Context) {        c.JSON(200, gin.H{            "message": "test",        })    })
    return r}

修改main.go的文件内容：

package main
import (	"fmt"	"net/http"
	"github.com/EDDYCJY/go-gin-example/routers"	"github.com/EDDYCJY/go-gin-example/pkg/setting")
func main() {	router := routers.InitRouter()
	s := &http.Server{		Addr:           fmt.Sprintf(":%d", setting.HTTPPort),		Handler:        router,		ReadTimeout:    setting.ReadTimeout,		WriteTimeout:   setting.WriteTimeout,		MaxHeaderBytes: 1 << 20,	}
	s.ListenAndServe()}

当前目录结构：

go-gin-example/├── conf│   └── app.ini├── main.go├── middleware├── models│   └── models.go├── pkg│   ├── e│   │   ├── code.go│   │   └── msg.go│   ├── setting│   │   └── setting.go│   └── util│       └── pagination.go├── routers│   └── router.go├── runtime