GlassFish偶发@Entity注解识别失败问题排查求助

核心可能原因 #

• 类加载器冲突：GlassFish自带的Jakarta EE API与应用打包的依赖版本冲突，导致实体类被错误类加载器加载，无法识别jakarta.persistence.Entity注解
• 依赖版本不兼容：pom.xml中混用javax.*和jakarta.*包，或Jakarta EE版本与GlassFish 7.0.3不匹配（GlassFish 7对应Jakarta EE 10）
• 部署缓存残留：GlassFish的部署缓存未正确清理，旧类文件干扰新部署的应用

逐步排查流程 #

1. 校验依赖版本一致性 #

• 确认pom.xml中所有Jakarta相关依赖统一使用Jakarta EE 10版本，禁止同时引入javax.*和jakarta.*包
• 检查部署后的依赖库列表，确保没有javax.persistence-api或其他旧javax包混入
• 验证persistence.xml使用jakarta.persistence.*命名空间，而非旧的javax.persistence.*

2. 确认实体类注解正确性 #

确保User实体类导入的是Jakarta版本的注解，而非旧javax版本：

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

@Entity
@Table(name = "users")
public class User {
    @Id
    private Long id;
    // 字段、getter/setter等
}

3. 检查GlassFish类加载配置 #

• 查看domain.xml中是否有自定义类加载器配置，确保应用优先使用自身类加载器，而非服务器全局类加载器
• 临时禁用类加载缓存：在domain.xml的<java-config>节点添加JVM参数：-Dcom.sun.enterprise.container.common.spi.util.InjectionManagerImpl.disableAnnotationScanningCache=true

4. 手动清理部署缓存 #

• 删除GlassFish缓存目录：glassfish7/glassfish/domains/domain1/generated和glassfish7/glassfish/domains/domain1/cache
• 重新部署时使用强制清理参数：asadmin deploy --force=true --clean=true your-app.war

最终解决方案 #

1. 统一依赖版本（使用Jakarta EE 10 BOM） #

在pom.xml中引入Jakarta EE 10 BOM管理所有依赖，避免版本冲突，同时将Jakarta API依赖设置为provided（GlassFish自带这些API）：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-bom</artifactId>
            <version>10.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 示例：持久化API依赖 -->
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <scope>provided</scope>
</dependency>

2. 修正persistence.xml命名空间 #

确保persistence.xml使用Jakarta EE 10对应的3.0版本命名空间：

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="3.0" xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">
    <persistence-unit name="YourPU" transaction-type="JTA">
        <jta-data-source>jdbc/YourDataSource</jta-data-source>
        <class>com.yourpackage.User</class>
    </persistence-unit>
</persistence>

3. 禁用类加载缓存（永久生效） #

修改GlassFish的domain.xml，添加禁用注解扫描缓存的JVM参数：

<java-config ...>
    <jvm-options>-Dcom.sun.enterprise.container.common.spi.util.InjectionManagerImpl.disableAnnotationScanningCache=true</jvm-options>
</java-config>

4. 自动化部署清理 #

在CI/CD部署脚本中添加缓存清理步骤，确保每次部署都是干净状态，避免缓存残留问题

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