Spring Boot 2迁移至3时触发JAXB非法注解异常

已完成从javax到jakarta的包迁移，但启动应用时抛出如下异常，根源为JAXB的IllegalAnnotationsException（存在3处非法注解问题）：

Caused by: org.springframework.oxm.UncategorizedMappingException: Unknown JAXB exception
    at org.springframework.oxm.jaxb.Jaxb2Marshaller.convertJaxbException(Jaxb2Marshaller.java:958) ~[spring-oxm-6.1.5.jar:6.1.5]
    at org.springframework.oxm.jaxb.Jaxb2Marshaller.getJaxbContext(Jaxb2Marshaller.java:519) ~[spring-oxm-6.1.5.jar:6.1.5]
    at org.springframework.oxm.jaxb.Jaxb2Marshaller.afterPropertiesSet(Jaxb2Marshaller.java:485) ~[spring-oxm-6.1.5.jar:6.1.5]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1833) ~[spring-beans-6.1.5.jar:6.1.5]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1782) ~[spring-beans-6.1.5.jar:6.1.5]
    ... 44 common frames omitted
Caused by: org.glassfish.jaxb.runtime.v2.runtime.IllegalAnnotationsException: 3 counts of IllegalAnnotationExceptions
    at org.glassfish.jaxb.runtime.v2.runtime.IllegalAnnotationsException$Builder.check(IllegalAnnotationsException.java:83) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.runtime.JAXBContextImpl.getTypeInfoSet(JAXBContextImpl.java:421) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.runtime.JAXBContextImpl.<init>(JAXBContextImpl.java:255) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.runtime.JAXBContextImpl$JAXBContextBuilder.build(JAXBContextImpl.java:1115) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.ContextFactory.createContext(ContextFactory.java:144) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.ContextFactory.createContext(ContextFactory.java:246) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at org.glassfish.jaxb.runtime.v2.JAXBContextFactory.createContext(JAXBContextFactory.java:58) ~[jaxb-runtime-4.0.5.jar:4.0.5 - cb19596]
    at jakarta.xml.bind.ContextFinder.find(ContextFinder.java:322) ~[jakarta.xml.bind-api-4.0.2.jar:4.0.2]
    at jakarta.xml.bind.JAXBContext.newInstance(JAXBContext.java:392) ~[jakarta.xml.bind-api-4.0.2.jar:4.0.2]
    at jakarta.xml.bind.JAXBContext.newInstance(JAXBContext.java:349) ~[jakarta.xml.bind-api-4.0.2.jar:4.0.2]
    at org.springframework.oxm.jaxb.Jaxb2Marshaller.createJaxbContextFromContextPath(Jaxb2Marshaller.java:542) ~[spring-oxm-6.1.5.jar:6.1.5]
    at org.springframework.oxm.jaxb.Jaxb2Marshaller.getJaxbContext(Jaxb2Marshaller.java:505) ~[spring-oxm-6.1.5.jar:6.1.5]

排查步骤与解决方案 #

1. 获取完整异常详情

当前堆栈仅提示存在3处非法注解，未显示具体错误点。可通过以下方式获取完整信息：

• 手动初始化JAXBContext捕获异常：

  import jakarta.xml.bind.JAXBContext;
  import jakarta.xml.bind.JAXBException;
  
  public class JaxbDiagnostic {
      public static void main(String[] args) {
          try {
              // 替换为你的实体类全限定名或JAXB上下文路径
              JAXBContext.newInstance("com.your.app.entity");
          } catch (JAXBException e) {
              e.printStackTrace(); // 此处会打印所有非法注解的具体描述
          }
      }
  }
  

• 调整日志级别：将org.glassfish.jaxb的日志级别设为DEBUG，启动应用后即可在日志中看到详细错误。

2. 常见非法注解问题及修复

根据完整异常信息，对应以下场景修复：

• 实体类缺少无参构造器：JAXB要求被映射类必须提供公共无参构造方法，直接添加即可。
• 字段与getter/setter注解冲突：例如同时在字段和对应get方法上标注@XmlElement，导致重复映射。统一注解位置，要么全在字段，要么全在get方法上。
• 未处理循环引用：若实体间存在双向引用（如A关联B，B关联A），需在其中一方的引用字段上添加@XmlTransient忽略映射，或使用@XmlID+@XmlIDREF处理关联。
• 使用JAXB不支持的类型：自定义类型需编写XmlAdapter并通过@XmlJavaTypeAdapter注册，实现类型与XML可映射类型的转换。
• 注解未完全迁移至jakarta：确认所有JAXB相关注解（如@XmlRootElement、@XmlElement等）均来自jakarta.xml.bind.annotation包，而非旧的javax.xml.bind.annotation包。

3. Spring Boot 3 JAXB依赖检查

Spring Boot 3不再默认包含JAXB相关依赖，需手动引入：

• Maven依赖：

  <dependency>
      <groupId>jakarta.xml.bind</groupId>
      <artifactId>jakarta.xml.bind-api</artifactId>
  </dependency>
  <dependency>
      <groupId>org.glassfish.jaxb</groupId>
      <artifactId>jaxb-runtime</artifactId>
      <scope>runtime</scope>
  </dependency>
  

• Gradle依赖：

  implementation 'jakarta.xml.bind:jakarta.xml.bind-api'
  runtimeOnly 'org.glassfish.jaxb:jaxb-runtime'
  

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