阿小信大人的头像
Talk is cheap. Show me the code. Linus Torvalds

pink-lady:Gin WebApp Project Skeleton2018-11-16 23:33

使用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

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

pink-lady用到的依赖包:

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即可

如果您觉得从我的分享中得到了帮助,并且希望我的博客持续发展下去,请点击支付宝捐赠,谢谢!

若非特别声明,文章均为阿小信的个人笔记,转载请注明出处。文章如有侵权内容,请联系我,我会及时删除。

#Golang#  
分享到:
阅读[183] 评论[0]

你可能也感兴趣的文章推荐

本文最近访客

网友52.*.*.237[火星]2018-12-16 19:02
网友111.*.*.93[火星]2018-12-16 18:45
网友14.*.*.9[广州]2018-12-16 17:45
网友220.*.*.123[火星]2018-12-16 17:07

发表评论