# gin框架模版

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

## Basic Information

- **Project Name**: gin框架模版
- **Description**: golang Gin框架的开发模版
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-23
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GinStandardTemplate

GinStandardTemplate 是一个基于 Gin 框架的现代化 Go 语言 Web 项目模板。它集成了众多主流的开发组件和最佳实践，旨在帮助开发者快速搭建高性能、可扩展的后端服务。

## 🚀 项目特性

* **Web 框架**: 使用 [Gin](https://github.com/gin-gonic/gin) 作为高性能 Web 框架。
* **依赖注入**: 集成 [Wire](https://github.com/google/wire) 进行依赖注入，实现松耦合。
* **ORM**: 使用 [GORM](https://gorm.io/) 进行数据库操作，支持 MySQL、PostgreSQL 等多种数据库。
* **代码生成**: 集成 [GORM Gen](https://gorm.io/gen/) 自动从数据库表生成类型安全的 Model 和 DAO 层代码，无需手写。
* **配置管理**: 使用 [Viper](https://github.com/spf13/viper) 管理配置，支持 YAML 格式，支持多环境配置。
* **日志管理**: 集成 [Zap](https://github.com/uber-go/zap) 高性能日志库，支持日志切割和归档。
* **鉴权机制**: 内置 JWT (JSON Web Token) 认证中间件。
* **缓存支持**:
	* **Redis**: 集成 [go-redis](https://github.com/redis/go-redis)，支持单机和集群模式。
	* **本地缓存**: 内置基于内存的本地缓存实现。
	* **分布式锁**: 提供基于 Redis 的分布式锁实现。
* **WebSocket**: 集成 [Gorilla WebSocket](https://github.com/gorilla/websocket)，支持 WebSocket 通信，并提供基于 Redis
  的集群消息广播方案。
* **国际化 (i18n)**: 支持多语言响应，基于 YAML 文件配置。
* **错误处理**: 统一的错误码和错误响应封装。
* **构建工具**: 提供 `Makefile` 简化构建、运行和代码生成流程。
* **目录结构**: 遵循 [Standard Go Project Layout](https://github.com/golang-standards/project-layout) 规范。

## 📂 目录结构

```text
GinStandardTemplate/
├── cmd/                    # 应用程序入口
│   ├── server/             # 主服务入口 (main.go)
│   └── generate/           # GORM Gen 代码生成工具入口
├── configs/                # 配置文件
│   ├── locales/            # 国际化语言包
│   └── config.yaml.example # 配置文件示例
├── internal/               # 内部业务代码 (不对外暴露)
│   ├── conf/               # 配置结构体定义及加载
│   ├── consts/             # 常量定义 (如缓存Key、WebSocket指令)
│   ├── dto/                # 数据传输对象 (Request/Response)
│   ├── handler/            # HTTP/WebSocket 处理器 (Controller)
│   ├── middleware/         # Gin 中间件 (Auth, CORS, Logger, etc.)
│   ├── model/              # 数据库模型 (Model) - 由 Gen 自动生成
│   ├── repository/         # 数据访问层 (DAO) - 由 Gen 自动生成
│   ├── router/             # 路由注册
│   ├── service/            # 业务逻辑层 (Service)
│   └── websocket/          # WebSocket 核心逻辑
├── pkg/                    # 公共库 (可被外部引用)
│   ├── cache/              # 缓存接口及实现 (Redis/Local)
│   ├── code/               # 错误码定义
│   ├── ctxkey/             # Context Key 定义
│   ├── errors/             # 自定义错误处理
│   ├── i18n/               # 国际化工具
│   ├── lock/               # 分布式锁接口及实现
│   ├── logger/             # 日志工具
│   ├── response/           # 统一响应封装
│   └── utils/              # 通用工具函数 (JWT, Hash, etc.)
├── test/                   # 测试文件
├── Makefile                # 构建脚本
├── go.mod                  # Go 模块定义
└── README.md               # 项目文档
```

## 🛠️ 快速开始

### 1. 环境准备

* Go 1.18+
* MySQL (或其他支持的数据库)
* Redis (可选，用于缓存和 WebSocket 集群)

### 2. 安装依赖

```bash
go mod download
```

### 3. 配置文件

复制示例配置文件并进行修改：

```bash
cp configs/config.yaml.example configs/config.yaml
```

编辑 `configs/config.yaml`，配置数据库、Redis、JWT 等信息。

### 4. 数据库初始化

确保数据库已创建。

### 5. 生成代码 (关键步骤)

本项目采用 **Database First** 模式。你需要先在数据库中建好表，然后运行以下命令，工具会自动读取数据库表结构，在
`internal/model` 生成结构体，在 `internal/repository/dao` 生成查询代码。

```bash
make gen
```

> **注意**: `internal/model` 和 `internal/repository/dao` 下的代码完全由工具生成，**请勿手动修改**
> ，否则下次生成时会被覆盖。如果数据库表结构发生变更，请再次运行 `make gen`。

### 6. 依赖注入

如果你修改了依赖注入关系（`wire.go`），需要重新生成 Wire 代码：

```bash
make wire
```

### 7. 运行服务

```bash
make run
```

服务默认监听 `8080` 端口 (可在配置文件中修改)。

## 📖 开发指南

### 1. 新增 API 接口

1. **定义 DTO**: 在 `internal/dto` 中定义请求和响应结构体。
2. **编写 Service**: 在 `internal/service` 中编写业务逻辑。
3. **编写 Handler**: 在 `internal/handler` 中处理 HTTP 请求，调用 Service，并返回响应。
4. **注册路由**: 在 `internal/router/router.go` 中注册新的路由。
5. **依赖注入**: 如果新增了 Service 或 Handler，需要在 `cmd/server/wire.go` (或相关 Provider Set) 中添加依赖，并运行
   `make wire`。

### 2. 数据库操作

项目使用 GORM Gen 生成类型安全的查询代码。

1. 在数据库中创建或修改表。
2. 运行 `make gen` 自动生成 Model 和 DAO 代码。
3. 在 Service 中注入 `*dao.Query`，使用 `s.repo.User.WithContext(ctx)...` 进行操作。

### 3. 缓存使用

Service 层可以注入 `cache.Cache` (Redis) 或 `*cache.LocalCache` (本地缓存)。

```go
// 使用 Redis 缓存
val, err := s.redisCache.Get(ctx, key, &targetStruct)

// 使用本地缓存
err := s.localCache.Get(ctx, key, &targetStruct)
```

### 4. WebSocket 开发

1. **定义指令**: 在 `internal/consts/wscmd` 中定义新的 WebSocket 消息指令。
2. **注册事件**: 在 `internal/handler/ws_handler.go` 的 `registerEvents` 方法中注册指令对应的处理函数。
3. **发送消息**: 使用 `client.SendMsg()` 发送消息。

### 5. 国际化

1. 在 `configs/locales` 目录下添加或修改 YAML 语言包文件 (e.g., `zh.yaml`, `en.yaml`)。
2. 在中间件中，`i18n` 会自动根据 `Accept-Language` 头匹配语言，并将 `*i18n.Localizer` 注入到 Context 中。
3. 在 Handler 中，可以从 Context 获取 Localizer 并进行翻译：

```go
// 从 Context 获取 Localizer
// 示例代码，MessageID 参考pkg/code
localizer := c.MustGet(ctxkey.Localizer).(*i18n.Localizer)
msg, _ := localizer.Localize(&i18n.LocalizeConfig{
	MessageID: "operation_timeout_error",
})
```

## 🔌 前后端对接

### 1. 统一响应格式

所有 HTTP 接口返回的 JSON 格式如下：

```json
{
	"code": 200,
	// 业务状态码，200 表示成功
	"msg": "success",
	// 提示信息
	"data": {
		...
	}
	// 业务数据
}
```

### 2. 鉴权方式

* **HTTP**: 在 Header 中添加 `Authorization: Bearer <token>`。
* **WebSocket**:
	* Query Param: `?token=<token>`
	* Sec-WebSocket-Protocol: `<token>`

### 3. 错误码

常见错误码定义在 `pkg/code/code.go` 中。前端应根据 `code` 字段判断业务状态。

## 🏗️ 构建与部署

### 编译

使用 Makefile 编译不同平台的二进制文件：

```bash
# 编译当前平台
go build -o app cmd/server/main.go

# 编译所有平台
make build-all

# 编译 Linux amd64
make build-linux-amd64
```

### 部署

将编译好的二进制文件、`configs` 目录上传至服务器即可运行。建议使用 Supervisor 或 Systemd 进行进程管理。