如何解决Spring JPA中的“Not a managed type”非法参数异常？

问题场景 #

Spring Boot项目集成JPA时，启动应用抛出如下错误，导致崩溃：

java.lang.IllegalArgumentException: Not a managed type: class com.domain.example.model.Course

用户提供的相关代码如下：

主类 #

package com.domain.example;

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

@SpringBootApplication
@EntityScan(basePackages = {"com.domain.example.model"})
public class Application {

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

模型类 #

package com.domain.example.model;

import java.util.UUID;

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

import com.fasterxml.jackson.annotation.JsonProperty;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

@Entity
@Data
@Table(name = "course")
public class Course {
    @Id
    @GeneratedValue(generator = "UUID")
    @Column(name = "course_id")
    private final UUID courseId;

    @NotNull
    @Column(name = "code")
    private final Long code;

    @NotBlank
    @Column(name = "name")
    private final String name;

    public Course(
        @JsonProperty("courseId") UUID courseId,
        @JsonProperty("code") Long code,
        @JsonProperty("name") String name
    ) {
        this.courseId = (courseId == null) ? UUID.randomUUID() : courseId;
        this.code = code;
        this.name = name;
    }
}

仓库接口 #

package com.domain.example.repository;

import java.util.List;
import java.util.UUID;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import com.domain.example.model.Course;

@Repository
public interface ICourseRepository extends JpaRepository<Course, UUID> {
    List<Course> findAllByCode(Long code);
}

服务类 #

package com.domain.example.service;

import java.util.List;
import org.springframework.stereotype.Service;
import com.domain.example.model.Course;
import com.domain.example.repository.ICourseRepository;
import lombok.RequiredArgsConstructor;

@Service
@RequiredArgsConstructor
public class CourseService implements ICourseService {

    private final ICourseRepository courseRepository;

    @Override
    public boolean saveCourse(Course course) {
        courseRepository.save(course);
        return true;
    }

    @Override
    public List<Course> getAllCourses() {
        return courseRepository.findAll();
    }

    @Override
    public List<Course> getAllCoursesByCode(Long code) {
        return courseRepository.findAllByCode(code);
    }
    
}

解决方案 #

1. 统一JPA注解的包规范 #

Spring Boot 3.x及以上版本已全面切换到Jakarta EE规范，不再支持javax.persistence包的注解。将模型类中所有JPA相关的导入替换为jakarta.persistence：

修改后的模型类导入部分：

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

2. 显式指定仓库扫描路径 #

虽然@SpringBootApplication默认扫描主类所在包及子包，但显式指定仓库扫描范围可避免扫描遗漏。在主类上添加@EnableJpaRepositories注解：

@SpringBootApplication
@EntityScan(basePackages = {"com.domain.example.model"})
@EnableJpaRepositories(basePackages = {"com.domain.example.repository"}) // 新增
public class Application {
    // ... 主方法不变
}

3. 修复实体类的构造方法问题 #

JPA实体类需要提供无参构造方法（Hibernate通过反射实例化实体时必须用到），同时final字段会导致JPA无法生成代理或进行字段修改。

方案A：添加无参构造方法

给Course类添加一个受保护的无参构造器：

@Entity
@Data
@Table(name = "course")
public class Course {
    // ... 现有字段

    // 新增无参构造方法，用于Hibernate反射
    protected Course() {
        this.courseId = UUID.randomUUID();
        this.code = null;
        this.name = null;
    }

    // ... 现有带参构造方法
}

方案B：移除字段的final修饰符

如果不需要字段不可变，去掉final关键字，让Lombok的@Data可以生成setter方法，同时JPA能正常操作字段：

@Id
@GeneratedValue(generator = "UUID")
@Column(name = "course_id")
private UUID courseId; // 移除final

@NotNull
@Column(name = "code")
private Long code; // 移除final

@NotBlank
@Column(name = "name")
private String name; // 移除final

4. 确保依赖版本一致 #

检查项目依赖，确保只引入spring-boot-starter-data-jpa，不要单独引入hibernate-core等依赖，避免版本冲突。以Maven为例，pom.xml中只需保留：

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

内容的提问来源于stack exchange，提问作者Yağız Can Aslan