如何在重命名Maven构件时提供迁移指引信息

我之前刚好处理过类似的需求，就是给重命名的Maven构件加上迁移指引，让老用户能快速找到新构件，其实核心就是通过Maven的配置把旧构件变成一个“迁移中转站”，同时在POM里明确标注迁移信息。下面一步步来给你讲怎么实现：

核心思路 #

我们需要维护旧构件的一个迁移专用版本，这个版本本身不包含任何业务代码，只做两件事：

1. 清晰告知用户构件已重命名，给出新构件的完整坐标
2. 自动引入新构件，让依赖旧构件的项目无缝过渡

具体配置步骤 #

1. 修改旧构件的POM（迁移版本） #

假设你的旧构件是io.github.hakky54:foo，现在要迁移到io.github.hakky54:bar:1.0.0，我们给旧构件发布一个新的迁移版本（比如6.0.0），修改其POM如下：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.github.hakky54</groupId>
    <artifactId>foo</artifactId>
    <version>6.0.0</version> <!-- 迁移专用版本，标记为最后一个foo版本 -->
    <packaging>jar</packaging>

    <!-- 关键：在description里清晰标注迁移信息，Maven仓库会展示这段内容 -->
    <description>
        **此构件已停止维护并重命名！**
        请使用新的构件坐标：`io.github.hakky54:bar:1.0.0`，所有后续功能更新和bug修复都会发布在新构件中。
    </description>

    <!-- 自动引入新构件，依赖旧版本的项目会自动加载新构件的代码 -->
    <dependencies>
        <dependency>
            <groupId>io.github.hakky54</groupId>
            <artifactId>bar</artifactId>
            <version>1.0.0</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

    <!-- 如果你的Java包路径也跟着变更了（比如从io.github.hakky54.foo改成io.github.hakky54.bar），添加shade插件做包路径映射 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.4.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <relocations>
                                <relocation>
                                    <pattern>io.github.hakky54.foo</pattern>
                                    <shadedPattern>io.github.hakky54.bar</shadedPattern>
                                </relocation>
                            </relocations>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

2. 发布迁移版本的旧构件 #

按照你平时发布Maven构件的流程，把这个迁移版本的foo:6.0.0发布到对应的仓库（比如Maven Central、私有仓库等）。

3. 新构件的补充说明（可选） #

在新构件bar:1.0.0的POM里，也可以添加一段说明，提到它是从io.github.hakky54:foo迁移而来的，方便用户反向查找：

<description>
    此构件是原`io.github.hakky54:foo`的重命名版本，承接原构件的所有功能和维护。
</description>

实现效果 #

• 用户在Maven仓库搜索旧构件foo时，会直接看到description里的迁移提示，快速定位到新构件
• 如果用户的项目依赖旧构件的迁移版本（foo:6.0.0），Maven会自动引入新的bar构件，无需手动修改依赖
• 若配置了包路径映射，项目里原本使用旧包名的代码也能正常运行，平滑过渡到新包名

内容来源于stack exchange