四、【API 开发篇 (上)】：使用 Django REST Framework 构建项目与模块 CRUD 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 已经基本搭建好了，现在来验证一下。

1. 启动 Django 开发服务器：
   在终端中 (确保在 test-platform 目录下，并且 (venv) 已激活)，运行：

   python manage.py runserver
   

   

2. 访问 DRF 的可浏览 API 界面：
   在浏览器中访问 http://127.0.0.1:8000/api/。
   

   如果看到以上页面内容，说明 DRF 和路由配置成功了。这个页面是 DefaultRouter 提供的根视图，列出了所有注册的 API 终端 (projects/ 和 modules/)。

3. 测试 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 的表单或按钮，你可以尝试修改或删除项目。

4. 测试 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 类似。
     

通过可浏览的 API 界面，你可以在不写任何前端代码的情况下，方便地验证你的后端 API 是否按照预期工作。

总结

你已经成功地迈出了后端 API 开发的关键一步：

• ✅ 理解了 DRF 在构建 API 中的作用和核心组件 (Serializers, ViewSets, Routers)。
• ✅ 为 Project 和 Module 模型创建了 ModelSerializer。
• ✅ 使用 ModelViewSet 快速实现了 Project 和 Module 的 CRUD 视图逻辑。
• ✅ 利用 DefaultRouter 自动生成了 API 的 URL 模式。
• ✅ 在项目 URL 配置中包含了 API App 的 URL。
• ✅ 通过 DRF 的可浏览 API 界面验证了你的 API 功能。

现在，你的后端已经能够响应前端对项目和模块数据的操作请求了。

在下一篇文章中，我们将继续 API 开发，但会处理稍微复杂一些的 测试用例 (TestCase) 模型。