REST API批量操作错误处理最佳实践咨询（Spring Boot 2.7+Kotlin）

是否应使用Multistatus状态码？ #

不应该。Multistatus（HTTP 207）的设计场景是部分成功、部分失败的批量操作（比如10个实体创建，7个成功3个失败），而你的场景是全量原子性操作——只要有一处错误就全量回滚，没有任何实体被创建。这种情况下207完全不适用，它会误导客户端认为有部分操作成功，不符合你的业务逻辑。

全量失败时的错误码选择 #

推荐使用HTTP 422 Unprocessable Entity，原因如下：

• 400 Bad Request通常用于请求格式错误（比如JSON语法错误、参数类型不匹配），而你的场景是请求格式合法，但语义上存在错误（比如引用的关联实体不存在、字段值违反业务规则）。
• 422专门用于“请求格式正确，但无法被服务器处理”的场景，完美匹配你这种全量校验失败导致的回滚操作。
  如果团队更倾向于通用错误码，也可以用400，但422的语义更精准，能让客户端更快定位问题类型。

这类场景的最佳实践 #

结合Spring Boot 2.7 + Kotlin技术栈，给出以下落地建议：

• 全量预校验，收集所有错误：不要遇到第一个错误就立即返回，而是遍历所有待创建实体，校验字段规则、关联关系（比如通过ID查询关联实体是否存在），将所有错误信息（比如实体在列表中的索引、错误字段、错误原因）收集起来。只有当所有实体校验通过后，才执行数据库批量插入操作。
• 事务保证原子性：在批量创建的Service方法上添加@Transactional(rollbackFor = [Exception::class])，确保一旦校验失败或数据库操作异常，所有已执行的插入都会被回滚（不过预校验通过后数据库操作失败的概率极低，主要靠预校验拦截错误）。
• 结构化错误响应：返回的错误体要包含足够的信息，示例结构如下：

  {
    "code": "BATCH_CREATE_FAILED",
    "message": "批量创建实体失败，共发现2处错误",
    "errors": [
      {
        "index": 0,
        "entityType": "User",
        "field": "departmentId",
        "reason": "数据库中不存在ID为100的部门"
      },
      {
        "index": 2,
        "entityType": "User",
        "field": "email",
        "reason": "邮箱格式不符合规则"
      }
    ]
  }
  

• 全局异常处理：用@ControllerAdvice定义全局异常处理器，捕获校验失败的自定义异常，统一返回上述结构化错误响应和422状态码。
• 避免中途提交：绝对不要在遍历实体时逐个插入，哪怕单个实体校验通过也不提前提交，必须等所有校验完成后再执行批量插入，保证原子性。

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