# gin项目模版

**Repository Path**: yternal/gin-project-template

## Basic Information

- **Project Name**: gin项目模版
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gin Web 项目模板

一个可直接用于新项目的 Go Web 模板，内置 Gin、GORM/Gen、PostgreSQL、Redis、Zap 日志、Goose 数据库迁移和 Docker 开发环境。

## 环境要求

- Go 1.26+
- Docker 与 Docker Compose
- Make

## 创建项目

复制本模板后，先替换 Go Module、应用名和端口：

```bash
make init \
  MODULE_NAME=github.com/acme/my-service \
  APP_NAME=my-service \
  PORT=8080
```

然后创建本地环境配置：

```bash
cp .env.example .env
cp configs/config.yaml.template configs/config.yaml
cp configs/config.development.yaml.template configs/config.development.yaml
cp configs/config.production.yaml.template configs/config.production.yaml
```

`make init` 会在配置文件不存在时自动从模板创建它们。按需修改 `.env` 和
`configs/*.yaml`；这些本地配置已被 Git 忽略，仓库只跟踪
`configs/*.yaml.template`。默认配置会连接本机 `5432` 端口的 PostgreSQL 和
`6379` 端口的 Redis。

### 配置生效规则

应用启动时按以下顺序加载配置，后加载的值会覆盖先加载的同名配置：

1. 程序内置默认值。
2. `configs/config.yaml`：必需的基础配置，文件不存在或 YAML 格式错误时启动失败。
3. `configs/config.<APP_ENV>.yaml`：可选的环境配置，只需填写需要覆盖的字段。
4. `APP_*` 环境变量：优先级最高。

`APP_ENV` 默认为 `development`，因此默认加载
`configs/config.development.yaml`；设置为 `production` 时加载
`configs/config.production.yaml`。目前支持 `development`、`test` 和
`production`。配置中的 `app.env` 最终也会被 `APP_ENV` 的值覆盖。

可通过环境变量覆盖以下配置：

| 环境变量 | 对应配置 |
| --- | --- |
| `APP_NAME` | `app.name` |
| `APP_HTTP_ADDR` | `http.addr` |
| `APP_HTTP_TRUSTED_PROXIES` | `http.trusted_proxies`，多个值以逗号分隔 |
| `APP_LOG_LEVEL` | `log.level` |
| `APP_DATABASE_DRIVER` | `database.driver` |
| `APP_DATABASE_DSN` | `database.dsn` |
| `APP_DATABASE_STARTUP_ATTEMPTS` | `database.startup_attempts` |
| `APP_DATABASE_STARTUP_BACKOFF` | `database.startup_backoff` |
| `APP_DATABASE_STARTUP_MAX_BACKOFF` | `database.startup_max_backoff` |
| `APP_DATABASE_STARTUP_TIMEOUT` | `database.startup_timeout` |
| `APP_REDIS_ENABLED` | `redis.enabled` |
| `APP_REDIS_ADDR` | `redis.addr` |
| `APP_REDIS_PASSWORD` | `redis.password` |
| `APP_REDIS_DB` | `redis.db` |
| `APP_REDIS_STARTUP_ATTEMPTS` | `redis.startup_attempts` |
| `APP_REDIS_STARTUP_BACKOFF` | `redis.startup_backoff` |
| `APP_REDIS_STARTUP_MAX_BACKOFF` | `redis.startup_max_backoff` |
| `APP_REDIS_STARTUP_TIMEOUT` | `redis.startup_timeout` |
| `APP_CORS_ORIGINS` | `cors.origins`，多个值以逗号分隔；空列表会同时禁用 CORS |

程序不会自动读取 `.env` 文件；本地运行前需要通过 `source .env` 将其导入当前
Shell，或者由容器、进程管理器及部署平台注入环境变量。全部配置合并后会统一校验，
例如生产环境必须提供 `database.dsn`。

启动时 PostgreSQL 默认最多尝试 5 次（1s 初始退避、8s 上限、每次 5s 超时），
启用的 Redis 默认最多尝试 5 次（500ms 初始退避、4s 上限、每次 2s 超时）。
两者均使用 50%–100% 抖动的有限指数退避，并会在启动 context 取消时立即停止。

## 本地启动

```bash
# 加载环境变量
set -a
source .env
set +a

# 启动 PostgreSQL、Redis 和 Nginx
make dev-up

# 初始化数据库
make migrate-up

# 启动应用
make run
```

启动后可访问：

- API 入口：`http://127.0.0.1:8088`
- 健康检查：`http://127.0.0.1:8088/healthz`
- 就绪检查：`http://127.0.0.1:8088/readyz`
- 版本信息：`http://127.0.0.1:8088/api/v1/version`

运行 `make dev-down` 可停止开发环境。

`/healthz` 只检查进程是否存活，不访问 PostgreSQL 或 Redis；`/readyz` 会检查
数据库以及已启用的 Redis。Kubernetes 的 liveness probe 应使用 `/healthz`，
readiness probe 应使用 `/readyz`。Docker Compose 也使用 `/readyz` 判断应用
是否可接收依赖感知的流量。

## 日常开发

所有 Makefile 命令的参数、依赖和注意事项，请查看 [Makefile 命令参考](docs/makefile-reference.md)。

### 检查代码

```bash
make check       # 格式、静态检查和单元测试
make check-all   # 额外运行集成测试、Schema 和生成代码检查
```

### 修改数据库

```bash
# 1. 创建迁移文件
make migration NAME=create_widgets

# 2. 编写迁移文件

# 3. 执行迁移
make migrate-up

# 4. 从数据库导出最新结构
make schema-dump

# 5. 重新生成 GORM 代码
make gen
```

应用启动时不会自动执行数据库迁移。请将迁移文件、`database/schema.sql`、生成代码和相关测试一起提交。

### 构建

```bash
make build

# 在本机交叉编译 Linux amd64 和 arm64 产物
make build-cross VERSION=v1.0.0
```

生成文件位于 `bin/`：

- `bin/server`：应用服务
- `bin/migrate`：数据库迁移工具
- `bin/linux-amd64/`、`bin/linux-arm64/`：交叉编译产物

构建并推送两个架构的 Docker 镜像：

```bash
make docker-login ACR_USERNAME=your-name
make docker-cross-push VERSION=v1.0.0
```

该命令推送 `amd64-v1.0.0` 和 `arm64-v1.0.0` 标签，并生成多架构
`latest` 标签。拉取 `latest` 时，Docker 会自动选择当前平台对应的镜像。

## 主要目录

```text
cmd/                 程序入口
configs/             环境配置模板和本地配置
database/            Schema 和迁移文件
internal/modules/    业务模块
internal/data/       GORM 生成代码
internal/platform/   数据库、缓存、日志等基础设施
```

业务模块在根包通过 `NewModule(Dependencies)` 完成内部装配，并实现统一的
`RouteRegistrar` 接口。新增模块只需加入 `internal/app` 的模块列表；模块之间
通过显式应用层接口协作，不直接访问彼此的 Repository 或数据表。`user` 示例
采用 `domain / application / adapter` 分层，简单的 `system` 模块保持轻量结构。