# Quick Go

**Repository Path**: uritchie/quick-go

## Basic Information

- **Project Name**: Quick Go
- **Description**: 一个基于 Gin、Gorm、MySQL、Redis 和 AI 能力的现代化 Go Web 开发框架，专为快速开发高质量的 Web 应用和 AI 服务而设计。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickGo - 现代化 Go Web 开发框架 🚀

一个基于 Gin、Gorm、MySQL、Redis 和 AI 能力的现代化 Go Web 开发框架，专为快速开发高质量的 Web 应用和 AI 服务而设计。

[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)]()

## ✨ 核心特性

### 🎯 现代化技术栈
- **🌐 Gin Framework**: 高性能 HTTP Web 框架
- **💾 GORM + MySQL**: 强大的 ORM 和数据库支持（中国时区优化）
- **⚡ Redis**: 高性能缓存和会话存储
- **📝 Zap Logger**: 结构化高性能日志系统
- **⚙️ Viper**: 灵活的配置管理（支持环境变量）

### 🤖 AI 能力集成
- **🧠 OpenAI API**: 完整的 GPT 系列模型支持
- **💬 智能对话**: 支持流式和非流式对话
- **📊 会话管理**: 完整的对话历史管理
- **🔤 文本向量化**: 支持文本嵌入和语义搜索
- **🔧 可扩展架构**: 易于集成其他 AI 提供商

### 🏗️ 企业级架构
- **📁 标准布局**: 遵循 Go 项目最佳实践
- **🔄 分层设计**: Handler → Service → Repository
- **🔗 依赖注入**: 松耦合的组件设计
- **🔍 统一响应**: 标准化的 API 响应格式
- **💊 健康监控**: 完整的系统健康检查
- **📈 性能优化**: 连接池、缓存策略等

## 📊 项目状态

### ✅ 已完成功能
- [x] 完整的项目重构和优化
- [x] 用户管理 CRUD API
- [x] AI 对话和文本处理
- [x] 数据库连接池优化
- [x] Redis 缓存集成
- [x] 结构化日志系统
- [x] Docker 容器化支持
- [x] 开发工具和脚本
- [x] API 测试套件
- [x] 配置管理系统

### 🚀 可直接使用的功能
- **用户管理**: 创建、查询、更新、删除用户
- **AI 对话**: 与 OpenAI 模型进行智能对话
- **系统监控**: 健康检查和系统状态监控
- **日志分析**: 结构化日志记录和分析

### 🔧 即将推出
- [ ] JWT 认证和授权
- [ ] 订单管理系统完整实现
- [ ] 文件上传和管理
- [ ] WebSocket 实时通信
- [ ] API 文档自动生成

## 🚀 快速开始

### 📋 环境要求
- **Go**: 1.21+ 
- **MySQL**: 5.7+ (支持中国时区)
- **Redis**: 6.0+
- **OpenAI API Key**: 可选，用于 AI 功能

### ⚡ 一键启动

使用我们提供的启动脚本快速开始：

```bash
# 1. 克隆项目
git clone <repository-url>
cd quick-go-main

# 2. 设置开发环境（自动安装依赖和工具）
./scripts/start.sh setup

# 3. 启动开发服务器
./scripts/start.sh dev
```

### 🔧 手动配置

如果你想手动配置：

1. **复制环境变量文件**：
```bash
cp .env.example .env
```

2. **配置数据库和服务**，编辑 `.env` 文件：
```bash
# 数据库配置（已优化中国时区）
QUICKGO_DB_HOST=127.0.0.1
QUICKGO_DB_PORT=3306
QUICKGO_DB_NAME=quickgo
QUICKGO_DB_USER=root
QUICKGO_DB_PASSWORD=your_password

# Redis 配置
QUICKGO_REDIS_HOST=127.0.0.1
QUICKGO_REDIS_PORT=6379

# AI 配置（可选）
QUICKGO_OPENAI_API_KEY=your_openai_api_key

# 安全配置
QUICKGO_JWT_SECRET=your-very-secure-secret
```

3. **启动服务**：

```bash
# 开发模式（支持热重载）
make dev
# 或
go run cmd/server/main.go

# 构建并运行
make build && ./build/quickgo
```

🎉 **服务启动成功！** 访问 `http://localhost:8080`

### ✅ 验证安装

```bash
# 检查服务状态
curl http://localhost:8080/health

# 运行 API 测试
./scripts/test_api.sh

# 或使用 make
make test
```

## 📁 项目结构

```
quick-go-main/
├── cmd/server/          # 应用入口
├── internal/            # 私有应用代码
│   ├── ai/             # AI 服务层
│   ├── api/v1/         # API 版本控制
│   ├── config/         # 配置管理
│   ├── db/             # 数据库连接管理
│   ├── handler/        # 请求处理器
│   ├── middleware/     # 中间件
│   ├── model/          # 数据模型
│   ├── repository/     # 数据访问层
│   └── service/        # 业务逻辑层
├── pkg/                # 可复用的包
│   ├── logger/         # 日志工具
│   ├── response/       # 响应工具
│   ├── utils/          # 通用工具
│   └── ai/             # AI 客户端
├── configs/            # 配置文件
├── docs/               # 文档
├── scripts/            # 脚本文件
├── web/                # 前端静态文件
└── deployments/        # 部署配置
```

## 🔌 API 接口文档

### 🏥 健康检查 API
```bash
GET /health          # 完整系统健康检查
GET /ping           # 简单连通性检查
```

### 👥 用户管理 API
```bash
# 用户 CRUD
GET    /api/v1/users           # 获取用户列表（支持分页、搜索）
POST   /api/v1/users           # 创建新用户
GET    /api/v1/users/{id}      # 获取用户详情
PUT    /api/v1/users/{id}      # 更新用户信息
DELETE /api/v1/users/{id}      # 删除用户（软删除）
PATCH  /api/v1/users/{id}/status # 修改用户状态
```

### 🤖 AI 功能 API
```bash
# AI 对话和处理
POST /api/v1/ai/chat           # 智能对话
POST /api/v1/ai/chat/stream    # 流式对话
POST /api/v1/ai/completion     # 文本补全
POST /api/v1/ai/embedding      # 文本向量化
GET  /api/v1/ai/models         # 获取可用模型列表

# 会话管理
GET  /api/v1/ai/sessions/{user_id}    # 获取用户会话列表
GET  /api/v1/ai/session/{session_id}  # 获取会话详情
DELETE /api/v1/ai/session/{session_id} # 删除会话
```

### 📊 系统监控 API
```bash
GET /api/v1/system/info        # 系统基本信息
GET /api/v1/system/stats       # 详细系统统计
```

## 💡 使用示例

### 🤖 AI 对话功能

#### 1. 基础对话
```bash
curl -X POST http://localhost:8080/api/v1/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请介绍一下你自己",
    "user_id": "user123",
    "session_id": "session456"
  }'
```

#### 2. 获取可用模型
```bash
curl http://localhost:8080/api/v1/ai/models
```

#### 3. 文本向量化
```bash
curl -X POST http://localhost:8080/api/v1/ai/embedding \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["这是一个测试文本", "另一个文本"],
    "user_id": "user123"
  }'
```

### 👥 用户管理功能

#### 1. 创建用户
```bash
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "password": "password123"
  }'
```

#### 2. 获取用户列表
```bash
# 基础列表
curl http://localhost:8080/api/v1/users

# 分页和搜索
curl "http://localhost:8080/api/v1/users?page=1&size=10&keyword=test&status=1"
```

#### 3. 更新用户信息
```bash
curl -X PUT http://localhost:8080/api/v1/users/1 \
  -H "Content-Type: application/json" \
  -d '{
    "username": "updateduser",
    "email": "updated@example.com"
  }'
```

## ⚙️ 配置说明

### 应用配置
```yaml
app:
  name: "quick-go"      # 应用名称
  version: "1.0.0"      # 版本号
  port: 8080            # 监听端口
  mode: "debug"         # 运行模式: debug/release
```

### AI 配置
```yaml
ai:
  openai:
    api_key: ""         # OpenAI API 密钥
    base_url: "https://api.openai.com/v1"
    model: "gpt-3.5-turbo"
    temperature: 0.7
    max_tokens: 1000
  azure:
    api_key: ""         # Azure OpenAI API 密钥
    base_url: ""        # Azure 端点
    deployment_name: ""
```

### 数据库配置
```yaml
database:
  host: "127.0.0.1"
  port: 3306
  database: "quickgo"
  username: "root"
  password: ""
  max_idle_conns: 10
  max_open_conns: 100
```

## 🛠️ 开发工具

### 📦 便捷脚本

项目提供了完整的开发脚本：

```bash
# 开发相关
./scripts/start.sh setup      # 设置开发环境
./scripts/start.sh dev        # 启动开发服务器（热重载）
./scripts/start.sh test       # 运行 API 测试

# 构建相关
./scripts/start.sh build      # 构建应用
./scripts/start.sh run        # 运行构建的应用

# 管理相关
./scripts/start.sh status     # 检查应用状态
./scripts/start.sh logs       # 查看应用日志
./scripts/start.sh stop       # 停止应用
```

### 🔧 Make 命令

使用 Makefile 进行常见操作：

```bash
# 开发流程
make setup          # 设置开发环境
make dev            # 开发模式启动
make build          # 构建应用
make test           # 运行测试

# 代码质量
make lint           # 代码检查
make fmt            # 代码格式化
make clean          # 清理构建文件

# Docker 操作
make docker-build   # 构建 Docker 镜像
make docker-run     # 运行 Docker 容器
```

## 🔧 开发指南

### 添加新的 API 端点

1. **创建数据模型**: `internal/model/`
2. **实现服务逻辑**: `internal/service/`
3. **编写处理器**: `internal/handler/`
4. **注册路由**: `cmd/server/main.go`

```go
// 示例：添加新的产品管理
// 1. internal/model/product.go
type Product struct {
    ID   uint   `json:"id"`
    Name string `json:"name"`
    // ...
}

// 2. internal/service/product.go
type ProductService interface {
    CreateProduct(ctx context.Context, req *ProductCreateRequest) (*Product, error)
    // ...
}

// 3. internal/handler/product.go
func (h *ProductHandler) CreateProduct(c *gin.Context) {
    // 处理逻辑
}

// 4. 在 main.go 中注册路由
products := v1.Group("/products")
{
    products.POST("", productHandler.CreateProduct)
    // ...
}
```

### 自定义 AI 提示词

```go
// 在 pkg/ai/types.go 中添加
SystemPrompts["customer_service"] = "你是一个专业的客服助手，请礼貌地回答用户问题..."
SystemPrompts["code_reviewer"] = "你是一个资深的代码审查专家..."
```

### 扩展 AI 功能

1. **实现 AI 提供商接口**:
```go
type CustomAIProvider struct{}

func (p *CustomAIProvider) Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error) {
    // 自定义实现
}
```

2. **注册到服务中**:
```go
// 在 internal/ai/service.go 中
service.providers["custom"] = &CustomAIProvider{}
```

## 📊 监控和日志

### 健康检查
访问 `/health` 端点查看系统健康状态：
```json
{
  "status": "healthy",
  "checks": {
    "database": {"status": "healthy"},
    "redis": {"status": "healthy"},
    "ai_service": {"status": "healthy"}
  }
}
```

### 日志配置
支持多种日志格式和输出方式：
```yaml
logger:
  level: "info"         # 日志级别
  format: "json"        # 格式: json/console
  output: "stdout"      # 输出: stdout/file
  filename: "logs/app.log"
```

## 🚀 生产部署

### 🐳 Docker 部署 (推荐)

1. **构建镜像**:
```bash
# 使用提供的 Dockerfile
docker build -t quickgo:latest .

# 或使用 make 命令
make docker-build
```

2. **运行容器**:
```bash
# 基础运行
docker run -d -p 8080:8080 \
  -e QUICKGO_DB_HOST=your_db_host \
  -e QUICKGO_DB_PASSWORD=your_db_password \
  -e QUICKGO_OPENAI_API_KEY=your_api_key \
  -e QUICKGO_JWT_SECRET=your_jwt_secret \
  quickgo:latest

# 使用配置文件
docker run -d -p 8080:8080 \
  -v $(pwd)/configs:/app/configs \
  -v $(pwd)/logs:/app/logs \
  --env-file .env \
  quickgo:latest
```

3. **Docker Compose 部署**:
```yaml
# docker-compose.yml
version: '3.8'
services:
  quickgo:
    build: .
    ports:
      - "8080:8080"
    environment:
      - QUICKGO_DB_HOST=mysql
      - QUICKGO_REDIS_HOST=redis
    depends_on:
      - mysql
      - redis
    
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: quickgo
      MYSQL_ROOT_PASSWORD: password
    
  redis:
    image: redis:7-alpine
```

### 📦 二进制部署

1. **交叉编译**:
```bash
# 使用 make 命令构建多平台
make build-all

# 或手动编译
# Linux
GOOS=linux GOARCH=amd64 go build -o build/quickgo-linux-amd64 cmd/server/main.go

# Windows  
GOOS=windows GOARCH=amd64 go build -o build/quickgo-windows-amd64.exe cmd/server/main.go

# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o build/quickgo-darwin-amd64 cmd/server/main.go

# macOS (M1/M2)
GOOS=darwin GOARCH=arm64 go build -o build/quickgo-darwin-arm64 cmd/server/main.go
```

2. **生产环境运行**:
```bash
# 设置生产环境变量
export QUICKGO_APP_MODE=release
export QUICKGO_JWT_SECRET=your-production-secret

# 运行应用
./quickgo
```

### ☁️ 云平台部署

**准备工作**：
- 确保数据库和 Redis 服务可用
- 配置环境变量
- 设置日志和监控

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [Gin Framework](https://github.com/gin-gonic/gin)
- [GORM](https://gorm.io/)
- [LangChain Go](https://github.com/tmc/langchaingo)
- [OpenAI API](https://platform.openai.com/docs)
- [Redis](https://redis.io/)

## 🧪 测试

### 运行测试套件

```bash
# 运行所有测试
make test

# 或使用脚本
./scripts/test_api.sh

# 运行特定测试
./scripts/test_api.sh --user    # 只测试用户 API
./scripts/test_api.sh --ai      # 只测试 AI API
```

### 测试覆盖率

```bash
# 生成覆盖率报告
make test-coverage

# 查看 HTML 报告
open coverage.html
```

## ❓ 常见问题

### Q: 数据库连接失败？
**A**: 检查数据库配置和网络连接：
```bash
# 检查 MySQL 服务
mysql -h 127.0.0.1 -u root -p -e "SELECT 1"

# 检查配置
grep QUICKGO_DB .env
```

### Q: AI 功能不可用？
**A**: 需要配置 OpenAI API 密钥：
```bash
# 设置环境变量
export QUICKGO_OPENAI_API_KEY=your_api_key

# 或在 .env 文件中配置
echo "QUICKGO_OPENAI_API_KEY=your_api_key" >> .env
```

### Q: 如何自定义日志格式？
**A**: 修改配置文件或环境变量：
```yaml
# configs/config.yaml
logger:
  level: "info"
  format: "json"    # 或 "console"
  output: "file"    # 或 "stdout"
```

### Q: 端口被占用怎么办？
**A**: 修改端口配置：
```bash
# 方法1：环境变量
export QUICKGO_APP_PORT=9000

# 方法2：配置文件
# 在 configs/config.yaml 中修改 app.port
```

### Q: 如何添加新的数据模型？
**A**: 按照以下步骤：
1. 在 `internal/model/` 定义模型
2. 在 `cmd/server/main.go` 中添加到 `AutoMigrate`
3. 创建对应的 Service 和 Handler

### Q: Docker 容器启动失败？
**A**: 检查日志和配置：
```bash
# 查看容器日志
docker logs quickgo

# 检查健康状态
docker exec quickgo curl -f http://localhost:8080/health
```

## 📞 支持

- 📚 **文档**: 查看 `docs/` 目录
- 🐛 **Bug 报告**: 提交 GitHub Issue
- 💡 **功能建议**: 提交 GitHub Issue
- 💬 **讨论**: GitHub Discussions

## 📄 许可证

本项目基于 **MIT 许可证** 开源。详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

感谢以下开源项目：
- [Gin](https://github.com/gin-gonic/gin) - HTTP Web 框架
- [GORM](https://gorm.io/) - Go ORM 库
- [Zap](https://github.com/uber-go/zap) - 高性能日志库
- [Viper](https://github.com/spf13/viper) - 配置管理
- [Redis](https://redis.io/) - 内存数据库

---

⭐ **如果这个项目对你有帮助，请给个 Star！** ⭐

🚀 **快速体验**: `git clone && ./scripts/start.sh setup && ./scripts/start.sh dev`