meowrain
1945cc2fb1
主要更新： 1. 新增管理员权限检查功能 - 添加 UserRoleEnum 枚举类统一管理用户角色（USER, ADMIN, BAN） - 改进 ContextHolderUtils.isAdmin() 方法，支持不区分大小写的角色比较 - 更新 UserServiceImpl 使用枚举常量代替硬编码字符串 - 新增管理员权限使用指南文档 (docs/admin-permission-guide.md) 2. 修复Maven打包配置 - 配置根POM的spring-boot-maven-plugin默认跳过repackage - 为所有服务模块启用repackage，确保可以打包为可执行JAR - 修复公共库模块打包失败的问题 - 涉及服务：gateway, auth, user-service, question-service, file-service, blog-service, upms-biz, ai-service 3. 更新项目文档 - README.md：添加详细的打包说明、首次克隆准备工作、服务启动顺序等 - CLAUDE.md：更新项目架构说明和开发指南 4. 重构题目服务责任链结构 - 将责任链类按功能分类到 question/ 和 submit/ 子目录 - 新增 QuestionSubmitJudgeInfoEnum 和相关查询功能 - 改进题目提交服务的实现 5. 其他改进 - 添加 Feign Token 中继拦截器 - 更新 AsyncConfig 配置 - 优化 Jackson 和 Security 配置
368 lines
9.3 KiB
Markdown
368 lines
9.3 KiB
Markdown
# AIOJ - Online Judge System
|
||
|
||
基于 Spring Boot 微服务架构的在线判题系统。
|
||
|
||
## 服务端口配置
|
||
|
||
| 服务名称 | 端口 | 说明 |
|
||
|---------|------|------|
|
||
| Gateway | 18085 | API 网关服务 |
|
||
| Auth Service | 18081 | 认证授权服务 |
|
||
| User Service | 18082 | 用户服务 |
|
||
| UPMS | 18083 | 用户权限管理服务 |
|
||
| File Service | 18066 | 文件服务 |
|
||
|
||
## 模块结构
|
||
|
||
### 核心模块 (aioj-backend-common)
|
||
|
||
- **aioj-backend-common-bom** - 依赖管理
|
||
- **aioj-backend-common-core** - 核心工具类
|
||
- **aioj-backend-common-feign** - Feign 客户端配置
|
||
- **aioj-backend-common-log** - 日志框架
|
||
- **aioj-backend-common-mybatis** - MyBatis 扩展
|
||
- **aioj-backend-common-starter** - 自动配置启动器
|
||
|
||
### 服务模块
|
||
|
||
- **aioj-backend-gateway** - API 网关
|
||
- **aioj-backend-auth** - 认证服务
|
||
- **aioj-backend-user-service** - 用户服务
|
||
- **aioj-backend-upms** - 权限管理服务
|
||
- **aioj-backend-file-service** - 文件服务
|
||
- **aioj-backend-judge-service** - 判题服务（开发中）
|
||
- **aioj-backend-question-service** - 题库服务（开发中）
|
||
- **aioj-backend-ai-service** - AI 服务（开发中）
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- JDK 17 或更高版本
|
||
- Maven 3.6 或更高版本
|
||
- MySQL 8.0 或更高版本
|
||
- Redis 6.0 或更高版本
|
||
- Nacos Server 2.x（用于服务注册和配置管理）
|
||
|
||
### 首次克隆后的准备工作
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd AI_OJ
|
||
```
|
||
|
||
2. **安装公共依赖模块**
|
||
|
||
首次克隆后，需要先将公共模块安装到本地Maven仓库：
|
||
```bash
|
||
mvn clean install -DskipTests
|
||
```
|
||
|
||
这个命令会：
|
||
- 编译所有模块
|
||
- 将公共库模块（aioj-backend-common-*）安装到本地Maven仓库
|
||
- 打包所有服务模块为可执行JAR
|
||
|
||
3. **配置数据库和中间件**
|
||
|
||
根据各服务的 `application.yml` 配置文件，设置：
|
||
- MySQL 数据库连接信息
|
||
- Redis 连接信息
|
||
- Nacos 服务地址
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
# 编译所有模块（不打包）
|
||
mvn clean compile
|
||
|
||
# 编译并跳过测试
|
||
mvn clean compile -DskipTests
|
||
```
|
||
|
||
## 项目打包
|
||
|
||
### 打包说明
|
||
|
||
本项目采用模块化架构，分为**公共库模块**和**服务模块**：
|
||
|
||
- **公共库模块**（aioj-backend-common-*）：编译为普通JAR，供其他模块依赖
|
||
- **服务模块**：打包为包含所有依赖的可执行Fat JAR（Spring Boot可执行JAR）
|
||
|
||
### 打包所有服务
|
||
|
||
```bash
|
||
# 打包所有服务（推荐）
|
||
mvn clean package -DskipTests
|
||
|
||
# 打包并运行测试
|
||
mvn clean package
|
||
```
|
||
|
||
打包完成后，每个服务模块的 `target` 目录下会生成两个JAR文件：
|
||
- `<service-name>-1.0.0.jar` - 可执行的Fat JAR（包含所有依赖，约60-100MB）
|
||
- `<service-name>-1.0.0.jar.original` - 原始JAR（仅包含本模块代码，约100KB）
|
||
|
||
### 打包单个服务
|
||
|
||
如果只需要打包某个特定服务：
|
||
|
||
```bash
|
||
# 打包网关服务
|
||
mvn clean package -pl aioj-backend-gateway -am -DskipTests
|
||
|
||
# 打包认证服务
|
||
mvn clean package -pl aioj-backend-auth -am -DskipTests
|
||
|
||
# 打包用户服务
|
||
mvn clean package -pl aioj-backend-user-service -am -DskipTests
|
||
|
||
# 打包题库服务
|
||
mvn clean package -pl aioj-backend-question-service -am -DskipTests
|
||
|
||
# 打包文件服务
|
||
mvn clean package -pl aioj-backend-file-service -am -DskipTests
|
||
|
||
# 打包博客服务
|
||
mvn clean package -pl aioj-backend-blog-service -am -DskipTests
|
||
|
||
# 打包权限管理服务
|
||
mvn clean package -pl aioj-backend-upms/aioj-backend-upms-biz -am -DskipTests
|
||
```
|
||
|
||
**参数说明：**
|
||
- `-pl <module>`: 指定要构建的模块
|
||
- `-am`: 同时构建该模块依赖的其他模块（also-make）
|
||
- `-DskipTests`: 跳过测试
|
||
|
||
### 打包后的文件位置
|
||
|
||
打包完成后，可执行JAR文件位于各服务模块的 `target` 目录：
|
||
|
||
```
|
||
aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
|
||
aioj-backend-auth/target/aioj-backend-auth-1.0.0.jar
|
||
aioj-backend-user-service/target/aioj-backend-user-service-1.0.0.jar
|
||
aioj-backend-question-service/target/aioj-backend-question-service-1.0.0.jar
|
||
aioj-backend-file-service/target/aioj-backend-file-service-1.0.0.jar
|
||
aioj-backend-blog-service/target/aioj-backend-blog-service-1.0.0.jar
|
||
aioj-backend-upms/aioj-backend-upms-biz/target/aioj-backend-upms-biz-1.0.0.jar
|
||
```
|
||
|
||
### 运行打包后的服务
|
||
|
||
使用 `java -jar` 命令运行打包后的服务：
|
||
|
||
```bash
|
||
# 运行网关服务
|
||
java -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
|
||
|
||
# 运行认证服务
|
||
java -jar aioj-backend-auth/target/aioj-backend-auth-1.0.0.jar
|
||
|
||
# 运行用户服务
|
||
java -jar aioj-backend-user-service/target/aioj-backend-user-service-1.0.0.jar
|
||
|
||
# 指定配置文件运行
|
||
java -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar --spring.profiles.active=prod
|
||
|
||
# 指定JVM参数运行
|
||
java -Xms512m -Xmx1024m -jar aioj-backend-gateway/target/aioj-backend-gateway-1.0.0.jar
|
||
```
|
||
|
||
### 使用Docker部署（可选）
|
||
|
||
项目已配置JIB插件，可以直接构建Docker镜像：
|
||
|
||
```bash
|
||
# 构建Docker镜像到本地
|
||
mvn package jib:dockerBuild -pl aioj-backend-gateway -am -DskipTests
|
||
|
||
# 构建并推送到远程仓库
|
||
mvn package jib:build -pl aioj-backend-gateway -am -DskipTests
|
||
```
|
||
|
||
### 开发模式运行
|
||
|
||
在开发过程中，可以使用 `spring-boot:run` 直接运行服务（无需打包）：
|
||
|
||
```bash
|
||
# 运行网关
|
||
mvn spring-boot:run -pl aioj-backend-gateway
|
||
|
||
# 运行认证服务
|
||
mvn spring-boot:run -pl aioj-backend-auth
|
||
|
||
# 运行用户服务
|
||
mvn spring-boot:run -pl aioj-backend-user-service
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
- Gateway: http://localhost:18085
|
||
- Auth Service: http://localhost:18081/api
|
||
- User Service: http://localhost:18082/api
|
||
- UPMS: http://localhost:18083/api
|
||
- File Service: http://localhost:18066/api
|
||
|
||
## 常用命令
|
||
|
||
### 代码格式化
|
||
|
||
```bash
|
||
# 格式化所有代码
|
||
mvn spring-javaformat:apply
|
||
|
||
# 检查代码格式
|
||
mvn spring-javaformat:check
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
mvn test
|
||
|
||
# 运行单个模块的测试
|
||
mvn test -pl aioj-backend-user-service
|
||
```
|
||
|
||
### 清理构建产物
|
||
|
||
```bash
|
||
# 清理所有模块的target目录
|
||
mvn clean
|
||
|
||
# 清理单个模块
|
||
mvn clean -pl aioj-backend-gateway
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 打包时提示找不到依赖
|
||
|
||
**问题**：打包服务时提示找不到 `aioj-backend-common-core` 等公共模块。
|
||
|
||
**解决方案**：首次克隆或更新公共模块后，需要先安装公共模块到本地仓库：
|
||
```bash
|
||
mvn clean install -DskipTests
|
||
```
|
||
|
||
### 2. 打包失败：Unable to find main class
|
||
|
||
**问题**：公共库模块（aioj-backend-common-*）打包时报错。
|
||
|
||
**解决方案**：这是正常的，公共库模块不应该被打包为可执行JAR。项目已配置为跳过公共模块的repackage。如果遇到此问题，请确保使用最新的配置。
|
||
|
||
### 3. 服务启动失败
|
||
|
||
**问题**：运行JAR时服务无法启动。
|
||
|
||
**可能原因**：
|
||
- 数据库连接失败：检查MySQL是否启动，连接信息是否正确
|
||
- Redis连接失败：检查Redis是否启动
|
||
- Nacos连接失败：检查Nacos Server是否启动
|
||
- 端口被占用：检查服务端口是否被其他程序占用
|
||
|
||
**解决方案**：查看日志输出，根据错误信息排查问题。
|
||
|
||
### 4. 内存不足
|
||
|
||
**问题**：打包或运行时提示内存不足。
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 增加Maven构建内存
|
||
export MAVEN_OPTS="-Xmx2048m"
|
||
|
||
# 或在Windows上
|
||
set MAVEN_OPTS=-Xmx2048m
|
||
|
||
# 运行服务时指定内存
|
||
java -Xms512m -Xmx1024m -jar <service>.jar
|
||
```
|
||
|
||
## 服务启动顺序
|
||
|
||
为确保系统正常运行，建议按以下顺序启动服务：
|
||
|
||
1. **基础设施服务**（必须先启动）
|
||
- MySQL 数据库
|
||
- Redis 缓存服务
|
||
- Nacos 服务注册中心
|
||
|
||
2. **核心服务**
|
||
- `aioj-backend-auth` - 认证服务（其他服务可能依赖认证）
|
||
- `aioj-backend-gateway` - API网关（统一入口）
|
||
|
||
3. **业务服务**（可并行启动）
|
||
- `aioj-backend-user-service` - 用户服务
|
||
- `aioj-backend-upms-biz` - 权限管理服务
|
||
- `aioj-backend-question-service` - 题库服务
|
||
- `aioj-backend-file-service` - 文件服务
|
||
- `aioj-backend-blog-service` - 博客服务
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
- **Spring Boot**: 3.5.7
|
||
- **Spring Cloud**: 2025.0.0
|
||
- **Spring Cloud Alibaba**: 2025.0.0.0
|
||
- **Java**: 17
|
||
|
||
### 基础设施
|
||
- **服务注册与发现**: Alibaba Nacos
|
||
- **流量控制**: Alibaba Sentinel
|
||
- **API网关**: Spring Cloud Gateway
|
||
- **负载均衡**: Spring Cloud LoadBalancer
|
||
|
||
### 数据存储
|
||
- **数据库**: MySQL 8.0
|
||
- **ORM框架**: MyBatis
|
||
- **缓存**: Redis
|
||
- **会话管理**: Spring Session (Redis)
|
||
|
||
### 安全认证
|
||
- **安全框架**: Spring Security
|
||
- **认证方式**: JWT (JSON Web Tokens)
|
||
|
||
### 其他组件
|
||
- **对象存储**: 腾讯云COS
|
||
- **Markdown解析**: Flexmark
|
||
- **API文档**: SpringDoc OpenAPI 3 + Knife4j
|
||
- **工具库**: Hutool
|
||
|
||
## 项目文档
|
||
|
||
- **[CLAUDE.md](./CLAUDE.md)** - 项目架构和开发指南
|
||
- **[管理员权限使用指南](./docs/admin-permission-guide.md)** - 管理员权限检查功能说明
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
- 遵循 Spring Java Format 规范
|
||
- 提交前运行 `mvn spring-javaformat:apply` 格式化代码
|
||
|
||
### 分支管理
|
||
- `main` - 主分支，保持稳定
|
||
- `develop` - 开发分支
|
||
- `feature/*` - 功能分支
|
||
- `bugfix/*` - 修复分支
|
||
|
||
### 提交规范
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档更新
|
||
- `refactor`: 代码重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建/工具链相关
|
||
|
||
## 许可证
|
||
|
||
[添加许可证信息]
|
||
|
||
## 联系方式
|
||
|
||
[添加联系方式]
|