5.7 KiB

Raw Blame History

艺考招生管理系统 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

快速启动

cd server
go mod tidy
swag init
go run main.go

配置说明

系统支持多环境配置文件：

config/config.dev.yaml - 开发环境
config/config.test.yaml - 测试环境
config/config.prod.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)
生产环境务必开启安全校验
需要配置合适的限流规则防止恶意请求
定期清理日志文件避免磁盘空间不足

5.7 KiB Raw Blame History