Ginner

Based on the Gin framework, this project integrates commonly used web components and tools, and demonstrates a reasonable code organization structure to help users develop web back-end applications efficiently.

简体中文

Features

• Go Modules
• Project directories organization structure design and demonstration
• API and Service version control demonstration
• Configuration
  • Object-oriented configuration
  • Load configuration file from command line parameters
  • Support sub-projects(in cmd/) to use independent configuration file
• Logger
  • Separation of error log and access log
  • The log format, log level, log retention time, log rotation interval, log directory name can be customized
  • Support sub-projects(in cmd/) to use logger to log to independent log file
  • If the runmode is debug, the log will be output to the screen at the same time
• Error code system
  • For centralized managing error response information
• Swagger
  • If the runmode is debug, swagger will be automatically enabled
• Middlewares
  • JWT Authentication
    • Login: get JWT token by username and password
    • API Signature Authentication: Users need to apply for appKey and appSecret in advance
  • API Signature Authentication
    • HmacMd5
    • HmacSha1
    • HmacSha256
    • Md5
    • AES
    • RSA
  • Basic Auth
  • CORS
  • RequestID(TraceID)
  • Access log
  • User operation audit
  • Global panic catch and recover
  • Pprof
  • Limiter
    • Request rate limiter based on client ip
    • Global request rate limiter
  • ACL
    • IP allowlist
    • Server API allowlist
• Databases
  • Relation Database(GORM)
    • MySQL
    • MssSQL
    • PostgreSQL
    • Sqlite
  • NoSQL
    • MongoDB
  • Cache
    • Redis
    • RedisCluster
  • Time Series Database
    • InfluxDB
  • Search
    • Elasticsearch
  • MQ
    • Kafka
• Subproject demo
  • cmd/daemonprocess
  • cmd/sync-data-into-es
• Crontab: cron
• Go cache: cache2go
• Utils
  • Processlock: avoid errors caused by repeated execution of the program(process)
  • Live reloading gin server in development phase
  • Pagination
  • Redis mutex
  • Gomail
• Graceful restart or stop gin server
• Health check when the server starts
• SSL support
• Deployment
  • Dockerfile
  • Systemd
  • Supervisord
  • Simple manage script: service.sh

Deployment

First you need to change the current project name to your own:

git clone [email protected]:windvalley/ginner.git
cd ginner

# This will change the current project name `ginner` to your own project name.
./change_project_name.sh your-project-name

Normal

go build

# development
./your-project-name -c conf/dev.config.toml

# production
./your-project-name -c conf/config.toml

Or:

./build.sh

# start
./service.sh start

# restart
./service.sh restart

# graceful reload
./service.sh reload

# graceful stop
./service.sh stop

# check status
./service.sh status

If you are using the configuration file of the development environment, the output after the program is started as follows:

[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 image
docker build -t your-project-name .

# dev
docker run --name your-project-name -p80:8000 -d your-project-name ./ginner -c conf/dev.config.toml

# production
docker run --name your-project-name -p80:8000 -d your-project-name ./ginner -c conf/config.toml

Systemd

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

# reload the new service config file
sudo systemctl daemon-reload

# autostart after rebooting
sudo systemctl enable your-project-name

# start
sudo systemctl start your-project-name

# restart
sudo systemctl restart your-project-name

# graceful stop
sudo systemctl stop your-project-name

# check status
sudo systemctl status your-project-name -l

Supervisord

sudo cp supervisord.conf /etc/

# supervisord restart
sudo supervisorctl reload

# start
sudo supervisorctl start your-project-name

# graceful stop
sudo supervisorctl stop your-project-name

# restart
sudo supervisorctl restart your-project-name

# check status
sudo supervisorctl status your-project-name

License

This project is under the MIT License. See the LICENSE file for the full license text.