REST API中深度与浅度插入的方法设计选型咨询

我们正在设计REST API，涉及course和student两个实体，满足以下关系：

• course包含多个student
• 多个course可共享同一个student
• 创建course时，需同时支持关联已有student（shallow insert）和创建新student（deep insert）

方案1：父层级拆分新学生与已有学生ID #

这种方案在请求体的父层级，分别用students数组存放新学生信息，studentIds数组存放已有学生ID：

POST /courses
{
  "courseName" : "Java 8",
  "students" : [
    {
      "name" : "John Doe" // 新学生（deep insert）
    }
  ],
  "studentIds" : [
    123, 124              // 已有学生（shallow insert）
  ]
}

优缺点：

• 优点：语义清晰，新老学生的区分一目了然，后端解析时无需判断每个子项类型，逻辑更简单。
• 缺点：把同类型的学生关联拆成两个字段，不符合"课程包含学生"的聚合直觉，结构不够紧凑。

方案2：子层级统一数组混合新老学生 #

这种方案在students数组中同时包含新学生信息和已有学生的ID项：

POST /courses
{
  "courseName" : "Java 8",
  "students" : [
    {
      "name" : "John Doe" // 新学生（deep insert）
    },
    {
      "studentId" :123    // 已有学生（shallow insert）
    },
    {
      "studentId" : 124   // 已有学生（shallow insert）
    }
  ]
}

优缺点：

• 优点：结构紧凑，所有学生关联都放在同一个数组下，完全贴合"课程包含学生"的直观语义，前端传数据时不用拆分两类学生。
• 缺点：后端需要判断每个数组项的类型；如果子项同时出现studentId和其他实体字段（比如name），会直接产生歧义，必须额外加规则约束。

该场景是否只有这两种设计选择？ #

不是，还有其他可选方案：

• 显式标记类型：在每个学生项中加type字段明确区分，彻底消除歧义：

POST /courses
{
  "courseName" : "Java 8",
  "students" : [
    {
      "type": "new",
      "name" : "John Doe"
    },
    {
      "type": "existing",
      "studentId" :123
    }
  ]
}

• 分步请求：先创建课程，再分别调用关联接口——比如用POST /courses/{id}/students传递ID关联已有学生，传递学生信息创建并关联新学生。但这种方式需要多次请求，不符合"一次完成创建+关联"的需求。

子实体中同时存在ID和实体字段导致JSON歧义是否可接受？ #

绝对不可接受。如果一个学生项同时有studentId和name这类字段，后端根本没法判断业务意图：是要更新ID为123的学生姓名？还是创建一个指定ID为123的新学生？这种歧义会直接导致业务逻辑混乱，甚至引发数据错误，必须通过明确的结构或规则彻底避免。

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