Skip to content

README.md

Latest commit

 

History

History
353 lines (263 loc) · 9.19 KB

README.md

File metadata and controls

353 lines (263 loc) · 9.19 KB

Hello Gin - 高可用高性能 API 项目

基于 Docker + Golang + Gin 构建的高可用高性能 API 服务。

目录

技术栈

  • Web 框架: Gin
  • 数据库: MySQL (GORM)
  • 缓存: Redis
  • 容器化: Docker & Docker Compose
  • 反向代理: Nginx
  • 日志: Zap
  • 配置管理: Viper
  • 认证: JWT

项目结构

hello-gin/
├── cmd/                    # 应用程序入口
│   ├── api/               # API 服务主程序
│   └── migrate/           # 数据库迁移工具
├── internal/              # 内部代码（不对外暴露）
│   ├── config/           # 配置管理
│   ├── handler/          # HTTP 处理器层
│   ├── service/          # 业务逻辑层
│   ├── repository/       # 数据访问层
│   ├── model/            # 数据模型
│   ├── dto/              # 数据传输对象（请求/响应结构体）
│   ├── middleware/       # 中间件（认证、日志、限流等）
│   ├── utils/            # 工具函数
│   └── logger/           # 日志管理
├── pkg/                   # 可复用的公共包
│   ├── response/         # 统一响应格式
│   ├── errors/           # 错误码定义和错误处理
│   ├── validator/        # 参数验证
│   ├── jwt/              # JWT 工具
│   └── password/         # 密码加密工具
├── config/                # 配置文件
│   └── nginx/            # Nginx 配置
├── scripts/               # 脚本文件
│   └── init.sql          # 数据库初始化脚本
├── tests/                 # 测试文件
│   ├── unit/             # 单元测试
│   └── integration/      # 集成测试
├── logs/                  # 日志目录
├── Dockerfile             # Docker 构建文件
├── docker-compose.yml     # Docker Compose 配置
├── go.mod                 # Go 模块依赖
├── go.sum                 # Go 模块依赖校验
├── Makefile              # 构建脚本
├── .gitignore            # Git 忽略文件
├── .dockerignore         # Docker 忽略文件
└── README.md             # 项目说明

快速开始

1. 环境要求

  • Go 1.21+
  • Docker & Docker Compose
  • Make (可选)

2. 配置环境变量（可选）

docker-compose.yml 已经包含了默认配置，可以直接使用。如果需要自定义配置：

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置数据库、Redis 等信息
# 然后在 docker-compose.yml 中取消 env_file 的注释

注意：

  • .env 文件是可选的，docker-compose.yml 中已设置默认值
  • Docker Compose 环境中的数据库和 Redis 主机名分别是 mysql 和 redis（服务名）
  • 本地开发时，主机名应使用 localhost

3. 使用 Docker Compose 启动

# 构建并启动所有服务
make docker-up

# 或者直接使用 docker-compose
docker-compose up -d

4. 本地开发

# 安装依赖
go mod download

# 运行应用
make run

# 或者
go run ./cmd/api

5. 访问服务

常用命令

构建和运行

# 构建应用
make build

# 运行应用
make run

# 运行测试
make test

# 清理构建文件
make clean

Docker 相关

make docker-build    # 构建镜像
make docker-up       # 启动服务
make docker-down     # 停止服务
make docker-restart  # 重启服务
make docker-logs     # 查看日志

代码质量

make fmt      # 代码格式化
make lint      # 代码检查（需要安装 golangci-lint）

数据库迁移

make migrate  # 运行数据库迁移

架构设计

分层架构

项目采用**分层架构（Layered Architecture）**模式，清晰的职责分离：

HTTP Request
    ↓
Handler 层 (HTTP 请求处理、参数验证)
    ↓
Service 层 (业务逻辑处理)
    ↓
Repository 层 (数据访问、数据库/缓存操作)
    ↓
Database/Redis (数据存储)

各层职责

  1. Handler 层 (internal/handler/)

    • 处理 HTTP 请求和响应
    • 参数验证和绑定
    • 调用 Service 层处理业务逻辑
    • 统一错误响应格式

  2. Service 层 (internal/service/)

    • 业务逻辑处理
    • 事务管理
    • 调用 Repository 层进行数据访问
    • 不直接处理 HTTP 相关逻辑

  3. Repository 层 (internal/repository/)

    • 数据访问抽象
    • 数据库操作（GORM）
    • 缓存操作（Redis）
    • 统一管理数据访问接口

  4. Model 层 (internal/model/)

    • 数据模型定义
    • 数据库表结构映射

  5. DTO 层 (internal/dto/)

    • 数据传输对象
    • 请求/响应结构体定义
    • 独立于业务逻辑的数据结构

架构优势

  • 职责分离: 每层只负责自己的职责，易于维护
  • 可测试性: 可以轻松 mock Repository 层，测试 Service 层
  • 可扩展性: 切换数据库只需修改 Repository 层
  • 代码复用: DTO 可以在多个层之间复用

代码组织

  • Handler: 只处理 HTTP 相关逻辑，不包含业务逻辑
  • Service: 包含所有业务逻辑，可调用多个 Repository
  • Repository: 只负责数据访问，不包含业务逻辑
  • DTO: 请求/响应结构体统一放在 internal/dto/ 目录

错误处理

项目采用统一的错误码规范：

  • 业务错误码: 10000+（通用错误）、20000+（用户相关）、30000+（业务逻辑）
  • HTTP 状态码: 自动根据业务错误码映射
  • 统一响应格式: 所有响应都遵循 {code, message, data} 格式

错误码定义在 pkg/errors/codes.go 中，便于统一管理和扩展。

中间件

  • Logger: 请求日志记录（使用 Zap），记录请求路径、方法、IP、延迟等信息
  • Recovery: 异常恢复，记录详细的 panic 信息（包括堆栈跟踪）到日志，返回友好错误响应
  • CORS: 跨域处理
  • Auth: JWT 认证（待实现完整验证逻辑）
  • RateLimit: 限流（可扩展）

配置管理

  • 使用 Viper 进行配置管理
  • 支持环境变量和配置文件（.env）
  • 配置文件加载失败时会记录警告，但不阻止启动（可使用环境变量和默认值）
  • 配置验证：数据库配置会在连接前进行验证

日志系统

  • 使用 Zap 作为日志库
  • 统一的日志格式和级别管理
  • 支持日志级别配置（debug/info/warn/error）
  • 优雅关闭时自动同步日志

数据库管理

phpMyAdmin（Web 界面）

项目已集成 phpMyAdmin，可以通过 Web 界面管理 MySQL 数据库：

  1. 访问地址: http://localhost:8081
  2. 登录信息:
    • 服务器: mysql（容器内）或 127.0.0.1（外部）
    • 用户名: root 或 appuser
    • 密码: rootpassword 或 apppassword

命令行连接

从宿主机连接

# 使用 root 用户连接
mysql -h 127.0.0.1 -P 3306 -u root -p
# 密码：rootpassword

# 使用应用用户连接
mysql -h 127.0.0.1 -P 3306 -u appuser -p hello_gin
# 密码：apppassword

从容器内连接

# 进入 MySQL 容器
docker exec -it hello-gin-mysql mysql -u root -p
# 密码：rootpassword

# 或使用 docker-compose
docker-compose exec mysql mysql -u root -p

数据库信息

  • 数据库名: hello_gin
  • Root 密码: rootpassword
  • 应用用户: appuser
  • 应用密码: apppassword
  • 端口: 3306

认证机制

项目实现了 Access Token + Refresh Token 双令牌机制，提供安全可靠的用户认证方案。

核心特性

  • Access Token：短期有效（2小时），用于访问 API
  • Refresh Token：长期有效（7天），用于刷新 Access Token
  • Token 旋转：刷新时生成新的 Refresh Token，旧的立即失效
  • 可撤销：Refresh Token 存储在 Redis，支持主动撤销

相关文档

快速开始

# 1. 登录获取双令牌
curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"123456"}'

# 2. 使用 Access Token 访问 API
curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer {access_token}"

# 3. 刷新 Access Token
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"{refresh_token}"}'

部署

Docker 部署

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f api

# 停止服务
docker-compose down