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**
   ```bash
   cd /path/to/your/new/project
   git status
   git add .
   git commit -m "Initial commit before refactoring"
   ```

2. **准备重构信息**
   - 新的包名信息（如：`org.leocoder.newproject`）
   - 新的模块前缀（如：`coder-newproject`）
   - 新的数据库名称（可选）

### 步骤 2: 执行重构脚本

```bash
# 进入项目目录
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 检查目录结构
```bash
# 检查是否还有重复目录
find . -type d -path "*/org/leocoder/org/leocoder*"

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

#### 4.2 检查包名
```bash
# 检查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语句
```bash
# 检查import语句是否正确
grep -r "import org.leocoder" . --include="*.java" | head -5

# 输出应该使用新的包名
```

#### 4.4 编译验证
```bash
# 重新编译项目
mvn clean compile

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

### 步骤 5: 测试验证

```bash
# 运行测试
mvn test

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

## 🛠️ 常见问题处理

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

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

**解决方案**：
```bash
# 使用简单修复脚本
bash script/simple-fix.sh
```

### 问题 2: 编译失败

**可能原因**：
- 包名引用不一致
- import语句错误
- 配置文件中的包名未更新

**解决方案**：
```bash
# 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**：重启开发环境

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

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

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

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

#### 配置文件格式

```bash
# 项目基本信息
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文件
- ✅ **修复重复包名问题**

## 🎯 最佳实践

### 重构流程建议

```bash
# 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：从通用框架改造为选课系统

```bash
# 交互式输入
./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：批量处理多个项目

```bash
# 为选课系统创建配置
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文件修改
- ✅ 支持配置文件批量处理
- ✅ 基础的目录结构重命名功能