首页

pink-lady是一个golang gin的web开发模板

pink-lady

proj-icon

go report card version-badge license issues PRs Welcome

Pinklady is a template project of gin app, which encapsulates mysql, redis, logging, viper, swagger, middlewares and other common components.

pink-lady 是基于 Golang web 开发框架 gin 来进行 HTTP API 开发的示例项目,新建项目时可以使用它作为项目模板。

之所以叫 pink-lady 首先字面意思就是红粉佳人或粉红女郎,有这个性感的名字相信你更会好好对你的代码负责。 其次,因为 gin 就是国外六大类烈酒之一的金酒,是近百年来调制鸡尾酒时最常使用的基酒,其配方多达千种以上, 而 pink lady 是以 gin 作 base 的国标鸡尾酒之一,在这里 pink-lady 则是以 gin 作 base 的代码骨架模板之一

使用 pink-lady 模板创建项目

点击 https://github.com/axiaoxin-com/pink-lady/generate 创建你的 github 项目(使用该方式创建项目时,如需修改项目名称需手动修改)

或者手动本地创建(如想自定义项目名,推荐使用该方式):

bash <(curl -s https://raw.githubusercontent.com/axiaoxin-com/pink-lady/master/misc/scripts/new_project.sh)
    

特性

使用 pink-lady/webserver 3 步组装一个 WEB 应用

  1. 确认配置文件正确。 配置文件必须满足能解析出指定的内容,复制或修改 config.default.toml 中的配置项
  2. 创建自定义中间件的 gin app NewGinEngine (可选)
  3. 运行 web 应用服务器 Run。 需传入 gin app 和在该 app 上注册 URL 路由注册函数

实现代码在src路径下,在 pink-lady 模板项目下,你只需关注如何实现你的业务逻辑,不用考虑如何组织项目结构和集成一些通用功能,比如数据库的连接封装,配置文件的读取,swagger 文档生成,统一的 JSON 返回结果,错误码定义,集成 Sentry 等等。

你可以在routes路径下实现你的 api,并在 routes/routes.goRoutes 函数中注册 URL 即可。外部第三方服务放在 services 包中进行加载或初始化。数据库模型相关定义放到 models 包中便于复用。

关于 gin

gin 框架源码图解

gin_arch.svg

gin 中间件原理解析

https://github.com/axiaoxin/axiaoxin/issues/17

开发环境搭建

安装 swagger api 文档生成工具 swag

go get -u github.com/swaggo/swag/cmd/swag
    

在项目根目录中执行以下命令会在 routes 目录中生成 api 文档

swag init --dir ./ --generalInfo routes/routes.go --propertyStrategy snakecase --output ./routes/docs
    

api 文档地址: http://localhost:4869/x/apidocs/index.html

服务启动时如果环境变量设置了 DISABLE_GIN_SWAGGER 会关闭 api 文档。 首次访问需经过 Basic 认证登录,登录账号密码可通过配置修改,默认为 admin admin

swag 中文文档: https://github.com/swaggo/swag/blob/master/README_zh-CN.md

配置文件

服务通过 viper 加载配置文件, viper 支持的配置文件格式都可以使用。

服务启动时默认加载当前目录的 config.default.toml

服务启动时可以通过以下参数指定其他配置文件:

只支持从1个目录读取1个配置文件。

建议:在开发自己的服务时,复制当前目录的 toml 配置创建一份新的配置,再在其上进行修改或新增配置,然后通过指定参数加载自己的配置。

日志打印

使用 logging 的方法打印带 trace id 的日志,可通过配置文件中 [logging] 下的配置项进行相关设置。

配置 sentry dsn 后,Error 级别以上的日志会被自动采集到 Sentry 便于错误发现与定位。

API 开发

使用 pink-lady 开发 web api 服务,你只需实现 gin 的 HandlerFunc 并在 routes/routes.goRoutes 函数中注册到对应的 URL 上即可。

api 中使用 c.Error(err) 会将 err 保存到 context 中,打印访问日志时会以 Error 级别自动打印错误信息。避免同一类错误打印多次日志影响问题定位效率。

手动完整的启动服务命令:

go run main.go -p . -c config.default -t toml
    

编译:

go generate
CGO_ENABLED=0 GOOS=linux go build -ldflags "-X github.com/axiaoxin-com/pink-lady/routes.BuildID=${buildid}" -o pink-lady
    

i18n国际化支持集成方法

对golang代码中需要进行翻译的文字使用webserver.CtxI18n(c, "文字")I18nString("文字")包裹,对网页模板中的翻译文字使用 文字包裹。具体的使用示例可以参考demo主页代码

# 自动提取需要翻译文字生成翻译模板
./i18n.sh

# 打开对应路径(默认为`statics/i18n`)下的po文件进行翻译,msgid对应的msgstr改为对应语言即可