175 lines
4.1 KiB
Markdown
175 lines
4.1 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 # 密码加密 (PBE)
|
|
├── middleware/
|
|
│ ├── auth.go # 登录鉴权
|
|
│ ├── security.go # 安全校验 (防暴力入侵)
|
|
│ └── ratelimit.go # 接口限流
|
|
├── modules/
|
|
│ ├── system/ # 系统模块
|
|
│ └── yx/ # 艺考模块
|
|
├── logs/ # 日志目录
|
|
│ └── 2025-12-17-1.html # HTML格式日志
|
|
└── docs/ # Swagger文档
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
cd server
|
|
go mod tidy
|
|
swag init
|
|
go run main.go
|
|
```
|
|
|
|
## 配置说明
|
|
|
|
修改 `config/config.go`:
|
|
|
|
```go
|
|
var AppConfig = &appConfig{
|
|
// 日志配置
|
|
Log: LogConfig{
|
|
Level: "debug", // debug/info/warn/error
|
|
Dir: "logs", // 日志目录
|
|
Console: true, // 是否输出到控制台
|
|
},
|
|
// 安全配置
|
|
Security: SecurityConfig{
|
|
Enable: true, // 是否启用
|
|
HeaderKey: "X-App-Sign", // 签名字段
|
|
SecretKey: "yts@2025#secure", // 签名密钥
|
|
},
|
|
// 限流配置
|
|
RateLimit: RateLimitConfig{
|
|
Enable: true,
|
|
Default: RateLimitRule{Interval: 2, MaxRequests: 1}, // 默认2秒1次
|
|
Rules: map[string]RateLimitRule{
|
|
"/api/auth/login": {Interval: 5, MaxRequests: 1}, // 登录5秒1次
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## 功能说明
|
|
|
|
### 1. 日志系统
|
|
|
|
- 支持 debug/info/warn/error 级别
|
|
- 输出到 HTML 文件，按日期和启动次数命名
|
|
- 可配置是否同时输出到控制台
|
|
|
|
```go
|
|
common.Debug("调试信息: %s", msg)
|
|
common.Info("普通信息: %s", msg)
|
|
common.Warn("警告信息: %s", msg)
|
|
common.LogError("错误信息: %s", msg)
|
|
```
|
|
|
|
### 2. 安全校验 (防暴力入侵)
|
|
|
|
请求头需携带签名:
|
|
```
|
|
X-App-Sign: MD5(timestamp + secretKey)
|
|
X-App-Timestamp: 毫秒时间戳
|
|
```
|
|
|
|
前端签名示例 (JavaScript):
|
|
```javascript
|
|
const timestamp = Date.now().toString();
|
|
const sign = md5(timestamp + 'yts@2025#secure');
|
|
|
|
fetch('/api/xxx', {
|
|
headers: {
|
|
'X-App-Sign': sign,
|
|
'X-App-Timestamp': timestamp,
|
|
'Authorization': 'Bearer ' + token
|
|
}
|
|
});
|
|
```
|
|
|
|
### 3. 接口限流
|
|
|
|
- 基于 Redis 滑动窗口算法
|
|
- 支持按用户ID或IP限流
|
|
- 不同接口可配置不同规则
|
|
|
|
默认规则: 2秒1次
|
|
超过限制返回: `{"code": 429, "message": "操作过快，请稍后再试"}`
|
|
|
|
配置示例:
|
|
```go
|
|
Rules: map[string]RateLimitRule{
|
|
"/api/auth/login": {Interval: 5, MaxRequests: 1}, // 5秒1次
|
|
"/api/yx-school-majors": {Interval: 1, MaxRequests: 5}, // 1秒5次
|
|
}
|
|
```
|
|
|
|
## 中间件执行顺序
|
|
|
|
```
|
|
请求 -> 安全校验 -> 限流 -> 登录鉴权 -> Controller
|
|
```
|
|
|
|
## 白名单配置
|
|
|
|
```go
|
|
// 安全校验白名单
|
|
middleware.AddSecurityWhitelist("/api/public/xxx")
|
|
|
|
// 限流白名单
|
|
middleware.AddRateLimitWhitelist("/api/public/xxx")
|
|
|
|
// 登录鉴权白名单
|
|
middleware.AddWhiteList("/api/public/xxx")
|
|
```
|
|
|
|
## API 接口
|
|
|
|
### 认证
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | /api/auth/login | 登录 |
|
|
| POST | /api/auth/logout | 登出 |
|
|
| GET | /api/auth/info | 获取当前用户 |
|
|
|
|
### 用户管理 `/api/sys-users`
|
|
### 院校专业 `/api/yx-school-majors`
|
|
### 历年招生 `/api/yx-history-enrolls`
|
|
### 计算专业 `/api/yx-calculation-majors`
|
|
|
|
## 日志文件示例
|
|
|
|
日志以 HTML 格式保存，支持浏览器直接打开查看:
|
|
|
|
```
|
|
logs/
|
|
├── 2025-12-17-1.html # 第1次启动
|
|
├── 2025-12-17-2.html # 第2次启动
|
|
└── 2025-12-18-1.html # 新的一天
|
|
```
|