Dependency "jakarta.annotation:jakarta.annotation-api:2.0.0" not found: 如何解决？

Question

在使用Maven或Gradle构建Java项目时，可能会遇到依赖无法解析的问题，例如提示“Dependency 'jakarta.annotation:jakarta.annotation-api:2.0.0' not found”。此问题通常出现在Spring Boot项目或Jakarta EE相关项目中。主要原因包括：Maven仓库中未正确配置、依赖版本不存在或拼写错误、项目使用了不兼容的仓库源等。此外，Jakarta项目从Java EE迁移后，包名由`javax.annotation`改为`jakarta.annotation`，开发者若误用旧版本或错误命名空间，也会导致依赖解析失败。解决此问题需要确认版本号是否正确、检查仓库配置，并确保使用兼容的Spring Boot或Jakarta平台版本。

Answer 1

1. 问题现象与常见表现

在使用Maven或Gradle构建Java项目时，尤其是Spring Boot或Jakarta EE相关项目，开发者常常会遇到依赖无法解析的问题。典型错误提示如下：

Dependency 'jakarta.annotation:jakarta.annotation-api:2.0.0' not found

该问题可能出现在本地构建、CI/CD流水线或IDE中，表现为项目无法编译或运行。

2. 常见原因分析

• 仓库配置错误：Maven或Gradle配置的仓库地址不正确，或未包含Jakarta官方仓库。
• 版本号错误：依赖版本不存在或拼写错误，如误将jakarta.annotation-api写成javax.annotation-api。
• 命名空间变更：Jakarta从Java EE迁移后，包名从javax变更为jakarta，旧版本引用会导致依赖失败。
• Spring Boot版本不兼容：某些Spring Boot版本未完全兼容Jakarta EE 9+，需升级Spring Boot或手动指定兼容版本。

3. 解决方案详解

3.1 检查依赖配置

确保pom.xml（Maven）或build.gradle（Gradle）中的依赖书写正确。例如：

<dependency>
    <groupId>jakarta.annotation</groupId>
    <artifactId>jakarta.annotation-api</artifactId>
    <version>2.0.0</version>
</dependency>

3.2 添加正确的仓库源

在pom.xml中添加Jakarta官方仓库：

<repositories>
    <repository>
        <id>jakarta</id>
        <url>https://repo.eclipse.org/content/repositories/jakartaee- releases/</url>
    </repository>
</repositories>

Gradle中添加：

repositories {
    mavenCentral()
    maven { url 'https://repo.eclipse.org/content/repositories/jakartaee-releases/' }
}

3.3 使用Spring Boot兼容版本

若使用Spring Boot，建议升级至2.6+版本以支持Jakarta EE 9+。可参考下表匹配Spring Boot与Jakarta EE版本：

Spring Boot版本	Jakarta EE版本	支持的Jakarta Annotation API版本
2.5.x	8.0.x	1.3.x
2.6.x	9.0.x	2.0.x
2.7.x	9.1.x	2.1.x

3.4 检查本地Maven缓存

有时候本地Maven缓存损坏也会导致依赖解析失败。可以尝试清除缓存：

mvn dependency:purge-local-repository

或手动删除目录：

rm -rf ~/.m2/repository/jakarta/annotation

4. 高级调试技巧

4.1 使用Maven或Gradle命令行调试

Maven中启用详细输出：

mvn dependency:resolve -X

Gradle中启用堆栈跟踪：

gradle dependencies --stacktrace

4.2 依赖树分析

查看依赖树是否引入了冲突版本：

mvn dependency:tree

或在Gradle中：

gradle dependencies

4.3 使用Maven BOM统一版本管理

在pom.xml中引入Jakarta EE BOM统一管理依赖版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-api</artifactId>
            <version>9.1.0</version>
            <scope>provided</scope>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

5. 常见错误与修复流程图

graph TD A[开始] --> B[检查依赖名称是否正确] B --> C{是否为javax命名空间?} C -->|是| D[改为jakarta命名空间] C -->|否| E[检查版本是否存在] E --> F{版本是否存在?} F -->|否| G[查找最新版本] F -->|是| H[检查仓库配置] H --> I{仓库是否正确?} I -->|否| J[添加Jakarta官方仓库] I -->|是| K[清理本地缓存] K --> L[重新构建项目]