# go-web-template

**Repository Path**: liu_zy_developer/go-web-template

## Basic Information

- **Project Name**: go-web-template
- **Description**: gin初始化模板
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-03-28
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go Web 模板

本项目是可直接用于商用项目起步的 Go Web 模板，目标是解决“能跑但不可维护”的常见问题，提供统一的分层结构、配置体系、日志体系、错误体系、可选基础设施模块，以及可复用的初始化工具 `gtpl init`。

## 项目定位

1. 适用于中后台、BFF、通用 Web 服务。
2. 强调可维护、可扩展、可排障，不是演示级最小样例。
3. 通过统一规范减少多人协作中的结构漂移和重复造轮子。
4. 初始化后可直接进入业务开发，不需要重复搭建基础设施。

## 技术栈

1. Go 1.25（模板生成时可写入 `--go 1.23.0` 与 `--toolchain go1.23.10`）
2. `gin-gonic/gin`
3. `go.uber.org/fx`
4. `spf13/viper`
5. `go.uber.org/zap`
6. `gopkg.in/natefinch/lumberjack.v2`
7. `gorm.io/gorm` + `gorm.io/driver/mysql`
8. `github.com/redis/go-redis/v9`
9. `github.com/IBM/sarama`
10. `github.com/go-resty/resty/v2`
11. `github.com/golang-jwt/jwt/v5`
12. `github.com/swaggo/swag` + `github.com/swaggo/gin-swagger`
13. `github.com/spf13/cobra`

## 目录结构

```text
.
├─ main.go
├─ go.mod
├─ go.sum
├─ Makefile
├─ Dockerfile
├─ README.md
├─ configs/
├─ docs/
├─ cmd/
│  └─ gtpl/
├─ internal/
│  ├─ app/
│  ├─ infra/
│  ├─ transport/
│  ├─ service/
│  ├─ repository/
│  ├─ client/
│  ├─ apperr/
│  ├─ constant/
│  ├─ enum/
│  ├─ util/
│  └─ scaffold/
├─ tests/
│  ├─ unit/
│  ├─ integration/
│  └─ e2e/
└─ deploy/
   └─ docker-compose/
```

## 本地启动

### 1. 依赖编排校验

```bash
docker compose -f deploy/docker-compose/dev-deps.yaml config
```

### 2. 启动依赖（按需）

```bash
docker compose -f deploy/docker-compose/dev-deps.yaml up -d
```

### 3. 启动应用

```bash
go run .
```

## 多环境构建

环境由 `BuildEnv` 控制，定义在 `internal/infra/config/build_env.go`。

### 示例：构建 test 环境

```bash
go build -ldflags "-X go-web-template/internal/infra/config.BuildEnv=test" .
```

### 示例：构建 prod 环境

```bash
go build -ldflags "-X go-web-template/internal/infra/config.BuildEnv=prod" .
```

当 `BuildEnv` 为空时，默认读取 `configs/config_env.yaml` 选择实际环境。

## 配置说明

配置文件位于 `configs/`：

1. `config_env.yaml`：默认环境选择
2. `config_test.yaml`：测试环境
3. `config_prod.yaml`：生产环境

关键配置模块：

1. `app`：应用标识与环境
2. `web`：监听地址、端口、超时
3. `log`：应用日志与访问日志
4. `mysql`：MySQL 初始化与连接池
5. `redis`：Redis 初始化、连接池与 key 规范
6. `kafka`：Producer、Consumer、提交策略、失败策略、幂等
7. `jwt`：签发与解析
8. `swagger`：文档入口开关与路径

## 模块说明

`--with` 支持模块：

1. `mysql`
2. `redis`
3. `kafka`
4. `jwt`
5. `swagger`

模块行为：

1. 未选择模块：不生成对应实现与测试路径。
2. 已选择模块：生成完整可编译代码、配置项和装配代码。
3. 选择 `kafka` 时必须同时选择 `redis`（用于幂等能力）。

## gtpl 初始化工具

### 命令格式

```bash
go run ./cmd/gtpl init \
  --name demo-order \
  --module example.com/demo-order \
  --go 1.23.0 \
  --toolchain go1.23.10 \
  --with mysql,redis,kafka,jwt,swagger
```

### 初始化后建议步骤

```bash
cd demo-order
go mod tidy
go build ./...
go test ./...
```

## 使用 go build 编译可执行文件

以下示例基于 Windows。

### 1. 编译模板服务可执行文件

在项目根目录执行：

```bash
go build -o bin/server.exe .
```

执行后会生成 `bin/server.exe`，可直接运行：

```bash
.\bin\server.exe
```

### 2. 编译 gtpl 工具可执行文件

```bash
go build -o bin/gtpl.exe ./cmd/gtpl
```

验证：

```bash
.\bin\gtpl.exe --help
```

### 3. 配置到环境变量（可全局执行）

建议将 `gtpl.exe` 放到固定工具目录，例如 `D:\tools\go-bin`：

```powershell
New-Item -ItemType Directory -Force -Path D:\tools\go-bin | Out-Null
Copy-Item .\bin\gtpl.exe D:\tools\go-bin\gtpl.exe -Force
```

将该目录加入用户级 `Path`：

```powershell
$target = "D:\tools\go-bin"
$current = [Environment]::GetEnvironmentVariable("Path", "User")
if (($current -split ';') -notcontains $target) {
  [Environment]::SetEnvironmentVariable("Path", "$current;$target", "User")
}
```

重开终端后验证：

```bash
gtpl --help
```

## 测试与质量门禁

建议作为提交前最小门禁：

```bash
gofmt -w .
go mod tidy
go build ./...
go test ./...
go test -race ./...
go vet ./...
```

补充说明：

1. `tests/unit`：工具包与纯逻辑单测。
2. `tests/integration`：MySQL/Redis/Kafka/配置/生命周期等集成验证。
3. `tests/e2e`：HTTP 与 `gtpl init` 端到端验证。

## 常见问题

### 1. 应用启动时报 MySQL/Redis/Kafka 连接失败

请确认：

1. 对应模块的 `enable` 是否为 `true`。
2. 依赖是否已启动并可达。
3. `configs/*.yaml` 中地址与端口是否正确。

### 2. Swagger 页面访问失败

请确认：

1. `swagger.enable` 是否开启。
2. 路径是否与 `swagger.path` 一致。
3. 初始化时是否选择了 `swagger` 模块。

### 3. `gtpl init` 提示模块组合非法

当前规则中 `kafka` 依赖 `redis` 幂等能力，需同时开启：

```bash
--with redis,kafka
```

### 4. 为什么项目统一返回 HTTP 200

该模板遵循统一响应体约束，通过 `code/message/tip` 表达业务与系统状态，便于历史兼容与统一治理。

## 版本与交付记录

1. 验收记录：`docs/FINAL_ACCEPTANCE.md`
2. 发布检查清单：`docs/RELEASE_CHECKLIST.md`
3. PR 摘要模板：`docs/PR_SUMMARY_TEMPLATE.md`