在 Django REST Framework (DRF) 中，裝飾器（Decorators）通常用于視圖函數或類視圖，以控制訪問權限、請求方法、認證等行為。以下是 DRF 中常用的裝飾器及其功能說明：

1. @api_view

• 用途: 用于基于函數的視圖，指定允許的 HTTP 請求方法（如 GET、POST、PUT 等）。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view
  from rest_framework.response import Response@api_view(['GET', 'POST'])
  def my_view(request):if request.method == 'GET':return Response({"message": "GET request"})elif request.method == 'POST':return Response({"message": "POST request"})
  

• 說明:
  • 限定視圖支持的 HTTP 方法。
  • 自動處理 Request 對象和 Response 對象的解析與返回。
  • 默認情況下，視圖會返回 405 狀態碼（Method Not Allowed）給不支持的請求方法。

2. @permission_classes

• 用途: 指定視圖的權限要求，控制哪些用戶可以訪問該視圖。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, permission_classes
  from rest_framework.permissions import IsAuthenticated@api_view(['GET'])
  @permission_classes([IsAuthenticated])
  def secure_view(request):return Response({"message": "This is a protected view"})
  

• 說明:
  • IsAuthenticated 要求用戶已登錄。
  • 可組合多個權限類，如 [IsAuthenticated, IsAdminUser]。
  • 常與 api_view 或類視圖一起使用。

3. @authentication_classes

• 用途: 指定視圖的認證方式，如 TokenAuthentication、SessionAuthentication 等。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, authentication_classes
  from rest_framework.authentication import TokenAuthentication@api_view(['GET'])
  @authentication_classes([TokenAuthentication])
  def token_protected_view(request):return Response({"message": "Token authenticated"})
  

• 說明:
  • 定義認證機制，驗證用戶身份。
  • 通常與 permission_classes 配合使用。

4. @throttle_classes

• 用途: 限制視圖的請求頻率，防止 API 濫用。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, throttle_classes
  from rest_framework.throttling import UserRateThrottle@api_view(['GET'])
  @throttle_classes([UserRateThrottle])
  def throttled_view(request):return Response({"message": "Throttled view"})
  

• 說明:
  • 使用 DRF 的限流機制（如 AnonRateThrottle、UserRateThrottle）。
  • 可通過配置文件自定義限流規則。

5. @renderer_classes

• 用途: 指定視圖的渲染方式，如 JSON、XML 等。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, renderer_classes
  from rest_framework.renderers import JSONRenderer@api_view(['GET'])
  @renderer_classes([JSONRenderer])
  def json_view(request):return Response({"message": "JSON response"})
  

• 說明:
  • 控制 API 的響應格式。
  • 默認使用 DRF 的全局渲染配置，但可通過此裝飾器覆蓋。

6. @parser_classes

• 用途: 指定視圖可以解析的請求數據格式，如 JSON、Form 數據等。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, parser_classes
  from rest_framework.parsers import JSONParser@api_view(['POST'])
  @parser_classes([JSONParser])
  def json_parser_view(request):return Response({"received": request.data})
  

• 說明:
  • 限制請求體的數據格式。
  • 常用于特定場景，如只接受 JSON 數據。

7. @action (用于 ViewSet)

• 用途: 在 ViewSet 中定義自定義動作，擴展默認的 CRUD 操作。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import action
  from rest_framework.viewsets import ViewSet
  from rest_framework.response import Responseclass MyViewSet(ViewSet):@action(detail=True, methods=['GET'])def custom_action(self, request, pk=None):return Response({"message": f"Custom action for {pk}"})
  

• 說明:
  • detail=True 表示針對單一資源（如 /resource/{pk}/custom_action/）。
  • detail=False 表示針對資源集合（如 /resource/custom_action/）。
  • 可指定允許的 HTTP 方法。

8. @schema

• 用途: 自定義 API 文檔的 schema，配合 DRF 的自動文檔生成工具（如 drf-yasg 或 drf-spectacular）。
• 模塊: rest_framework.decorators
• 示例:

  from rest_framework.decorators import api_view, schema
  from rest_framework.schemas import AutoSchema@api_view(['GET'])
  @schema(AutoSchema(manual_fields=[]))
  def documented_view(request):return Response({"message": "Documented view"})
  

• 說明:
  • 用于自定義 OpenAPI 文檔的元數據。
  • 通常結合文檔生成工具使用。

使用注意事項

1. 裝飾器順序: 在基于函數的視圖中，@api_view 必須是最外層的裝飾器，否則會報錯。

   # 正確
   @api_view(['GET'])
   @permission_classes([IsAuthenticated])
   def my_view(request):pass# 錯誤
   @permission_classes([IsAuthenticated])
   @api_view(['GET'])
   def my_view(request):pass  # 會拋出異常
   

2. 類視圖: 裝飾器（如 @permission_classes、@authentication_classes）通常用于函數視圖。對于類視圖，推薦在類中設置屬性（如 permission_classes、authentication_classes）。

   from rest_framework.views import APIView
   from rest_framework.permissions import IsAuthenticatedclass MyAPIView(APIView):permission_classes = [IsAuthenticated]def get(self, request):return Response({"message": "Class-based view"})
   

3. 全局配置: 許多裝飾器功能（如權限、認證、限流）可以通過 DRF 的全局設置（REST_FRAMEWORK）配置，減少重復代碼。

總結

DRF 的裝飾器為視圖提供了靈活的控制方式，適用于權限、認證、限流、數據解析和渲染等場景。常用的裝飾器包括 @api_view、 @permission_classes、 @authentication_classes、 @throttle_classes 等。對于 ViewSet，@action 是擴展自定義路由的利器。