OData创建含一对多关系实体时抛出ODataJPARuntimeException异常

问题场景 #

在OData实体创建操作中处理一对多关联关系时，携带导航属性发起POST请求触发运行时异常。
使用的请求JSON如下：

{
   "parentProperty1":"",
   "parentProperty2":"",
   "parentProperty3":"",
   "NavigationProperty":[
      {
         "childProperty1":""
      }
   ]
}

抛出的异常栈信息：

org.apache.olingo.odata2.jpa.processor.api.exception.ODataJPARuntimeException: "OData - JPA Runtime: JPA create request is not correct" 
   at org.apache.olingo.odata2.jpa.processor.api.exception.ODataJPARuntimeException.throwException(ODataJPARuntimeException.java:100 undefined) ~[olingo-odata2-jpa-processor-api-2.0.12.jar:2.0.12] 
   at org.apache.olingo.odata2.jpa.processor.core.access.data.JPALink.linkJPAEntities(JPALink.java:242 undefined) ~[olingo-odata2-jpa-processor-core-2.0.12.jar:2.0.12]

异常由JPALink类的linkJPAEntities方法抛出。

根因分析 #

该异常是Apache Olingo OData2 JPA Processor处理深度插入（Deep Insert） 请求时的关联校验失败，触发场景集中在三类配置错误：

• 双向关联配置不完整或错误：Olingo JPA处理器处理一对多导航属性持久化时，强制要求父子实体配置双向JPA关联，且@OneToMany注解必须明确指定mappedBy属性指向子实体中父对象的引用字段。如果仅配置父到子的单向@OneToMany，或者mappedBy字段名和子实体实际字段不匹配，框架无法建立父子实体的引用关系，直接抛出该异常。
• 级联持久化配置缺失：父实体的@OneToMany注解未配置CascadeType.PERSIST级联权限，框架无法在创建父实体时同步持久化子实体，触发关联逻辑校验失败。
• 请求逻辑不符合OData V2规范：深度插入仅支持同时新建父实体和关联的全新子实体，如果导航属性的子对象中携带了已存在的实体主键值（即尝试在新建父实体时同时绑定已存在的子实体），框架会判定请求格式非法。

修复步骤 #

1. 修正JPA实体关联配置
   父实体（一方）的一对多字段必须正确配置mappedBy和级联规则：

   // 父实体代码片段
   @OneToMany(mappedBy = "parentRef", cascade = CascadeType.PERSIST)
   private List<ChildEntity> NavigationProperty;
   

   子实体（多方）必须添加反向的多对一关联字段，字段名和父实体mappedBy配置值完全一致：

   // 子实体代码片段
   @ManyToOne
   @JoinColumn(name = "parent_record_id") // 对应数据库中父表外键字段
   private ParentEntity parentRef;
   

   注意：禁止在双向关联的两个实体上都配置@JoinColumn，外键配置仅需要加在子实体的@ManyToOne字段上。

2. 调整请求逻辑

   • 深度插入场景下，导航属性中的子实体不要传入主键字段，主键由JPA持久化逻辑自动生成。
   • 如果需要关联已经存在的子实体，不要使用深度插入语法：先单独发起POST请求创建父实体，再通过/ParentEntitySet('{parentId}')/$links/NavigationProperty接口发起POST请求绑定已存在的子实体。

3. 校验EDM模型配置
   确认OData EDM中该导航属性的关联多重性配置和JPA一致：父实体端多重性为1，子实体端多重性为*，不存在两端配置颠倒的问题。

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