217 lines
5.7 KiB
Markdown
217 lines
5.7 KiB
Markdown
# 艺考招生管理系统 API
|
|
|
|
## 项目概述
|
|
|
|
艺考招生管理系统是一个基于 Go + Gin + GORM + Redis 的 RESTful API 服务，用于管理和计算艺考志愿填报、成绩统计和录取概率等功能。
|
|
|
|
### 核心技术栈
|
|
|
|
- **Go 1.21+** - 主要开发语言
|
|
- **Gin** - Web 框架
|
|
- **GORM** - ORM 框架
|
|
- **MySQL 8.0** - 数据存储
|
|
- **Redis** - 会话存储和限流
|
|
- **Swaggo** - API 文档生成
|
|
|
|
### 项目架构
|
|
|
|
项目采用典型的分层架构模式：
|
|
|
|
```
|
|
server/
|
|
├── main.go # 应用程序入口
|
|
├── config/ # 配置文件
|
|
│ ├── config.go # 应用配置
|
|
│ ├── database.go # MySQL 配置
|
|
│ └── redis.go # Redis 配置
|
|
├── common/ # 公共组件
|
|
│ ├── response.go # 统一响应格式
|
|
│ ├── context.go # 上下文工具
|
|
│ ├── logger.go # 日志工具
|
|
│ └── password.go # 密码加密
|
|
├── middleware/ # 中间件
|
|
│ ├── auth.go # 登录鉴权
|
|
│ ├── security.go # 安全校验
|
|
│ ├── ratelimit.go # 接口限流
|
|
│ └── cors.go # 跨域处理
|
|
├── modules/ # 业务模块
|
|
│ ├── system/ # 系统模块 (用户认证、权限管理)
|
|
│ ├── user/ # 用户模块 (用户相关功能)
|
|
│ └── yx/ # 艺考模块 (核心业务)
|
|
├── docs/ # API 文档
|
|
└── logs/ # 日志目录
|
|
```
|
|
|
|
### 业务模块
|
|
|
|
#### 1. 系统模块 (system)
|
|
- 用户认证 (登录/登出/用户信息)
|
|
- 用户管理
|
|
|
|
#### 2. 用户模块 (user)
|
|
- 成绩管理
|
|
- 专业选择
|
|
- 志愿填报
|
|
- 用户认证
|
|
|
|
#### 3. 艺考模块 (yx)
|
|
- 院校专业管理
|
|
- 历年招生数据
|
|
- 计算专业逻辑
|
|
- 用户成绩管理
|
|
- 志愿管理
|
|
- 志愿记录管理
|
|
|
|
## 部署与运行
|
|
|
|
### 环境要求
|
|
- Go 1.21+
|
|
- MySQL 8.0
|
|
- Redis
|
|
|
|
### 快速启动
|
|
|
|
```bash
|
|
cd server
|
|
go mod tidy
|
|
swag init
|
|
go run main.go
|
|
```
|
|
|
|
### 配置说明
|
|
|
|
系统支持多环境配置文件：
|
|
|
|
- `config/config.dev.yaml` - 开发环境
|
|
- `config/config.test.yaml` - 测试环境
|
|
- `config/config.prod.yaml` - 生产环境
|
|
|
|
配置文件格式示例：
|
|
```yaml
|
|
server:
|
|
port: 8081
|
|
|
|
database:
|
|
driver: mysql
|
|
host: localhost
|
|
port: 3306
|
|
database: yitisheng
|
|
username: root
|
|
password: "password"
|
|
|
|
redis:
|
|
addr: localhost:6379
|
|
password: "password"
|
|
db: 1
|
|
```
|
|
|
|
## 安全机制
|
|
|
|
### 1. 登录鉴权
|
|
- 基于 JWT Token 的身份验证
|
|
- 支持白名单配置，允许特定接口无需登录访问
|
|
- Token 存储在 Redis 中，支持过期时间设置
|
|
|
|
### 2. 安全校验
|
|
- 请求头需携带签名进行验证
|
|
- 防暴力破解机制
|
|
- 支持白名单配置
|
|
|
|
### 3. 接口限流
|
|
- 基于 Redis 滑动窗口算法
|
|
- 支持按用户ID或IP限流
|
|
- 可为不同接口配置不同限流规则
|
|
|
|
## API 接口
|
|
|
|
### 认证相关
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | /api/user/auth/login | 用户登录 |
|
|
| POST | /api/user/auth/logout | 用户登出 |
|
|
| GET | /api/user/auth/info | 获取当前用户信息 |
|
|
|
|
### 系统管理
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/sys-users | 获取用户列表 |
|
|
| POST | /api/sys-users | 创建用户 |
|
|
| PUT | /api/sys-users/:id | 更新用户 |
|
|
| DELETE | /api/sys-users/:id | 删除用户 |
|
|
|
|
### 艺考相关
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/yx-school-majors | 获取院校专业列表 |
|
|
| GET | /api/yx-history-enrolls | 获取历年招生数据 |
|
|
| GET | /api/yx-calculation-majors | 获取计算专业数据 |
|
|
| GET | /api/yx-user-scores | 获取用户成绩 |
|
|
| GET | /api/yx-volunteers | 获取志愿列表 |
|
|
| POST | /api/yx-volunteers | 创建志愿 |
|
|
| PUT | /api/yx-volunteers/:id | 更新志愿 |
|
|
| DELETE | /api/yx-volunteers/:id | 删除志愿 |
|
|
|
|
### 中间件执行顺序
|
|
|
|
```
|
|
请求 -> 安全校验 -> 限流 -> 登录鉴权 -> Controller
|
|
```
|
|
|
|
## 数据实体
|
|
|
|
### YxVolunteer (志愿表)
|
|
- ID: 主键
|
|
- VolunteerName: 志愿单名称
|
|
- ScoreId: 关联成绩ID
|
|
- CreateType: 生成类型 (1.手动生成, 2.智能生成)
|
|
- State: 状态 (0-未使用, 1-使用中, 2-历史)
|
|
- CreateBy: 创建人
|
|
- CreateTime: 创建时间
|
|
- UpdateBy: 更新人
|
|
- UpdateTime: 更新时间
|
|
|
|
## 常量定义
|
|
|
|
### 业务状态常量
|
|
- StateActive ("1") - 使用中
|
|
- StateInactive ("0") - 未使用/已删除
|
|
- StateHistory ("2") - 历史记录
|
|
|
|
### 令牌相关
|
|
- TokenHeader: "Authorization"
|
|
- HeaderTokenPrefix: "Bearer "
|
|
- RedisTokenExpire: 24小时
|
|
|
|
## 日志系统
|
|
|
|
- 支持 debug/info/warn/error 级别
|
|
- 输出到 HTML 文件，按日期和启动次数命名
|
|
- 可配置是否同时输出到控制台
|
|
|
|
## 开发规范
|
|
|
|
### 代码风格
|
|
- 使用 Go 语言标准格式 (go fmt)
|
|
- 遵循 Go 语言命名规范
|
|
- 使用有意义的变量和函数名
|
|
|
|
### 错误处理
|
|
- 统一使用 common.Error(c, code, message) 返回错误
|
|
- 业务错误码使用 HTTP 标准码或自定义业务码
|
|
- 记录详细错误日志便于调试
|
|
|
|
### 接口文档
|
|
- 使用 Swaggo 注解生成 API 文档
|
|
- 所有公开接口都应有完整的文档注释
|
|
- 包含请求参数、响应格式和错误码说明
|
|
|
|
## 额外说明
|
|
|
|
项目还包含一些 Java 代码文件，如 `ScoreUtil.java`，这表明项目可能正在从 Java 版本迁移到 Go 版本，或者 Java 版本作为参考。Go 版本中的 `server/modules/yx/service/score_util.go` 文件可能包含与 Java 版本相同功能的实现。
|
|
|
|
## 注意事项
|
|
|
|
- 开发环境中的安全校验默认关闭 (enable: false)
|
|
- 生产环境务必开启安全校验
|
|
- 需要配置合适的限流规则防止恶意请求
|
|
- 定期清理日志文件避免磁盘空间不足 |