批量插入数据库时单条触发唯一约束冲突，API处理方案及状态码选择

最佳实践方案 #

针对你需求的「保存无冲突数据，返回冲突条目错误」场景，推荐以下实践：

1. 数据库层面的容错插入+冲突识别 #

根据使用的数据库类型，利用原生语法实现批量插入时跳过冲突数据，同时精准识别冲突条目：

• PostgreSQL：使用INSERT INTO table (col1, col2) VALUES (...) ON CONFLICT (unique_col) DO NOTHING RETURNING *。通过RETURNING子句获取所有成功插入的条目，对比原输入数组，未出现在返回结果中的即为冲突数据。
• MySQL：使用INSERT INTO table (col1, col2) VALUES (...) ON DUPLICATE KEY UPDATE id=id（id=id是无意义的空更新，避免修改现有数据）。执行后通过ROW_COUNT()获取成功插入的行数，再结合SELECT unique_col FROM table WHERE unique_col IN (...)查询找出已存在的冲突值。
• 通用兼容方案：若数据库不支持上述语法，可将批量操作拆分为单条插入，每条捕获唯一约束异常（如SQLState 23505），收集冲突条目，成功的直接提交。数据量较大时可分小批次处理，平衡执行效率和容错性。

2. 前置校验优化（可选） #

在插入前先查询数据库，筛选出已存在的唯一键值，提前标记冲突条目。但需注意并发场景下的竞态问题：查询和插入之间可能有其他请求插入相同数据，导致仍有冲突，因此前置校验只能作为优化手段，不能替代数据库的唯一约束。

3. 清晰的响应结构 #

返回的响应体需明确区分成功与失败部分，示例结构如下：

{
  "success_count": 8,
  "failed_count": 2,
  "failed_items": [
    {
      "data": {"id": "123", "name": "张三"},
      "error": "唯一键冲突：name='张三'已存在"
    },
    {
      "data": {"id": "456", "name": "李四"},
      "error": "唯一键冲突：name='李四'已存在"
    }
  ]
}

响应状态码选择 #

针对部分成功的场景，推荐两种状态码：

1. 207 Multi-Status #

这是最贴合语义的选择，该状态码原本为WebDAV设计，专门用于表示请求部分成功、部分失败的情况。客户端看到这个状态码就能直接知晓需要解析响应体中的详细结果。

2. 200 OK #

如果团队对非标准HTTP状态码有顾虑，也可以返回200 OK，同时在响应体中明确说明部分成功的情况。但这种方式下状态码本身无法体现请求的部分失败，需要客户端主动解析响应内容才能知晓结果。

不推荐使用4xx状态码：4xx系列（如400 Bad Request）表示整个请求无效，而你的场景是部分数据处理成功，不符合这类状态码的语义。

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