Spring Boot报错：Not a managed type: class com.example.payroll.Employee

问题背景 #

在开发Spring Boot payroll项目（跟随官方REST教程）时，编译运行遇到JPA相关错误，已尝试修改javax.persistence版本、添加EntityScan注解，但问题未解决。项目使用Spring Boot 3.1.3 + Java 20。

项目目录结构 #

└───payroll
    │   .gitignore
    │   HELP.md
    │   mvnw
    │   mvnw.cmd
    │   pom.xml
    │
    ├───.idea
    │       .gitignore
    │       compiler.xml
    │       encodings.xml
    │       jarRepositories.xml
    │       misc.xml
    │       uiDesigner.xml
    │       workspace.xml
    │
    ├───.mvn
    │   └───wrapper
    │           maven-wrapper.jar
    │           maven-wrapper.properties
    │
    ├───src
    │   ├───main
    │   │   ├───java
    │   │   │   └───com
    │   │   │       └───example
    │   │   │           └───payroll
    │   │   │                   Employee.java
    │   │   │                   EmployeeRepository.java
    │   │   │                   LoadDatabase.java
    │   │   │                   PayrollApplication.java
    │   │   │
    │   │   └───resources
    │   │       │   application.properties
    │   │       │
    │   │       ├───static
    │   │       └───templates
    │   └───test
    │       └───java
    │           └───com
    │               └───example
    │                   └───payroll
    │                           PayrollApplicationTests.java
    │
    └───target
        ├───classes
        │   │   application.properties
        │   │
        │   └───com
        │       └───example
        │           └───payroll
        │                   Employee.class
        │                   EmployeeRepository.class
        │                   LoadDatabase.class
        │                   PayrollApplication.class
        │
        ├───generated-sources
        │   └───annotations
        ├───generated-test-sources
        │   └───test-annotations
        └───test-classes
            └───com
                └───example
                    └───payroll
                            PayrollApplicationTests.class

关键代码文件 #

Employee.java

package com.example.payroll;

import java.util.Objects;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

@Entity
class Employee {

    private @Id @GeneratedValue Long id;
    private String name;
    private String role;

    Employee() {}

    Employee(String name, String role) {
        this.name = name;
        this.role = role;
    }

    // Getters and Setters
    public Long getId() { return this.id; }
    public String getName() { return this.name; }
    public String getRole() { return this.role; }
    public void setId(Long id) { this.id = id; }
    public void setName(String name) { this.name = name; }
    public void setRole(String role) { this.role = role; }

    // equals, hashCode, toString
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Employee)) return false;
        Employee employee = (Employee) o;
        return Objects.equals(this.id, employee.id) && Objects.equals(this.name, employee.name)
                && Objects.equals(this.role, employee.role);
    }

    @Override
    public int hashCode() {
        return Objects.hash(this.id, this.name, this.role);
    }

    @Override
    public String toString() {
        return "Employee{" + "id=" + this.id + ", name='" + this.name + '\'' + ", role='" + this.role + '\'' + '}';
    }
}

pom.xml（原文件）

<?xml version="1.0" encoding="UTF-8"?>
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>payroll</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>payroll</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>20</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>javax.persistence</groupId>
            <artifactId>persistence-api</artifactId>
            <version>1.0.2</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${project.parent.version}</version>
            </plugin>
        </plugins>
    </build>

</project>

问题分析 #

Spring Boot 3.x基于Jakarta EE 9+，原Java EE的javax.*包已全部迁移至jakarta.*命名空间。项目中存在两个冲突点：

1. 手动引入了javax.persistence:persistence-api依赖，与spring-boot-starter-data-jpa中自带的Jakarta Persistence依赖冲突；
2. Employee.java中使用了javax.persistence下的注解，Spring Boot 3不再识别这些注解。

解决方案 #

1. 移除冲突依赖

编辑pom.xml，删除手动添加的javax.persistence依赖块：

<!-- 移除以下内容 -->
<dependency>
    <groupId>javax.persistence</groupId>
    <artifactId>persistence-api</artifactId>
    <version>1.0.2</version>
    <scope>provided</scope>
</dependency>

2. 替换JPA注解的包路径

修改Employee.java中的导入语句，将javax.persistence替换为jakarta.persistence：

// 替换前
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

// 替换后
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;

3. 重新编译运行

执行以下命令清理并重新构建项目：

./mvnw clean install
./mvnw spring-boot:run

说明 #

Spring Boot 3.x彻底完成了从Java EE到Jakarta EE的迁移，所有相关API（JPA、Servlet等）的包路径都从javax改为jakarta，确保项目中所有依赖和代码都使用新的命名空间即可解决此类兼容性问题。

内容的提问来源于stack exchange，提问作者Ilya