coder-common-thin-backend/script/README.md

项目重构脚本使用指南

这是一套用于Maven项目重构和包名修复的自动化脚本，可以帮助你快速将一个项目模板重构为新的项目，并修复常见的包名重复问题。

📋 脚本概览

本目录包含了用于项目重构和包名修复的自动化脚本：

🔧 脚本文件说明

script/
├── project-refactor.sh           # ⭐ 主要推荐：完整重构脚本
├── simple-fix.sh                 # ⭐ 简单修复脚本  
├── fix-duplicate-packages.sh     # 专门修复重复包名
├── fix-directory-structure.sh    # 目录结构重建脚本
├── batch-refactor.sh             # 批量重构脚本（配置文件）
├── refactor-config.example       # 配置文件模板
└── README.md                     # 本使用说明文件

🎯 脚本选择建议

1. 主要推荐：project-refactor.sh ⭐⭐⭐⭐⭐

适用场景：

• 完整的项目重构（包名、模块名、数据库名等全面修改）
• 从一个框架模板创建新项目
• 大规模的包名重构

功能特点：

• ✅ 功能最完整（POM文件、Java文件、XML文件、配置文件全覆盖）
• ✅ 有备份功能
• ✅ 有验证步骤
• ✅ 支持嵌套模块处理
• ✅ 已修复包名重复问题

2. 简单场景：simple-fix.sh ⭐⭐⭐

适用场景：

• 只需要修复包名重复问题
• 简单的包名调整
• 紧急修复

功能特点：

• ✅ 执行速度快
• ✅ 逻辑简单可靠
• ✅ 不需要交互

3. 备用选择：fix-duplicate-packages.sh ⭐⭐

适用场景：

• 专门修复包名重复问题
• 需要详细的检测报告

🚀 新项目重构完整指南

步骤 1: 准备工作

1. 确保项目已提交到Git

   cd /path/to/your/new/project
   git status
   git add .
   git commit -m "Initial commit before refactoring"
   

2. 准备重构信息

   • 新的包名信息（如：org.leocoder.newproject）
   • 新的模块前缀（如：coder-newproject）
   • 新的数据库名称（可选）

步骤 2: 执行重构脚本

# 进入项目目录
cd /path/to/your/new/project

# 执行完整重构脚本
bash script/project-refactor.sh

步骤 3: 交互式配置

脚本会提示你输入以下信息：

3.1 项目目录

请输入项目根目录路径 (默认: 当前目录):
项目路径: [直接回车使用当前目录]

3.2 旧配置信息

旧的 GroupId (例如: org.leocoder.thin): org.leocoder.estate
旧的 ArtifactId (例如: coder-common-thin-backend): coder-estate-backend
旧的模块前缀 (例如: coder-common-thin): coder-estate

3.3 新配置信息

新的 GroupId (例如: org.leocoder.course): org.leocoder.newproject
新的 ArtifactId (例如: coder-course-backend): coder-newproject-backend
新的模块前缀 (例如: coder-course): coder-newproject

3.4 数据库配置（可选）

旧的数据库名称 (留空跳过): coder_estate
新的数据库名称: coder_newproject

3.5 确认执行

是否创建备份? (Y/n): Y
是否继续重构? (y/N): y

步骤 4: 验证重构结果

4.1 检查目录结构

# 检查是否还有重复目录
find . -type d -path "*/org/leocoder/org/leocoder*"

# 应该没有任何输出，如果有输出说明还存在重复目录

4.2 检查包名

# 检查Java文件包名是否正确
grep -r "package org.leocoder" . --include="*.java" | head -5

# 输出应该类似：
# ./src/main/java/org/leocoder/newproject/web/Application.java:package org.leocoder.newproject.web;

4.3 检查import语句

# 检查import语句是否正确
grep -r "import org.leocoder" . --include="*.java" | head -5

# 输出应该使用新的包名

4.4 编译验证

# 重新编译项目
mvn clean compile

# 如果编译成功，说明重构正确

步骤 5: 测试验证

# 运行测试
mvn test

# 启动应用（如果是Spring Boot项目）
mvn spring-boot:run

🛠️ 常见问题处理

问题 1: 发现重复包名目录

症状：

find . -type d -path "*/org/leocoder/org/leocoder*"
# 有输出，存在重复目录

解决方案：

# 使用简单修复脚本
bash script/simple-fix.sh

问题 2: 编译失败

可能原因：

• 包名引用不一致
• import语句错误
• 配置文件中的包名未更新

解决方案：

# 1. 检查具体错误信息
mvn clean compile

# 2. 手动检查和修复特定文件
grep -r "org\.leocoder\.estate" . --include="*.java"
grep -r "org\.leocoder\.estate" . --include="*.xml"
grep -r "org\.leocoder\.estate" . --include="*.yml"

# 3. 如果需要，再次运行修复脚本
bash script/fix-duplicate-packages.sh

问题 3: IDE中显示错误

解决方案：

1. 刷新项目：在IDE中刷新整个项目
2. 重新导入：重新导入Maven项目
3. 清理缓存：清理IDE缓存和索引
4. 重启IDE：重启开发环境

📚 方法二：配置文件批量重构（推荐批量处理）

# 1. 复制配置文件模板
cp refactor-config.example my-project.conf

# 2. 编辑配置文件
vim my-project.conf

# 3. 运行批量重构
./batch-refactor.sh my-project.conf

配置文件格式

# 项目基本信息
PROJECT_DIR="/path/to/your/project"

# 旧配置
OLD_GROUP_ID="org.leocoder.thin"
OLD_ARTIFACT_ID="coder-common-thin-backend"
OLD_MODULE_PREFIX="coder-common-thin"
OLD_DATABASE_NAME="coder-common-thin"

# 新配置
NEW_GROUP_ID="org.leocoder.course"
NEW_ARTIFACT_ID="coder-course-backend"
NEW_MODULE_PREFIX="coder-course"
NEW_DATABASE_NAME="coder-course"

# 其他选项
CREATE_BACKUP="true"      # 是否创建备份
AUTO_CONFIRM="false"      # 是否自动确认（跳过确认步骤）

📋 脚本详细说明

project-refactor.sh 执行步骤

1. 步骤 1: 获取重构参数
2. 步骤 2: 配置摘要确认
3. 步骤 3: 备份项目
4. 步骤 4: 修改 POM 文件
5. 步骤 5: 修改 Java 包名
6. 步骤 6: 修改 XML 映射文件
7. 步骤 7: 修改配置文件
8. 步骤 8: 重命名目录结构
9. 步骤 9: 处理遗漏的嵌套模块
10. 步骤 10: 修复重复包名
11. 步骤 11: 重命名 SQL 文件
12. 步骤 12: 清理和验证

simple-fix.sh 执行内容

• 删除错误的目录结构
• 清理空目录
• 修复Java文件中的包名
• 修复XML文件中的包名
• 验证修复结果

🔧 重构内容说明

脚本会自动处理以下内容：

1. POM文件修改

• ✅ 修改根POM和所有子模块的 <groupId>
• ✅ 修改根POM和所有子模块的 <artifactId>
• ✅ 修改 <name> 标签
• ✅ 修改 <module> 引用
• ✅ 修改依赖引用中的groupId和artifactId

2. Java源码修改

• ✅ 修改所有Java文件的 package 声明
• ✅ 修改所有Java文件的 import 语句
• ✅ 修改注解中的包名引用（如@SpringBootApplication的scanBasePackages）

3. XML映射文件

• ✅ 修改MyBatis Mapper文件的 namespace
• ✅ 修改 resultType 中的包名引用

4. 配置文件

• ✅ 修改YAML/Properties文件中的包扫描配置
• ✅ 修改数据库连接配置中的数据库名
• ✅ 修改文件路径配置

5. 目录结构重构

• ✅ 重命名Java包目录结构（src/main/java/com/old/package → src/main/java/com/new/package）
• ✅ 重命名模块目录（old-module-name → new-module-name）
• ✅ 重命名SQL文件
• ✅ 修复重复包名问题

🎯 最佳实践

重构流程建议

# 1. 创建新分支
git checkout -b refactor-to-newproject

# 2. 执行重构
bash script/project-refactor.sh

# 3. 验证结果
mvn clean compile
mvn test

# 4. 提交变更
git add .
git commit -m "refactor: change package from org.leocoder.estate to org.leocoder.newproject"

# 5. 合并到主分支（如果一切正常）
git checkout main
git merge refactor-to-newproject

命名规范建议

• 包名：org.leocoder.{项目名}
• 模块前缀：coder-{项目名}
• 数据库名：coder_{项目名}

示例配置

# 电商项目示例
旧包名: org.leocoder.estate → 新包名: org.leocoder.ecommerce
旧模块: coder-estate → 新模块: coder-ecommerce
旧数据库: coder_estate → 新数据库: coder_ecommerce

# 教育项目示例  
旧包名: org.leocoder.estate → 新包名: org.leocoder.education
旧模块: coder-estate → 新模块: coder-education
旧数据库: coder_estate → 新数据库: coder_education

💡 使用示例

示例1：从通用框架改造为选课系统

# 交互式输入
./project-refactor.sh

# 输入示例：
# 项目路径: /Users/leocoder/my-project
# 旧的 GroupId: org.leocoder.estate
# 旧的 ArtifactId: coder-estate-backend
# 旧的模块前缀: coder-estate
# 新的 GroupId: org.leocoder.course
# 新的 ArtifactId: coder-course-backend
# 新的模块前缀: coder-course

示例2：批量处理多个项目

# 为选课系统创建配置
cat > course-system.conf << EOF
PROJECT_DIR="/Users/leocoder/course-project"
OLD_GROUP_ID="org.leocoder.estate"
OLD_ARTIFACT_ID="coder-estate-backend"
OLD_MODULE_PREFIX="coder-estate"
NEW_GROUP_ID="org.leocoder.course"
NEW_ARTIFACT_ID="coder-course-backend"
NEW_MODULE_PREFIX="coder-course"
CREATE_BACKUP="true"
AUTO_CONFIRM="false"
EOF

# 为库存系统创建配置
cat > inventory-system.conf << EOF
PROJECT_DIR="/Users/leocoder/inventory-project"
OLD_GROUP_ID="org.leocoder.estate"
OLD_ARTIFACT_ID="coder-estate-backend"
OLD_MODULE_PREFIX="coder-estate"
NEW_GROUP_ID="org.leocoder.inventory"
NEW_ARTIFACT_ID="coder-inventory-backend"
NEW_MODULE_PREFIX="coder-inventory"
CREATE_BACKUP="true"
AUTO_CONFIRM="false"
EOF

# 执行批量重构
./batch-refactor.sh course-system.conf
./batch-refactor.sh inventory-system.conf

⚠️ 重要注意事项

使用前必读

1. 备份项目：始终在Git中提交代码后再执行脚本
2. 关闭IDE：执行脚本前关闭IDE，避免文件锁定
3. 检查权限：确保脚本有执行权限（chmod +x script/*.sh）
4. 逐步验证：每个步骤完成后都进行验证

安全建议

1. 测试环境：先在测试环境中执行，确认无误后再在生产代码中使用
2. 分支操作：建议在新的Git分支中执行重构操作
3. 备份重要：重要项目建议手动备份整个项目目录

重构后需要手动检查的项目

• IDE中的运行配置（主类路径）
• 数据库连接配置
• 第三方服务配置
• 测试用例
• 文档更新

🆘 获取帮助

如果在使用过程中遇到问题：

1. 查看日志：脚本执行过程中的详细日志
2. 检查文件：手动检查具体的错误文件
3. 重新执行：如果部分失败，可以重新执行脚本
4. 手动修复：对于特殊情况，可能需要手动修复部分文件

常见问题

Q: 脚本执行后项目无法启动？ A: 检查IDE的运行配置，确保主类路径已更新为新的包名。

Q: 某些文件没有被修改？ A: 检查文件是否在target目录下，脚本会跳过编译输出目录。

Q: 包名格式验证失败？ A: 确保包名符合Java命名规范，只能包含字母、数字、下划线和点号。

Q: 权限被拒绝？ A: 确保脚本有执行权限：chmod +x *.sh

调试技巧

1. 查看详细日志: 脚本会显示处理的文件信息
2. 检查备份: 如果出现问题，可以从备份恢复
3. 分步执行: 可以注释掉脚本中的某些步骤来分步调试

🔧 扩展功能

你可以根据需要扩展脚本功能：

1. 添加新的文件类型: 在相应的函数中添加处理逻辑
2. 自定义替换规则: 修改sed命令的正则表达式
3. 集成到CI/CD: 将脚本集成到自动化流水线中

---

创建时间: 2025-01-09
最后更新: 2025-01-09
版本: v2.0
作者: Leocoder

📝 更新日志

v2.0 (2025-01-09)

• ✅ 新增重复包名检测和修复功能
• ✅ 新增 simple-fix.sh 快速修复脚本
• ✅ 新增 fix-duplicate-packages.sh 专门修复重复包名
• ✅ 完善了使用指南和最佳实践
• ✅ 增加了详细的问题排查步骤
• ✅ 优化了目录结构处理逻辑

v1.0 (2025-07-06)

• ✅ 基础项目重构功能
• ✅ 支持POM文件、Java文件、XML文件修改
• ✅ 支持配置文件批量处理
• ✅ 基础的目录结构重命名功能