# gin-tmp

**Repository Path**: rdisme/gin-tmp

## Basic Information

- **Project Name**: gin-tmp
- **Description**: gin框架模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# My API Project

基于 Go + Gin 的 RESTful API 项目，采用 Clean Architecture 分层设计。

## 目录结构

```
my-api-project/
├── cmd/                        # 程序入口
│   └── api/                    # API 服务入口
├── internal/                   # 私有代码
│   ├── handler/                # HTTP 处理器层
│   ├── service/                # 业务逻辑层
│   ├── repository/             # 数据访问层
│   └── model/                  # 数据模型
├── pkg/                        # 公共包
│   ├── config/                 # 配置管理（按模块拆分）
│   ├── logger/                 # 日志初始化
│   ├── middleware/             # Gin 中间件
│   └── response/               # 统一响应格式
├── routes/                     # 路由注册
├── storage/                    # 运行时文件存储
├── Makefile                    # 常用命令快捷方式
├── config.example.yaml         # 配置模板
└── .gitignore
```

---

## cmd/

程序入口目录，每个子目录对应一个可执行程序。

| 路径 | 说明 |
|---|---|
| `cmd/api/main.go` | API 服务入口。负责初始化配置、日志、数据库连接，完成依赖注入，启动 HTTP 服务。 |

**原则：** `main.go` 只做"组装"工作，不包含业务逻辑。读配置文件 → 初始化依赖 → 拼装对象 → 启动服务，四步走完。

---

## internal/

Go 的 `internal` 机制保证此目录下的代码**无法被外部项目 import**，强制封装。

### internal/handler/

HTTP 请求处理器，相当于 MVC 中的 Controller。

**职责：**
- 绑定和校验请求参数
- 调用 service 层处理业务
- 返回统一格式的 JSON 响应

**原则：** handler 必须保持薄层。不做任何业务判断，不写任何 SQL，只做参数绑定 → 调用 service → 返回结果。

### internal/service/

业务逻辑层，是整个项目的核心。

**职责：**
- 实现所有业务规则和流程
- 调用 repository 获取/持久化数据
- 处理事务、缓存、外部 API 调用等

**原则：** 所有 Service 通过接口定义（`interfaces.go`），方便单元测试时 mock。Service 不知道 HTTP 的存在，也不知道底层是什么数据库。

### internal/repository/

数据访问层，负责与数据库交互。

**职责：**
- 封装所有 SQL 操作
- 将数据库记录映射为 model struct
- 提供接口定义（`interfaces.go`）以便替换数据库实现

`repository/mysql/` 子目录用于存放 MySQL 特定实现，方便后续扩展其他数据库（PostgreSQL、MongoDB 等）。

### internal/model/

纯数据结构定义，不包含任何业务逻辑或数据库操作。

- `user.go` — 用户模型
- `common.go` — 通用结构（分页请求/响应等）

---

## pkg/

可被外部项目引用的公共包。与 `internal/` 相反，这里的代码是对外开放的。

### pkg/config/

配置读取与管理，按模块拆分为多个文件。

| 文件 | 说明 |
|---|---|
| `config.go` | `Config` 聚合结构 + `Load()` 入口 |
| `server.go` | Server 配置（端口、模式、可信代理） |
| `log.go` | 日志配置（级别、文件输出、轮转） |
| `db.go` | 数据库配置（驱动、连接信息） |
| `jwt.go` | JWT 配置（密钥、过期时间） |

- 每个模块有自己的 struct 定义和默认值（`xxxDefaults`）
- `Load()` 先构造默认值，再通过 Viper 用 `config.yaml` 覆盖
- 对应 `config.example.yaml` 配置文件模板

### pkg/logger/

日志系统初始化与全局实例。

- 基于 [zap](https://github.com/uber-go/zap) 高性能日志库
- 使用 [lumberjack](https://github.com/natefinch/lumberjack) 自动轮转日志文件
- 提供全局变量 `logger.L`，全项目直接使用
- 同时输出到 stdout 和文件（可配置）

**用法：**
```go
logger.L.Infow("user created", "id", 1, "username", "alice")
logger.L.Errorw("db error", "error", err)
```

### pkg/middleware/

Gin 中间件集合。

| 文件 | 说明 |
|---|---|
| `auth.go` | JWT 认证中间件，从 Authorization header 提取 token 并验证 |
| `logger.go` | HTTP 请求日志，记录方法、路径、状态码、耗时 |
| `recovery.go` | panic 恢复中间件，防止单个请求崩溃导致整个进程退出 |
| `cors.go` | 跨域中间件，处理 OPTIONS 预检请求 |

### pkg/response/

统一 JSON 响应格式。

**提供的函数：**
| 函数 | HTTP 状态码 | 用途 |
|---|---|---|
| `OK(c, data)` | 200 | 成功返回数据 |
| `Created(c, data)` | 201 | 创建资源成功 |
| `Error(c, code, msg)` | 自定义 | 业务错误 |
| `Paged(c, list, total, page, size)` | 200 | 分页列表 |

所有 handler 不直接调用 `c.JSON()`，统一使用这些函数，保证响应格式一致。

---

## routes/

集中路由注册。

`routes.go` 包含：
- 全局中间件：`RequestLogger`、`Recovery`（所有路由都走）
- 健康检查：`GET /health`
- 公开路由组：`/api/v1/auth`（登录、注册）、`/api/v1/users`（列表、详情）
- 分组方式：通过 `r.Group()` 按业务划分路由前缀

**原则：** 路由只做"这个路径走哪个 middleware 和 handler"的注册，不写业务逻辑。

---

## 中间件

Gin 中间件支持三种注册粒度：

| 粒度 | 写法 | 示例 |
|---|---|---|
| 全局 | `r.Use(mw)` | 日志、异常恢复 |
| 组 | `group.Use(mw)` | 鉴权、权限校验 |
| 路由 | `r.GET(path, mw, handler)` | 单条路由特殊处理 |

执行顺序：**全局 → 组 → 单条路由**，越靠近路径越后执行。

---

## storage/

运行时生成文件的存放目录，对标 Laravel 的 `storage/`。

| 目录 | 用途 |
|---|---|
| `logs/` | 应用日志文件 |
| `uploads/` | 用户上传文件 |
| `cache/` | 本地文件缓存 |

除 `.gitkeep` 占位文件外，所有内容均被 `.gitignore` 忽略，不提交到版本库。

---

## scripts/

存放数据库迁移、数据填充、部署等脚本文件。

---

## 配置文件

| 文件 | 说明 |
|---|---|
| `config.example.yaml` | 配置模板，提交到 Git |
| `config.yaml` | 本地配置（含敏感信息），在 `.gitignore` 中，不提交 |

---

## Makefile

| 命令 | 说明 |
|---|---|
| `make run` | 启动开发服务器（`go run ./cmd/api`） |
| `make build` | 编译二进制文件（输出到 `bin/api`） |
| `make test` | 运行测试（`./internal/... ./pkg/...`） |
| `make install` | 整理和下载依赖（`go mod tidy + download`） |

---

## 依赖关系与数据流

```
HTTP Request
    │
    ▼
┌─────────────────┐
│  routes.go      │  路由匹配 + 中间件链
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  handler/       │  参数绑定、校验
│  (薄层)          │  调用 service
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  service/       │  业务逻辑、事务控制
│  (核心)          │  调用 repository
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  repository/    │  SQL 执行、数据映射
│  (数据访问)      │
└────────┬────────┘
         │
         ▼
   [ Database ]
```

**依赖方向：** handler → service → repository → database

**接口方向：** 每一层只依赖下一层的接口，不依赖具体实现（依赖倒置）。

---

## 快速开始

```bash
# 1. 创建配置
cp config.example.yaml config.yaml

# 2. 安装依赖
make install

# 3. 启动服务
make run
```

访问 `http://localhost:8080/health` 确认服务运行正常。