零基础掌握 Django REST Framework：API开发入门 – wiki大全

作者： /

零基础掌握 Django REST Framework：API 开发入门

1. 简介：什么是 Django REST Framework (DRF)？

在现代 Web 开发中，应用程序不再仅仅是简单的网页。随着移动应用、单页应用 (SPA) 和各种客户端的兴起，后端服务需要以一种独立于前端的技术提供数据，这就是 API (Application Programmatic Interface) 的作用。

Django REST Framework (DRF) 是一个强大而灵活的工具包，用于在 Django 的基础上构建 Web API。它极大地简化了 API 的开发过程，提供了许多开箱即用的功能，如序列化、认证、权限、视图集和路由等，让开发者能够快速、高效地构建生产级的 RESTful API。

为什么选择 DRF？
* Django 生态集成: 与 Django 完美结合，利用其 ORM、Admin 等强大功能。
* 快速开发: 提供了大量通用视图和序列化器，减少重复代码。
* 丰富的功能: 内置认证、权限、限流、过滤、分页等功能。
* 良好的文档: 详细而清晰的官方文档。
* 活跃的社区: 遇到问题时容易找到帮助和资源。

2. 前置知识

在深入 DRF 之前，建议你对以下内容有一定的了解：
* Python 基础: 掌握 Python 语法和面向对象编程。
* Django 基础: 了解 Django 项目结构、模型 (Models)、视图 (Views)、URL 配置 (URLs) 和 ORM。
* RESTful API 概念: 理解 RESTful 设计原则，如资源、HTTP 方法（GET, POST, PUT, DELETE）、状态码等。

3. 环境搭建与项目初始化

步骤 1: 安装 Django 和 DRF

首先，创建一个虚拟环境（推荐），然后安装 Django 和 Django REST Framework。

“`bash

创建并激活虚拟环境 (Windows)

python -m venv venv
venv\Scripts\activate

创建并激活虚拟环境 (macOS/Linux)

python3 -m venv venv
source venv/bin/activate

安装 Django 和 DRF

pip install Django djangorestframework
“`

步骤 2: 创建 Django 项目和应用

接下来，创建一个 Django 项目和一个应用程序。

bash
django-admin startproject myapi_project . # 注意点，表示在当前目录创建
python manage.py startapp myapp

步骤 3: 配置 Django 项目

打开 myapi_project/settings.py 文件，将 'rest_framework' 和 'myapp' 添加到 INSTALLED_APPS 列表中。

“`python

myapi_project/settings.py

INSTALLED_APPS = [
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,
‘rest_framework’, # 添加 DRF
‘myapp’, # 添加你的应用
]

… 其他设置

“`

运行数据库迁移：

bash
python manage.py migrate

4. DRF 核心概念

DRF 的核心在于将 Django 的模型层与 API 接口连接起来，主要通过以下几个关键组件：

4.1. 序列化器 (Serializers)

序列化器负责将复杂的 Django 模型实例（以及其他数据类型）转换为 Python 原生数据类型，然后可以很方便地将其渲染为 JSON、XML 或其他内容类型。反之，它也可以将接收到的原生数据反序列化回模型实例，并进行验证。

ModelSerializer 是最常用的序列化器，它可以自动为你创建与 Django 模型字段相对应的字段。

4.2. 视图 (Views)

在 DRF 中，视图处理传入的 HTTP 请求并返回响应。DRF 提供了多种类型的视图：
* APIView: DRF 提供的 View 类的基础版本，处理所有 HTTP 方法（GET, POST 等），你可以自定义逻辑。
* GenericAPIView: APIView 的扩展，增加了对 DRF 泛型视图（mixins）的支持，用于实现常用操作如 list, create, retrieve, update, destroy。
* 泛型视图 (Generic Views): GenericAPIView 和一组 mixins 的组合，提供了更高级别的抽象，例如 ListCreateAPIView (用于列表和创建资源)、RetrieveUpdateDestroyAPIView (用于检索、更新和删除单个资源)。
* 视图集 (ViewSets): 将相关视图的逻辑组合在一个类中，例如 ModelViewSet 可以一次性提供一个模型的 list, create, retrieve, update, destroy 操作。

4.3. 路由器 (Routers)

路由器用于自动为视图集生成 URL 配置。当你使用 ModelViewSet 时，路由器可以大大简化 urls.py 的编写。DefaultRouter 是最常用的路由器。

5. 实践项目：一个简单的 Todo List API

我们将创建一个简单的待办事项 (Todo List) API，包含创建、读取、更新和删除 (CRUD) 功能。

步骤 1: 定义模型 (Model)

在 myapp/models.py 中定义 Todo 模型。

“`python

myapp/models.py

from django.db import models

class Todo(models.Model):
title = models.CharField(max_length=100)
description = models.TextField(blank=True)
completed = models.BooleanField(default=False)
created_at = models.DateTimeField(auto_now_add=True)

def __str__(self):
    return self.title

“`

运行迁移以创建数据库表：

bash
python manage.py makemigrations myapp
python manage.py migrate

步骤 2: 创建序列化器 (Serializer)

在 myapp 目录下创建 serializers.py 文件，并定义 TodoSerializer。

“`python

myapp/serializers.py

from rest_framework import serializers
from .models import Todo

class TodoSerializer(serializers.ModelSerializer):
class Meta:
model = Todo
fields = ‘all‘ # 或者指定你想要暴露的字段，例如 [‘id’, ‘title’, ‘completed’]
“`

步骤 3: 创建视图 (Views)

在 myapp/views.py 中使用 DRF 的泛型视图来创建 Todo API 的视图。

“`python

myapp/views.py

from rest_framework import generics
from .models import Todo
from .serializers import TodoSerializer

class TodoListCreateAPIView(generics.ListCreateAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer

class TodoRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
queryset = Todo.objects.all()
serializer_class = TodoSerializer
“`

步骤 4: 配置 URL (URLs)

首先，在 myapp 目录下创建 urls.py 文件，并定义应用的 URL 模式。

“`python

myapp/urls.py

from django.urls import path
from .views import TodoListCreateAPIView, TodoRetrieveUpdateDestroyAPIView

urlpatterns = [
path(‘todos/’, TodoListCreateAPIView.as_view(), name=’todo-list-create’),
path(‘todos//’, TodoRetrieveUpdateDestroyAPIView.as_view(), name=’todo-detail’),
]
“`

然后，在项目根目录的 myapi_project/urls.py 中包含 myapp 的 URL。

“`python

myapi_project/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(‘myapp.urls’)), # 包含 myapp 的 API URL
]
“`

步骤 5: 启动开发服务器并测试

运行 Django 开发服务器：

bash
python manage.py runserver

现在，你可以使用浏览器访问 http://127.0.0.1:8000/api/todos/。DRF 提供了一个美观的浏览器 API 界面，你可以直接在浏览器中进行 GET 和 POST 请求。

通过 curl 或 Postman/Insomnia 等工具测试 API：

  • 获取所有 Todo：
    bash
    curl -X GET http://127.0.0.1:8000/api/todos/

  • 创建一个 Todo：
    bash
    curl -X POST -H "Content-Type: application/json" -d '{"title": "学习 DRF", "description": "完成 DRF 入门指南", "completed": false}' http://127.0.0.1:8000/api/todos/

  • 获取单个 Todo (假设 ID 为 1)：
    bash
    curl -X GET http://127.0.0.1:8000/api/todos/1/

  • 更新一个 Todo (假设 ID 为 1)：
    bash
    curl -X PUT -H "Content-Type: application/json" -d '{"title": "完成 DRF 指南", "description": "学习并完成 DRF 入门指南", "completed": true}' http://127.0.0.1:8000/api/todos/1/

  • 删除一个 Todo (假设 ID 为 1)：
    bash
    curl -X DELETE http://127.0.0.1:8000/api/todos/1/

6. 进阶概念概览 (入门级介绍)

6.1. 认证 (Authentication) 与 权限 (Permissions)

API 通常需要保护，以确保只有授权用户才能访问。
* 认证 (Authentication): 识别用户的身份（你是谁？）。DRF 提供了多种认证方式，如 TokenAuthentication (最常用)、SessionAuthentication、BasicAuthentication 等。
* 权限 (Permissions): 决定用户是否有权执行特定操作（你能做什么？）。例如，IsAuthenticated (只允许已认证用户)、IsAdminUser (只允许管理员)、AllowAny (允许所有用户)、IsAuthenticatedOrReadOnly (已认证用户可读写，匿名用户只读)。

你可以在 settings.py 中全局配置认证和权限，也可以在视图类中局部配置。

“`python

myapi_project/settings.py

REST_FRAMEWORK = {
‘DEFAULT_AUTHENTICATION_CLASSES’: [
‘rest_framework.authentication.TokenAuthentication’,
‘rest_framework.authentication.SessionAuthentication’,
],
‘DEFAULT_PERMISSION_CLASSES’: [
‘rest_framework.permissions.IsAuthenticatedOrReadOnly’,
]
}

myapp/views.py (局部配置)

from rest_framework.permissions import IsAdminUser

class MyProtectedView(generics.ListAPIView):
queryset = MyModel.objects.all()
serializer_class = MyModelSerializer
permission_classes = [IsAdminUser] # 只允许管理员访问
“`

6.2. 视图集 (ViewSets) 和 路由器 (Routers)

对于一个模型的所有 CRUD 操作，可以使用 ModelViewSet 配合 DefaultRouter 来极大地简化 URL 配置。

“`python

myapp/views.py (使用 ViewSet)

from rest_framework import viewsets
from .models import Todo
from .serializers import TodoSerializer

class TodoViewSet(viewsets.ModelViewSet):
queryset = Todo.objects.all()
serializer_class = TodoSerializer

myapi_project/urls.py (使用 Router)

from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from myapp.views import TodoViewSet

router = DefaultRouter()
router.register(r’todos’, TodoViewSet) # 注册 TodoViewSet

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(router.urls)), # 包含 router 生成的 URL
]
``
使用ModelViewSet和DefaultRouter后，访问http://127.0.0.1:8000/api/todos/会自动生成/api/todos/(列表/创建) 和/api/todos//` (详情/更新/删除) 等 URL。

7. 总结与展望

通过本文，你已经学习了 Django REST Framework 的基本概念，并构建了一个简单的 Todo List API。DRF 的强大之处远不止于此，这仅仅是一个开始。

接下来你可以继续探索：
* 过滤 (Filtering): 如何根据查询参数过滤资源列表。
* 分页 (Pagination): 如何限制返回数据的数量，实现分页功能。
* 限流 (Throttling): 如何限制用户或客户端对 API 的请求频率。
* 自定义字段和序列化器方法: 处理更复杂的序列化逻辑。
* 嵌套序列化: 处理关联模型的序列化。
* 测试: 为你的 API 编写单元测试和集成测试。
* 生产部署: 如何将你的 DRF 应用部署到生产环境。

Django REST Framework 是构建高效、可维护 API 的绝佳选择。祝你在 API 开发的道路上越走越远！

滚动至顶部