Maven 项目转换器

Maven 项目转换器

自动将 Java 项目转换为 Maven 标准结构，包括重组目录、更新包名和生成构建配置。

快速开始

在目标项目上运行转换脚本：

python3 scripts/​maven_converter.py [项目路径] [选项]

常用选项：

• --dry-run: 预览更改而不修改文件
• --group-id: 设置 Maven groupId（默认：com.example）
• --artifact-id: 设置 Maven artifactId（默认：项目目录名）
• --version: 设置项目版本（默认：1.0-SNAPSHOT）

示例：

# 预览转换
python3 scripts/​maven_converter.py /​path/​to/​project --dry-run

# 执行转换并自定义 groupId
python3 scripts/​maven_converter.py /​path/​to/​project --group-id com.mycompany --artifact-id my-app

功能说明

转换器自动执行以下操作：

1. 创建 Maven 标准结构

   • src/​main/​java/ - 生产源代码
   • src/​main/​resources/ - 生产资源文件
   • src/​test/​java/ - 测试源代码
   • src/​test/​resources/ - 测试资源文件

2. 重组文件

   • 分析 Java 文件中的包声明
   • 将文件移动到适当的 Maven 目录
   • 识别测试文件（通过注解、导入、命名规则）
   • 复制资源文件到 Maven 资源目录

3. 转换包名

   • 将包声明中的 test 替换为 example
   • 处理模式：test.*、*.test.*、*.test
   • 更新所有 Java 文件中的 package 语句
   • 示例：
     • package test; → package example;
     • package com.test.app; → package com.example.app;
     • package com.app.test.utils; → package com.app.example.utils;

4. 生成 pom.xml

   • 如果不存在则创建标准 Maven POM
   • 包含 JUnit 5 依赖
   • 配置编译器插件（Java 11）
   • 设置构建插件（surefire、jar）
   • 使用 UTF-8 编码

5. 清理

   • 移动文件后删除空目录
   • 保留现有的 Maven 结构

使用工作流

步骤 1：评估项目

转换前先了解项目结构：

# 查看当前结构
find /​path/​to/​project -type f -name "*.java" | head -20

# 检查是否已有 Maven 设置
ls -la /​path/​to/​project/​pom.xml
ls -la /​path/​to/​project/​src/

步骤 2：运行预演模式

始终先预览更改：

python3 scripts/​maven_converter.py /​path/​to/​project --dry-run

检查输出以验证：

• 文件移动是否合理
• 包转换是否正确
• 没有遗漏重要文件

步骤 3：执行转换

运行实际转换：

python3 scripts/​maven_converter.py /​path/​to/​project \
  --group-id com.company \
  --artifact-id project-name \
  --version 1.0.0

步骤 4：验证结果

检查转换后的结构：

# 查看 Maven 结构
tree /​path/​to/​project/​src -L 4

# 验证 pom.xml
cat /​path/​to/​project/​pom.xml

# 测试构建
cd /​path/​to/​project
mvn clean compile
mvn test

步骤 5：手动调整

根据需要进行检查和调整：

1. 检查 pom.xml

   • 添加项目特定的依赖
   • 如果不是 Java 11，设置正确的 Java 版本
   • 如果构建可执行 JAR，配置主类
   • 添加其他插件

2. 验证包名

   • 确保所有 import 仍能解析
   • 检查代码中硬编码的包字符串
   • 更新引用旧包的文档

3. 检查移动的文件

   • 确认测试文件在 src/​test/​java
   • 确认主代码在 src/​main/​java
   • 检查资源文件在适当的目录

自定义 POM 模板

如果要使用自定义 pom.xml 模板而不是自动生成：

1. 将模板放在 assets/​pom_template.xml
2. 转换前将其复制到项目：

   cp assets/​pom_template.xml /​path/​to/​project/​pom.xml
   

3. 运行转换器（如果文件存在则跳过 pom.xml 生成）

assets/​pom_template.xml 中的模板提供了起点，包含：

• 标准 Maven 结构
• JUnit 5 配置
• 常用插件（compiler、surefire、jar）
• 依赖和主类的占位符

功能限制

• 已有 Maven 项目：跳过已在 src/​main/​java 或 src/​test/​java 中的文件
• 已有 pom.xml：不修改现有的 POM 文件
• 复杂包结构：不寻常的包结构需要手动检查
• 非 Java 资源：专用资源可能需要手动放置
• import 语句：不更新 import 语句（仅包声明）

故障排除

文件未正确移动

• 检查包声明是否与实际包结构匹配
• 验证文件有正确的 .java 扩展名
• 检查文件编码（脚本期望 UTF-8）

包转换问题

• 查看 dry-run 输出检查意外转换
• 如果模式不匹配，手动调整包名
• 更新引用旧包名的 import 语句

转换后构建失败

• 运行 mvn clean compile 检查编译
• 验证 pom.xml 中的所有依赖
• 检查 Java 版本是否与编译器配置匹配
• 确保资源文件在正确的目录

脚本错误

• 验证已安装 Python 3：python3 --version
• 检查项目目录的文件权限
• 确保没有文件被锁定或正在使用