技術文章 » 深入探索 Django Rest Framework

深入探索 Django Rest Framework

2023-07-13 21:00:58

這篇文章會詳細介紹Django REST Framework的核心組成部分，包括Serializers、ViewSets、Routers、許可權和認證系統以及測試和偵錯工具。文章從基礎開始，逐步深入，旨在幫助讀者掌握使用Django REST Framework構建複雜API的技能。

導言

Django REST框架的定義和目的

Django REST框架，通常簡稱為DRF，是一個強大而靈活的Web API工具包。使用DRF，開發者可以快速構建可延伸的、可維護的RESTful API服務。DRF提供了一整套的工具和模組，包括認證、許可權、序列化、檢視、路由等，幫助我們處理許多Web開發中常見的問題。

DRF的主要目的是使Django應用程式能夠輕鬆地構建和管理API。此外，DRF還關注API的可瀏覽性和易用性，使得開發者可以通過Web瀏覽器存取API，並進行互動。

Django REST框架和其他框架（如Flask）的比較

雖然Django REST框架和其他Python的Web框架（如Flask）有著共同的目標，即幫助開發者構建Web應用，但是它們在設計理念、功能和使用場景上有所不同。

  • 設計理念：DRF是一個比較「重量級」的框架，提供了一整套的解決方案，包括模型、檢視、模板、表單、路由、認證、許可權等等。而Flask更加輕量級和靈活，它只提供了最基礎的工具，其他的功能需要通過安裝擴充套件來實現。
# Django view範例
from django.http import HttpResponse
def hello_world(request):
    return HttpResponse("Hello, World!")

# Flask view範例
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
    return 'Hello, World!'

  • 功能：DRF提供了許多內建的功能，如認證、許可權、序列化、反序列化、檢視、路由等，這些功能都經過了精心設計，使得開發者可以更加專注於業務邏輯，而不是基礎設施的建設。而Flask則更加註重靈活性，它允許開發者選擇和客製化所需要的功能。

  • 使用場景：如果你的專案需要快速構建RESTful API，或者需要與Django的其他部分（如ORM、模板系統等）緊密整合，那麼DRF可能是一個更好的選擇。如果你需要更大的靈活性，或者只需要構建一個簡單的Web服務，那麼Flask可能更合適。

基礎部分

Django REST框架的安裝和設定

在開始使用Django REST框架前，首先需要安裝和設定相關環境。假設你已經安裝了Python和Django，你可以使用pip來安裝DRF：

pip install djangorestframework

然後，需要將rest_framework新增到你的Django專案的INSTALLED_APPS設定中：

# settings.py

INSTALLED_APPS = [
    ...,
    'rest_framework',
]

這樣，我們就成功安裝和設定好了Django REST框架，接下來可以開始構建我們的第一個DRF專案了。

一個基本的Django REST框架專案搭建教學

在本教學中，我們將建立一個簡單的API，用於管理圖書資訊。首先，我們需要建立一個新的Django app：

python manage.py startapp books

然後，我們需要在books app中定義我們的模型：

# models.py

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    published_date = models.DateField()

    def __str__(self):
        return self.title

接著，我們需要定義對應的Serializer和Viewset：

# serializers.py

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'published_date']


# views.py

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

最後，我們需要在urls.py中新增路由：

# urls.py

from django.urls import include, path
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

以上就是一個基本的Django REST框架專案的搭建過程。在這個例子中，我們建立了一個可以進行CRUD操作的圖書資訊API。

Django REST框架中的基本元件：Serializers, Viewsets, Routers

在上面的例子中，我們使用了DRF的三個主要元件：Serializers, Viewsets, 和 Routers。以下是它們的簡單介紹：

  • Serializers：負責將複雜的資料型別（如Django模型範例）轉換為可以被渲染成JSON、XML等格式的Python資料型別。同時，也可以用於解析上述格式的資料，轉換為複雜的資料型別。

  • Viewsets：一個用於封裝檢視邏輯的類。與Django的類檢視類似，但提供了更多與REST相關的功能，例如預設的GET、POST、PUT、PATCH和DELETE方法。

  • Routers：負責自動生成URL路由。與Django的URLconf類似，但是對於DRF的Viewsets有更好的支援，可以根據Viewset中的方法自動建立對應的路由。

在接下來的部分，我們將深入探討這三個元件的工作原理和使用方法。

Serializers

在Django REST框架中，Serializers扮演著至關重要的角色。它們負責轉換複雜的資料型別，如Django模型範例或者複雜的查詢集，使得它們可以被渲染為像JSON或者XML這樣的可傳輸格式。同時，Serializers也負責在資料接收時完成反序列化的工作，將接收的資料轉換為Python資料型別。

什麼是Serializer？

Serializer類似於Django的Form和ModelForm類，但它們不僅包含了簡單的資料驗證功能，還包含了複雜的型別轉換功能。它們可以對複雜的資料型別進行序列化（轉換為Python基本資料型別），也可以對已序列化的資料進行反序列化（轉換為複雜的資料型別）。

# serializers.py

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'published_date']

在上述例子中，BookSerializer就是一個Serializer，它繼承自ModelSerializer類，用於序列化和反序列化Book模型範例。

Serializers的工作原理

當序列化物件時，Serializers首先將物件轉換為Python內建的資料型別，然後再將這些資料型別轉換為可傳輸的格式。反序列化時，Serializers會進行相反的過程，先將接收的資料轉換為Python內建的資料型別，然後再將這些資料型別轉換為複雜的資料型別。

以下是一個簡單的例子，演示瞭如何使用BookSerializer進行序列化和反序列化：

# 使用Serializer進行序列化
book = Book.objects.get(id=1)
serializer = BookSerializer(book)
print(serializer.data)
# 輸出：{'id': 1, 'title': 'Django for Beginners', 'author': 'William S. Vincent', 'published_date': '2022-07-01'}

# 使用Serializer進行反序列化
data = {'title': 'REST API with Django', 'author': 'William S. Vincent', 'published_date': '2023-07-01'}
serializer = BookSerializer(data=data)
if serializer.is_valid():
    book = serializer.save()
print(book)
# 輸出：<Book: REST API with Django>

Serializers的範例和使用

Serializers最常見的使用場景就是在檢視中，用於序列化和反序列化檢視處理的資料。

例如，我們可以在檢視中使用Serializer，來處理使用者端發來的POST請求，建立新的圖書：

# views.py

from rest_framework import status
from rest_framework.response import Response
from rest_framework.views import APIView
from .models import Book
from .serializers import BookSerializer

class BookList(APIView):
    def post(self, request):
        serializer = BookSerializer(data=request.data)
        if serializer.is_valid():
            book = serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

在上述例子中，我們在檢視的POST方法中使用了BookSerializer，將接收的資料反序列化為Book模型範例，並儲存到資料庫中。

Serializers的使用非常廣泛，它們不僅可以用於基本的資料驗證和轉換，還可以用於複雜的場景，如處理巢狀的資料、自定義欄位、動態欄位等。在掌握了基本用法後，你可以根據你的需求，進一步探索Serializers的各種高階用法。

ViewSets

在Django REST框架中，ViewSets是一個重要的元件，它提供了一種高階的檢視抽象，使我們能夠更方便地實現基於RESTful原則的API介面。

什麼是ViewSet？

ViewSet可以看作是多個檢視的集合。在Django REST框架中，ViewSet類似於Django中的類檢視（Class-Based Views），但是它提供了更多的預設行為和更廣泛的功能，比如預設實現的GET、POST、PUT、PATCH和DELETE操作。

# views.py

from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

在上述例子中，BookViewSet就是一個ViewSet。它繼承自ModelViewSet類，為Book模型實現了一整套的CRUD操作。

ViewSets的工作原理

ViewSet的工作原理與Django的類檢視非常相似。它將HTTP方法對映到ViewSet中的相應方法，比如GET請求會對映到list或者retrieve方法，POST請求會對映到create方法，PUT和PATCH請求會對映到update方法，DELETE請求會對映到destroy方法。

以下是一個簡單的例子，演示瞭如何使用BookViewSet處理GET和POST請求：

# 使用ViewSet處理GET請求
from rest_framework.test import APIRequestFactory

factory = APIRequestFactory()
request = factory.get('/books/')
response = BookViewSet.as_view({'get': 'list'})(request)
print(response.status_code)
# 輸出：200

# 使用ViewSet處理POST請求
request = factory.post('/books/', {'title': 'Django REST Framework', 'author': 'Tom Christie', 'published_date': '2023-07-01'})
response = BookViewSet.as_view({'post': 'create'})(request)
print(response.status_code)
# 輸出：201

ViewSets的範例和使用

ViewSet最常見的使用場景就是在URLconf中，用於為API介面建立URL路由。

例如，我們可以在URLconf中使用BookViewSet，來建立圖書API的URL路由：

# urls.py

from django.urls import include, path
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

在上述例子中，我們在URLconf中註冊了BookViewSet，Django REST框架會自動為BookViewSet建立一套URL路由，對應到其定義的各種操作。

ViewSet的使用非常靈活，它們不僅可以用於實現基本的CRUD操作，還可以用於實現複雜的邏輯，如許可權控制、過濾、分頁等。在掌握了基本用法後，你可以根據你的需求，進一步探索ViewSet的各種高階用法。

Routers

在 Django REST 框架中，Routers 為檢視集 (ViewSets) 提供了一種簡潔的方式來建立和管理 URL 設定。使用 Routers，我們可以快速建立並設定 URL，減少重複的工作。

什麼是Router？

Router 可以自動地為檢視集建立 URL 設定，它為每個檢視集提供了一套標準的增刪改查（CRUD）操作的 URL 設定。Router 的使用可以極大地提高開發效率，避免了手動建立每個 URL 的繁瑣工作。

以下是一個簡單的使用 Router 的例子：

# urls.py

from django.urls import include, path
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

在上述例子中，我們使用 DefaultRouter 建立了一個 router，然後呼叫其 register 方法註冊了 BookViewSet。這會自動為 BookViewSet 建立一套標準的 URL 設定。

Router 的工作原理

當你向 Router 註冊一個檢視集時，Router 會自動為這個檢視集建立一套 URL 設定。這套 URL 設定對應到檢視集的各個方法，如 list、create、retrieve、update 和 destroy。

router = DefaultRouter()
router.register(r'books', BookViewSet)

在上述例子中，router 會為 BookViewSet 建立以下的 URL 設定：

  • /books/：對應到 BookViewSet 的 list 和 create 方法，分別處理 GET 和 POST 請求；
  • /books/{pk}/：對應到 BookViewSet 的 retrieve、update 和 destroy 方法，分別處理 GET、PUT/PATCH 和 DELETE 請求。

Router 的範例和使用

在 Django REST 框架中，有兩種常見的 Router：DefaultRouter 和 SimpleRouter。DefaultRouter 提供了一套包含額外的瀏覽器介面的路由設定，而 SimpleRouter 則提供了一套簡單的基礎路由設定。

Router 的使用非常靈活，你可以根據需要註冊任意數量的檢視集，也可以在不同的 Django app 中使用不同的 Router。在掌握了基本用法後，你還可以深入研究如何自定義 Router，如自定義 URL 設定，自定義 URL 名稱等。

許可權和認證

在構建API時，許可權和認證是非常重要的一環，它們決定了使用者能否存取你的API以及使用者可以做什麼。Django REST Framework提供了一套完善的許可權和認證系統，讓你可以輕鬆地控制使用者的存取許可權。

認證

認證是確定使用者身份的過程。Django REST Framework支援多種認證方式，如SessionAuthentication、TokenAuthentication、BasicAuthentication等。

以下是如何在檢視中使用TokenAuthentication的範例：

# views.py

from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework import viewsets
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    authentication_classes = [TokenAuthentication]
    permission_classes = [IsAuthenticated]

在這個例子中，我們為BookViewSet設定了authentication_classes屬性，指定了使用TokenAuthentication。當用戶請求BookViewSet時，Django REST Framework會檢查請求的HTTP頭部是否包含有效的令牌，以確定使用者的身份。

許可權

許可權是決定已經認證的使用者可以做什麼的規則。Django REST Framework提供了多種許可權管理方式，如IsAuthenticated、IsAdminUser、IsAuthenticatedOrReadOnly等。

在上述例子中，我們為BookViewSet設定了permission_classes屬性，指定了使用IsAuthenticated。這意味著只有認證過的使用者才可以存取BookViewSet。

自定義認證和許可權

除了使用Django REST Framework提供的認證和許可權管理方式，你還可以自定義認證和許可權。自定義認證和許可權可以讓你更靈活地控制使用者的存取許可權。

以下是一個自定義許可權的例子，這個許可權類只允許作者存取他們自己的圖書：

# permissions.py

from rest_framework import permissions

class IsAuthor(permissions.BasePermission):
    def has_object_permission(self, request, view, obj):
        return obj.author == request.user

然後你可以在檢視中使用這個自定義許可權：

# views.py

from .permissions import IsAuthor
# 其他匯入...

class BookViewSet(viewsets.ModelViewSet):
    # 其他程式碼...
    permission_classes = [IsAuthenticated, IsAuthor]

在這個例子中，IsAuthor許可權類會對每個請求進行檢查，如果請求的使用者不是圖書的作者，那麼請求將被拒絕。

測試與偵錯

測試和偵錯是保證程式碼質量的重要步驟。Django REST Framework提供了一套用於測試和偵錯API的工具。

測試

Django REST Framework整合了Django的測試框架，並提供了一些額外的功能用於測試API。你可以使用Django REST Framework的APIClient類來模擬API請求，然後檢查響應。

以下是一個測試範例：

# tests.py

from django.urls import reverse
from rest_framework import status
from rest_framework.test import APITestCase, APIClient
from .models import Book

class BookTests(APITestCase):
    def setUp(self):
        self.client = APIClient()
        self.book = Book.objects.create(title='Test Book', author='Test Author')

    def test_get_book(self):
        url = reverse('book-detail', kwargs={'pk': self.book.pk})
        response = self.client.get(url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response.data['title'], 'Test Book')
        self.assertEqual(response.data['author'], 'Test Author')

在這個例子中，我們首先在setUp方法中建立了一個APIClient和一個Book範例。然後，在test_get_book方法中，我們使用APIClient發出GET請求，然後檢查響應的狀態碼和資料。

偵錯

Django REST Framework提供了一個瀏覽器介面用於偵錯API。你可以在瀏覽器中直接存取API，檢視響應資料，或者發出POST、PUT、PATCH和DELETE請求。瀏覽器介面非常直觀，是偵錯API的好工具。

要使用瀏覽器介面，你只需要在settings.py中啟用它：

# settings.py

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework.renderers.JSONRenderer',
        # 其他渲染器...
    ]
}

在上述設定中，我們啟用了BrowsableAPIRenderer，這將啟用瀏覽器介面。你現在可以在瀏覽器中存取API了。

使用工具進行偵錯

有許多工具可以幫助你偵錯API，如Postman、Insomnia等。這些工具可以模擬各種HTTP請求，檢視請求和響應的詳細資訊，以及儲存和組織API請求。如果你需要進行復雜的API偵錯，這些工具可能會很有幫助。

雖然測試和偵錯可能會花費一些時間，但它們是保證程式碼質量的關鍵。在編寫程式碼時，不要忘記寫測試和進行偵錯。

總結

至此，我們對Django REST Framework進行了一次深入的概覽。我們開始時介紹了Django REST Framework的基礎知識，然後深入學習了Serializers、ViewSets和Routers。我們還討論了許可權和認證系統，以及如何進行測試和偵錯。

Django REST Framework提供了許多強大的工具，使得構建複雜的API變得輕鬆。然而，掌握這些工具需要時間和實踐。我希望這篇文章能幫助你開始你的Django REST Framework之旅。

最後，我想重申一下我們在文章中討論的一些關鍵點：

  • Serializers用於資料序列化和反序列化。
  • ViewSets是用於處理檢視邏輯的類。
  • Routers負責URL的生成和分發。
  • Django REST Framework提供了一套強大的許可權和認證系統。
  • 你可以使用Django REST Framework的測試工具和偵錯介面來測試和偵錯你的API。

如有幫助，請多關注
個人微信公眾號：【Python全視角】
TeahLead_KrisChang，10+年的網際網路和人工智慧從業經驗，10年+技術和業務團隊管理經驗，同濟軟體工程本科，復旦工程管理碩士，阿里雲認證雲服務資深架構師，上億營收AI產品業務負責人。