AgentSkillsCN

maven-converter

将 Java 项目转换为标准 Maven 结构，自动重组目录、转换包名（test→example）并生成 pom.xml。当用户需要将非 Maven Java 项目转换为 Maven 项目、重构现有项目为 Maven 标准结构，或请求 Maven 项目设置/转换时使用此技能。

中文原作
SKILL.md
--- frontmatter
name: maven-converter
description: 将 Java 项目转换为标准 Maven 结构，自动重组目录、转换包名（test→example）并生成 pom.xml。当用户需要将非 Maven Java 项目转换为 Maven 项目、重构现有项目为 Maven 标准结构，或请求 Maven 项目设置/转换时使用此技能。

Maven 项目转换器

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

快速开始

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

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

常用选项：

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

示例：

bash
# 预览转换
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：评估项目

转换前先了解项目结构：

bash
# 查看当前结构
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：运行预演模式

始终先预览更改：

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

检查输出以验证：

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

步骤 3：执行转换

运行实际转换：

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

步骤 4：验证结果

检查转换后的结构：

bash
# 查看 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. •转换前将其复制到项目：
    bash
    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
  • •检查项目目录的文件权限
  • •确保没有文件被锁定或正在使用