工程本地启动指导

📋 目录

环境要求
环境安装指导
- macOS 环境安装
- Windows 环境安装
数据库配置
后端启动
前端启动
常见问题

🔧 环境要求

必需环境

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 环境安装

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. 启动主应用服务

./hot-start.sh

等待提示: 看到 "主应用启动成功" 或访问 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 hot-start.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
```
1. 检查依赖冲突
2. 测试关键功能
🔧 升级后的验证步骤
1. 编译测试 bash mvn clean compile
运行测试用例
检查生成的映射器代码
验证业务功能

💡 额外建议

保持依赖版本一致性
- 确保所有MapStruct相关依赖版本保持一致
- 检查lombok-mapstruct-binding版本兼容性
监控升级影响
- 升级后密切关注编译和运行时错误
- 特别关注MapStruct生成的代码质量

🎯 总结

建议升级到MapStruct Plus 1.5.0或更高版本，这将：

✅ 解决当前的编译问题
✅ 提高与Spring Boot 3.x的兼容性
✅ 获得更好的JDK 17/21支持
✅ 享受更多的bug修复和性能优化

升级是更安全、更可持续的选择，能够为您的项目带来长期的稳定性和性能提升。

工程本地启动指导.md 8.8 KB Histórico Em bruto