学习笔记

使用go进行web开发，前期经过一些选型，最终决定使用gin这个框架来做开发，gin和flask这类框架很像，一个文件就能起一个服务，但是当项目变得庞大复杂，一个文件是很难维护的，通常我们需要将其拆分为多个目录来存放代码，根据自己的需求实现各种mvc之类的模式。

pink-lady是根据我个人习惯整理而成的代码结构。开发时主要可以总结为ASM（apis services models）模式，开发时只需要关注这三个地方，主要流程是在apis中配置路由routes，编写路由处理方法，处理方法细分为apis接入层和可复用的services层，models定义db数据表结构。

pink-lady这个名字来源于gin，因为gin的名字应该是来源于martini，都是酒名，而pink lady是以gin酒作为基酒的国标鸡尾酒之一。

项目地址： https://github.com/axiaoxin/pink-lady

代码组织结构如下

> tree -I "vendor"
.
├── app                                          // 源码目录
│   ├── apis                                    // （开发时关注的地方）在这里新建包或者文件来编写你的API
│   │   ├── init.go                            // 存放一些默认的api
│   │   ├── init_test.go
│   │   ├── router                             // gin的router，可在这里注册中间件
│   │   │   ├── router.go
│   │   │   └── router_test.go
│   │   ├── routes.go                          // （开发时关注的地方）在这里注册你的路由
│   │   └── routes_test.go
│   ├── app.yaml                                // 配置文件
│   ├── docs                                    // swag生成的api文档目录
│   │   ├── docs.go
│   │   └── swagger
│   │       ├── swagger.json
│   │       └── swagger.yaml
│   ├── main.go                                 // main函数，运行一个可优雅停止的服务
│   ├── middleware                              // 存放中间件的目录，新加中间件应该放在这里
│   │   ├── errorhandler.go                    // 处理404和500为json返回的中间件
│   │   ├── errorhandler_test.go
│   │   ├── ginlogrus.go                       // 日志中间件，使用logrus打印gin的日志
│   │   ├── ginlogrus_test.go
│   │   ├── init.go
│   │   ├── requestid.go                       // 请求中生成requestid，可以gin的日志中打印
│   │   └── requestid_test.go
│   ├── models                                  // （开发时关注的地方）在这里新建你的model
│   │   ├── init.go                            // 提供一个BaseModel用来定义model
│   │   └── init_test.go
│   ├── services                                // （开发时关注的地方）在这里存放你可以复用的业务逻辑代码
│   │   ├── init.go
│   │   ├── init_test.go
│   │   └── retcode                            // 业务返回码在这里定义
│   │       ├── retcode.go
│   │       └── retcode_test.go
│   └── utils                                   // 在这里存放通用的业务无关的工具类方法
│       ├── endless.go                          // 提供优雅重启的服务
│       ├── gorequest.go                        // 提供一个好用的http客户端
│       ├── gorm.go                             // 提供一个orm
│       ├── gorm_test.go
│       ├── init.go
│       ├── jsontime.go                         // 提供一个可以自定义json时间字段的类型
│       ├── jsontime_test.go
│       ├── logrus.go                           // 提供一个好用的日志工具
│       ├── logrus_test.go
│       ├── pagination.go                       // 提供一个计算分页信息的工具
│       ├── pagination_test.go
│       ├── redis.go                            // 提供redis客户端
│       ├── redis_test.go
│       ├── response                            // 提供统一的json响应方法
│       │   ├── response.go
│       │   └── response_test.go
│       ├── testing.go                          // 提供一些单元测试会用到的方法
│       ├── viper.go                            // 提供一个解析配置的工具
│       └── viper_test.go
├── Gopkg.lock                                   // 依赖管理工具dep生成的文件
├── Gopkg.toml                                   // 依赖管理工具dep生成的文件
├── misc                                         // 这里存放各种工具类脚本
│   ├── pre-push.githook                        // 一个git hook用于push前跑测试
│   ├── README.md
│   ├── release.sh                              // 一个编译发布版本的工具脚本
│   └── supervisor.conf                         // supervisor配置示例
└── README.md

开发依赖以下程序，你需要先安装在你的机器上且能使用，安装方法参考他们的主页

• [Go >= 1.9] dep is a dependency management tool for Go. It requires Go 1.9 or newer to compile.
• [golang/dep] Go dependency management tool https://golang.github.io/dep/
• [swaggo/swag] Automatically generate RESTful API documentation with Swagger 2.0 for Go.
• [pilu/fresh] Build and (re)start go web apps after saving/creating/deleting source files.

pink-lady用到的依赖包：

• [spf13/viper] Go configuration with fangs
• [sirupsen/logrus] Structured, pluggable logging for Go.
• [fvbock/endless] Zero downtime restarts for go servers (Drop in replacement for http.ListenAndServe)
• [jinzhu/gorm] The fantastic ORM library for Golang, aims to be developer friendly http://gorm.io
• [satori/go.uuid] UUID package for Go
• [go-redis/redis] Type-safe Redis client for Golang https://godoc.org/github.com/go-redis/redis
• [swaggo/gin-swagger] gin middleware to automatically generate RESTful API documentation with Swagger 2.0.
• [gin-contrib/cors] Official CORS gin's middleware
• [gin-contrib/sentry] Middleware to integrate with sentry crash reporting.
• [alicebob/miniredis] Pure Go Redis server for Go unittests
• [parnurzeal/gorequest] GoRequest -- Simplified HTTP client ( inspired by nodejs SuperAgent ) http://parnurzeal.github.io/gorequest/

pink-lady的特性：

• 清晰的代码结构。
• 经过生产环境的检测。
• 灵活丰富的配置，可以轻松对server，日志，数据库，redis，sentry进行配置。
• 更加详细的按级别打印日志信息，使用logrus打印gin日志和gorm日志，请求日志自动包含requestid方便定位问题。
• 支持多种数据库操作，比如sqlite3, mysql, postgresql 和 sqlserver.
• 支持redis客户端连接，高可用sentinel和集群连接。
• 支持配置sentry自动收集panic日志信息。
• 优雅重启或停止服务，不会强行中断客户端的连接。
• 集成常用的工具包括第三方的gorequest等或者自定义的pagination等。
• 提供统一的json返回结构，统一返回包含code, message, data 字段的json.
• 提供易用的业务返回码
• 自动对404和500错误进行处理为json数据响应而不是错误页面。
• 支持自动根据注释生成API文档的能力
• 提供一个易用的发布工具misc/release.sh,根据提示输入信息即可万无一失的为你打包发布新版二进制文件

如何使用pink-lady进行web api开发？

1. Clone pink-lady 到你的gopath下的src目录即可开始你的开发:

   cd $(go env GOPATH)/src
   git clone git@github.com:axiaoxin/pink-lady.git
   cd pink-lady
   

   vendor目录已包含所有依赖包，安装所有依赖使用

   dep ensure
   

   在你的项目中新加依赖包请使用dep进行安装后再编写代码

   dep ensure --add xxxxxx
   

   如果你想修改项目位置到其他位置或其他名称，除了把mv pink-lady以外，还需要替换掉import中的路径:

   mv pink-lady GOPATH/src/XXX/YYY/ZZZ
   cd GOPATH/src/XXX/YYY/ZZZ/app
   sed -i  "s|pink-lady|XXX/YYY/ZZZ|g"  `grep "pink-lady" . -rl`
   

2. 准备好项目骨架后便可以开始进行开发了，在apis目录下编写你的api, 你可以在这里创建单文件或者子目录作为包来组织你的代码，写完逻辑handler后在 apis/routes.go 注册你的api，把handler注册到url上即可

3. 在app目录运行你的server：

   cd app
   go test ./...
   go run main.go
   

4.发布你的api server, 运行 misc/release.sh 将会要你根据提示自动构建二进制文件并打成tar.gz包，打包前会对代码进行version的升级，测试，生成api文档并为这次发布提交commit和打上tag

    cd misc
    ./release.sh

生成API文档的命令为：

cd app
swag init -g apis/init.go

你可以通过http://pink-lady:4869/x/apidocs/index.html访问到你的api文档，当然你要为pink-lady配置host以便不同的机器部署

开发建议

• 把API处理方法都放在app/apis目录下，可以是单文件或者包的形式，看具体情况，然后再app/apis/routes.go中统一注册你所有的路由。
• 新增中间件都放在app/middleware目录下, 统一在app/apis/router/router.go注册使用。
• 使用app/models/init.go中的BaseModel来定义你的model并以单文件或者包的形式放在 app/models目录下，如果需要自动migration，在model定义时的init函数中将model添加到models的MigrationModels中即可，参考demo
• 抽出可复用的业务逻辑代码以单文件或者包的形式统一存放到app/services目录下。
• 在app/services/retcode/retcode.go中统一定义业务返回码。
• 新增通用的业务无关的工具类方法统一存放在 app/utils 中。
• 新增其他工具类型的脚本或者其他文件统一存在在misc目录。
• 为你的代码编写单元测试和文档
• 集成Travis和go report
• 每次改完代码都要重启server才能生效，这里可以使用fresh进行动态reload，在app目录执行fresh命令即可在文件发生变更时自动reload server
• pink-lady中有一个不成熟的demo示例，你可以参考它来实现自己的api，当然你可以删掉他，删掉apis/demo services/demo models/demo即可