Spring Boot自定义JpaRepository时出现Entity not managed错误排查

项目环境 #

• Spring Boot 3.0.6（也曾尝试2.7.13版本）
• Java 19.0.2
• PostgreSQL 作为数据库
• Gradle 构建配置如下：

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.0.6'
    id 'io.spring.dependency-management' version '1.1.0'
}

group = 'com.app'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'org.postgresql:postgresql'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

代码结构与配置 #

1. User 实体类（com.app.code.entities.user.User） #

import jakarta.persistence.*;

@Entity
@Table(name = "users")
@SequenceGenerator(name = "users_seq", sequenceName = "users_seq", initialValue = 1024)
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "users_seq")
    private Long id;

    @Column(name = "first_name", nullable = false, length = 50)
    private String firstName;

    @Column(name = "last_name", nullable = false, length = 50)
    private String lastName;

    @Column(name = "username", nullable = false, length = 50)
    private String username;

    @Column(name = "email", nullable = false, length = 50)
    private String email;

    @Column(name = "phone_number", nullable = false, length = 50)
    private String phoneNumber;

    // Getter and Setters
}

2. UserRepository 接口（com.app.code.repositories.user.UserRepository） #

import com.app.code.entities.user.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.util.List;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    @Query("from User u where u.key = :key")
    public User getUserByKey(@Param("key") Long key);

    @Query("from User u where u.username = :username")
    public List<User> getExistingUserByUsername(@Param("username") String username);
}

3. 启动类配置（com.app.ServerApplication） #

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

@SpringBootApplication
@EnableJpaRepositories("com.app.code.*")
@ComponentScan(basePackages = { "com.app.code.*"})
@EntityScan("com.app.code.*")
public class ServerApplication {

    public static void main(String[] args) {
        ApplicationContext context = SpringApplication.run(ServerApplication.class, args);
    }

}

问题现象 #

启动应用时抛出以下异常：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'userRepository' defined in com.app.code.repositories.user.UserRepository defined in @EnableJpaRepositories declared on ServerApplication: Not a managed type: class com.app.code.entities.user.User

• 仅在扫描UserRepository时报错，移除仓库扫描后应用可正常启动，实体类能在控制器、服务类中正常引用。
• 已尝试切换Spring Boot 2.7.13版本并将jakarta.persistence替换为javax.persistence，问题依旧存在。

解决方案 #

1. 修正包扫描路径的通配符写法 #

Spring的包扫描注解（@EnableJpaRepositories、@EntityScan、@ComponentScan）中，单个*仅匹配单层子包，要扫描com.app.code下的所有层级子包，需使用com.app.code（默认扫描所有子包）或com.app.code..（两个点明确匹配所有子层级）。

修改启动类注解：

@SpringBootApplication
@EnableJpaRepositories(basePackages = "com.app.code")
@ComponentScan(basePackages = "com.app.code")
@EntityScan(basePackages = "com.app.code")
public class ServerApplication {
    // 主方法不变
}

2. 校验实体类JPA注解的正确性 #

• Spring Boot 3.x 必须使用jakarta.persistence.Entity等jakarta开头的JPA包
• Spring Boot 2.x 必须使用javax.persistence.Entity等javax开头的JPA包
  切换版本时需确保所有相关包引用同步替换。

3. 修复Repository中的JPQL错误 #

getUserByKey方法的JPQL存在字段错误：实体类User中没有key字段，应改为id：

@Query("from User u where u.id = :key")
public User getUserByKey(@Param("key") Long key);

4. 简化配置（可选） #

如果启动类ServerApplication位于com.app包下，而所有业务代码都在com.app.code子包中，可直接省略@ComponentScan、@EntityScan、@EnableJpaRepositories注解——@SpringBootApplication默认会扫描启动类所在包及其所有子包。

简化后的启动类：

@SpringBootApplication
public class ServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServerApplication.class, args);
    }
}

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