Django REST Framework (DRF) 认证与异常处理完全指南

一、核心问题分析

在 DRF 开发中，身份认证失败时应返回 401 Unauthorized，但开发者常遇到以下问题：

• 直接使用 raise ValidationError 导致返回错误状态码 400（Bad Request）
• 手动设置 Response(..., status=401) 破坏代码规范性
• 不同场景需要差异化的错误提示和状态码控制

---

二、标准解决方案

1. 认证校验流程示例

from rest_framework import serializers
from rest_framework.exceptions import AuthenticationFailedclass SSOAuthSerializer(serializers.Serializer):access_token = serializers.CharField()uuid = serializers.UUIDField()def validate(self, data):# 1. 基础参数校验token = data.get('access_token')uuid = data.get('uuid')error_msg = "您未登录，请先登录"# 2. 关键参数验证if not token:raise AuthenticationFailed(detail=error_msg,code='invalid_access_token')if not uuid:raise AuthenticationFailed(detail=error_msg,code='invalid_uuid')# 3. 外部系统校验（示例）user_info = self.uuc_validate_token(token, uuid)if not user_info:raise AuthenticationFailed(detail=error_msg,code='token_verify_failed')self.sso_user = user_inforeturn datadef uuc_validate_token(self, token, uuid):"""模拟第三方Token验证服务"""# 实际项目中应调用认证中心APIreturn {"user_id": 123} if token == "valid_token" else None

2. 关键实现要点

步骤	操作说明	注意事项
① 参数获取	使用 data.get() 安全获取字段	避免 KeyError 异常
② 统一错误话术	定义标准化错误消息模板	提升前端交互一致性
③ 精准异常类型	始终使用 AuthenticationFailed	自动触发 401 状态码
④ 错误代码体系	通过 code 字段区分具体原因	便于前端进行差异化处理

---

三、DRF 异常与HTTP状态码对照表

常用异常类速查表

异常类	HTTP状态码	典型应用场景
APIException	500	通用后端错误基类
AuthenticationFailed	401	Token过期/无效
PermissionDenied	403	用户无访问权限
NotFound	404	请求资源不存在
MethodNotAllowed	405	HTTP方法禁止
Throttled	429	请求频率超限
ValidationError	400	参数格式校验失败

扩展建议

# 自定义业务异常示例
from rest_framework.views import exception_handlerdef custom_exception_handler(exc, context):response = exception_handler(exc, context)if isinstance(exc, AuthenticationFailed):response.data = {"code": exc.default_code,"message": exc.detail,"status_code": 401}return response

---

四、最佳实践总结

✅ 推荐做法

1. 优先使用框架内置异常：如 AuthenticationFailed 而非手动构造 Response
2. 建立错误代码体系：通过 code 字段明确区分错误类型
3. 分层校验逻辑：
   • 基础参数校验 → ValidationError
   • 业务逻辑校验 → 自定义异常
   • 认证授权校验 → AuthenticationFailed/PermissionDenied

⚠️ 常见问题规避

• 不要混合使用多种异常类型：保持认证相关错误统一使用 AuthenticationFailed
• 避免硬编码状态码：依赖框架自动转换机制
• 敏感信息保护：不在响应体中暴露过多系统细节

💡 提示：可通过 settings.py 配置全局异常处理器：

REST_FRAMEWORK = {'EXCEPTION_HANDLER': 'myapp.utils.custom_exception_handler',
}