四、【API 開發篇 (上)】：使用 Django REST Framework 構建項目與模塊 CRUD API

【API 開發篇】：使用 Django REST Framework 構建項目與模塊 CRUD API

- 前言
- - 為什么選擇 Django REST Framework (DRF)？
  - 第一步：創建 Serializers (序列化器)
  - 第二步：創建 ViewSets (視圖集)
  - 第三步：配置 URLs (路由)
  - 第四步：在項目 URLconf 中包含 App 的 URLs
  - 第五步：測試 API
- 總結

前言

還記得我們的架構藍圖嗎？

前端 (Vue3) 負責展示和交互。
后端 API (DRF) 是前后端溝通的橋梁。
后端邏輯 (Django) 處理業務和數據。
數據持久層 (Models/Database) 存儲數據。

今天，我們的重點就是構建中間的“橋梁”——后端 API 層。

為什么選擇 Django REST Framework (DRF)？

在 Django 生態系統中，DRF 是構建 RESTful API 的標準。它提供了一系列強大的工具，可以極大地加速 API 的開發過程：

Serializers (序列化器): 輕松地將復雜的 Django 模型對象轉換成 JSON/XML 等格式（用于響應前端），或將接收到的數據反序列化并驗證（用于創建或更新數據）。
Views / ViewSets (視圖/視圖集): 處理請求和響應。ViewSets 特別方便，可以將多個相關的視圖邏輯（如列表、詳情、創建、更新、刪除）合并到一個類中。
Routers (路由): 自動生成 URL 模式，省去了手動編寫大量 URLconf 的麻煩。
Authentication & Permissions (認證和權限): 提供了多種認證和權限機制，方便保護你的 API。
Browsable API (可瀏覽的 API): DRF 提供了一個非常友好的網頁界面，可以直接在瀏覽器中測試 API，對于開發和調試非常有用。

第一步：創建 Serializers (序列化器)

Serializers 負責數據的進出轉換。我們需要為 Project 和 Module 模型創建對應的序列化器。

在 api 文件夾下，創建一個新文件 serializers.py。
在這里插入圖片描述

打開 api/serializers.py，添加以下代碼：
在這里插入圖片描述

# test-platform/api/serializers.pyfrom rest_framework import serializers
from .models import Project, Module, TestCase # 導入你之前定義的模型class ProjectSerializer(serializers.ModelSerializer):"""項目序列化器"""class Meta:model = Project # 指明要序列化的模型fields = '__all__' # 序列化模型中的所有字段class ModuleSerializer(serializers.ModelSerializer):"""模塊序列化器"""class Meta:model = Module # 指明要序列化的模型# 明確指定需要序列化的字段，包括外鍵 project# 注意：默認情況下，ModelSerializer 序列化外鍵時只會包含關聯對象的 IDfields = ['id', 'name', 'description', 'project', 'create_time', 'update_time']# 也可以用 '__all__', 但明確指定有助于理解# fields = '__all__'

代碼解釋：

from rest_framework import serializers: 導入 DRF 的序列化器模塊。
from .models import ...: 導入我們在 models.py 中定義的模型。
class ProjectSerializer(serializers.ModelSerializer):: 定義一個名為 ProjectSerializer 的類，它繼承自 serializers.ModelSerializer。ModelSerializer 是 DRF 提供的一個便捷類，可以根據 Django 模型自動生成序列化器的字段。
class Meta:: 在序列化器類內部定義一個 Meta 類，用于配置序列化器。
model = Project: 指明這個序列化器是為哪個模型服務的。
fields = '__all__': 表示序列化該模型的所有字段。你也可以使用一個列表來指定需要序列化的字段，例如 fields = ['id', 'name', 'owner']。對于 ModuleSerializer，我們明確列出了字段，包括了 project 外鍵字段。當序列化時，DRF 默認會顯示外鍵關聯對象的 ID。

第二步：創建 ViewSets (視圖集)

ViewSets 負責處理 HTTP 請求，調用序列化器進行數據轉換，并與數據庫交互。使用 ModelViewSet 可以非常快速地實現 CRUD 操作。

打開 api/views.py 文件，添加以下代碼：
在這里插入圖片描述

# test-platform/api/views.py# from django.shortcuts import render # 這個現在用不到了
from rest_framework import viewsets
from .models import Project, Module, TestCase # 導入模型
from .serializers import ProjectSerializer, ModuleSerializer # 導入序列化器class ProjectViewSet(viewsets.ModelViewSet):"""項目管理視圖集提供項目列表、創建、詳情、更新、刪除等接口"""queryset = Project.objects.all() # 指定視圖集查詢的數據集serializer_class = ProjectSerializer # 指定用于序列化和反序列化的序列化器class ModuleViewSet(viewsets.ModelViewSet):"""模塊管理視圖集提供模塊列表、創建、詳情、更新、刪除等接口"""queryset = Module.objects.all() # 指定視圖集查詢的數據集serializer_class = ModuleSerializer # 指定用于序列化和反序列化的序列化器# TestCaseViewSet 將在下一篇文章中實現，因為它涉及更復雜的序列化和邏輯
# class TestCaseViewSet(viewsets.ModelViewSet):
#     queryset = TestCase.objects.all()
#     serializer_class = TestCaseSerializer

代碼解釋：

from rest_framework import viewsets: 導入 DRF 的視圖集模塊。
from .models import ... 和 from .serializers import ...: 導入相關的模型和序列化器。
class ProjectViewSet(viewsets.ModelViewSet):: 定義一個 ProjectViewSet，繼承自 viewsets.ModelViewSet。
queryset = Project.objects.all(): 這是 ModelViewSet 所需的關鍵屬性之一。它指定了該視圖集將操作哪些數據集合。這里是所有的 Project 對象。DRF 會根據這個 queryset 來執行列表、詳情等操作。
serializer_class = ProjectSerializer: 這是 ModelViewSet 所需的另一個關鍵屬性。它指定了該視圖集使用哪個序列化器來進行數據的輸入驗證和輸出格式化。
ModelViewSet 會自動為我們生成以下路由和對應的操作：
- GET /projects/: 獲取項目列表 (list action)
- POST /projects/: 創建新項目 (create action)
- GET /projects/{id}/: 獲取指定 ID 的項目詳情 (retrieve action)
- PUT /projects/{id}/: 更新指定 ID 的項目 (update action)
- PATCH /projects/{id}/: 部分更新指定 ID 的項目 (partial_update action)
- DELETE /projects/{id}/: 刪除指定 ID 的項目 (destroy action)

ModuleViewSet 的原理和 ProjectViewSet 完全一樣，只是操作的對象變成了 Module 模型和 ModuleSerializer。

第三步：配置 URLs (路由)

DRF 的 Routers 可以自動幫我們生成 ModelViewSet 對應的 URL 模式。

在 api 文件夾下，創建一個新文件 urls.py。
在這里插入圖片描述

打開 api/urls.py，添加以下代碼：
在這里插入圖片描述

# test-platform/api/urls.pyfrom django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ProjectViewSet, ModuleViewSet # 導入視圖集# 創建一個 DefaultRouter 實例
router = DefaultRouter()# 注冊視圖集
# 第一個參數是 URL 前綴，例如 'projects'
# 第二個參數是視圖集類
# 第三個參數是可選的 basename，用于生成 URL 名稱，通常與 URL 前綴一致
router.register(r'projects', ProjectViewSet, basename='project')
router.register(r'modules', ModuleViewSet, basename='module')# router.urls 會自動生成包含所有注冊的 ViewSet 對應的 URL 模式列表
urlpatterns = [path('', include(router.urls)), # 將 router 生成的 URL 模式包含進來
]

代碼解釋：

from rest_framework.routers import DefaultRouter: 導入 DRF 的默認路由類。
from .views import ...: 導入我們剛剛創建的視圖集。
router = DefaultRouter(): 創建一個路由器實例。DefaultRouter 會自動包含根視圖（顯示所有注冊的 API 列表）和格式后綴模式。
router.register(r'projects', ProjectViewSet, basename='project'): 注冊 ProjectViewSet。訪問路徑會以 /projects/ 開頭。例如 /projects/ (列表/創建), /projects/1/ (詳情/更新/刪除 ID 為 1 的項目)。
router.register(r'modules', ModuleViewSet, basename='module'): 注冊 ModuleViewSet，訪問路徑以 /modules/ 開頭。
urlpatterns = [...]: 定義 URL 模式列表。
path('', include(router.urls)): 這一行將路由器自動生成的 URL 模式全部包含進 api 應用的 URLconf 中。因為我們將這個 include 的第一個參數設為 ''，所以視圖集注冊時的 URL 前綴（如 projects, modules）會直接跟在應用 URL（例如 api/，我們稍后會在項目 urls.py 中配置）后面。

第四步：在項目 URLconf 中包含 App 的 URLs

最后一步，我們需要在整個 Django 項目的 URL 配置文件 (backend/urls.py) 中，包含我們 api App 的 URL 模式。

打開 test-platform/backend/urls.py 文件：
在這里插入圖片描述

# test-platform/backend/urls.pyfrom django.contrib import admin
from django.urls import path, include # 確保導入了 includeurlpatterns = [path('admin/', admin.site.urls), # Django Admin 的 URLpath('api/', include('api.urls')), # 添加這一行，將所有以 'api/' 開頭的請求轉發到 api.urls 處理
]

代碼解釋：

from django.urls import path, include: 確保導入了 include 函數。
path('api/', include('api.urls')): 這一行是關鍵。它告訴 Django，任何以 api/ 開頭的 URL 請求都應該“包含”并交給 api 應用下的 urls.py 文件去處理。
結合 api/urls.py 中的 path('', include(router.urls))，最終的完整 URL 路徑會是 /api/projects/, /api/modules/ 等。

第五步：測試 API

后端 API 已經基本搭建好了，現在來驗證一下。

啟動 Django 開發服務器：
在終端中 (確保在 test-platform 目錄下，并且 (venv) 已激活)，運行：
```
python manage.py runserver
```
訪問 DRF 的可瀏覽 API 界面：
在瀏覽器中訪問 http://127.0.0.1:8000/api/。

如果看到以上頁面內容，說明 DRF 和路由配置成功了。這個頁面是 DefaultRouter 提供的根視圖，列出了所有注冊的 API 終端 (projects/ 和 modules/)。
測試 Project API：
點擊 http://127.0.0.1:8000/api/projects/ 鏈接。
- GET (列表): 你會看到一個獲取項目列表的頁面。如果之前你在 Django Admin 中創建過項目，這里會顯示出來。頁面下方有一個表單，可以用來發送 POST 請求創建新項目。
- POST (創建): 在頁面下方的表單中填寫項目信息（名稱, 描述, 負責人, 項目狀態），然后點擊 POST 按鈕。如果成功，會返回新創建的項目數據，并在上方列表中刷新顯示。
- GET (詳情): 在項目列表頁面，點擊某個項目的 URL (例如 http://127.0.0.1:8000/api/projects/1/)，可以查看該項目的詳情。
- PUT/PATCH/DELETE: 在項目詳情頁面，也會有 PUT (完全更新), PATCH (部分更新) 和 DELETE 的表單或按鈕，你可以嘗試修改或刪除項目。
測試 Module API：
返回 http://127.0.0.1:8000/api/，點擊 http://127.0.0.1:8000/api/modules/ 鏈接。
- GET (列表): 查看模塊列表。
- POST (創建): 創建模塊時，請注意表單中會有 project 字段。你需要填寫該模塊所屬項目的 ID。例如，如果你創建的第一個項目 ID 是 1，那么這里就填寫 1。填寫其他模塊信息（name, description），然后 POST。
- 測試詳情、更新、刪除操作與 Project 類似。