Spring Boot多模块项目编译报错：javax.persistence.Entity类未找到

问题背景 #

开发Spring Boot多模块项目时，核心模块core负责存放实体类、仓库、服务等可共享代码，但编译时抛出java.lang.ClassNotFoundException: javax.persistence.Entity错误。将model包移至website模块后编译正常，但不符合架构设计，需在保持现有架构的前提下解决问题。

错误栈 #

org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':core:compileJava'.
    ...
Caused by: java.lang.ClassNotFoundException: javax.persistence.Entity

项目配置 #

settings.gradle #

rootProject.name = 'platform'
include 'core', 'website'

根build.gradle #

ext {
    lombokVersion = '1.18.28'
    jakartaVersion = '2.1.1'
}
subprojects {
    apply plugin: 'java'
    group = 'tech.muntasir.platform'
    version = '1.0.0'
    compileJava {
        sourceCompatibility = '20'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        add 'annotationProcessor', "org.projectlombok:lombok:${lombokVersion}"
        add 'annotationProcessor', "jakarta.annotation:jakarta.annotation-api:${jakartaVersion}"
        add 'compileOnly', "org.projectlombok:lombok:${lombokVersion}"
        add 'compileOnly', "jakarta.annotation:jakarta.annotation-api:${jakartaVersion}"
        add 'implementation', 'org.apache.commons:commons-lang3:3.12.0'
    }
}
wrapper {
    gradleVersion = '8.1.1'
    distributionType = Wrapper.DistributionType.ALL
}

core/build.gradle #

plugins {
    id 'java-library'
}
ext {
    jakartaPersistenceVersion = '3.1.0'
    querydslVersion = '5.0.0'
}
dependencies {
    annotationProcessor group: 'jakarta.persistence', name: 'jakarta.persistence-api', version: jakartaPersistenceVersion
    annotationProcessor "com.querydsl:querydsl-apt:${querydslVersion}:jpa"
    api group: 'jakarta.persistence', name: 'jakarta.persistence-api', version: jakartaPersistenceVersion
    api group: 'com.querydsl', name: 'querydsl-jpa', version: querydslVersion
    implementation group: 'org.springframework.data', name: 'spring-data-jpa', version: '3.1.2'
}

website/build.gradle #

plugins {
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.1.2'
}
dependencies {
    implementation project(':core')
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'com.mysql:mysql-connector-j'
}

实体类代码 #

BaseEntity #

package tech.muntasir.platform.model;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.MappedSuperclass;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;
import lombok.experimental.SuperBuilder;
import java.io.Serial;
import java.io.Serializable;
@AllArgsConstructor
@NoArgsConstructor
@SuperBuilder(toBuilder = true)
@MappedSuperclass
public abstract class BaseEntity implements Serializable {
    @Serial private static final long serialVersionUID = -6829291079395405325L;
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    public Long getId() {
        return id;
    }
}

User #

package tech.muntasir.platform.model;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;
import jakarta.persistence.UniqueConstraint;
import lombok.*;
import lombok.experimental.SuperBuilder;
import java.io.Serial;
@AllArgsConstructor
@NoArgsConstructor
@SuperBuilder(toBuilder = true)
@Getter
@Setter
@Entity
@Table(
        name = "users",
        uniqueConstraints = {
                @UniqueConstraint(columnNames = {"email"}, name = "users_uc_email"),
                @UniqueConstraint(columnNames = {"phone"}, name = "users_uc_phone")
        }
)
public class User extends BaseEntity {
    @Serial private static final long serialVersionUID = 8065341740680850019L;
    @Column(name = "name", nullable = false)
    private String name;
    @Column(name = "email", nullable = false)
    private String email;
    @Column(name = "phone", nullable = false)
    private String phone;
    @Column(name = "remarks", columnDefinition = "TEXT")
    private String remarks;
    @Column(name = "is_active", nullable = false, columnDefinition = "BOOLEAN DEFAULT TRUE")
    @Builder.Default
    private boolean active = true;
    @Column(name = "is_deleted", nullable = false, columnDefinition = "BOOLEAN DEFAULT FALSE")
    @Builder.Default
    private boolean deleted = false;
}

解决方案 #

问题根源 #

错误提示找不到javax.persistence.Entity，但实体类实际使用的是jakarta.persistence.Entity（Spring Boot 3+已全面从javax迁移到jakarta命名空间）。问题出在编译core模块时，存在依赖冲突或旧javax.persistence依赖被意外引入，导致编译路径混乱。

修复步骤 #

1. 排除Spring Data JPA中的旧javax依赖
   修改core/build.gradle中的spring-data-jpa依赖，显式排除可能存在的旧javax.persistence依赖：

   implementation group: 'org.springframework.data', name: 'spring-data-jpa', version: '3.1.2', {
       exclude group: 'javax.persistence', module: 'javax.persistence-api'
   }
   

2. 锁定core模块的jakarta依赖版本
   在core/build.gradle中添加dependency management，确保jakarta.persistence-api的版本不会被其他模块覆盖：

   dependencyManagement {
       dependencies {
           dependency "jakarta.persistence:jakarta.persistence-api:${jakartaPersistenceVersion}"
       }
   }
   

3. 清理缓存并重新编译
   执行以下命令清理Gradle缓存，强制重新解析依赖：

   ./gradlew clean build --refresh-dependencies
   

4. 验证实体类导入
   再次确认所有实体类的JPA注解均来自jakarta.persistence包，无javax.persistence的导入语句（当前提供的代码已符合要求，若有其他类需检查）。

验证 #

完成上述步骤后，重新执行编译任务，core:compileJava应能正常完成，实体类保留在core模块中也不会再出现ClassNotFoundException。

内容的提问来源于stack exchange，提问作者Md. Muntasir Enam