gin-kit

中文

gin-kit 是一个基于 Gin 的 Go 后端基础项目脚手架，面向“新项目开箱即用”的场景设计。它保留了常见服务端项目最容易重复搭建的基础能力，让新业务可以直接在稳定骨架上继续开发。

内置能力

• Gin 路由与中间件链
• Wire 依赖注入
• Viper 配置加载与环境变量覆盖
• Zap + Lumberjack 日志
• MySQL + Redis + Elasticsearch 初始化
• PostgreSQL 备用接入实现
• 启动初始化器与周期任务 ticker
• pprof
• 优雅停机
• 优雅重启
• 事务封装

默认接口

• GET /health
• GET /ping
• GET /example
• POST /example

example 模块是一个最小示例，用来展示 api -> service -> biz -> data 的分层接线方式，不承载具体业务语义。

快速开始

1. 复制 configs/config.yaml.example 为 configs/config.yaml
2. 修改数据库、Redis、Elasticsearch 连接信息
3. 执行以下命令

make init
make tidy
make wire
make test
make run

如果本机没有 make，也可以直接执行：

go mod tidy
go generate ./cmd
go test ./...
go run ./cmd

数据库说明

• 当前默认启用的是 MySQL
• PostgreSQL 代码和配置项已经保留在脚手架中，但还没有切换成默认注入
• 如果新项目更偏向 PostgreSQL，可以把 Wire 注入从 NewMysqlClient 切换为 NewPgClient

pprof 与优雅重启

• pprof 已集成，通过 server.pprof.enabled 和 server.pprof.port 控制
• 优雅停机已集成，监听 SIGINT 和 SIGTERM
• 优雅重启已集成，监听 SIGHUP
• 收到 SIGHUP 后会拉起新进程并继承监听 socket，旧进程会在新进程就绪后退出
• 零停机重启基于 github.com/cloudflare/tableflip
• Linux 和 macOS 支持零停机重启；Windows 下会自动退化为仅优雅停机
• 如果要验证优雅重启，建议使用构建后的二进制，而不是 go run

项目目录

gin-kit/
├── api/
│   ├── example.go
│   └── health.go
├── cmd/
│   ├── main.go
│   ├── wire.go
│   └── wire_gen.go
├── configs/
│   ├── dev/
│   │   └── config.yaml
│   ├── prod/
│   │   └── config.yaml
│   ├── sit/
│   │   └── config.yaml
│   ├── config.yaml.example
│   ├── config.yaml.backup
│   └── config.yaml.prod
├── deploy/
│   └── README.md
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEVELOPMENT.md
│   ├── GRACEFUL_SHUTDOWN.md
│   ├── MAKEFILE.md
│   └── README.md
├── internal/
│   ├── biz/
│   │   ├── biz.go
│   │   ├── example.go
│   │   └── startup.go
│   ├── conf/
│   │   └── conf.go
│   ├── data/
│   │   ├── database/
│   │   │   ├── database.go
│   │   │   ├── db.go
│   │   │   ├── elasticsearch.go
│   │   │   ├── mysql.go
│   │   │   ├── postgres.go
│   │   │   ├── redis.go
│   │   │   └── transaction.go
│   │   ├── model/
│   │   │   ├── base.go
│   │   │   └── example.go
│   │   ├── data.go
│   │   └── example.go
│   ├── pkg/
│   │   ├── gormtype/
│   │   │   └── time.go
│   │   ├── response/
│   │   │   └── response.go
│   │   ├── startup/
│   │   │   ├── init.go
│   │   │   └── ticker.go
│   │   └── README.md
│   └── service/
│       ├── example.go
│       └── service.go
├── middleware/
│   └── middleware.go
├── pkg/
│   ├── const/
│   │   └── const.go
│   ├── logger/
│   │   └── logger.go
│   ├── tool/
│   │   ├── README.md
│   │   └── tool.go
│   └── README.md
├── router/
│   ├── app.go
│   └── router.go
├── scripts/
│   ├── sql/
│   │   └── init_postgres.sql
│   ├── init-config.ps1
│   └── kill-port.ps1
├── third_party/
│   └── README.md
├── .gitignore
├── LICENSE
├── Makefile
├── go.mod
├── go.sum
└── README.md

目录说明

• api/ 请求与响应 DTO 定义，保持轻量，不放业务逻辑。
• cmd/ 应用入口与 Wire 注入入口。
• configs/ 配置样例和不同环境的占位配置。
• docs/ 架构、开发、停机重启、Makefile 等文档说明。
• internal/biz/ 用例层，负责组合业务流程、封装事务边界、组织后台任务。
• internal/conf/ 配置加载入口。
• internal/data/ 仓储实现、数据库访问、模型定义。
• internal/pkg/ 仅供项目内部使用的基础能力。
• internal/service/ HTTP handler，负责请求绑定、参数校验、响应组织。
• middleware/ 请求链路中间件。
• pkg/ 可被多个模块复用的公共能力。
• router/ 路由注册与 Gin app 初始化。
• scripts/ 本地开发脚本与初始化 SQL。

推荐开发流程

1. 先在 api/ 定义输入输出结构
2. 在 internal/data/model/ 定义模型
3. 在 internal/data/ 实现 repo
4. 在 internal/biz/ 实现 use case
5. 在 internal/service/ 暴露 handler
6. 在 router/ 注册接口
7. 执行 make wire 和 make test

---

English

gin-kit is a Go backend project scaffold built on top of Gin. It is designed as a reusable starting point for new services, with the common infrastructure already wired in.

Built-in capabilities

• Gin routing and middleware chain
• Wire dependency injection
• Viper config loading and environment overrides
• Zap + Lumberjack logging
• MySQL + Redis + Elasticsearch initialization
• Optional PostgreSQL integration
• Startup initializer and background ticker tasks
• pprof
• Graceful shutdown
• Graceful restart
• Transaction wrapper

Default endpoints

• GET /health
• GET /ping
• GET /example
• POST /example

The example module is intentionally minimal and exists only to demonstrate the api -> service -> biz -> data layering pattern.

Quick start

1. Copy configs/config.yaml.example to configs/config.yaml
2. Update database, Redis, and Elasticsearch settings
3. Run:

make init
make tidy
make wire
make test
make run

If make is not available on your machine, you can use raw Go commands instead:

go mod tidy
go generate ./cmd
go test ./...
go run ./cmd

Database notes

• MySQL is the default active database client
• PostgreSQL code and config are preserved, but it is not the default injected client yet
• If a new project prefers PostgreSQL, switch the Wire binding from NewMysqlClient to NewPgClient

pprof and graceful restart

• pprof is integrated and controlled by server.pprof.enabled and server.pprof.port
• Graceful shutdown listens for SIGINT and SIGTERM
• Graceful restart listens for SIGHUP
• On restart, a child process inherits the listeners and the old process exits after the child becomes ready
• Zero-downtime restart is implemented with github.com/cloudflare/tableflip
• Linux and macOS support zero-downtime restarts; Windows falls back to graceful shutdown only
• Use a built binary instead of go run when verifying graceful restart behavior

Project layout

See the expanded tree above. The main structure is:

• api/ for DTOs
• cmd/ for the entrypoint and Wire
• internal/biz/ for use cases
• internal/data/ for repositories and models
• internal/service/ for HTTP handlers
• middleware/ for request middleware
• pkg/ for reusable shared packages
• router/ for route wiring
• configs/ for config templates
• docs/ for project documentation