from rest_framework import exceptions


def some_service():
    raise exceptions.ValidationError("Some message")

["Some message"]

from rest_framework import exceptions


def some_service():
    raise exceptions.ValidationError({"error": "Some message"})

{
  "error": "Some message"
}

from rest_framework import exceptions


def some_service():
    raise exceptions.NotFound()

{
  "detail": "Not found."
}

// ❌ 糟糕的体验：前端需要写大量的类型检查和保护逻辑
try {
  await api.post("/users/register", data);
} catch (error: any) {
  const responseData = error.response.data;
  let errorMessage = "未知错误";

  if (Array.isArray(responseData)) {
    // 处理情况 1：数组格式 ["msg"]
    errorMessage = responseData[0];
  } else if (typeof responseData === "object" && responseData.detail) {
    // 处理情况 2：详情格式 {"detail": "..."}
    errorMessage = responseData.detail;
  } else if (typeof responseData === "object") {
    // 处理情况 3：字段格式 {"email": "..."}
    errorMessage = Object.values(responseData)[0] as string;
  }

  toast.error(errorMessage);
}

// ✅ 优雅的体验：结构永远固定，前端心智负担极低
try {
  await api.post("/users/register", data);
} catch (error: any) {
  // 我们知道结构永远是 { message: string, ... }
  const { message } = error.response.data;
  toast.error(message);
}

from django.core.exceptions import ValidationError as DjangoValidationError


def some_service():
    raise DjangoValidationError("Some error message")

def some_service():
    user = BaseUser()
    user.full_clean()  # 抛出 ValidationError
    user.save()

from django.core.exceptions import ValidationError as DjangoValidationError

from rest_framework.views import exception_handler
from rest_framework.serializers import as_serializer_error
from rest_framework import exceptions


def custom_exception_handler(exc, ctx):
    # 将 Django 的 ValidationError 转换为 DRF 的 ValidationError
    if isinstance(exc, DjangoValidationError):
        exc = exceptions.ValidationError(as_serializer_error(exc))

    # 调用 DRF 的默认异常处理器
    response = exception_handler(exc, ctx)

    # 如果发生意外错误（服务器错误等）
    if response is None:
        return response

    return response

if isinstance(exc, DjangoValidationError):
    exc = exceptions.ValidationError(as_serializer_error(exc))

{
  "message": "Some error message here"
}

{
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "fields": {
    "email": ["This field is required."],
    "password": ["Password is too weak."]
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

# config/django/base.py

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'project.api.exception_handlers.custom_exception_handler'
}

{
  "detail": "Some error"
}

{
  "detail": ["Some error", "Another error"]
}

{
  "detail": {
    "key": "... some arbitrary nested structure ..."
  }
}

from django.core.exceptions import ValidationError as DjangoValidationError, PermissionDenied
from django.http import Http404

from rest_framework.views import exception_handler
from rest_framework import exceptions
from rest_framework.serializers import as_serializer_error


def drf_default_with_modifications_exception_handler(exc, ctx):
    # 处理 Django 的 ValidationError
    if isinstance(exc, DjangoValidationError):
        exc = exceptions.ValidationError(as_serializer_error(exc))

    # 处理 Django 的 Http404
    if isinstance(exc, Http404):
        exc = exceptions.NotFound()

    # 处理 Django 的 PermissionDenied
    if isinstance(exc, PermissionDenied):
        exc = exceptions.PermissionDenied()

    # 调用 DRF 的默认异常处理器
    response = exception_handler(exc, ctx)

    # 如果发生意外错误（服务器错误等）
    if response is None:
        return response

    # 确保所有错误都包装在 detail 键中
    if isinstance(exc.detail, (list, dict)):
        response.data = {
            "detail": response.data
        }

    return response

# Django ValidationError → DRF ValidationError
if isinstance(exc, DjangoValidationError):
    exc = exceptions.ValidationError(as_serializer_error(exc))

# Django Http404 → DRF NotFound
if isinstance(exc, Http404):
    exc = exceptions.NotFound()

# Django PermissionDenied → DRF PermissionDenied
if isinstance(exc, PermissionDenied):
    exc = exceptions.PermissionDenied()

if isinstance(exc.detail, (list, dict)):
    response.data = {
        "detail": response.data
    }

def some_service():
    raise DjangoValidationError("Some error message")

{
  "detail": {
    "non_field_errors": ["Some error message"]
  }
}

from django.core.exceptions import PermissionDenied

def some_service():
    raise PermissionDenied()

{
  "detail": "You do not have permission to perform this action."
}

from django.http import Http404

def some_service():
    raise Http404()

{
  "detail": "Not found."
}

def some_service():
    raise RestValidationError("Some error message")

{
  "detail": ["Some error message"]
}

def some_service():
    raise RestValidationError(detail={"error": "Some error message"})

{
  "detail": {
    "error": "Some error message"
  }
}

class NestedSerializer(serializers.Serializer):
    bar = serializers.CharField()


class PlainSerializer(serializers.Serializer):
    foo = serializers.CharField()
    email = serializers.EmailField(min_length=200)
    nested = NestedSerializer()


def some_service():
    serializer = PlainSerializer(data={
        "email": "foo",
        "nested": {}
    })
    serializer.is_valid(raise_exception=True)

{
  "detail": {
    "foo": ["This field is required."],
    "email": [
      "Ensure this field has at least 200 characters.",
      "Enter a valid email address."
    ],
    "nested": {
      "bar": ["This field is required."]
    }
  }
}

from rest_framework import exceptions


def some_service():
    raise exceptions.Throttled()

{
  "detail": "Request was throttled."
}

def some_service():
    user = BaseUser()
    user.full_clean()  # 触发验证错误

{
  "detail": {
    "password": ["This field cannot be blank."],
    "email": ["This field cannot be blank."]
  }
}

{
  "message": "The error message here",
  "extra": {}
}

{
  "message": "Validation error.",
  "extra": {
    "fields": {
      "password": ["This field cannot be blank."],
      "email": ["This field cannot be blank."]
    }
  }
}

from django.core.exceptions import ValidationError as DjangoValidationError, PermissionDenied
from django.http import Http404

from rest_framework.views import exception_handler
from rest_framework import exceptions
from rest_framework.serializers import as_serializer_error
from rest_framework.response import Response

from styleguide_example.core.exceptions import ApplicationError


def hacksoft_proposed_exception_handler(exc, ctx):
    """
    自定义异常处理器，返回格式：
    {
        "message": "Error message",
        "extra": {}
    }
    """
    # 1. 处理 Django 异常 → DRF 异常
    if isinstance(exc, DjangoValidationError):
        exc = exceptions.ValidationError(as_serializer_error(exc))

    if isinstance(exc, Http404):
        exc = exceptions.NotFound()

    if isinstance(exc, PermissionDenied):
        exc = exceptions.PermissionDenied()

    # 2. 调用 DRF 的默认异常处理器
    response = exception_handler(exc, ctx)

    # 3. 如果发生意外错误（服务器错误等）
    if response is None:
        # 处理我们自定义的 ApplicationError
        if isinstance(exc, ApplicationError):
            data = {
                "message": exc.message,
                "extra": exc.extra
            }
            return Response(data, status=400)

        # 其他未处理的异常，返回 None（会导致 500）
        return response

    # 4. 确保响应数据有 detail 键（如果是 list 或 dict）
    if isinstance(exc.detail, (list, dict)):
        response.data = {
            "detail": response.data
        }

    # 5. 转换为我们的标准格式
    if isinstance(exc, exceptions.ValidationError):
        # 验证错误的特殊处理
        response.data["message"] = "Validation error"
        response.data["extra"] = {
            "fields": response.data["detail"]
        }
    else:
        # 其他错误
        response.data["message"] = response.data["detail"]
        response.data["extra"] = {}

    # 6. 删除 detail 键（我们已经用 message 替换了）
    del response.data["detail"]

    return response

if response is None:
    if isinstance(exc, ApplicationError):
        data = {
            "message": exc.message,
            "extra": exc.extra
        }
        return Response(data, status=400)

if isinstance(exc, exceptions.ValidationError):
    response.data["message"] = "Validation error"
    response.data["extra"] = {
        "fields": response.data["detail"]
    }

else:
    response.data["message"] = response.data["detail"]
    response.data["extra"] = {}

# project/core/exceptions.py

class ApplicationError(Exception):
    """
    应用层的自定义异常
    """
    def __init__(self, message, extra=None):
        super().__init__(message)
        self.message = message
        self.extra = extra or {}

from project.core.exceptions import ApplicationError


def some_business_logic():
    if not user.is_eligible():
        raise ApplicationError(
            message="User is not eligible for this action",
            extra={"reason": "account_not_verified"}
        )

from styleguide_example.core.exceptions import ApplicationError


def trigger_application_error():
    raise ApplicationError(
        message="Something is not correct",
        extra={"type": "RANDOM"}
    )

{
  "message": "Something is not correct",
  "extra": {
    "type": "RANDOM"
  }
}

def some_service():
    raise DjangoValidationError("Some error message")

{
  "message": "Validation error",
  "extra": {
    "fields": {
      "non_field_errors": ["Some error message"]
    }
  }
}

from django.core.exceptions import PermissionDenied

def some_service():
    raise PermissionDenied()

{
  "message": "You do not have permission to perform this action.",
  "extra": {}
}

from django.http import Http404

def some_service():
    raise Http404()

{
  "message": "Not found.",
  "extra": {}
}

def some_service():
    raise RestValidationError("Some error message")

{
  "message": "Validation error",
  "extra": {
    "fields": ["Some error message"]
  }
}

def some_service():
    raise RestValidationError(detail={"error": "Some error message"})

{
  "message": "Validation error",
  "extra": {
    "fields": {
      "error": "Some error message"
    }
  }
}

class NestedSerializer(serializers.Serializer):
    bar = serializers.CharField()


class PlainSerializer(serializers.Serializer):
    foo = serializers.CharField()
    email = serializers.EmailField(min_length=200)
    nested = NestedSerializer()


def some_service():
    serializer = PlainSerializer(data={
        "email": "foo",
        "nested": {}
    })
    serializer.is_valid(raise_exception=True)

{
  "message": "Validation error",
  "extra": {
    "fields": {
      "foo": ["This field is required."],
      "email": [
        "Ensure this field has at least 200 characters.",
        "Enter a valid email address."
      ],
      "nested": {
        "bar": ["This field is required."]
      }
    }
  }
}

from rest_framework import exceptions


def some_service():
    raise exceptions.Throttled()

{
  "message": "Request was throttled.",
  "extra": {}
}

def some_service():
    user = BaseUser()
    user.full_clean()  # 触发验证错误

{
  "message": "Validation error",
  "extra": {
    "fields": {
      "password": ["This field cannot be blank."],
      "email": ["This field cannot be blank."]
    }
  }
}

# project/core/exceptions.py

class ApplicationError(Exception):
    """基础应用异常"""
    def __init__(self, message, extra=None):
        super().__init__(message)
        self.message = message
        self.extra = extra or {}


class ApplicationValidationError(ApplicationError):
    """应用层验证错误"""
    pass


class ApplicationPermissionError(ApplicationError):
    """应用层权限错误"""
    pass


class ApplicationNotFoundError(ApplicationError):
    """应用层未找到错误"""
    pass

def user_update(*, user_id: int, data: dict):
    try:
        user = User.objects.get(id=user_id)
    except User.DoesNotExist:
        raise ApplicationNotFoundError(
            message="User not found",
            extra={"user_id": user_id}
        )

    if not user.can_update():
        raise ApplicationPermissionError(
            message="User cannot be updated",
            extra={"reason": "account_locked"}
        )

    # ... 更新逻辑 ...

def hacksoft_proposed_exception_handler(exc, ctx):
    # ... 前面的代码 ...

    if response is None:
        if isinstance(exc, ApplicationError):
            # 根据异常类型决定状态码
            status_code = 400  # 默认

            if isinstance(exc, ApplicationNotFoundError):
                status_code = 404
            elif isinstance(exc, ApplicationPermissionError):
                status_code = 403
            elif isinstance(exc, ApplicationValidationError):
                status_code = 400

            data = {
                "message": exc.message,
                "extra": exc.extra
            }
            return Response(data, status=status_code)

    # ... 剩余代码 ...

class ApplicationError(Exception):
    """基础应用异常"""
    def __init__(self, message, code=None, extra=None):
        super().__init__(message)
        self.message = message
        self.code = code or "APPLICATION_ERROR"
        self.extra = extra or {}

{
  "message": "User is not eligible",
  "code": "USER_NOT_ELIGIBLE",
  "extra": {
    "reason": "account_not_verified"
  }
}

// 前端代码示例
if (error.code === "USER_NOT_ELIGIBLE") {
  showVerificationPrompt();
} else if (error.code === "PAYMENT_FAILED") {
  showPaymentRetryDialog();
}

def fully_custom_exception_handler(exc, ctx):
    """
    完全自定义的异常处理器
    """
    # 初始化响应
    data = {}
    status_code = 500

    # 处理我们的自定义异常
    if isinstance(exc, ApplicationError):
        data = {
            "message": exc.message,
            "code": exc.code,
            "extra": exc.extra
        }
        status_code = 400

    # 处理 DRF ValidationError
    elif isinstance(exc, exceptions.ValidationError):
        data = {
            "message": "Validation error",
            "code": "VALIDATION_ERROR",
            "extra": {
                "fields": exc.detail
            }
        }
        status_code = 400

    # 处理其他 DRF 异常
    elif isinstance(exc, exceptions.APIException):
        data = {
            "message": str(exc.detail),
            "code": exc.default_code.upper(),
            "extra": {}
        }
        status_code = exc.status_code

    # 处理 Django 异常
    elif isinstance(exc, DjangoValidationError):
        data = {
            "message": "Validation error",
            "code": "VALIDATION_ERROR",
            "extra": {
                "fields": as_serializer_error(exc)
            }
        }
        status_code = 400

    # 未知异常 - 返回 None，让 Django 处理
    else:
        return None

    return Response(data, status=status_code)

from django.core.exceptions import ObjectDoesNotExist

def enhanced_exception_handler(exc, ctx):
    # 处理 ObjectDoesNotExist
    if isinstance(exc, ObjectDoesNotExist):
        exc = exceptions.NotFound()

    # ... 其余处理逻辑 ...

import logging

logger = logging.getLogger(__name__)


def exception_handler_with_logging(exc, ctx):
    # 记录所有异常
    logger.error(
        f"Exception in {ctx['view'].__class__.__name__}: {exc}",
        exc_info=True,
        extra={
            'view': ctx['view'].__class__.__name__,
            'request': ctx['request'],
        }
    )

    # ... 异常处理逻辑 ...

from django.conf import settings


def exception_handler_with_debug_info(exc, ctx):
    response = custom_exception_handler(exc, ctx)

    # 在开发环境添加额外的调试信息
    if settings.DEBUG and response is not None:
        response.data['debug'] = {
            'exception_type': type(exc).__name__,
            'view': ctx['view'].__class__.__name__,
            'traceback': traceback.format_exc() if settings.DEBUG else None
        }

    return response

{
  "message": "Something went wrong",
  "extra": {},
  "debug": {
    "exception_type": "ValidationError",
    "view": "UserCreateApi",
    "traceback": "Traceback (most recent call last):\n..."
  }
}

import sentry_sdk


def exception_handler_with_sentry(exc, ctx):
    response = custom_exception_handler(exc, ctx)

    # 对于 500 错误，发送到 Sentry
    if response is None or response.status_code >= 500:
        sentry_sdk.capture_exception(exc)

    return response

from django.utils.translation import gettext as _


class ApplicationError(Exception):
    def __init__(self, message_key, extra=None):
        self.message_key = message_key
        self.message = _(message_key)  # 翻译
        self.extra = extra or {}

raise ApplicationError(
    message_key="errors.user.not_eligible",
    extra={"reason": "account_not_verified"}
)

import uuid


def exception_handler_with_tracking(exc, ctx):
    response = custom_exception_handler(exc, ctx)

    if response is not None:
        # 添加唯一的错误追踪 ID
        error_id = str(uuid.uuid4())
        response.data['error_id'] = error_id

        # 记录到日志
        logger.error(
            f"Error {error_id}: {exc}",
            exc_info=True,
            extra={'error_id': error_id}
        )

    return response

{
  "message": "Something went wrong",
  "error_id": "123e4567-e89b-12d3-a456-426614174000",
  "extra": {}
}

开始
  ↓
项目规模大吗？
  ├─ 否 → 使用方法 1（DRF + 修改）
  └─ 是 ↓
       需要复杂的错误处理吗？
         ├─ 否 → 使用方法 1
         └─ 是 ↓
              有时间投资初始设置吗？
                ├─ 否 → 使用方法 1
                └─ 是 → 使用方法 2（HackSoft）