DRF中POST请求触发UniqueConstraint异常时如何捕获并返回错误响应

字段长度校验默认在序列化器/表单校验阶段执行，未触发数据库操作，校验不通过时会直接返回结构化的400错误响应；而UniqueConstraint是数据库层面的约束，如果没有在入库前添加对应校验，执行save()操作时数据库会直接抛出IntegrityError，未做捕获的情况下框架会返回500服务错误，无法返回规范的字段错误提示。

方案1：序列化器层添加联合唯一校验（优先推荐） #

该方案将校验逻辑前置到数据库操作之前，返回格式和其他字段校验完全统一，符合框架设计规范。
如果使用Django REST Framework，有两种实现方式：

• 方式一：使用内置校验器
  UniqueTogetherValidator可直接识别联合唯一规则，即使模型层使用UniqueConstraint而非旧版unique_together也可正常生效：

from rest_framework import serializers
from .models import MyModel

class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = '__all__'
        validators = [
            serializers.UniqueTogetherValidator(
                queryset=MyModel.objects.all(),
                fields=['name', 'key'],
                message='name与key的组合已存在'
            )
        ]

• 方式二：自定义联合校验方法
  灵活性更高，可自定义错误绑定的字段，适配更复杂的校验逻辑：

def validate(self, attrs):
    name = attrs.get('name')
    key = attrs.get('key')
    # 更新场景下需要排除当前实例本身，避免误判
    exists = MyModel.objects.filter(name=name, key=key)
    if self.instance:
        exists = exists.exclude(id=self.instance.id)
    if exists.exists():
        # 可将错误绑定到指定字段，和现有字段错误格式保持一致
        raise serializers.ValidationError({"name": ["当前name和key的组合已存在，请调整后重试"]})
    return attrs

添加上述校验后，违反唯一约束的请求会直接返回400状态码和结构化错误，不会再抛出服务端异常。

方案2：全局异常捕获兜底 #

如果存在批量创建、非序列化器触发的入库等无法前置校验的场景，可以通过全局异常处理捕获数据库唯一约束错误，统一转换为规范响应。
首先自定义DRF异常处理方法：

from django.db import IntegrityError
from rest_framework.views import exception_handler
from rest_framework.response import Response
from rest_framework import status

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    # 处理未被默认逻辑捕获的IntegrityError
    if isinstance(exc, IntegrityError) and response is None:
        err_msg = str(exc).lower()
        # 匹配唯一约束违反的错误特征，可根据自身使用的数据库类型调整匹配规则
        if 'unique constraint' in err_msg or 'duplicate entry' in err_msg:
            return Response(
                {"non_field_errors": ["提交的数据违反唯一约束，请检查字段组合"]},
                status=status.HTTP_400_BAD_REQUEST
            )
    return response

随后在settings.py中注册该异常处理器：

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': '你的项目配置路径.custom_exception_handler'
}

注意：该方案仅作为兜底逻辑使用，优先选择前置校验的方案，数据库抛出异常时SQL已执行，性能和可控性弱于前置校验。

原生Django场景适配 #

如果未使用DRF，仅用Django原生视图/Form开发，逻辑完全一致：要么在Form的clean方法中添加联合唯一校验，要么在视图逻辑中捕获IntegrityError，返回对应错误提示即可。

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