/RuoYi-Vue-Plus-Configurator

Primary LanguagePython

Ruoyi-Vue-Plus Vue项目自定义工具 - 用户使用指南

功能概述

本工具可帮助您自定义Ruoyi-Vue-Plus项目的文件名前缀和包名，适用于Vue版本（Cloud版本没有测试过）。工具提供以下功能：

  1. 将特定前缀(如"ruoyi")的文件名和目录名更改为您指定的前缀
  2. 将特定包名(如"org.dromara")更改为您指定的包名
  3. 保留特定依赖模块(org.dromara.sms4j和org.dromara.warm)的包名不变
  4. 处理.import文件中的包引用
  5. 创建项目快照用于备份和恢复
  6. 提供详细的日志记录

安装要求

  • Python 3.6+
  • 无需额外依赖库，使用Python标准库

基本使用

命令行参数

python3 customerProject.py [选项]

主要参数：

参数 描述
--base-dir 项目根目录，默认为当前目录
--old-prefix 旧的文件名前缀，默认为"ruoyi"
--new-prefix 新的文件名前缀
--old-package 旧的包名，默认为"org.dromara"
--new-package 新的包名
--create-snapshot 在修改前创建项目快照
--list-snapshots 列出所有可用的项目快照
--restore-snapshot 从指定的快照ID恢复项目
--snapshot-desc 快照描述
--log-file 日志文件路径
--verbose 详细日志输出

常用操作示例

推荐使用命令

# 修改前自动创建快照，同时生成日志
python3 customerProject.py --log-file custom.log --create-snapshot --new-prefix myapp --new-package com.mycompany

修改文件前缀和包名

# 只修改文件名前缀
python3 customerProject.py --new-prefix myapp

# 只修改包名
python3 customerProject.py --new-package com.mycompany

# 同时修改文件名前缀和包名
python3 customerProject.py --new-prefix myapp --new-package com.mycompany

快照管理

# 创建项目快照
python3 customerProject.py --create-snapshot --snapshot-desc "项目初始状态"

# 列出所有可用快照
python3 customerProject.py --list-snapshots

# 从快照恢复
python3 customerProject.py --restore-snapshot 20250418_162119

# 修改前自动创建快照，同时生成日志
python3 customerProject.py --log-file custom.log --create-snapshot --new-prefix myapp --new-package com.mycompany

日志选项

# 指定日志文件
python3 customerProject.py --new-prefix myapp --log-file customization.log

# 显示详细日志
python3 customerProject.py --verbose --new-prefix myapp --new-package com.mycompany

工作流程说明

脚本执行项目自定义时遵循以下步骤顺序：

  1. 更新文件内容 - 首先替换文件内容中的包名和文件名引用
  2. 特别处理.import文件 - 确保自动配置文件正确更新
  3. 重命名文件 - 更改符合条件的文件名
  4. 更新包结构 - 重构Java包目录结构
  5. 重命名目录 - 最后进行目录重命名

这个顺序设计用来确保引用被正确处理，避免路径变更带来的问题。

快照功能详解

什么是项目快照

快照是项目当前状态的完整备份，保存在.project_snapshots目录下。每个快照以时间戳命名，包含：

  • 项目文件的ZIP归档
  • 描述性元数据（创建时间、描述等）

快照的使用场景

  • 安全备份：在进行重大修改前保存项目状态
  • 版本控制：在没有使用Git等工具时提供基本的版本管理
  • 错误恢复：在修改导致项目损坏时恢复到之前的状态

恢复快照安全保障

当恢复快照时，脚本会自动创建当前状态的备份，确保即使恢复过程出错，您也能回到恢复前的状态。

安全特性

  1. 选择性包保留：保留指定依赖包（org.dromara.sms4j和org.dromara.warm）不做修改
  2. 目录排除：自动排除特殊目录（.git、.project_snapshots、target、node_modules）
  3. 精确替换：使用正则表达式确保只替换完整单词，避免部分替换
  4. 异常处理：完善的错误捕获和日志记录
  5. 自动备份：关键操作前自动创建状态备份

最佳实践

  1. 始终创建快照：在执行任何修改前使用--create-snapshot选项
  2. 使用描述性的快照说明：便于日后识别每个快照的用途
  3. 保存日志：使用--log-file选项保存操作日志，便于排查问题
  4. 测试环境验证：首先在测试环境中运行脚本，验证结果符合预期
  5. 定期清理快照：定期删除不再需要的快照以节省磁盘空间

故障排除

常见问题

  1. 问题：脚本报错"找不到文件/目录" 解决方案：确认您在正确的目录中运行脚本，或使用--base-dir指定正确路径

  2. 问题：文件内容替换不完整 解决方案：使用--verbose选项查看详细日志，检查是否有异常情况

  3. 问题：恢复快照后项目无法运行 解决方案：检查是否需要重新构建项目或更新依赖

  4. 问题：部分目录名未被修改 解决方案：确认这些目录是否在排除列表中，或手动重命名

获取帮助

如果您遇到未列出的问题，可以：

  1. 查看完整日志了解详细错误信息
  2. 使用--help选项查看所有可用参数
  3. 从最近的快照恢复项目状态

限制和注意事项

  • 脚本不会修改二进制文件（如.jar、.war等）
  • 大型项目可能需要较长时间处理
  • 虽然脚本尽量安全处理修改，但仍建议在重要项目上使用版本控制系统
  • 特殊的文件格式或编码可能导致处理异常

高级用例

自定义排除规则

如果需要保留额外的包名不被修改，可以修改脚本中的preserved_packages列表。

批量处理多个项目

可以创建简单的shell脚本循环处理多个项目：

#!/bin/bash
for project in /path/to/projects/*; do
  if [ -d "$project" ]; then
    python3 customerProject.py --base-dir "$project" --new-prefix myapp --new-package com.mycompany
  fi
done

更新历史

v1.1.0:

  • 增加递归处理子目录功能
  • 更精确的文件名处理
  • 改进错误处理
  • 优化执行顺序
  • 增强日志和进度报告

v1.0.0:

  • 初始版本
  • 基本的文件名和包名修改功能
  • 快照和日志功能

感谢使用Ruoyi-Vue-Plus项目自定义工具！如有建议或改进意见，欢迎反馈。