如何在Django Rest Framework API Key库中添加自定义错误消息？

能否实现？ #

完全可以实现。djangorestframework-api-key库内置了细分的认证异常类（如APIKeyNotFound、InvalidAPIKey、ExpiredAPIKey等），你可以通过自定义认证逻辑或异常处理器，将不同的认证失败场景映射为具体的提示信息。

实现方案 #

方案1：自定义认证类 #

继承库中的BaseHasAPIKey权限类，重写authenticate方法，根据不同失败场景抛出带具体信息的异常：

from rest_framework_api_key.permissions import BaseHasAPIKey
from rest_framework_api_key.models import APIKey
from rest_framework.exceptions import AuthenticationFailed
from django.utils import timezone

class CustomHasAPIKey(BaseHasAPIKey):
    def authenticate(self, request):
        key = self.get_key(request)
        if not key:
            raise AuthenticationFailed("Authentication credentials were not provided.")
        
        try:
            api_key = APIKey.objects.get_from_key(key)
        except APIKey.DoesNotExist:
            raise AuthenticationFailed("Invalid API key.")
        
        if api_key.expiry_date is not None and timezone.now() > api_key.expiry_date:
            raise AuthenticationFailed("API key has expired.")
        
        if not api_key.is_active:
            raise AuthenticationFailed("API key is inactive.")
        
        return (None, api_key)

之后在视图或全局配置中使用该类：

# 单个视图使用
from rest_framework.views import APIView

class YourAPIView(APIView):
    permission_classes = [CustomHasAPIKey]
    # ... 视图逻辑

# 全局配置（settings.py）
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'your_app.permissions.CustomHasAPIKey',
    ],
}

方案2：自定义异常处理器 #

利用DRF的异常扩展机制，捕获库抛出的细分异常并返回自定义响应：

# 项目utils.py中编写处理器
from rest_framework.views import exception_handler
from rest_framework_api_key.exceptions import APIKeyNotFound, InvalidAPIKey, ExpiredAPIKey
from rest_framework.response import Response
from rest_framework import status

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    
    if isinstance(exc, APIKeyNotFound):
        return Response(
            {"detail": "Authentication credentials were not provided."},
            status=status.HTTP_401_UNAUTHORIZED
        )
    elif isinstance(exc, InvalidAPIKey):
        return Response(
            {"detail": "Invalid API key."},
            status=status.HTTP_403_FORBIDDEN
        )
    elif isinstance(exc, ExpiredAPIKey):
        return Response(
            {"detail": "API key has expired."},
            status=status.HTTP_403_FORBIDDEN
        )
    
    return response

在settings.py中配置处理器：

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

安全性分析 #

返回具体错误信息在合理范围内是安全的，需注意以下要点：

• 避免泄露敏感信息：仅返回"无效密钥"、"密钥已过期"这类通用提示，不要暴露密钥关联的用户ID、过期时间等细节。
• 遵循HTTP规范：未提供凭据用401 Unauthorized，无效/过期密钥用403 Forbidden，符合HTTP语义且不会过度暴露信息。
• 潜在风险：攻击者可能通过"已过期"的提示判断该密钥曾有效，但这类信息泄露的风险极低，除非你的业务对密钥存在性有极高保密要求。

总体来看，返回细分错误信息利大于弊，既提升了客户端开发体验，又不会引入显著安全风险。

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