# gin_gorm_oj

**Repository Path**: go_27/gin_gorm_oj

## Basic Information

- **Project Name**: gin_gorm_oj
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-01
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gin_gorm_oj

## 项目介绍

**gin_gorm_oj** 是一个基于 Go 语言开发的轻量级在线评测系统（Online Judge）后端服务。该项目采用现代化的 Web 技术栈，提供高效、稳定的编程题评测平台后端支持，包含题目管理、用户系统、代码提交与评测等核心功能，适用于教育、竞赛和学习场景。

## 技术栈

| 类别 | 技术/框架 | 版本要求 | 用途 | 官方手册地址 |
|------|----------|---------|------|------------|
| 编程语言 | Go | 1.16+ | 项目开发语言 | [https://golang.org/doc/](https://golang.org/doc/) |
| Web 框架 | Gin | v1.9+ | HTTP 请求处理与路由管理 | [https://gin-gonic.com/](https://gin-gonic.com/) |
| ORM 工具 | GORM | v1.25+ | 数据库操作与模型管理 | [https://gorm.io/](https://gorm.io/) |
| 数据库 | MySQL | 5.7+ | 数据存储 | [https://dev.mysql.com/doc/](https://dev.mysql.com/doc/) |
| 缓存 | Redis | 6.0+ | 数据缓存与临时存储 | [https://redis.io/documentation](https://redis.io/documentation) |
| 工具库 | go.uuid | v1.2+ | UUID生成 | [https://github.com/satori/go.uuid](https://github.com/satori/go.uuid) |
| API 文档 | Swagger | v2 | 自动生成 API 文档 | [https://swagger.io/docs/](https://swagger.io/docs/) |
| 辅助功能 | email | - | 邮件发送支持 | [https://github.com/jordan-wright/email](https://github.com/jordan-wright/email) |
| 认证 | JWT | - | 用户身份验证 | [https://jwt.io/introduction](https://jwt.io/introduction) |

## 项目架构

项目采用标准的分层架构设计，各模块职责明确，便于维护和扩展：

```
gin_gorm_oj/
├── code/           # 代码运行相关
│   ├── code-user/  # 用户代码目录
│   └── run.go      # 代码运行管理
├── core/           # 核心功能模块
│   └── init_db.go  # 数据库初始化与连接配置
├── define/         # 常量定义模块
│   └── define.go   # 系统全局配置参数
├── helper/         # 工具函数库
│   └── helper.go   # 通用辅助函数（JWT、加密、邮件、UUID、Redis等）
├── middlewares/    # 中间件层
│   ├── auth_admin.go # 管理员权限验证
│   └── auth_user.go  # 用户权限验证
├── models/         # 数据模型层
│   ├── base.go            # 基础模型结构
│   ├── problem.go         # 题目模型
│   ├── problem_category.go # 题目分类关联模型
│   ├── category.go        # 分类模型
│   ├── submit.go          # 提交记录模型
│   ├── test_case.go       # 测试用例模型
│   └── user.go            # 用户模型
├── router/         # 路由层
│   └── app.go     # 路由配置与注册
├── service/        # 业务逻辑层
│   ├── category.go # 分类管理服务
│   ├── ping.go     # 健康检查服务
│   ├── problem.go  # 题目相关业务逻辑
│   ├── submit.go   # 提交相关业务逻辑
│   └── user.go     # 用户相关业务逻辑
├── test/           # 测试目录
│   ├── email_test.go # 邮件功能测试
│   ├── gorm_test.go # 数据库操作测试
│   ├── jwt_test.go  # JWT功能测试
│   ├── redis_test.go # Redis功能测试
│   └── uuid_test.go  # UUID生成测试
├── main.go         # 应用程序入口
├── go.mod          # Go 模块依赖管理
├── go.sum          # 依赖版本锁定文件
├── README.md       # 项目说明文档
├── README.en.md    # 英文版项目说明
└── swag.md         # Swagger文档配置文件
```

### 各层职责说明

- **code**: 管理用户提交代码的运行和评测环境
- **core**: 负责数据库连接初始化等核心基础设施
- **define**: 存储系统配置参数、分页默认值等常量
- **helper**: 提供通用工具函数，包括JWT令牌生成、密码加密等功能
- **middlewares**: 实现认证中间件，处理用户身份验证和权限控制
- **models**: 定义数据库表结构和数据访问方法
- **router**: 配置 API 路由，将请求映射到对应的服务处理函数
- **service**: 实现业务逻辑，处理请求与响应
- **test**: 包含单元测试和功能测试代码

## 核心功能

- **题目管理**
  - 问题列表查询（支持分页、关键词搜索、分类筛选）
  - 题目详情查看（包含完整题目信息）
  - 题目分类关联管理

- **用户系统**
  - 用户登录认证（密码MD5加密，JWT令牌生成）
  - 用户信息查询与展示
  - 安全的数据访问（密码字段自动过滤）

- **代码提交与评测**
  - 提交记录存储与管理
  - 多维度查询支持（按用户、题目、状态等）
  - 实时代码执行与判题
  - 多测试用例并发评测
  - 运行时资源监控（内存、时间限制）
  - 判题结果反馈（正确、错误、超时、内存溢出、编译错误）

- **分类管理**
  - 分类的增删改查
  - 题目分类关联管理

- **API 接口**
  - RESTful API 设计规范
  - Swagger 文档自动生成
  - 统一的响应格式与错误处理

- **辅助功能**
  - 邮件发送支持
  - 数据加密与安全保障
  - UUID生成（唯一标识符）
  - Redis缓存支持
  - 中间件认证（用户认证、管理员认证）

## 快速开始

### 环境要求

- Go 1.16 或更高版本
- MySQL 5.7 或更高版本
- Redis 6.0 或更高版本
- Git

### 安装步骤

1. **克隆代码仓库**
   ```bash
   git clone <仓库地址>
   cd gin_gorm_oj
   ```

2. **安装依赖**
   ```bash
   go mod tidy
   ```

3. **数据库配置**
   - 创建数据库：`CREATE DATABASE gin_gorm_oj CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`
   - 根据需要修改 `core/init_db.go` 中的数据库连接信息

4. **启动服务**
   ```bash
   go run main.go
   ```
   服务默认监听在 `http://localhost:8080`

## API 接口文档

系统集成了 Swagger 自动文档生成功能，启动服务后可通过以下地址访问完整的 API 文档：

- **Swagger 文档**: `http://localhost:8080/swagger/index.html`

### 常用 API 接口

| API路径 | 方法 | 功能描述 | 参数说明 |
|---------|------|----------|----------|
| `/ping` | GET | 服务健康检查 | 无 |
| `/login` | POST | 用户登录认证 | username: 用户名<br>password: 密码 |
| `/problem-list` | GET | 获取问题列表 | page: 页码<br>size: 每页数量<br>keyword: 搜索关键词<br>category_id: 分类ID |
| `/problem-detail` | GET | 获取问题详情 | identity: 题目唯一标识 |
| `/user-detail` | GET | 获取用户详情 | identity: 用户唯一标识 |
| `/submit-list` | GET | 获取提交列表 | page: 页码<br>size: 每页大小<br>problem_identity: 问题标识<br>user_identity: 用户标识<br>status: 状态 |
| `/submit` | POST | 提交代码 | problem_identity: 问题标识（Query参数）<br>body: 代码内容 |
| `/category-list` | GET | 获取分类列表 | page: 页码<br>size: 每页大小 |
| `/category-create` | POST | 创建分类 | name: 分类名称<br>identity: 分类标识（可选） |
| `/category-modify` | PUT | 修改分类 | identity: 分类标识<br>name: 分类名称 |
| `/category-delete` | DELETE | 删除分类 | identity: 分类标识 |

## 数据库设计

系统包含以下主要数据表：

- **users**: 用户信息表（存储用户名、密码加密、创建时间、提交次数、通过次数等）
- **problems**: 题目表（存储题目内容、标题、难度、时间限制、内存限制、提交次数、通过次数等）
- **categories**: 分类表（存储题目分类信息）
- **problem_categories**: 题目分类关联表（多对多关系映射）
- **submits**: 提交记录表（存储代码提交记录、评测结果、运行时间、内存使用等）
- **test_cases**: 测试用例表（存储题目测试数据和期望输出）

## 安全特性

- 用户密码字段在查询时自动排除，保护敏感信息
- 密码存储采用MD5加密方式
- JWT令牌认证机制，保障API访问安全
- 统一的错误处理和状态码返回机制
- 参数校验和输入验证

## 开发指南

### 代码风格
- 遵循 Go 语言官方代码风格
- 使用 `go fmt` 统一代码格式
- 关键逻辑添加详细注释
- 采用接口驱动设计模式

### 模型查询示例

```go
// 构建查询：关联问题表和用户表，并排除问题内容字段
tx := DB.Model(&Submit{}).Preload("Problem", func(db *gorm.DB) *gorm.DB {
    return db.Omit("content") // 预加载Problem关联时，排除content字段（不查询问题内容）
}).Preload("User") // 预加载User关联（用户信息）

// 分类查询示例
tx := models.GetSubmitList(problemIdentity, userIdentity, status)
err = tx.Count(&count).Debug().Offset(page).Limit(size).Find(&data).Error
```

### 项目初始化流程

1. 配置数据库连接信息（core/init_db.go）
2. 初始化Redis连接（helper/helper.go中的InitRedisDB函数）
3. 创建必要的目录结构（code/code-user/）
4. 初始化路由和中间件（router/app.go）
5. 启动HTTP服务器（main.go）

### Swagger文档配置

项目使用swag.md文件配置Swagger API文档，启动服务后可通过Web界面查看自动生成的API文档。

### md5
```go
// GetMd5 计算字符串的MD5哈希值
func GetMd5(s string) string {
    // 将输入字符串转换为字节切片，计算MD5哈希，并格式化为十六进制字符串
    return fmt.Sprintf("%x", md5.Sum([]byte(s)))
}
password = GetMd5(password)
```

## JWT认证

### 安装JWT依赖
```bash
go get github.com/dgrijalva/jwt-go
```

### JWT使用示例

```go
// 生成JWT令牌
token, err := helper.GenerateToken(data.Identity, data.Name)
// 验证JWT令牌
claims, err := helper.ParseToken(token)
```

### 中间件认证示例

```go
// 用户认证中间件
token := c.GetHeader("Token")
if token == "" {
    c.JSON(http.StatusOK, gin.H{
        "code": -1,
        "msg":  "未登录",
    })
    c.Abort()
    return
}

// 解析Token
userClaims, err := helper.AnalyseToken(token)
if err != nil {
    c.JSON(http.StatusOK, gin.H{
        "code": -1,
        "msg":  "认证失败",
    })
    c.Abort()
    return
}

// 存储用户信息到上下文
c.Set("user", userClaims)

## 密码安全

### MD5加密示例
```go
// GetMd5 计算字符串的MD5哈希值
func GetMd5(s string) string {
    // 将输入字符串转换为字节切片，计算MD5哈希，并格式化为十六进制字符串
    return fmt.Sprintf("%x", md5.Sum([]byte(s)))
}
password = GetMd5(password) // 用户登录时密码加密
```


## 发送邮件功能

### 安装依赖
```bash
go get github.com/jordan-wright/email
```
```go
// SendCode 发送邮件验证码
// toUserEmail: 收件人邮箱地址
// code: 要发送的验证码
func SendCode(toUserEmail, code string) error {

	e := email.NewEmail()                   // 创建邮件对象
	e.From = "Get <getcharzhaopan@163.com>" // 设置发件人信息
	e.To = []string{toUserEmail}            // 设置收件人邮箱
	e.Subject = "验证码发送"                     // 设置邮件主题
	// 设置HTML格式的邮件内容，包含验证码
	e.HTML = []byte("您的验证码：<b>" + code + "</b>")

	// 使用TLS加密方式发送邮件
	return e.SendWithTLS(
		"smtp.163.com:465", // SMTP服务器地址和端口
		smtp.PlainAuth(
			"",                       // 身份标识（通常为空）
			"getcharzhaopan@163.com", // 发件人邮箱账号
			"XYQHBVISUAHXXRQ",        // SMTP授权密码
			"smtp.163.com",           // SMTP服务器地址
		),
		&tls.Config{
			InsecureSkipVerify: true,           // 跳过证书验证（生产环境不建议）
			ServerName:         "smtp.163.com", // 服务器名称
		},
	)
}
```

### 功能说明
邮件发送功能主要用于系统通知、用户验证等场景，位于helper包中实现。相关功能可在test目录下的email_test.go中查看使用示例。

## UUID

### 安装依赖
```bash
go get github.com/satori/go.uuid
```

```go
// 生成版本4的UUID并转换为字符串格式
s := uuid.NewV4().String()
// 打印生成的UUID到控制台
println(s)
```

```go
// GetUUID 生成全局唯一标识符
func GetUUID() string {
    // 使用UUID v4版本生成随机唯一标识符并返回字符串格式
    return uuid.NewV4().String()
}
```

## redis

### 安装依赖
```bash
go get github.com/go-redis/redis/v8
```

```go
// InitRedisDB 初始化Redis数据库连接
// 返回Redis客户端实例指针
func InitRedisDB() *redis.Client {
    return redis.NewClient(&redis.Options{
    Addr:     "localhost:6379", // Redis服务器地址和端口
    Password: "1234",           // 密码（空表示无密码）
    DB:       0,                // 数据库编号（0表示默认数据库）
})
}

```

---

## 参与贡献

我们欢迎社区贡献！请按照以下步骤参与项目开发：

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 文件

## 联系方式

如有问题或建议，欢迎通过以下方式联系我们：

- **Issues**: 通过项目仓库的Issues提交反馈
- **项目维护者**: 可在代码贡献历史中查看主要维护者信息