8.8 KiB
8.8 KiB
工程本地启动指导
📋 目录
🔧 环境要求
必需环境
- JDK: 17 (推荐使用 Oracle JDK 或 OpenJDK)
- Maven: 3.8.8+
- Node.js: 20.15.x+ (推荐 20.15.0)
- npm: 10.7.x+
- MySQL: 5.7+ 或 8.0+（本机可不安装，使用阿里云的环境）
- Redis: 5.0+ （本机可不安装，使用阿里云的环境）
推荐配置
- 操作系统: macOS 12+, Windows 10+, Ubuntu 20.04+
- 内存: 8GB+ (推荐 16GB)
- 磁盘: 20GB+ 可用空间
🛠 环境安装指导
macOS 环境安装
1. 安装 Homebrew (如未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. 安装 JDK 17
# 方法1: 使用 Homebrew
brew install openjdk@17
# 创建软链接
sudo ln -sfn /usr/local/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk
# 方法2: 下载 Oracle JDK
# 访问: https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html
# 下载 macOS x64 版本并安装
3. 安装 Maven 3.8.8
# 方法1: 使用 Homebrew
brew install maven@3.8
# 方法2: 手动安装
cd ~/Downloads
wget https://archive.apache.org/dist/maven/maven-3/3.8.8/binaries/apache-maven-3.8.8-bin.tar.gz
tar -xzf apache-maven-3.8.8-bin.tar.gz
sudo mv apache-maven-3.8.8 /opt/maven
4. 配置环境变量
# 编辑 ~/.zshrc 或 ~/.bash_profile
vim ~/.zshrc
# 添加以下内容
export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-17.jdk/Contents/Home
export MAVEN_HOME=/opt/maven
export PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH
# 使配置生效
source ~/.zshrc
5. 安装 Node.js 和 npm
# 使用 Homebrew
brew install node@20
# 或者下载官方安装包
# 访问: https://nodejs.org/
Windows 环境安装
1. 安装 JDK 17
步骤 1: 下载 JDK
- 访问 Oracle JDK 下载页面
- 下载 Windows x64 版本的 JDK 17
- 或者访问 OpenJDK 下载免费版本
步骤 2: 安装 JDK
- 运行下载的安装包
- 选择安装路径 (推荐:
C:\Program Files\Java\jdk-17) - 完成安装
步骤 3: 配置环境变量
# 打开系统属性 -> 高级 -> 环境变量
# 新建系统变量
变量名: JAVA_HOME
变量值: C:\Program Files\Java\jdk-17
# 编辑 Path 变量，添加
%JAVA_HOME%\bin
2. 安装 Maven 3.8.8
步骤 1: 下载 Maven
- 访问 Maven 下载页面
- 下载
apache-maven-3.8.8-bin.zip
步骤 2: 解压安装
- 解压到
C:\Program Files\Apache\maven-3.8.8
步骤 3: 配置环境变量
# 新建系统变量
变量名: MAVEN_HOME
变量值: C:\Program Files\Apache\maven-3.8.8
# 编辑 Path 变量，添加
%MAVEN_HOME%\bin
3. 安装 Node.js
- 访问 Node.js 官网
- 下载 Windows 安装包 (推荐 LTS 版本)
- 运行安装包，按默认选项安装
4. 验证安装
打开 Command Prompt 或 PowerShell，执行：
java -version
mvn -version
node -version
npm -version
🗄 数据库配置
MySQL 配置
- 启动 MySQL 服务
- 创建数据库
CREATE DATABASE hzdyjs_xg CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
- 导入数据库脚本
# 导入完整数据库
mysql -u root -p hzdyjs_xg < docs/设计文档/database/hzdyjs_xg.sql
# 或按模块导入
mysql -u root -p hzdyjs_xg < docs/设计文档/database/05-system-management-module.sql
mysql -u root -p hzdyjs_xg < docs/设计文档/database/03-logistics-module.sql
# ... 其他模块
Redis 配置
启动 Redis 服务：
# macOS
brew services start redis
# Windows (如使用 WSL)
sudo service redis-server start
# 或直接运行
redis-server
🚀 后端启动
⚠️ 重要说明
后端服务必须按照以下顺序启动，每个服务启动成功后再启动下一个！
启动顺序
1. 启动监控服务
cd backend
./start-monitor.sh
等待提示: 看到 "监控服务启动成功" 或类似日志后，再进行下一步
2. 启动任务调度服务
./start-job.sh
等待提示: 看到 "任务调度服务启动成功" 或类似日志后，再进行下一步
3. 启动主应用服务
等待提示: 看到 "主应用启动成功" 或访问 http://localhost:8080 正常返回
启动验证
服务启动成功后，可通过以下方式验证：
- 监控服务: http://localhost:9090
- 任务调度服务: http://localhost:8081
- 主应用服务: http://localhost:8080
- API 接口文档: http://localhost:8080/swagger-ui/index.html ⭐
Windows 环境启动
如果在 Windows 环境下，可以使用以下方式：
# 在 Git Bash 或 WSL 中执行
cd backend
bash start-monitor.sh
bash start-job.sh
bash start-main.sh
# 或者直接运行 Java 命令
java -jar ruoyi-extend/ruoyi-monitor-admin/target/ruoyi-monitor-admin.jar
java -jar ruoyi-extend/ruoyi-snailjob-server/target/ruoyi-snailjob-server.jar
java -jar ruoyi-admin/target/ruoyi-admin.jar
🎨 前端启动
首次启动
1. 安装依赖
cd web
npm install
注意: 首次启动时必须先执行 npm install 安装项目依赖
2. 启动开发服务器
npm run dev
日常启动
如果已经安装过依赖，后续启动只需：
cd web
npm run dev
启动成功验证
- 浏览器自动打开或手动访问: http://localhost
- 能够看到登录页面表示启动成功
其他可用命令
# 构建生产版本
npm run build
# 代码格式检查
npm run lint
# 代码格式修复
npm run lint:fix
# 类型检查
npm run type-check
🔍 MapStruct版本分析与建议
根据我的分析，关于您项目中MapStruct Plus 1.4.8版本的问题，我有以下建议：
📊 当前状态分析
您的项目配置：
- MapStruct Plus版本: 1.4.8
- Lombok版本: 1.18.36
- Spring Boot版本: 3.4.6
- Java版本: JDK 17/21
🎯 版本建议：建议升级
基于我的研究和行业最佳实践，建议升级到MapStruct Plus 1.5.0或更高版本，原因如下：
🔼 升级的理由
-
Bug修复和稳定性提升
- MapStruct Plus 1.4.8是一个相对较老的版本
- 1.5.0及更高版本修复了许多已知的编译时问题
- 特别是与Spring Boot 3.x的兼容性得到了改善
-
JDK兼容性
- 您的项目使用JDK 17/21，而较新版本的MapStruct对新JDK的支持更好
- 解决了类似"sourcefile is null"的NullPointerException问题
-
与Spring Boot 3.4.6的兼容性
- 您使用的Spring Boot 3.4.6是最新版本
- 新版本的MapStruct Plus与最新Spring Boot版本兼容性更好
-
Lombok集成改进
- 您使用Lombok 1.18.36，新版本MapStruct对Lombok的集成更稳定
- 减少了注解处理器之间的冲突
🚫 不建议降级的原因
-
功能缺失
- 降级到1.4.7会失去1.4.8中的bug修复
- 可能重新引入已修复的问题
-
向后兼容性
- 降级可能导致与现有代码的兼容性问题
- 需要更多的代码修改工作
🛠️ 推荐的升级方案
方案1：保守升级（推荐）
<code_block_to_apply_changes_from>
方案2：最新稳定版
<mapstruct-plus.version>1.6.3</mapstruct-plus.version>
📋 升级前的准备工作
- 备份当前代码
- 清理编译缓存
mvn clean - 检查依赖冲突
- 测试关键功能
🔧 升级后的验证步骤
- 编译测试
mvn clean compile - 运行测试用例
- 检查生成的映射器代码
- 验证业务功能
💡 额外建议
-
保持依赖版本一致性
- 确保所有MapStruct相关依赖版本保持一致
- 检查lombok-mapstruct-binding版本兼容性
-
监控升级影响
- 升级后密切关注编译和运行时错误
- 特别关注MapStruct生成的代码质量
🎯 总结
建议升级到MapStruct Plus 1.5.0或更高版本，这将：
- ✅ 解决当前的编译问题
- ✅ 提高与Spring Boot 3.x的测试git提交
- ✅ 获得更好的JDK 17/21支持
- ✅ 享受更多的bug修复和性能优化
升级是更安全、更可持续的选择，能够为您的项目带来长期的稳定性和性能提升。