Skip to content

Latest commit

 

History

History
238 lines (194 loc) · 9.63 KB

README_ZH.md

File metadata and controls

238 lines (194 loc) · 9.63 KB

Ginner Go Report Card Codacy Badge Quality Gate Status Go GoDoc License

Go Gin脚手架, 帮助用户高效地编写高质量的Web API.

主要特性

  • 项目依赖管理Go Modules
  • 项目的目录组织结构设计与示范
  • API与Service的版本控制示范
  • 配置文件组件
    • 采用面向对象配置文件包toml
    • 从命令行加载配置文件, 故可以灵活加载不同环境下的配置文件
    • 支持子项目(在cmd目录下)使用独立的配置文件
  • 日志记录组件
    • 访问日志文件与错误日志文件分离
    • 自定义日志目录名称、日志保留天数、日志轮转间隔时间、日志格式(json/txt)、日志级别
    • 支持子项目(在cmd目录下)使用该日志组件将日志写到子项目下独立的日志文件
    • runmode为debug时日志写入到文件的同时也输出到屏幕上
  • 错误码组件, 将返回用户的错误信息进行统一管理
  • Swagger文档
    • runmode为debug模式时启用Swagger文档
  • 路由中间件
    • JWT鉴权
      • 支持通过用户名和密码获取JWT的场景
      • 支持API签名验证的场景, 用户需要提前向服务方申请appKey和appSecret
    • API签名验证
      • HmacMd5加密
      • HmacSha1加密
      • HmacSha256加密
      • Md5组合加密
      • AES对称加密
      • RSA非对称加密
    • Basic Auth
    • 跨域资源共享(CORS)
    • 请求链路跟踪(RequestID)
    • 访问日志
    • 用户审计: 用户操作日志记录到数据库
    • Panic捕获与恢复
    • API性能分析
    • 限流
      • 根据用户IP访问频率进行限制
      • 服务端全局访问频率限制
    • 访问限制
      • IP白名单
      • 服务端API白名单
  • 数据库组件
    • 关系数据库(GORM)
      • MySQL
      • MssSQL
      • PostgreSQL
      • Sqlite
    • NoSQL
      • MongoDB
    • 缓存
      • Redis
      • RedisCluster
    • 时序数据库
      • InfluxDB
    • 搜索引擎
      • Elasticsearch
    • 消息队列
      • Kafka
  • 子项目demo
    • 后台常驻进程示例: cmd/daemonprocess
    • 同步数据到Elasticsearch程序示例: cmd/sync-data-into-es
  • 计划任务cron
  • 进程内缓存cache2go
  • 其他小工具(util)
    • 进程锁processlock: 防止程序被重复执行导致未知错误
    • 内置的实时reload工具, 用于开发阶段, 提升开发效率
    • 分页pagination
    • 实现redis分布式锁工具
    • 发送邮件gomail
  • 支持优雅地重启和停止
  • 服务健康检查
  • 支持开启HTTPS
  • 项目部署
    • 云原生支持, 提供Dockerfile
    • 简单的服务管理脚本: service.sh
    • Systemd
    • Supervisord

项目部署

首先将当前项目名称ginner, 改成你自己的项目名称:

git clone git@github.com:windvalley/ginner.git
cd ginner

# 执行完该脚本后, 当前Go项目的package名称将变更为your-project-name
./change_project_name.sh your-project-name

常规方式

go build

# 开发环境
./your-project-name -c conf/dev.config.toml

# 生产环境
./your-project-name -c conf/config.toml

或者使用本项目提供的服务脚本:

./build.sh

# 启动服务
./service.sh start

# 重启服务
./service.sh restart

# 优雅重启服务
./service.sh reload

# 优雅关闭服务
./service.sh stop

# 查看当前服务运行状态
./service.sh status

开发环境下, 程序启动后的输出效果如下所示:

[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    /debug/pprof/             --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/cmdline      --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/profile      --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] POST   /debug/pprof/symbol       --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/symbol       --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/trace        --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/allocs       --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/block        --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/goroutine    --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/heap         --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/mutex        --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /debug/pprof/threadcreate --> github.com/gin-contrib/pprof.pprofHandler.func1 (9 handlers)
[GIN-debug] GET    /doc/*any                 --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (9 handlers)
[GIN-debug] GET    /s/*filepath              --> github.com/gin-gonic/gin.(*RouterGroup).createStaticHandler.func1 (9 handlers)
[GIN-debug] HEAD   /s/*filepath              --> github.com/gin-gonic/gin.(*RouterGroup).createStaticHandler.func1 (9 handlers)
[GIN-debug] GET    /status                   --> ginner/router.urls.func1 (9 handlers)
[GIN-debug] GET    /ping                     --> ginner/router.urls.func2 (9 handlers)
[GIN-debug] POST   /login                    --> ginner/api/v1.Login (9 handlers)
[GIN-debug] GET    /login                    --> ginner/api/v1.Login (9 handlers)
[GIN-debug] POST   /v1/users                 --> ginner/api/v1.CreateUser (9 handlers)
[GIN-debug] GET    /v1/users/:username       --> ginner/api/v1.GetUser (11 handlers)
[GIN-debug] POST   /v1/users/:username       --> ginner/api/v1.GetUser (11 handlers)
[GIN-debug] POST   /v2/users                 --> ginner/api/v2.CreateUser (9 handlers)
[GIN-debug] GET    /v2/users/:username       --> ginner/api/v2.GetUser (11 handlers)
[GIN-debug] POST   /v2/users/:username       --> ginner/api/v2.GetUser (11 handlers)
[GIN-debug] GET    /v1/sign-demo             --> ginner/api/v1.SignatureDemo (10 handlers)
[GIN-debug] GET    /v1/basic-auth-demo       --> ginner/api/v1.BasicAuthDemo (10 handlers)
[GIN-debug] GET    /v1/handle-dbs-demo/kafka --> ginner/api/v1.HandleKafkaDemo (9 handlers)
[GIN-debug] POST   /v1/handle-dbs-demo/influxdb --> ginner/api/v1.HandleInfluxdbDemo (9 handlers)
[GIN-debug] GET    /v1/handle-dbs-demo/mongodb --> ginner/api/v1.HandleMongodbDemo (9 handlers)
[GIN-debug] GET    /v1/handle-dbs-demo/elasticsearch --> ginner/api/v1.FilterRecordsFromES (9 handlers)
[Endless-debug] current pid is 43627
[Endless-debug] server port is :8000
DEBU[0000] checking url: http://127.0.0.1:8000/ping
INFO[0000] accesslog                                     client_ip=127.0.0.1 http_status=200 latency_time=2.6493e-05 request_body= request_id= request_method=GET request_proto=HTTP/1.1 request_referer= request_ua=Go-http-client/1.1 request_uri=/ping response_code= response_msg= username=guest
[GIN] 2020/12/18 - 17:17:06 | 200 |     772.603µs |       127.0.0.1 | GET      "/ping"
DEBU[0000] server(43627) started

容器方式

# 创建项目的容器镜像
docker build -t your-project-name .

# 开发环境下运行容器
docker run --name your-project-name -p80:8000 -d your-project-name ./ginner -c conf/dev.config.toml

# 生产环境下运行容器
docker run --name your-project-name -p80:8000 -d your-project-name ./ginner -c conf/config.toml

Systemd

CentOS7+系统下建议使用Systemd管理服务.

sudo cp your-project-name.service /usr/lib/systemd/system/

# 加载新的服务配置文件
sudo systemctl daemon-reload

# 开机自动启动服务
sudo systemctl enable your-project-name

# 启动服务
sudo systemctl start your-project-name

# 重启服务
sudo systemctl restart your-project-name

# 优雅关闭服务
sudo systemctl stop your-project-name

# 查看当前服务运行状态
sudo systemctl status your-project-name -l

Supervisord

非CentOS7+系统下建议使用Supervisord管理服务.

sudo cp supervisord.conf /etc/

# 重启supervisord来加载新配置
sudo supervisorctl reload

# 启动服务
sudo supervisorctl start your-project-name

# 优雅关闭服务
sudo supervisorctl stop your-project-name

# 重启服务
sudo supervisorctl restart your-project-name

# 查看当前服务运行状态
sudo supervisorctl status your-project-name

授权许可

本项目采用MIT开源授权许可证, 完整的授权说明已放置在LICENSE文件中.